Skip to main content

 

 
8x8 Support

8x8 Contact Center Statistics Reporting API

Note-Icon.png

All future enhancements will be on those APIs and within Analytics for Contact Center

Analytics for Contact Center offers a full suite of Summary, Detailed and Realtime APIs. 

These newer APIs directly match the capabilities of Analytics for Contact Center and provide the same extensive range of metrics and dimensions.

While there is no current end of service for the APIs below, it is strongly advised to leverage the Analytics for Contact Center APIs for any new projects and consider adopting them in existing projects.

Overview

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

The Historical Reporting database contains data about agents and their interactions, statuses, status stats and outbound calls, and queues and their interactions.

The Historical Reporting database contains two types of data; event and aggregated. Some queries will return unique event records, but most will return data that has been aggregated into 30 minute periods.

Note-Icon.png

Note: There would be instances where when querying the API data, 25 columns will not have values; destinationorignal, destinationtranslated, directiontransaction, interactiontype, agentid, agentname, accepttimestamp, processtime, postprocess, totaltime, recordingfilename, maxhold, holdcount, totalhold, leg1postdial, leg2postdial, leg1answertime, leg2answertime, leg1sipid, leg2sipid, campaignname, recordid, recordstatus, dispositioncode, agentaccepttime.

This is due to the API query being run less than one hour before the calls were accepted by agents.

All API requests are authenticated using a token that is issued to a valid Virtual Contact Center tenant. Responses are sent in either XML,CSV or JSON format. A sample Java program is available, which demonstrates how to issue a request and work with the response.

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

The API allows you to fetch data on agents' skills. You can pass an API request to fetch:

  • Skill levels of an agent for all the queues he is a member of
  • Skill levels of all agents for a given queue

The response to the request will display agents' skill levels with the status. Click here for sample requests.

Important-Icon.png

The NA/EU server numbers used in the URL's in this document are only an example. If copying and pasting the code, edit the code to the appropriate server number, this can be seen in the URL when logging in to 8x8 Contact Centre. For an example, if on na2, the code should read,  

http://vcc-na2.8x8.com/api/stats/agents/fred.xml

Revise your query URL to include the login URL of your tenant. (Refer to the Platform URL Guide to retrieve your login URL)

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:

http://vcc-na4.8x8.com/api/stats/agents/fred.xml

will return information about fred, in XML format.

Important-Icon.png

The NA server numbers above are only an example. If copying and pasting the code, edit the code to the appropriate NA server number. For an example, if on na2, the code should read:

http://vcc-na2.8x8.com/api/stats/agents/fred.xml

Revise your query URL to include 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 http://vcc-na4.8x8.com/api/stats/groups.csv

will return a list of groups, in CSV format. The -u argument identifies the username and password; use your tenant name as the username, and your authentication token as the password.

Groups

List groups

/groups

Returns a list of all groups.

<?xml version='1.0'  encoding='UTF-8' ?>
<groups>
    <group>

        <group-id>122</group-id>
        <group-name>Support</group-name>
        <deleted>No</deleted>
    </group>

    <group>
        <group-id>123</group-id>
        <group-name>East Coast Sales</group-name>
        <deleted>Yes</deleted>

    </group>
    <group>
      ... 
    </group>
</groups>

Agents

List all agents

/agents?n={offset}

Returns a list of details for all agents.

List agents in a group

/groups/{group-id}/agents?n={offset}

Returns a list of details for all agents for a named group.

Show a named agent

/agents/{agent-id}

Shows details of a single agent.

<?xml version='1.0'  encoding='UTF-8' ?>
<agents>
    <agent>
        <agent-id>fred</agent-id>
        <group-id>148</group-id> 
        <date-hired-date>2008-03-23</date-hired-date> 
        <direct-agent-access>no</direct-agent-access> 
        <email-address>fred@acme.com</email-address> 
        <enabled>Y</enabled> 
        <first-name>Fred</first-name> 
        <full-name>Fred Bloggs</full-name> 
        <last-name>Bloggs</last-name> 
        <phone-used>PSTN</phone-used> 
        <phone-extension>007</phone-extension>

        <user-rights>agent</user-rights> 
        <voice-mail-activated>no</voice-mail-activated> 
    </agent>
    <agent>
      ... 
    </agent>

</agents>

Activities

List activities for a named agent

/agents/{agent-id}/activities?d={date range}&n={offset}

Returns a list of activities for a named agent.

List activities for all agents in a group

/groups/{group-id}/activities?d={date range}&n={offset}

Returns a list of activities for all agents in a named group.

<?xml version='1.0'  encoding='UTF-8' ?>
<activities>
    <activity>
        <agent-id>fred</agent-id>

        <agent-name>Fred Bloggs</agent-name>
        <group-id>122</group-id>
        <group-name>Sales</group-name>
        <media-type>Phone</media-type>

        <channel-id>62</channel-id>
        <channel-obj-id>5030001</channel-obj-id>
        <queue-obj-id>tenantp1~~queue~~phone~~102</queue-obj-id>
        <queue-name>phoneq1</queue-name>

        <transaction_id>133</transaction_id>
        <origination>4245567232</origination>
        <customer-name>N/A</customer-name>
        <trans-accept-time>2009-06-03T23:09:04-07:00</trans-accept-time>

        <trans-proc-time>8</trans-proc-time>
        <trans-post-proc-time>7</trans-post-proc-time>
        <trans-total-time>15</trans-total-time>
        <trans-transfer-from />

        <trans-conference-from />
        <case-id />
        <tcl-list-id>1</tcl-list-id>
        <tcl-item-id>1</tcl-item-id>
        <tcl-item-shortcode-text>c1</tcl-item-shortcode-text>

        <tcl-item-report-text>transcode1</tcl-item-report-text>
        <recording-filename>S20090604/R200906040609030100.wav</recording-filename>
    </activity>
</activities>

Agent Interactions

Interaction reports only include Queued interactions.

List interactions for a named agent

/agents/{agent-id}/interactions?d={date range}&n={offset}&{query vars}

Returns a list of interactions for a named agent.

List interactions for all agents in a group

/groups/{group-id}/interactions?d={date range}&n={offset}&{query vars}

Returns a list of interactions for all agents in a named group.

<?xml version='1.0'  encoding='UTF-8' ?>
<interactions>
    <interaction>
        <interaction-id>1428</interaction-id>
        <agent-id>fred</agent-id>

        <agent-name>Fred Bloggs</agent-name>
        <group-id>132</group-id>
        <group-name>Support</group-name>
        <accept-timestamp>2008-03-09T09:13:02-07:00</accept-timestamp>

        <process-time>104</process-time>
        <post-process-time>70</post-proc-time>
        <finish-timestamp>2008-03-09T09:23:09-07:00</finish-timestamp>
        <transfer-from></transfer-from>

        <conference-from></conference-from>
    </interaction>
    <interaction>
      ... 
    </interaction>
</interactions>

Queue Interactions

List interactions

/interactions/?d={date range}&n={offset}&{query vars}

Returns a list of interactions.

List interactions for a queue

/queues/{queue-id}/interactions?d={date range}&n={offset}&{query vars}

Returns a list of interactions for a queue.

List interactions for a channel

/channels/{channel-id}/interactions?d={date range}&n={offset}&{query vars}

Returns a list of interactions for a channel.

There are several supported media types:

  • T = Telephone
  • V = Voice Mail
  • C = Chat
  • Z = Email
<?xml version='1.0'  encoding='UTF-8' ?>
<interactions>
    <interaction>
        <interaction-id>463</interaction-id>
        <queue-name>Support</queue-name>

        <channel-id>12</channel-id>
        <media-type>T</media-type>
        <create-timestamp>2008-02-09T14:13:32-07:00</create-timestamp>
        <accept-timestamp></accept-timestamp>

        <process-time>0</process-time>
        <post-process-time>0</post-process-time>
        <abandon-timestamp></abandon-timestamp>
        <finish-timestamp></finish-timestamp>

        <voice-message-left>Y</voice-message-left>
        <origination>Y</origination>
        <customer-name>Y</customer-name>
        <ivr-treatment-time>10</ivr-treatment-time>

        <max-hold-time>0</max-hold-time> 
        <hold-count>0</hold-count> 
        <total-hold-time>0</total-hold-time> 
        <call-leg1-post-dial-delay>2</call-leg1-post-dial-delay> 
        <call-leg2-post-dial-delay>2</call-leg2-post-dial-delay> 
        <call-leg1-answer-time>0</call-leg1-answer-time> 
        <call-leg2-answer-time>0</call-leg2-answer-time> 
        <call-leg1-sip-id>088e926d2f05a78e23f568557699891d</call-leg1-sip-id> 
        <call-leg2-sip-id>1b82fe39718634c548d04cfd373c5a8c</call-leg2-sip-id>

        <inbound-sip-id>6a4e7e2-1f1bee-4b433660@192</inbound-sip-id>
    </interaction>
</interactions>

Campaign Interactions

List interactions for a campaign

/campaigns/{campaign-id}/interactions?d={date range}&n={offset}&{query vars}

Returns a list of interactions for a campaign.

There are several predefined record status:

  • = New
  • 1 = Queued
  • 2 = Accepted
  • 3 = Completed
  • 4 = Scheduled
  • 5 = API Scheduled - scheduled via API
  • 6 = Deleted
  • 7 = Sent to Interaction Router (cached to dial)

and server predefined disposition code:

  • 1000 = None
  • 1001 = Try Again
  • 1002 = Scheduled Call Back

process-time and post-process-time are in seconds.

total-process-time = process-time + post-process-time.

Note-Icon.png

We can only delete records from campaigns in VCC when their status is 04 or 5.

In VCC v9.10.6.1 onwards, there was an improvement to enable record deletion in the following statuses: 014 and 5.

<?xml version='1.0'  encoding='UTF-8' ?>
<interactions>
    <interaction>
        <campaign-name>Sales Campaign</campaign-name>
        <campaign-id>555</campaign-id>

        <agent-name>Fred Bloggs</agent-name>
        <queue-name>Sales Queue</queue-name>
        <accept-timestamp>2011-02-28T18:52:55-08:00</accept-timestamp>
        <record-status>1</record-status>

        <record-id>0015000000WIBJrAAP</record-id>
        <interaction-id>188</interaction-id>
        <wrap-up-code>retry</wrap-up-code>
        <wrap-up-text>Try Again Later</wrap-up-text>

        <disposition-code>1001</disposition-code>
        <called-number>5551234</called-number>
        <ext-trans-data>[AccountName|John Smith]</ext-trans-data>
        <process-time>125</process-time>

        <post-process-time>60</post-process-time>
        <total-process-time>185</total-process-time>
        <recordinf-filename>S20110228/R20110228175312223.wav</recording-filename>
    </interaction>

    <interaction>
      ... 
    </interaction>
</interactions>

All Interactions

This also includes non queued interactions such as agent to agent or direct to agent calls.

List all interactions

/allinteractions/?d={date range}&n={offset}&{query vars}

Returns a list of all interactions. Those include agent/queue/campaign interactions, but also abandoned/direct agent access/Forward to external number transactions.

media-type can be either Phone, Chat, Email or Voice Mail.

interaction-direction can be empty, or set to either inbound or outbound.

interaction-type can be empty, or set to one of the following values:

  • Web Callback
  • DAA
  • Fwd to Ext. Number
  • Campaign
  • Consult

For possible values for record-status and disposition-code, see the previous paragraph (Campaign Interactions).

<?xml version='1.0'  encoding='UTF-8' ?>
<interactions>
    <interaction>
        <media-type>Phone</media-type>
        <channel-obj-id>9691000</channel-obj-id>
        <queue-name>Engineering Phone Queue</queue-name>
        <interaction-id>7</interaction-id>
        <orig-interaction-id />
        <origination>pma</origination>
        <destination-original />
        <destination-translated />
        <customer-name>N/A, N/A</customer-name>
        <case-id />
        <interaction-direction />
        <interaction-type />
        <dial-code />
        <dial-text />
        <create-timestamp>2011-09-22T18:35:10-07:00</create-timestamp>
        <agent-name />
        <accept-timestamp />
        <process-time />
        <post-process-time />
        <total-time />
        <abandon-timestamp>2011-09-22T18:35:30-07:00</abandon-timestamp>
        <voice-message-left />
        <recording-filename />
        <ivr-treatment-time>2</ivr-treatment-time>
        <transfer-from />
        <conference-from />
        <max-hold-time>0</max-hold-time> 
        <hold-count>0</hold-count> 
        <total-hold-time>0</total-hold-time> 
        <call-leg1-post-dial-delay>0</call-leg1-post-dial-delay> 
        <call-leg2-post-dial-delay>0</call-leg2-post-dial-delay> 
        <call-leg1-answer-time>0</call-leg1-answer-time> 
        <call-leg2-answer-time>0</call-leg2-answer-time> 
        <call-leg1-sip-id />
        <call-leg2-sip-id />
        <inbound-sip-id>MTM2MjZkNDdiMzU3ZmQ3OTQ1OWM3MmI0M2E4ZGI</inbound-sip-id>
        <notes />
        <campaign-name />
        <record-id />
        <record-status />
        <disposition-code />
        <ext-trans-data />
        <wrap-up-code>N/A</wrap-up-code>
        <wrap-up-text>N/A</wrap-up-text>
    </interaction>
</interactions>

Interaction Statistics

List statistics for an agent

/agents/{agent-id}/statistics?d={date range}&n={offset}&{query vars}

Returns a list of interaction statistics for an agent, reported in 30 minute periods.

List statistics for a queue

/queues/{queue-id}/statistics?d={date range}&n={offset}&{query vars}

Returns a list of interaction statistics for a queue, reported in 30 minute periods.

List statistics for a channel

/channels/{channel-id}/statistics?d={date range}&n={offset}&{query vars}

Returns a list of interaction statistics for a channel, reported in 30 minute periods.

<?xml version='1.0'  encoding='UTF-8' ?>
<statistics>
    <statistic>
        <queue-name>Support</queue-name>

        <channel-id>23</channel-id>
        <time-stamp>2008-02-22T13:30:00-07:00</time-stamp>
        <media-type>T</media-type>
        <entered-count>24</entered-count>

        <accepted-count>21</accepted-count>
        <sla-met-count>18</sla-met-count>
        <abandoned-count>1</abandoned-count>
        <finish-processing-count>2</finish-processing-count>

        <finish-post-count>2</finish-post-count>
        <voice-message-left-count>0</voice-message-left-count>
        <time-waiting>845</time-waiting>
        <time-processing>512</time-processing>

        <time-post-processing>142</time-post-processing>
        <total-time-to-abandon>56</total-time-to-abandon>
        <time-max-wait-accept>110</time-max-wait-accept>
        <time-max-wait-abandon>56</time-max-wait-abandon>

    </statistic>
</statistics>

SLAs

SLAs are data about the number of interactions accepted or abandoned, split by time period. The SLA response differs, depending on whether the queue being queried is an "on line" (telephony, chat), or an "off line" (emails, voice mails) queue.

List on-line SLAs for a queue

/queues/{queue-id}/online_slas?d={date range}&n={offset}&{query vars}

Returns a list of SLA stats for an online (telephony, chat) queue, reported in 30 minute periods.

List online SLAs for a channel

/channels/{channel-id}/online_slas?d={date range}&n={offset}&{query vars}

Returns a list of SLA stats for an online (telephony, chat) channel, reported in 30 minute periods.

<?xml version='1.0'  encoding='UTF-8' ?>
<online_slas>
    <online_sla>

        <queue-name>Support</queue-name>
        <channel-id>23</channel-id>
        <time-stamp>2008-02-22T13:30:00-07:00</time-stamp>
        <media-type>T</media-type>

        <entered-count>24</entered-count>
        <accepted-count>21</accepted-count>
        <sla-met-count>18</sla-met-count>
        <accepted>

            <t0-5sec>8</t0-5sec>
            <t5-10sec>5</t5-10sec>
            <t10-20sec>2</t10-20sec>
            <t20-30sec>3</t20-30sec>

            <t30-40sec>2</t30-40sec>
            <t30-45sec>0</t30-45sec>
            <t45-1min>1</t45-1min>
            <t1-2min>0</t1-2min>

            <t2-5min>0</t2-5min>
            <t5-10min>0</t5-10min>
            <t10-or-more>0</t10-or-more>
        </accepted>

        <abandoned>
            <t0-5sec>0</t0-5sec>
            <t5-10sec>0</t5-10sec>
            <t10-20sec>0</t10-20sec>

            <t20-30sec>0</t20-30sec>
            <t30-40sec>0</t30-40sec>
            <t30-45sec>0</t30-45sec>
            <t45-1min>0</t45-1min>

            <t1-2min>0</t1-2min>
            <t2-5min>0</t2-5min>
            <t5-10min>0</t5-10min>
            <t10-or-more>0</t10-or-more>

        </abandoned>
    </online_sla>
</online_slas>

List off-line SLAs for a queue

/queues/{queue-id}/offline_slas?d={date range}&n={offset}&{query vars}

Returns a list of SLA stats for an offline (email, voicemail) queue, reported in 30 minute periods.

/channels/{channel-id}/offline_slas?d={date range}&n={offset}&{query vars}

Returns a list of SLA stats for an offline (email, voicemail) channel, reported in 30 minute periods.

<?xml version='1.0'  encoding='UTF-8' ?>
<offline_slas>
    <offline_sla>
        <queue-id>32</queue-id>

        <queue-name>Support</queue-name>
        <channel-id>18</channel-id>
        <time-stamp>2008-02-22T13:30:00-07:00</time-stamp>
        <media-type>E</media-type>

        <entered-count>12</entered-count>
        <accepted-count>8</accepted-count>
        <sla-met-count>8</sla-met-count>
        <accepted>

            <t0-30min>4</t0-30min>
            <t30min-1hr>4</t30min-1hr>
            <t1hr-1hr30min>2</t1hr-1hr30min>
            <t1hr30min-2hr>1</t1hr30min-2hr>

            <t2hr-3hr>0</t2hr-3hr>
            <t3hr-or-more>1</t3hr-or-more>
        </accepted>
    </offline_sla>
</offline_slas>

Agent Statuses

List statuses for a named agent

/agents/{agent-id}/statuses?d={date range}&n={offset}

Returns a list of statues for a named agent.

List statuses for all agents in a group

/groups/{group-id}/statuses?d={date range}&n={offset}

Returns a list of statuses for all agents in a named group.

<?xml version='1.0'  encoding='UTF-8' ?>
<statuses>
    <status>
        <agent-id>fred</agent-id>

        <agent-name>Fred Bloggs</agent-name>
        <group-id>12</group-id>
        <group-name>grp2</group-name>
        <status>On Break</status>

        <event-time>2009-05-21T14:23:05-07:00</event-time>
        <scl-list-id></scl-list-id>
        <scl-item-id></scl-item-id>
        <scl-item-shortcode-text>Scheduled break</scl-item-shortcode-text>

        <scl-item-report-text>Scheduled break</scl-item-report-text>
        <transaction-id>1000</transaction-id>
    </status>
</statuses>

Agent Statuses Statistics

List statuses statistics for a named agent

  /agents/{agent-id}/statuses/statistics?d={date range}&n={offset}

Returns a named agent’s aggregated data about her statuses.

<statuses>
    <status>
            <period-start>2015-07-08T14:30:00-07:00</period-start>
            <period-end>2015-07-08T15:00:00-07:00</period-end>
            <agent-id>pma</agent-id>
            <agent-name>Agent Smith</agent-name>
            <group-id>101</group-id>
            <group-name>DEV</group-name>
            <status-waiting>0</status-waiting>
            <status-processing>0</status-processing>
            <status-post-processing>0</status-post-processing>
            <status-working-offline>0</status-working-offline>
            <status-transaction-offered>0</status-transaction-offered>
            <status-break>1696</status-break>
            <time-logged-in>1696</time-logged-in>

    </status>

<statuses>

Agent / Queue Skills

List skills by agent id

/agents/{agent-id}/skills

Returns a list of skills for a named agent. This API does not support any query parameters.

<?xml version='1.0'  encoding='UTF-8' ?>
<skills>
    <skill>
        <enabled>Y</enabled>
        <queue-id>102</queue-id>
        <agent-id>kol</agent-id>
        <skill-level>high</skill-level>
</skill>
    <skill>
        <enabled>N</enabled>
        <queue-id>103</queue-id>
        <agent-id>kol</agent-id>
        <skill-level>medium</skill-level>
    </skill>
</skills>

List skills by queue id

/queues/{queue-id}/skills

Returns a list of agent skills for a given queue. This API does not support any query parameters.

<?xml version='1.0'  encoding='UTF-8' ?>
<skills>
    <skill>
        <enabled>Y</enabled>
        <agent-id>phegde</agent-id>
        <queue-id>102</queue-id>
        <skill-level>high</skill-level>
</skill>
    <skill>
        <enabled>N</enabled>
        <agent-id>kol</agent-id>
        <queue-id>102</queue-id>
        <skill-level>medium</skill-level>
    </skill>
</skills>

Outbound Calls

List outbound calls for a named agent

/agents/{agent-id}/outboundcalls?d={date range}&n={offset}

Returns a list of outbound calls for a named agent.

List outbound calls for all agents in a group

/groups/{group-id}/outboundcalls?d={date range}&n={offset}

Returns a list of outbound calls for all agents in a named group.

<?xml version='1.0'  encoding='UTF-8' ?>
<outboundcalls>
    <outboundcall>
        <agent-id>fred</agent-id>
        <agent-name>Fred Bloggs</agent-name>

        <group-id>12</group-id>
        <transaction-id>123</transaction-id>
        <destination>14155524562</destination>
        <start-time>2009-05-26T17:53:55-07:00</start-time>

        <total-time>14</total-time>
        <tcl-list-id>1</tcl-list-id>
        <tcl-item-id>1</tcl-item-id>
        <tcl-item-shortcode-text>c1</tcl-item-shortcode-text>

        <tcl-item-report-text>report text 1</tcl-item-report-text>
        <tcl-outbound-list-id>2</tcl-outbound-list-id>
        <tcl-outbound-item-id>3</tcl-outbound-item-id>
        <tcl-outbound-item-shortcode-text>ttt</tcl-outbound-item-shortcode-text>

        <tcl-outbound-item-report-text>ttt</tcl-outbound-item-report-text>
        <recording-filename>S20090526/R20090526175312223.wav</recording-filename>
        <max-hold-time>0</max-hold-time> 
        <hold-count>0</hold-count> 
        <total-hold-time>0</total-hold-time> 
        <call-leg1-post-dial-delay>2</call-leg1-post-dial-delay> 
        <call-leg2-post-dial-delay>2</call-leg2-post-dial-delay> 
        <call-leg1-answer-time>0</call-leg1-answer-time> 
        <call-leg2-answer-time>0</call-leg2-answer-time> 
        <call-leg1-sip-id>088e926d2f05a78e23f568557699891d</call-leg1-sip-id> 
        <call-leg2-sip-id>1b82fe39718634c548d04cfd373c5a8c</call-leg2-sip-id>

    </outboundcall>
</outboundcalls>

Queues

List all queues

/queues?n={offset}

Returns a list of details for all queues

List a single queue

/queues/{queue-id}

Show details for a single queue.

There are several supported media types:

  • T = Telephone
  • V = Voice Mail
  • C = Chat
  • Z = Email
<?xml version='1.0'  encoding='UTF-8' ?>
<queues>
    <queue>
        <queue-id>121</queue-id>

        <queue-name>Support</queue-name>
        <queue-desc>First tier support</queue-desc>
        <media-type>T</media-type>
        <enabled>Y</enabled>

        <sla-enabled>N</sla-enabled>
        <sla-time>0</sla-time>
    </queue>
</queues>

Channels

List all channels

/channels?n={offset}

Returns a list of details for all channels

<?xml version='1.0'  encoding='UTF-8' ?>
<channels>
    <channel>
        <channel-id>52</channel-id>

        <channel-name>sales@acme.com</channel-name>
        <channel-desc>Sales Email</channel-desc>
    </channel>
</channels>

Campaigns

List all campaigns

/campaigns?n={offset}

Returns a list of details for all campaigns

List a single campaign

/campaigns/{campaign-id}

Show details for a single campaign.

There are several predefined campaign status:

  • 0 = New
  • = Manual Started
  • 2 = Schedule Started
  • 3 = Manual Running
  • 4 = Schedule Running
  • 5 = Manual Stopped
  • 6 = Completed
  • 7 = Scheduled Stopped
  • 8 = Manual Paused
  • 9 = Schedule Paused 
  • 10 = Manual Purged 
  • 11 = Schedule Purged

retry-interval is in minutes.

daily-start-time and daily-end-time are integer values of minutes from beginning of the day.

<?xml version='1.0'  encoding='UTF-8' ?>
<campaigns>
    <campaign>
        <campaign-name>Sales Campaign</campaign-name>

        <campaign-id>123</campaign-id>
        <enabled>Y</enabled>
        <status>6</status>
        <no-of-records>100</no-of-records>

        <caller-id>5551234</caller-id>
        <start-time>2011-02-01T10:00:00-08:00</start-time>
        <end-time>2011-02-28T17:30:00-08:00</end-time>
        <actual-run-time>2011-02-01T10:00:30-08:00</actual-run-time>

        <actual-stop-time>2011-02-23T12:09:36-08:00</actual-stop-time>
        <daily-start-time>600</daily-start-time>
        <daily-end-time>1110</daily-end-time>
        <retry-interval>90</retry-interval>

        <max-retry>3</max-retry>
    </campaign>
</campaigns>

Campaign Records

List all records of a single campaign

/campaigns/{campaign-id}/records?n={offset}

Show details for all records of s campaign.

There are several predefined record status:

  • 0 = New
  • 1 = Queued
  • 2 = Accepted
  • 3 = Completed
  • 4 = Scheduled

, status code:

  • 0 = Default
  • 1 = Max Attempt Reached
  • = Skipped
  • = No Phone Number
  • = Invalid Phone Number

and disposition code:

  • 1000 = None
  • 1001 = Try Again
  • 1002 = Scheduled Call Back
<?xml version='1.0'  encoding='UTF-8' ?>
<records>
    <record>
        <campaign-name>Sales Campaign</campaign-name>
        <campaign-id>123</campaign-id>

        <record-id>0015000000WIBJrAAP</record-id>
        <phone-list>Phone|(650)555-1234</phone-list>
        <status>3</status>
        <status-code>0</status-code>

        <ext-trans-data>[AccountName|John Smith]</ext-trans-data>
        <disposition-code>1000</disposition-code>
    </record>
    <record>
      ...
    </record>

</recordss>

Transaction Code List

List all transaction codes

/tcls?n={offset}

Returns a list of details for all transaction codes

<?xml version='1.0'  encoding='UTF-8' ?>
<tcl-trans>

    <tcl-tran>
        <tcl-list-id>1</tcl-list-id>
        <tcl-name>ag-trans-code</tcl-name>
        <tcl-description>agent transaction code</tcl-description>

        <tcl-admin-notes />
        <tcl-active>Y</tcl-active>
        <tcl-autosort>N</tcl-autosort>
        <tcl-used>Y</tcl-used>

        <tcl-category-id />
        <tcl-assignment-type>groups</tcl-assignment-type>
        <tcl-required>Y</tcl-required>
        <tcl-multiple-choice>Y</tcl-multiple-choice>

        <tcl-required-before-outbound>Y</tcl-required-before-outbound>
        <tcl-item-id>1</tcl-item-id>
        <tcl-item-ordinate>0</tcl-item-ordinate>
        <tcl-item-active>Y</tcl-item-active>

        <tcl-item-used>Y</tcl-item-used>
        <tcl-item-call-line-id>140823322222</tcl-item-call-line-id>
        <tcl-lang-id>en_US</tcl-lang-id>
        <tcl-item-menu-text>code 1</tcl-item-menu-text>

        <tcl-item-report-text>code 1</tcl-item-report-text>
        <tcl-item-shortcode-text>c1</tcl-item-shortcode-text>
    </tcl-tran>
</tcl-trans>

Status Code List

List all status codes

/scls?n={offset}

Returns a list of details for all status codes

<?xml version='1.0'  encoding='UTF-8' ?>
<scl-trans>
    <scl-tran>
        <scl-list-id>1</scl-list-id>

        <scl-name>ag-status-code</scl-name>
        <scl-description>agent status code</scl-description>
        <scl-admin-notes />
        <scl-active>Y</scl-active>

        <scl-autosort>N</scl-autosort>
        <scl-used>Y</scl-used>
        <scl-category-id />
        <scl-item-id>1</scl-item-id>

        <scl-item-ordinate>0</scl-item-ordinate>
        <scl-item-active>Y</scl-item-active>
        <scl-item-used>Y</scl-item-used>
        <scl-lang-id>en_US</scl-lang-id>

        <scl-item-menu-text>code 1</scl-item-menu-text>
        <scl-item-report-text>code 1</scl-item-report-text>
        <scl-item-shortcode-text>c1</scl-item-shortcode-text>
    </scl-tran>

</scl-trans>

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 Virtual Configuration Manager for Contact Center, 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.

Dates

Date formats in queries adhere to the ISO 8601 standard. The {date range} argument can take one of two forms. To specify records from a given day, specify the date, with an optional time zone parameter:

http://vcc-na4.8x8.com/api/stats/agents/{agentId}/interactions?d=2007-08-05&tz=America/New_York

Note that if no time is given, a day begins at midnight (00:00:00), and if no time zone is specified, the time defaults to the tenant time zone. A list of valid time zones can be found here (TZ column): List of valid time zones. To specify a date range, separate the dates with a comma (",")

http://vcc-na4.8x8.com/api/stats/agents/fred/interactions?d=2007-08-05,2007-08-07

You can include times in date ranges as well, separated with a space ("%20″ in the URI):

http://vcc-na4.8x8.com/api/stats/queues/Sales/interactions?d=2007-08-05 13:15Z,2007-08-07 14:30Z

"Z" is the time zone designator, signifying that the time is in UTC (Coordinated Universal Time). Dates may also be formatted as a single string, with no separators, and a capital "T" separating date and time:

http://vcc-na4.8x8.com/api/stats/queues/Sales/interactions?d=20070805T1315Z,20070807T1430Z

There are several date constants available to represent relative dates:

today

  • the current date, at the start of the day (midnight)

today-1d

  • yesterday, at the start of the day (midnight)

today-7d

  • seven days ago, at the start of the day (midnight)

To see yesterday's status changes for Sally:

http://vcc-na4.8x8.com/api/stats/agents/sally/statuses?d=today-1d,today&tz=America/Denver

Dates in responses also adhere to the ISO 8601 standard.

They take the form:

2008-02-14T10:12:13-08:00

where "-08:00″ represents the offset with the UTC timezone (Coordinated Universal Time). A negative offset typically represents timezones west UTC.

Pagination

Requests that would return a large number of records will respond with 50 records per request. You can iterate through these response sets by setting the {offset} argument. In this example, we are asking for agent interactions, starting with the 101st record.

http://vcc-na4.8x8.com/api/stats/agents/{agentId}/interactions?n=101
Note-Icon.png

Note: VCC APIs have a max return of 50 entries. To get the next 50 entries, the API request will have to be modified to return rows starting at 51.

For example: https://vcc-eu2.8x8.com/api/stats/queues?n=51

Query Variables

Queries that return interaction data may be further constrained by supplying query variables. These take the form of field=value where field is any field normally returned by the query.

For example, to return only the set of telephone interactions (as opposed to chat or email, say):

http://vcc-na4.8x8.com/api/stats/agents/{agentId}/interactions?media-type=T

For telephone interactions for a single queue:

http://vcc-na4.8x8.com/api/stats/agents/{agentId}/interactions?media-type=T&queue-id=102

Responses

Each resource may be returned in either XML, CSV, or JSON format.

To specify, add ".xml", ".csv" or ".json" to the URL:

http://vcc-na4.8x8.com/api/stats/agents/{agentId}.csv

The default is XML.

Response Codes

Code Number Code Label 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

 

Examples

Please note these examples are to be used as a guide only, for testing the API please use either a Browser, cURL or Postman.

List interactions using the Python Requests Module

Note this will return the first page of 50 results only

import requests

url = f"https://vcc-na4.8x8.com/api/stats/interactions.json"

headers = {
  'Authorization': "Basic {yourCredentials}"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
  • Was this article helpful?