Real Time Statistics Reporting API (7.1.0.20v)

Overview

The 8x8 real time statistics reporting API is composed of a set of URIs that identify and request real time statistical data from the 8x8 system. This style of API makes it very easy to compose and send a query, which is always done using an HTTP GET request.

The API provides real time data about agents and queues. It allows queries on all agents and queues or particular agent and queue with provided ID.

The data returned by the API is from a server cache that is refreshed every 10 seconds.

All API requests are authenticated using a token that is issued to a valid 8x8 tenant. The API supports XML and JSON as the response formats.

For security reasons, the Real Time Statistics API only accepts request using HTTPS, so that request headers and response data are encrypted.

Testing Using A Browser

The Statistics API makes it easy to submit a query, for experimentation, testing or debugging purposes. From a web browser, simply enter the URL. You will be prompted to enter a username and password. Enter your tenant name as the username, and your authentication token as the password. Then, the query result will be displayed in your browser. For example,

  https://mycontactual.com/api/rtstats/stats/agents

will return information about all agents in XML format.

Revise your query URL based on the login URL of your tenant:

https://na1.mycontactual.com/api/rtstats/stats
https://na2.mycontactual.com/api/rtstats/stats
https://na3.mycontactual.com/api/rtstats/stats
https://na4.mycontactual.com/api/rtstats/stats
https://vcc-na7.8x8.com/api/rtstats/stats
For tenants in Cananda: https://www.mycontactual.ca/api/rtstats/stats
For tenants in UK: https://www.mycontactual.co.uk/api/rtstats/stats

Testing Using curl

In a Linux environment, the curl utility will submit an HTTP request, and allow you to view the result.

  curl -u acme:ac12343934687a839cf https://mycontactual.com/api/rtstats/stats/agent/jdoe.json

will return the data of agent with login id jdoe, in JSON format. The -u argument identifies the username and password; use your tenant name as the username, and your authentication token as the password.

Agents

List all agents

  /agents

Returns a list of details for all agents.

Show a named agent

  /agent/{agent-id}

Shows details of a single agent. The agent id is the login id of desired agent.

<agents>
    <agent>
        <agent-id>ag1</agent-id>
        <agent-media-id>1</agent-media-id>
        <agent-name>John Doe</agent-name>
        <agent-status>1</agent-status>
        <assigned-skill-count>4</assigned-skill-count>
        <day-accepted-count>0</day-accepted-count>
        <day-available-time>0</day-available-time>
        <day-avg-processing-time>0</day-avg-handling-time>
        <day-break-time>0</day-break-time>
        <day-login-time>0</day-login-time>
        <day-offline-time>0</day-offline-time>
        <day-processing-time>0</day-processing-time>
        <day-rejected-count>1</day-offered-count>
        <day-wrap-up-time>0</day-wrap-up-time>
        <enabled-skill-count>4</enabled-skill-count>
        <group-id>101</group-id>
        <last-login-time>-1</last-login-time>
        <phone-line1-status>0</phone-line1-status>
        <phone-line1-status-time>-1</phone-line1-status-time>
        <phone-line2-status>0</phone-line2-status>
        <phone-line2-status-time>-1</phone-line2-status-time>
        <status-code-item-id/>
        <status-code-item-short-code/>
        <status-code-list-id/>
        <thirty-min-accepted-count>0</thirty-min-accepted-count>
        <thirty-min-available-time>0</thirty-min-available-time>
        <thirty-min-avg-handling-time>0</thirty-min-avg-handling-time>
        <thirty-min-break-time>0</thirty-min-break-time>
        <thirty-min-offline-time>0</thirty-min-offline-time>
        <thirty-min-processing-time>0</thirty-min-processing-time>
        <thirty-min-rejected-count>0</thirty-min-rejected-count>
        <thirty-min-wrap-up-time>0</thirty-min-wrap-up-time>
        <time-in-status>-1</time-in-status>
    </agent>
    <agent>
        <agent-id>clee</agent-id>
        <agent-media-id>2</agent-media-id>
        <agent-name>Cecilia Lee</agent-name>
        <agent-status>1</agent-status>
        <assigned-skill-count>4</assigned-skill-count>
        <day-accepted-count>0</day-accepted-count>
        <day-available-time>0</day-available-time>
        <day-avg-handling-time>0</day-avg-handling-time>
        <day-break-time>0</day-break-time>
        <day-login-time>0</day-login-time>
        <day-offline-time>0</day-offline-time>
        <day-processing-time>0</day-processing-time>
        <day-rejected-count>0</day-offered-count>
        <day-wrap-up-time>0</day-wrap-up-time>
        <enabled-skill-count>4</enabled-skill-count>
        <group-id>101</group-id>
        <last-login-time>1323826680</last-login-time>
        <phone-line1-status>5</phone-line1-status>
        <phone-line1-status-time>102</phone-line1-status-time>
        <phone-line2-status>0</phone-line2-status>
        <phone-line2-status-time>-1</phone-line2-status-time>
        <status-code-item-id/>
        <status-code-item-short-code/>
        <status-code-list-id/>
        <thirty-min-accepted-count>0</thirty-min-accepted-count>
        <thirty-min-available-time>0</thirty-min-available-time>
        <thirty-min-avg-handling-time>0</thirty-min-avg-handling-time>
        <thirty-min-break-time>0</thirty-min-break-time>
        <thirty-min-offline-time>0</thirty-min-offline-time>
        <thirty-min-processing-time>0</thirty-min-processing-time>
        <thirty-min-rejected-count>0</thirty-min-rejected-count>
        <thirty-min-wrap-up-time>0</thirty-min-wrap-up-time>
        <time-in-status>-1</time-in-status>
    </agent>
    <agent>
      ... 
    </agent>
    </agents>
</groups>

Queues

List all queues

  /queues

Returns a list of details of all queues.

Show a named queue

  /queue/{queue-id}

Shows details of a single queue. The queue id is the id of a queue. The queue id can be retrieved by going to the queues tab in the configuration manager.

<queues>
<queue> <agent-count-busy>3</agent-count-busy> <agent-count-loggedOut>2</agent-count-loggedOut> <agent-count-onBreak>2</agent-count-onBreak> <agent-count-postProcess>1</agent-count-postProcess> <agent-count-waitTransact>0</agent-count-waitTransact> <agent-count-workOffline>0</agent-count-workOffline> <day-abandoned>2</day-abandoned> <day-accepted>10</all-day-accepted> <day-avg-duration>134</all-day-avg-duration> <day-avg-wait-time>566</all-day-avg-wait-time> <day-queued>30</all-day-queued> <day-sla-activity>-1</all-day-sla-activity> <assigned-agent-count>9</assigned-agent-count> <enabled-agent-count>8</enabled-agent-count> <longest-wait-time>1113</longest-wait-time> <media-type>phone</media-type> <number-in-offered>1</number-in-offered> <number-in-progress>2</number-in-progress> <queue-id>115</queue-id> <queue-name>outbound queue</queue-name> <queue-size>4</queue-size> <sla-activity>0</sla-activity> <sla-target>0</sla-target> <thirty-min-abandoned>0</thirty-min-abandoned> <thirty-min-accepted>4</thirty-min-accepted> <thirty-min-avg-duration>34</thirty-min-avg-duration> <thirty-min-avg-wait-time>110</thirty-min-avg-wait-time> <thirty-min-longest-wait-time>340</thirty-min-longest-wait-time> <thirty-min-queued>24</thirty-min-queued> <thirty-min-sla-activity>-1</thirty-min-sla-activity> </queue>
    <queue> <agent-count-busy>1</agent-count-busy> <agent-count-loggedOut>1</agent-count-loggedOut> <agent-count-onBreak>0</agent-count-onBreak> <agent-count-postProcess>1</agent-count-postProcess> <agent-count-waitTransact>2</agent-count-waitTransact> <agent-count-workOffline>2</agent-count-workOffline> <day-abandoned>1</day-abandoned> <all-day-accepted>0</all-day-accepted> <all-day-avg-duration>0</all-day-avg-duration> <all-day-avg-wait-time>0</all-day-avg-wait-time> <all-day-queued>0</all-day-queued> <all-day-sla-activity>-1</all-day-sla-activity> <assigned-agent-count>1</assigned-agent-count> <enabled-agent-count>1</enabled-agent-count> <longest-wait-time>0</longest-wait-time> <media-type>chat</media-type> <number-in-offered>1</number-in-offered> <number-in-progress>0</number-in-progress> <queue-id>111</queue-id> <queue-name>sales-chat</queue-name> <queue-size>1</queue-size> <sla-activity>0</sla-activity> <sla-target>0</sla-target> <thirty-min-abandoned>1</thirty-min-abandoned> <thirty-min-accepted>0</thirty-min-accepted> <thirty-min-avg-duration>0</thirty-min-avg-duration> <thirty-min-avg-wait-time>0</thirty-min-avg-wait-time> <thirty-min-longest-wait-time>-1</thirty-min-longest-wait-time> <thirty-min-queued>0</thirty-min-queued> <thirty-min-sla-activity>-1</thirty-min-sla-activity> </queue>
    <queue> … </queue>
</queues>

Authentication

In order to make an API request, you must first obtain an authentication token that has been issued for your tenant. This token combines username and password into a single long string. To get your token, log into the Configuration Manager, select “Integration”, and click the “API Token” tab. Next, click the “New Token” button next to “Data Request Token”. This generates a new private token for your tenant. You will use this token in all requests to the Statistics API. You may generate a new token at any time.

Responses

Each resource returned in XML or JSON format. To specify, add “.xml” or “.json” to the URL:

  https://mycontactual.com/api/rtstats/stats/agent/ag1.json

The default response format is XML.

The following table describes the meaning of each of the fields in the response type.

Agent

Field Name Description Remarks
agent-id Agent login ID
agent-name Agent full name (Firstname Lastname)
agent-status Agent current status (in status code) 0: available1: transaction offered

2: busy

3: post processing

4: on break

5: work offline

9: logged out

agent-media-id The media type ID of the transaction this agent last processed or currently processing. 0: no media since system start1: Phone

2: Chat

3: Email

4: Voice Mail

assigned-skill-count Total number of skill assigned to this agent
day-accepted-count Total accepted transaction count from beginning of the day
day-available-time Total available time from beginning of the day Data is in seconds
day-avg-processing-time Average transaction processing time from beginning of the day Data is in seconds
day-break-time Total break time from beginning of the day Data is in seconds
day-login-time Total login time from beginning of the day Data is in seconds
day-rejected-count Total rejected transaction count from beginning of the day
day-offline-time Total time of working offline from beginning of the day Data is in seconds
day-processing-time Total transaction processing time from beginning of the day Data is in seconds
day-wrap-up-time Total transaction wrap up time from beginning of the day Data is in seconds
enabled-skill-count Total number of skill enabled to this agent
group-id Group ID of the group this agent belong to
last-login-time Last login time stamp in UTC seconds. Value -1 means system has been restarted and no previous record of the data yet.
phone-line1-status Current status of phone line 1 Supported status code are:-1: not use

0: idle or at post-processing

1: on hold

2: on mute

3: being offered with transaction

4: monitoring

5: busy

phone-line1-status-time Status time of the current status of phone line 1 Data is in seconds
phone-line2-status Current status of phone line 2 Supported status code are:-1: not use

0: being offered with transaction

1: on hold

2: on mute

3: error

4: monitoring

5: busy

phone-line2-status-time Status time of the current status of phone line 2 Data is in seconds
status-code-item-id Code ID of current status code of this agent
status-code-item-short-code Short code of current status code of this agent
status-code-list-id Code List ID of the current status code of this agent
thirty-min-accepted-count Total accepted transaction count in last 30 minutes
thirty-min-available-time Average available time in last 30 minutes Data is in seconds
thirty-min-avg-handling-time Average transaction handling time in last 30 minutes Data is in seconds
thirty-min-break-time Total break time in last 30 minutes Data is in seconds
thirty-min-offline-time Total time of working offline in last 30 minutes Data is in seconds
thirty-min-processing-time Total transaction processing time in last 30 minutes Data is in seconds
thirty-min-rejected-count Total number of transaction rejected by this agent in last 30 minutes
thirty-min-wrap-up-time Total transaction wrap up time in last 30 minutes Data is in seconds
time-in-status Total time in current status Data is in seconds

Queue

Field Name Description Remarks
agent-count-busy Agents busy on interactions from this queue and other queues. Busy state includes agents, who are being offered with a transaction.
agent-count-loggedOut Agents enabled for this queue, who are logged out.
agent-count-onBreak Agents enabled for this queue, who are on break.
agent-count-postProcess Agents post processing interactions from this queue and other queues.
agent-count-waitTransact Agents available to take interactions from this queue.
agent-count-workOffline Agents enabled for this queue, who are working offline.
day-accepted Total number of accepted transaction from beginning of the day
day-avg-duration Average duration among all accepted transaction from beginning of the day Data is in seconds
day-avg-wait-time Average wait time among all queued transaction from beginning of the day Data is in seconds
day-queued Total number of queued transaction from beginning of the day
day-sla-activity SLA activity from beginning of the day In Percent
assigned-agent-count Current number of assigned agents to this queue
enabled-agent-count Number of agents currently enabled in this queue. Includes agents enabled by the administrator as well as enabled in the Agent Profile.
longest-wait-time Duration (sec) of the longest waiting interaction in this queue.
media-type Queue type of this queue Possible data are: phone, chat, vmail, email
number-in-offered Interactions from this queue in the state of alerting agents.
number-in-progress Agents busy on interactions from this queue. The statistics include agents in processing and post processing states.
queue-id Queue ID of this queue This is the queue ID displayed on CM queues tab.
queue-name Queue Name of this queue
queue-size Number of interactions waiting in the queue. Does it include transaction in progress?
sla-activity Current SLA activity In percent
sla-target Target hours for raising SLA This is the configuration from SLA tab of this queue.
thirty-min-accepted Total number of accepted transactions in last 30 minutes
thirty-min-avg-duration Average duration of accepted transactions in last 30 minutes Data is in seconds
thirty-min-avg-wait-time Average wait time of the queued transactions in last 30 minutes Data is in seconds
thirty-min-longest-wait-time Longest wait time among the queued transaction in last 30 minutes Data is in seconds
thirty-min-queued Total number of queued transactions in last 30 minutes
thirty-min-sla-activity SLA activity in last 30 minutes In percent. Value -1 means no SLA activity available.

Response Codes

200 OK Request was successful
400 Bad request The syntax of the request was wrong
403 Forbidden The request was not allowed, usually due to incorrect authentication
404 Not found The requested resource was not found
500 Internal error The server encountered an unexpected condition which prevented it from fulfilling the request
503 Server busy The server is currently unable to handle the request due to temporary overloading