Overview

The 8x8 Streaming API (SAPI) features a set of functionalities to allow Virtual Contact Center tenants to receive information related to Agent status updates, Agent provisioning updates, and Interaction updates. These updates are referred to as events. Any Async HTTP client can be used to receive SAPI events.

The primary purpose of this SAPI is to provide data on real time events. Data is published to all clients through a server push mechanism. To learn more about this mechanism, see this article on Server push.


Subscribing to Events

The best way to understand and test the features of the 8x8 SAPI is to use a web client. The web client is easy to use. In a browser on the same network as your tenant, enter the link provided below.

https://vcc-naX.8x8.com/api/sapi/TenantUpdates.jsp

This link will open a page with some input fields.
tenant updates

Purpose of the Fields

  1. Subscription id is the unique id for identifying the SAPI connection from the tenant. Each tenant should manage its own subscription id. Since the SAPI stores messages for a certain period of time even if the client is disconnected, using same subscription id is important in order to receive stored messages.
  2. Tenant id is the tenant id provided by 8x8.
  3. Desired Output type. This can be either XML or JSON.
  4. Subscribe will initiate a subscription to events over the next 60 minutes.
  5. Unsubscribe will disconnect the client from the SAPI server and start storing messages for reconnection.

Agent Status Updates

This configuration returns information from agents about real time agent status changes.

<?xml version='1.0'  encoding='UTF-8' ?>
<AgentStatusChange>
    <agentId>marcus</agentId>
    <newState>2</newState>
    <statusEventTS>1381563857</statusEventTS>
</AgentStatusChange>

Agent Provisioning Updates

This configuration returns information from agents about real time provisioning changes.

<?xml version='1.0'  encoding='UTF-8' ?>
<AgentProvChange>
    <agentId>122</agentId>
    <numberofChangesThisTime>1</numberofChangesThisTime>
    <provisioningItems>
      <provisioningItem>
        <provisioningItemKey>phoneUri</provisioningItemKey>
        <provisioningItemNewValue>+17034443909</provisioningItemOldValue>
        <provisioningItemOldValue>17034443910</provisioningItemOldValue>
     </provisioningItem>
    </provisioningItems>
      ... 
    </provisioningItem>
</AgentProvChange>

Interaction Updates

This configuration returns information from agents about real time interactions.

<?xml version='1.0'  encoding='UTF-8' ?>
<Interaction>
    <direction>in</direction>
    <eventTS>1381573170</eventTS>
    <inboundChannelid>4070001</inboundChannelid>
    <interactionGUID>int-dev6ctl-09c05006-0f19-44cf-9410-c55fe515d76c-phone-00iQ1DcskDJEumYROhxeq3gvYeY
</interactionGUID>
    <mediaType>phone</mediaType>
    <outboundCampaignid>0</outboundCampaignid>
    <queueId>dev6ctl~~queue~~phone~~102</queueId>
    <queueTime>1381573170</queueTime>
    <transactionNum>1</transactionNum>
    <attachedData>
      <attachedDatum>
        <attachedDataKey>tenantSkillName</attachedDataKey>
        <attachedDataValue>Sales</attachedDataValue>
     </attachedDatum>
    </attachedDatum>
      ... 
    </attachedDatum>
</Interaction>

Authentication

In order to make a SAPI request, you must first obtain the authentication token that has been issued for your tenant. This token combines username and password into a single string. You will use this token in all requests to the SAPI. You may generate a new token at any time.

To generate the Authentication Token

  1. Log into the SAPI Configuration Manager.
  2. Select Integration.
  3. Click API Token.
  4. Click New Token next to Data Request Token. This generates a new private token for your tenant. The image below shows the authentication window.
    authentication window

Important Notes

Some things to keep in mind when using the 8x8 SAPI:

  1. Only three clients per tenant are allowed to listen at a given time.
  2. The subscription id should be unique for every connection.
  3. A subscription session is valid for only 60 minutes. That is, if the connection times out, you will need to reconnect. However, no data is lost if reconnection occurs within two hours, since messages are stored and sent when the connection is restored.
  4. A two-hour history of events is provided, if the client connects with the previously used subscription id.
  5. Desired output can be either XML or JSON.
  6. If a subscription has been disconnected for more than two hours, it will be automatically unsubscribed. No more messages will be stored after unsubscribing.

To download the 8x8 SAPI client, click here.