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://vcc-na4.8x8.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. (Refer to the Platform URL Guide to retrieve your login URL.)
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://vcc-na4.8x8.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.
<agent>
<active-customer-chat-count>-1</active-customer-chat-count>
<agent-guid>
detestacct801-ag3276621-cb1f16ae-d5a8-4658-a467-e1d9c3b8467f
</agent-guid>
<agent-id>ag3276621</agent-id>
<agent-media-id>0</agent-media-id>
<agent-name>Marie Sanders</agent-name>
<agent-status>9</agent-status>
<agent-sub-status>none</agent-sub-status>
<assigned-skill-count>3</assigned-skill-count>
<day-accepted-count>0</day-accepted-count>
<day-available-time>0</day-available-time>
<day-avg-processing-time>0</day-avg-processing-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-rejected-count>
<day-wrap-up-time>0</day-wrap-up-time>
<enabled-skill-count>3</enabled-skill-count>
<group-id>108</group-id>
<idle-start-time>-1</idle-start-time>
<last-login-time>-1</last-login-time>
<longest-active-customer-chat-duration>-1</longest-active-customer-chat-duration>
<max-concurrent-customer-chat>1</max-concurrent-customer-chat>
<phone-line1-status>-1</phone-line1-status>
<phone-line1-status-time>0</phone-line1-status-time>
<phone-line2-status>-1</phone-line2-status>
<phone-line2-status-time>0</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>206526</time-in-status>
</agent>
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.
<queue>
<agent-count-busy>0</agent-count-busy>
<agent-count-loggedOut>1</agent-count-loggedOut>
<agent-count-onBreak>0</agent-count-onBreak>
<agent-count-postProcess>0</agent-count-postProcess>
<agent-count-waitTransact>0</agent-count-waitTransact>
<agent-count-workOffline>0</agent-count-workOffline>
<day-abandoned>0</day-abandoned>
<day-accepted>0</day-accepted>
<day-avg-duration>0</day-avg-duration>
<day-avg-wait-time>0</day-avg-wait-time>
<day-queued>0</day-queued>
<day-sla-activity>0</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>vmail</media-type>
<number-in-offered>0</number-in-offered>
<number-in-progress>0</number-in-progress>
<queue-id>116</queue-id>
<queue-name>Tech Support</queue-name>
<queue-size>0</queue-size>
<queue-type>vmail</queue-type>
<sla-activity>0</sla-activity>
<sla-target>0</sla-target>
<thirty-min-abandoned>0</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>0</thirty-min-longest-wait-time>
<thirty-min-queued>0</thirty-min-queued>
<thirty-min-sla-activity>0</thirty-min-sla-activity>
</queue>
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 authentication token:
- Log in to Configuration Manager.
- Select Integration.
- Select the API Token tab.
- Next to Data Request Token, select New 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://vcc-na4.8x8.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: available 1: 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 start 1: 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: monitoring5: 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 | 0: Session closed from Jabber 1: Session Timed-Out 2: Maintenance Mode 3: Logout from Operation Dashboard 4: Call Ignored from phone 5: Interaction Timed Out 6: Agent Relogin |
| 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 |
| Agent-sub-status | Agent-sub-status is for agents who can handle more than one chat transaction at a time |
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
| Code | Error | Description |
|---|---|---|
| 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 |