Streaming API

Overview

The 8x8 Streaming API (SAPI) enables you to receive streaming event update information via your 8x8 Analytics for Contact Center tenant. You can receive notifications for both agent status and provisioning as well as interactions that occur within your enterprise.

SAPI provides data for real-time events via server push notifications. It uses a Websocket protocol-based event stream and does not use HTTP. Therefore, in order to communicate via WebSocket protocol, you need to create a WebSocket object to open a connection to the server.

The SAPI client

You can receive SAPI event notifications by installing and using the SAPI client. The SAPI client downloadable .zip package utility is available from your 8x8 representative

The SAPI client is a Java-based command-line utility that facilitates connection to the SAPI endpoint. You can use the SAPI client rather than developing your own client to consume SAPI events.

Note: SAPI Status codes are displayed as numbers that correspond to the manually selected status code. Agent status codes do not come up with the same status ID number in SAPI if you have more than one status code list. For example, the status code for when one agent is on lunch break may be represented as a different lunch break status code in another different list on the same tenant.

Authentication

In order to subscribe to SAPI events, you must first obtain an authentication token that has been issued for your tenant. This token is a single string that combines your username and password.

To either obtain an existing or generate a new authentication token:

  1. Log into Contact Center (CC) Configuration Manager.
  2. On the menu, pane go to Integration > API Token
  3. If no tokens are present, click the New Token box next to the Data Request Token field.
  1. Copy the generated Data Request Token to your clipboard for authentication use.

Note: The generated authentication token for your tenant can be used for your SAPI as well as other 8x8 API requests. It does not expire nor have a time limit unless you decide to change it. If you already have a token and you click on the New Token button, your existing authentication token becomes invalid. You should save a copy in a safe storage location for future reference.

Subscribing to events

In the SAPI web client, the SAPI query URL in the browser field is constructed as follows:

https://vcc-(login_tenant_URL).8x8.com/api/streaming/v1/TenantUpdates.jsp

Revise your query URL based on the login URL of your Tenant. (Refer to the Platform URL Guide to retrieve your login URL)

To access your tenant:

  1. Click the Subscribe button.

    The authentication window displays:

  1. Enter your tenant User Name and your Authentication Token in the Password field and click OK.

Following successful connection with the Tenant, the Tenant Updates screen displays:

The displayed Tenant Updates screen consists of the following information fields:

  • Subscription ID - the unique ID for the SAPI connection from the Tenant. Each tenant manages its own subscription ID. Since the SAPI stores messages for a certain period of time (even if the client is disconnected), using the same, consistently named subscription ID is important in order to receive stored messages.
  • Tenant ID - your 8x8 Tenant ID.
  • Desired Output Type - can be in either XML or JSON formats.
  • Subscribe - initiates a subscription to events for the next 60 minutes.
  • Unsubscribe - disconnects the client from the SAPI server and starts storing messages for possible reconnection.

Important

Please review the following details before you begin using SAPI:

  • Only three SAPI clients per tenant can listen for a given time.
  • The subscription ID should be unique for every connection.
  • A subscription session is valid for only sixty minutes. Therefore, if the connection times out, you will need to reconnect. No data is lost if reconnection occurs within two hours. Messages are stored and sent when the connection is restored.
  • A two-hour history of events is available if the previously used subscription ID is used for the connection.
  • If a subscription has been disconnected for more than two hours, it is automatically unsubscribed. No more messages are stored after unsubscribing.

Event types

The following table lists the SAPI Event Type with the corresponding Call State ID and definition:

Event TypecallState IDDefinition
AgentStatusChangeNA1Indicates the current status of the monitored agent.
AgentProvChangeNAIndicates a change to the agent profile. For example; display name change, etc.
InteractionCreatedCS_IDLE, CS_QUEUEDIndicates that a new outbound or inbound phone call has been created. Note that if it is an outbound type, it will be subject to queuing if part of a campaign prior to dialing.
InteractionDeletedCS_DISCONNECTEDIndicates a phone call hangup or a single call leg when leaving a conference scenario.
Also includes the following enums:

hangupInitiator-

SYSTEM
AGENT
CUSTOMER

callHangupReason-

CEC_NONE
CEC_DISCONNECT_NORMAL
CEC_DISCONNECT_BUSY
CEC_DISCONNECT_BADADDRESS
CEC_DISCONNECT_NOANSWER
CEC_DISCONNECT_CANCELLED
CEC_DISCONNECT_REJECTED
CEC_DISCONNECT_FAILED
CEC_DISCONNECT_BLOCKED
Interaction Hold/UnholdCS_HOLD /CS_CONNECTEDIndicates the playing of music on hold (MOH) for an ongoing phone call.
InteractionQueuedCS_QUEUEDIndicates an incoming phone call. The newly created inbound phone call has been queued and is waiting to be assigned to an agent.
InteractionAssignedCS_IDLEThis means an outbound or an inbound call has been assigned to an available agent.
InteractionRecordingStartedNAIndicates that the system has started recording a call leg.
InteractionAcceptedCS_INPROGRESS /CS_CONNECTEDIndicates an outbound phone call is in progress and ringing at the destination with an accepted agent waiting for the customer to answer. If inbound, this means the queued phone call has been accepted by an agent
InteractionCustomerAcceptedCS_CONNECTEDIndicates that a ringing outbound phone call has been answered by the destination external participant / customer.
InteractionPostProcessCS_DISCONNECTEDIndicates the start of a phone call wrap-up for a call that has concluded.
InteractionRecordingReadyNAIndicates that an interaction recording is ready for analysis.
InteractionEndPostProcessCS_DISCONNECTEDIndicates the conclusion of a phone call wrap process.
InteractionDeassignedCS_DISCONNECTEDIndicates the reassigning of a phone call from an available agent. This can occur if the agent has not accepted the offered phone call on preview mode and then the call times out.
InteractionParticipantChangeCS_DISCONNECTEDWhen two phone lines are joined or when a supervisor joins an ongoing call.

1 callState is not added to any event types indicated by NA.

Examples

This section describes example call flow scenarios with the EventTypes and callStates that are encountered.

Inbound call

ActionEventTypecallState
1. An incoming call from a customer.InteractionCreatedCS_QUEUED
2. The call goes into queue and is waiting to be assigned to an agent.InteractionQueuedCS_QUEUED
3. The call is assigned to an agent.InteractionAssignedCS_QUEUED
4. The agent accepts the call and speaks with the customer.InteractionAcceptedCS_CONNECTED
5. Automatic post processing starts (i.e., the conclusion or wrapping up of a call).InteractionPostProcessCS_DISCONNECTED
6. Automatic post processing concludes.InteractionEndPostProcessCS_DISCONNECTED
7. The customer ends the call.InteractionDeassignedCS_DISCONNECTED
8. The agent ends the call.InteractionDeassignedCS_DISCONNECTED

Outbound call without queue

ActionEventTypecallState
1. An incoming call from a customer.InteractionCreatedCS_IDLE
2. The call is assigned to an agent.InteractionAssignedCS_IDLE
3. The system has started recording a call leg.InteractionRecordingStartedNA
4. The outbound phone call is in progress and ringing at the destination with an accepted agent waiting for the customer to answer.InteractionAcceptedCS_INPROGRESS
5. The outbound phone call has been answered by the destination external participant / customer.InteractionCustomerAcceptedCS_CONNECTED
6. The conclusion of the phone call wrap up process.InteractionEndPostProcessCS_DISCONNECTED
7. The phone call has been reassigned from an agent.InteractionDeAssignedCS_DISCONNECTED

Outbound call with queue

ActionEventTypecallState
1. An outbound phone call has been created and is a queue.InteractionCreatedCS_IDLE
2. The outbound call has been assigned to an available agent.InteractionAssignedCS_IDLE
3. The system has started call leg recording.InteractionRecordingStartedNA
4. The outbound phone call is in progress and ringing at the destination with an accepted agent waiting for the customer to answer.InteractionAcceptedCS_INPROGRESS
5. The outbound phone call has been answered by the intended destination external participant / customer.InteractionCustomerAcceptedCS_CONNECTED
6. The start of call wrap-up for the concluded phone call.InteractionEndPostProcessCS_DISCONNECTED
7. The phone call has been reassigned from an available agent. This can occur if the agent has not accepted the offered phone call on preview mode and then the call times out.InteractionDeAssignedCS_DISCONNECTED

Outbound conference call (with queue)

ActionEventTypeCallState
1. An outbound phone call has been created by an agent and is in the queue.InteractionCreatedCS_IDLE
2. The agent’s phone rings.InteractionQueuedCS_IDLE
3. The agent picks up the incoming call.InteractionAssignedCS_IDLE
4. The customer’s phone rings.InteractionAcceptedCS_INPROGRESS
5. The customer picks up the call.InteractionCustomerAcceptedCS_CONNECTED
6. The initial first agent calls a second agent on line 2 (from the agent tab on the line 1 call).InteractionCreatedCS_IDLE
7. The second agent’s phone starts ringing.InteractionAssignedCS_IDLE
8. The second agent picks up the call.InteractionAcceptedCS_INPROGRESS
9. The second agent is connected on the agent Graphical User Interface (AGUI).InteractionAssignedCS_INPROGRESS
10. The first agent and the second agent are connected on line 2.InteractionAcceptedCS_CONNECTED
11. The first agent joins the calls together on line 1.InteractionEndPostProcessCS_DISCONNECTED
12. Line 2 is de-assignedInteractionDeassignedCS_DISCONNECTED
13. All calls are joined together.InteractionReconnectCS_DISCONNECTED
14. All calls are joined together.InteractionParticipantChangeCS_CONNECTED
15. Line 2 is deassignedInteractionDeassignedCS_DISCONNECTED
16. The system disconnects line 21.InteractionDeletedCEC_DISCONNECT_NORMAL
17. A conference call is created.InteractionJoinLinesRequestNA
18. The first agent leaves the created conference call.InteractionPostProcessCS_DISCONNECTED
19. All calls are disconnected**`InteractionParticipantChangeCS_DISCONNECTED
20. The conclusion of the phone call wrap up process.InteractionEndPostProcessCS_DISCONNECTED
21. The phone call has been reassigned from an agent.InteractionDeassignedCS_DISCONNECTED
22. The second agent leaves the callInteractionPostProcessCS_DISCONNECTED
23. The conclusion of the phone call wrap up process.InteractionEndPostProcessCS_DISCONNECTED
24. The phone call has been reassigned from an agent.InteractionDeassignedCS_DISCONNECTED
25.2 The agent leaves the conference call scenario.InteractionDeletedCEC_DISCONNECT_NORMAL

1 - hangupInitiator value = SYSTEM
2 - hangupInitiator value = AGENT

Transfer of call to another agent (inbound or outbound call)

ActionEventTypecallState
1. An outbound phone call has been created by the first agent and is subject to queuing.InteractionCreatedCS_IDLE
2. The agent’s phone starts ringing.InteractionQueuedCS_IDLE
3. The agent picks up the phone call.InteractionAssignedCS_IDLE
4. The customer’s phone starts ringing.InteractionAcceptedCS_INPROGRESS
5. The customer picks up the call.InteractionCustomerAcceptedCS_CONNECTED
6. The first agent calls another agent on line 2 (from the agent tab on the line 1 call).InteractionCreatedCS_IDLE
7. The second agent’s phone starts ringing.InteractionAssignedCS_IDLE
8. The second agent picks up the phone call.InteractionAcceptedCS_INPROGRESS
9. The second agent is connected on the AGUI.InteractionAssignedCS_INPROGRESS
10. The first agent and the second agent are connected on line 2.InteractionAcceptedCS_CONNECTED
11. The first agent transfers the call to the second agent.InteractionTransferRequestNA
12.The start of call wrap-up for the concluded phone call.`InteractionPostProcessCS_DISCONNECTED
13. Another agent has joined the ongoing call.InteractionParticipantChangeCS_CONNECTED
14. The phone call wrap up process has concluded.InteractionEndPostProcessCS_DISCONNECTED
15. The phone call has been reassigned from the answering agent.InteractionDeassignedCS_DISCONNECTED
16. The start of phone call wrap-up.InteractionPostProcessCS_DISCONNECTED
17. All of the separate calls have been reconnected.InteractionReconnectCS_DISCONNECTED
18. Another agent has joined the ongoing call.InteractionParticipantChangeCS_DISCONNECTED
19. The re-assignment of the phone call from an available agent.InteractionDeassignedCS_DISCONNECTED
20. The phone interaction has been deleted.InteractionDeletedCS_DISCONNECTED
21. The customer ends the call with the second agent.InteractionEndPostProcessCS_DISCONNECTED
22. The phone call has been reassigned from an available agent.InteractionDeassignedCS_DISCONNECTED
23. The phone calls are joined in the ongoing call.InteractionParticipantChangeCS_DISCONNECTED
24. The start of phone call wrap-up for the concluded call.`InteractionPostProcessCS_DISCONNECTED
25. The reassigning of a phone call from an available agent.InteractionDeassignedCS_DISCONNECTED
26. The phone call has concluded.InteractionDeletedCUSTOMER

1 - hangupInitiator value = AGENT
2 - hangupInitiator value = CUSTOMER

Transfer of a call to an inbound queue

ActionEventTypecallState
1. An outbound phone call has been created by the first agent and is subject to queuing.InteractionCreatedCS_IDLE
2. The agent’s phone starts ringing.InteractionQueuedCS_IDLE
3. The agent picks up the phone call.InteractionAssignedCS_IDLE
4. The customer’s phone starts ringing.InteractionAcceptedCS_INPROGRESS
5. The customer picks up the call.InteractionCustomerAcceptedCS_CONNECTED
6. The agent transfers the call to an inbound queue.`InteractionPostProcessCS_DISCONNECTED
7. A new interaction is created.InteractionCreatedCS_IDLE
8. The customer is queuing in the Inbound queue.InteractionQueuedCS_IDLE
9. The agent call on line 1 has concluded.InteractionEndPostProcessCS_DISCONNECTED
10. The call has been deassigned.InteractionDeassignedCS_DISCONNECTED
111.The phone call has concluded.InteractionDeletedCS_DISCONNECTED

1 - hangupInitiator value = AGENT


Did this page help you?