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:

Log into Contact Center (CC) Configuration Manager.
On the menu, pane go to Integration > API Token
If no tokens are present, click the New Token box next to the Data Request Token field.

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:

Click the Subscribe button.

The authentication window displays:

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 Type	callState ID	Definition
`AgentStatusChange`	`NA`¹	Indicates the current status of the monitored agent.
`AgentProvChange`	`NA`	Indicates a change to the agent profile. For example; display name change, etc.
`InteractionCreated`	`CS_IDLE, CS_QUEUED`	Indicates 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.
`InteractionDeleted`	`CS_DISCONNECTED`	Indicates 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/Unhold`	`CS_HOLD /CS_CONNECTED`	Indicates the playing of music on hold (MOH) for an ongoing phone call.
`InteractionQueued`	`CS_QUEUED`	Indicates an incoming phone call. The newly created inbound phone call has been queued and is waiting to be assigned to an agent.
`InteractionAssigned`	`CS_IDLE`	This means an outbound or an inbound call has been assigned to an available agent.
`InteractionRecordingStarted`	`NA`	Indicates that the system has started recording a call leg.
`InteractionAccepted`	`CS_INPROGRESS /CS_CONNECTED`	Indicates 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
`InteractionCustomerAccepted`	`CS_CONNECTED`	Indicates that a ringing outbound phone call has been answered by the destination external participant / customer.
`InteractionPostProcess`	`CS_DISCONNECTED`	Indicates the start of a phone call wrap-up for a call that has concluded.
`InteractionRecordingReady`	`NA`	Indicates that an interaction recording is ready for analysis.
`InteractionEndPostProcess`	`CS_DISCONNECTED`	Indicates the conclusion of a phone call wrap process.
`InteractionDeassigned`	`CS_DISCONNECTED`	Indicates 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.
`InteractionParticipantChange`	`CS_DISCONNECTED`	When two phone lines are joined or when a supervisor joins an ongoing call.

¹ 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

Action	EventType	callState
1. An incoming call from a customer.	`InteractionCreated`	`CS_QUEUED`
2. The call goes into queue and is waiting to be assigned to an agent.	`InteractionQueued`	`CS_QUEUED`
3. The call is assigned to an agent.	`InteractionAssigned`	`CS_QUEUED`
4. The agent accepts the call and speaks with the customer.	`InteractionAccepted`	`CS_CONNECTED`
5. Automatic post processing starts (i.e., the conclusion or wrapping up of a call).	`InteractionPostProcess`	`CS_DISCONNECTED`
6. Automatic post processing concludes.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
7. The customer ends the call.	`InteractionDeassigned`	`CS_DISCONNECTED`
8. The agent ends the call.	`InteractionDeassigned`	`CS_DISCONNECTED`

Outbound call without queue

Action	EventType	callState
1. An incoming call from a customer.	`InteractionCreated`	`CS_IDLE`
2. The call is assigned to an agent.	`InteractionAssigned`	`CS_IDLE`
3. The system has started recording a call leg.	`InteractionRecordingStarted`	`NA`
4. The outbound phone call is in progress and ringing at the destination with an accepted agent waiting for the customer to answer.	`InteractionAccepted`	`CS_INPROGRESS`
5. The outbound phone call has been answered by the destination external participant / customer.	`InteractionCustomerAccepted`	`CS_CONNECTED`
6. The conclusion of the phone call wrap up process.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
7. The phone call has been reassigned from an agent.	`InteractionDeAssigned`	`CS_DISCONNECTED`

Outbound call with queue

Action	EventType	callState
1. An outbound phone call has been created and is a queue.	`InteractionCreated`	`CS_IDLE`
2. The outbound call has been assigned to an available agent.	`InteractionAssigned`	`CS_IDLE`
3. The system has started call leg recording.	`InteractionRecordingStarted`	`NA`
4. The outbound phone call is in progress and ringing at the destination with an accepted agent waiting for the customer to answer.	`InteractionAccepted`	`CS_INPROGRESS`
5. The outbound phone call has been answered by the intended destination external participant / customer.	`InteractionCustomerAccepted`	`CS_CONNECTED`
6. The start of call wrap-up for the concluded phone call.	`InteractionEndPostProcess`	`CS_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.	`InteractionDeAssigned`	`CS_DISCONNECTED`

Outbound conference call (with queue)

Action	EventType	CallState
1. An outbound phone call has been created by an agent and is in the queue.	`InteractionCreated`	`CS_IDLE`
2. The agent’s phone rings.	`InteractionQueued`	`CS_IDLE`
3. The agent picks up the incoming call.	`InteractionAssigned`	`CS_IDLE`
4. The customer’s phone rings.	`InteractionAccepted`	`CS_INPROGRESS`
5. The customer picks up the call.	`InteractionCustomerAccepted`	`CS_CONNECTED`
6. The initial first agent calls a second agent on line 2 (from the agent tab on the line 1 call).	`InteractionCreated`	`CS_IDLE`
7. The second agent’s phone starts ringing.	`InteractionAssigned`	`CS_IDLE`
8. The second agent picks up the call.	`InteractionAccepted`	`CS_INPROGRESS`
9. The second agent is connected on the agent Graphical User Interface (AGUI).	`InteractionAssigned`	`CS_INPROGRESS`
10. The first agent and the second agent are connected on line 2.	`InteractionAccepted`	`CS_CONNECTED`
11. The first agent joins the calls together on line 1.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
12. Line 2 is de-assigned	`InteractionDeassigned`	`CS_DISCONNECTED`
13. All calls are joined together.	`InteractionReconnect`	`CS_DISCONNECTED`
14. All calls are joined together.	`InteractionParticipantChange`	`CS_CONNECTED`
15. Line 2 is deassigned	`InteractionDeassigned`	`CS_DISCONNECTED`
16. The system disconnects line 2¹.	`InteractionDeleted`	`CEC_DISCONNECT_NORMAL`
17. A conference call is created.	InteractionJoinLinesRequest	`NA`
18. The first agent leaves the created conference call.	`InteractionPostProcess`	`CS_DISCONNECTED`
19. All calls are disconnected	**`InteractionParticipantChange	`CS_DISCONNECTED`
20. The conclusion of the phone call wrap up process.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
21. The phone call has been reassigned from an agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
22. The second agent leaves the call	`InteractionPostProcess`	`CS_DISCONNECTED`
23. The conclusion of the phone call wrap up process.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
24. The phone call has been reassigned from an agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
25.² The agent leaves the conference call scenario.	`InteractionDeleted`	`CEC_DISCONNECT_NORMAL`

¹ - hangupInitiator value = SYSTEM
² - hangupInitiator value = AGENT

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

Action	EventType	callState
1. An outbound phone call has been created by the first agent and is subject to queuing.	`InteractionCreated`	`CS_IDLE`
2. The agent’s phone starts ringing.	`InteractionQueued`	`CS_IDLE`
3. The agent picks up the phone call.	`InteractionAssigned`	`CS_IDLE`
4. The customer’s phone starts ringing.	`InteractionAccepted`	`CS_INPROGRESS`
5. The customer picks up the call.	`InteractionCustomerAccepted`	`CS_CONNECTED`
6. The first agent calls another agent on line 2 (from the agent tab on the line 1 call).	`InteractionCreated`	`CS_IDLE`
7. The second agent’s phone starts ringing.	`InteractionAssigned`	`CS_IDLE`
8. The second agent picks up the phone call.	`InteractionAccepted`	`CS_INPROGRESS`
9. The second agent is connected on the AGUI.	`InteractionAssigned`	`CS_INPROGRESS`
10. The first agent and the second agent are connected on line 2.	`InteractionAccepted`	`CS_CONNECTED`
11. The first agent transfers the call to the second agent.	`InteractionTransferRequest`	`NA`
12.The start of call wrap-up for the concluded phone call.	`InteractionPostProcess	`CS_DISCONNECTED`
13. Another agent has joined the ongoing call.	`InteractionParticipantChange`	`CS_CONNECTED`
14. The phone call wrap up process has concluded.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
15. The phone call has been reassigned from the answering agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
16. The start of phone call wrap-up.	`InteractionPostProcess`	`CS_DISCONNECTED`
17. All of the separate calls have been reconnected.	`InteractionReconnect`	`CS_DISCONNECTED`
18. Another agent has joined the ongoing call.	`InteractionParticipantChange`	`CS_DISCONNECTED`
19. The re-assignment of the phone call from an available agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
20. The phone interaction has been deleted.	`InteractionDeleted`	`CS_DISCONNECTED`
21. The customer ends the call with the second agent.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
22. The phone call has been reassigned from an available agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
23. The phone calls are joined in the ongoing call.	`InteractionParticipantChange`	`CS_DISCONNECTED`
24. The start of phone call wrap-up for the concluded call.	`InteractionPostProcess	`CS_DISCONNECTED`
25. The reassigning of a phone call from an available agent.	`InteractionDeassigned`	`CS_DISCONNECTED`
26. The phone call has concluded.	`InteractionDeleted`	`CUSTOMER`

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

Transfer of a call to an inbound queue

Action	EventType	callState
1. An outbound phone call has been created by the first agent and is subject to queuing.	`InteractionCreated`	`CS_IDLE`
2. The agent’s phone starts ringing.	`InteractionQueued`	`CS_IDLE`
3. The agent picks up the phone call.	`InteractionAssigned`	`CS_IDLE`
4. The customer’s phone starts ringing.	`InteractionAccepted`	`CS_INPROGRESS`
5. The customer picks up the call.	`InteractionCustomerAccepted`	`CS_CONNECTED`
6. The agent transfers the call to an inbound queue.	`InteractionPostProcess	`CS_DISCONNECTED`
7. A new interaction is created.	`InteractionCreated`	`CS_IDLE`
8. The customer is queuing in the Inbound queue.	`InteractionQueued`	`CS_IDLE`
9. The agent call on line 1 has concluded.	`InteractionEndPostProcess`	`CS_DISCONNECTED`
10. The call has been deassigned.	`InteractionDeassigned`	`CS_DISCONNECTED`
11¹.The phone call has concluded.	`InteractionDeleted`	`CS_DISCONNECTED`

¹ - hangupInitiator value = AGENT