Five9 Secure Pay JS Library Docs

Appearance

API Reference ​

This doc covers methods and events that are available in the five9-secureivr js lib.

Secure IVR Client is an event-based library for Five9 Secure Pay that allows you to start a Secure IVR session, cancel a Secure IVR session, and receive events for the Secure IVR session.

Secure IVR Client Methods ​

Initialize Client ​

Initialize the Secure IVR Client.

Example ​

js
const secureIvrClient = new SecureIvrClient();
const secureIvrClient = new SecureIvrClient();

Start Secure Pay ​

If the agent is on a call, initialize a conference to the Secure Pay campaign. This intializes the secure payment call flow.

Example ​

js
secureIvrClient.startSecurePay({
  withEvents: true,
  callVariables: {
    'SecurePay.FirstName': firstName,
    'SecurePay.LastName': lastName,
    'SecurePay.InvoiceNumber': paymentAmount,
    'SecurePay.PaymentAmount': invoiceNumber,
  },
});
secureIvrClient.startSecurePay({
  withEvents: true,
  callVariables: {
    'SecurePay.FirstName': firstName,
    'SecurePay.LastName': lastName,
    'SecurePay.InvoiceNumber': paymentAmount,
    'SecurePay.PaymentAmount': invoiceNumber,
  },
});

In this example, we are passing in four Call Variables and their values to be set for use in the Secure Pay IVR.

The format for Call Variables that are passed in should be CavGroup.CavName. If the group is not included, the Call Variables will not be set properly and thus will not be accessible in the Secure Payment IVR.

Parameters

withEvents - (optional) - boolean
Whether to start secure payment with bridge events or not. If true, bridge events will be received on your event listener as 'secureivr.message' events. If you do not want a WebSocket connection to be made with the Bridge Service, this option can be set to false, but secureivr.message events for the in-progress Secure IVR call will not be received.

callVariables - (optional) - object Call variables to set when starting the secure ivr. The "key" is the CallVariable in your Five9 VCC (including the call variable group), and the "value" is its value.

Cancel Secure Pay ​

Cancel an active secure ivr call. Brings the caller back to the agent immediately. The secure ivr flow can be started again after the caller is brought back.

Example ​

js
secureIvrClient.cancelSecurePay();
secureIvrClient.cancelSecurePay();

Listen to Events ​

Listen to events from the secure ivr client. When defining event listeners, you can use the "event" payload to respond accordingly to each event based on the data inside.

Each "event" payload should always contain an evt, status, and data property.

Example ​

js
secureIvrClient.on('secureivr.message', (event) => {
  /**
   *  'event' in each callback contains these properties.
   * {
   *  evt: 'secureivr.started',
   *  status: 'OK', // Could also be 'ERROR'
   *  data: { sessionId: "ABCD-EFGH-IJKL-MNOP"} // ... additional properties in 'data' depending * on the event type
   * }
   **/
});
secureIvrClient.on('secureivr.message', (event) => {
  /**
   *  'event' in each callback contains these properties.
   * {
   *  evt: 'secureivr.started',
   *  status: 'OK', // Could also be 'ERROR'
   *  data: { sessionId: "ABCD-EFGH-IJKL-MNOP"} // ... additional properties in 'data' depending * on the event type
   * }
   **/
});

Events ​

The Secure IVR API triggers events based on the operations that are initiated. These events can be listened to on your webpage (see example) so that you can respond accordingly

This section shows an example of each event, and those events which have additional properties have the properties listed.

A status of OK means that the event indicates a success. ERROR means that something went wrong with the event.

The success-case flow of events should be: secureivr.ready -> secureivr.started -> secureivr.not_ready -> secureivr.message (any number of times) -> secureivr.ended -> secureivr.ready; where status.changed will occur periodically as the agent transitions through call states.

secureivr.ready ​

Secure IVR is ready for use. This indicates that the "Start" button can be pressed to initialize a Secure IVR. Also indicates that the "Cancel" button should be available for use.

json
{ "evt": "secureivr.ready", "status": "OK", "data": {} }
{ "evt": "secureivr.ready", "status": "OK", "data": {} }

secureivr.not_ready ​

Secure IVR is not ready for use. This indicates that the "Start" button should be disabled.

json
{ "evt": "secureivr.not_ready", "status": "OK", "data": {} }
{ "evt": "secureivr.not_ready", "status": "OK", "data": {} }

secureivr.started ​

Triggered when the Secure IVR call has started. A conference will be active on the Agent's screen at this point, and the caller will be on a Secure IVR call flow.

data

sessionId: This is the value of Call.session_id of the Secure IVR call.

json
{ "evt": "secureivr.started", "status": "OK", "data": { "sessionId": "578C07C7DB78446EAC3D39743D8C38DA" } }
{ "evt": "secureivr.started", "status": "OK", "data": { "sessionId": "578C07C7DB78446EAC3D39743D8C38DA" } }

secureivr.ended ​

Triggered when the Secure IVR has ended. The caller should be returned to the Agent at this point on a call.

json
{ "evt": "secureivr.ended", "status": "OK", "data": {} }
{ "evt": "secureivr.ended", "status": "OK", "data": {} }

secureivr.message ​

Indicates that a secure IVR message has been received, and can be handled or shown in the UI. This event will be received while a Secure Payment is active, and messages will be delivered as the caller progresses through the Secure IVR menu depending on how the IVR is configured to emit bridge messages. RESULT indicates that it is the final result of the payment, usually a confirmation code or an error. MESSAGE indicates a message that occurs in the Secure Payment flow prior to a result being received, I.E. "Customer has just finished entering their card number."

data

message: The received message.

type: The type of message received. Either MESSAGE, or RESULT.

json
{
  "evt": "secureivr.message",
  "status": "OK",
  "data": { "message": "Customer is entering credit card number.", "type": "MESSAGE" }
}

{
  "evt": "secureivr.message",
  "status": "OK",
  "data": { "message": "Payment Reference ID: ABCD", "type": "RESULT" }
}
{
  "evt": "secureivr.message",
  "status": "OK",
  "data": { "message": "Customer is entering credit card number.", "type": "MESSAGE" }
}

{
  "evt": "secureivr.message",
  "status": "OK",
  "data": { "message": "Payment Reference ID: ABCD", "type": "RESULT" }
}

status.changed ​

Indicates a change in the Agent status or Secure IVR status. Includes agent events, call events, and secure ivr events. These events can be displayed on the UI to indicate the status of the agent relative to Secure IVR.

Use this event to determine what value to show on the user's status chip in the UI.

data

status: The new status. Could be INACTIVE, ACTIVE, WORKING, RINGING_ON_OTHER_SIDE, TALKING, STARTED, TALKING, WRAP_UP.

json
{ "evt": "status.changed", "status": "OK", "data": {"status": "ACTIVE"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "WORKING", "agentId":"4599762","agentUserName":"tony.stark@five9.com"} }
{ "evt": "status.changed", "status": "OK", "data": {"status":"RINGING_ON_OTHER_SIDE","callId":"5208ACB3AFA542F6BDC36489B1971C98"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "TALKING", "callId": "74B0168E85FF4183A02E0CD44DE3D1B8"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "STARTED"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "TALKING"} }
{ "evt": "status.changed", "status": "OK", "data": {"status":"WRAP_UP","callId":"74B0168E85FF4183A02E0CD44DE3D1B8"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "ACTIVE"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "WORKING", "agentId":"4599762","agentUserName":"tony.stark@five9.com"} }
{ "evt": "status.changed", "status": "OK", "data": {"status":"RINGING_ON_OTHER_SIDE","callId":"5208ACB3AFA542F6BDC36489B1971C98"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "TALKING", "callId": "74B0168E85FF4183A02E0CD44DE3D1B8"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "STARTED"} }
{ "evt": "status.changed", "status": "OK", "data": {"status": "TALKING"} }
{ "evt": "status.changed", "status": "OK", "data": {"status":"WRAP_UP","callId":"74B0168E85FF4183A02E0CD44DE3D1B8"} }

connection.changed ​

Indicates a change in the connection between the client and the Bridge Service. The Bridge Service connection is what allows a stream of events that shows the caller's status on the Secure IVR.

WARNING

Usage of this is almost never necessary.

json
{ "evt": "connection.changed", "status": "OK", "data": {"type": "CONNECTED"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "DISCONNECTED"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "RECONNECTING"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "RECONNECTED"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "CONNECTED"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "DISCONNECTED"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "RECONNECTING"} }
{ "evt": "connection.changed", "status": "OK", "data": {"type": "RECONNECTED"} }

Handling Errors ​

If an event contains a status of ERROR rather than OK, there will be an additional property in the event data error, which provides a reason for the error, which can help in troubleshooting.

For example, the following error occurs if you try to initialize secure IVR as an agent without having the "Can Conference With Campaign" agent permission.

json
{ "evt": "secureivr.started", "status": "ERROR", "data": { "error": "Failed trying to conference with campaign" } }
{ "evt": "secureivr.started", "status": "ERROR", "data": { "error": "Failed trying to conference with campaign" } }

You may choose to show the error to the user through a toast or banner.

As long as you are managing the UI state based on those two events, you should not have to explicitly add an additional disablement of buttons when receiving an "ERROR" status event, since the secureivr.ready and secureivr.not_ready should still fire properly after an error.