8x8 Contact Center Recordings and Chat Transcripts API

Updated: 07/31/2024

Overview

The 8x8 Recordings API is composed of a set of URIs that identify and request recordings data from the 8x8 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 Recordings database contains data about call recordings; the recording file name, phone number called, customer ANI, and so on.

All API requests are authenticated using a token that is issued to a valid 8x8 tenant. Responses are sent in either XML or CSV format.

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

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 the username and password into a single long string. To get your token:

Log in to Configuration Manager for Contact Center.
Open Integration, and go to the API Token tab.
Next to Data Request Token, click the New Token button to generate a new private token for your tenant. Use this token in all requests to the Recordings API. You may generate a new token at any time.

Caution! Generating a new token will immediately revoke the existing token. If the existing token is currently being utilized by a customization, integration, or script, these will cease to function until updated with the newly generated token.

Test Using a Browser

The Recordings API makes it easy to submit a query for experimentation, testing, or debugging purposes.

From a web browser, enter your API query URL, which contains your platform URL. The platform URL varies based on the tenant your system is hosted on. For details, refer to the 8x8 Contact Center Platform URL Guide. In the following example, replace "X" in the URL as needed based on your tenant platform URL:
```
https://vcc-naX.8x8.com/api/recordings/files/
```
At the prompt, enter a username and password. Enter your tenant name as the username, and your authentication token as the password. The query result is then displayed in your browser.

The query returns information about all call recording files, in XML format.

Test Using curl

In a Linux environment, the curl utility submits an HTTP request, and allows you to view the result:

curl -u acme:ac12343934687a839cf https://vcc-naX.8x8.com/api/recordings/files.csv

The query returns a list of recording files, 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.

Files

You can use a query to look up files.

List All Call Recording Files

/files

The above query returns a list of all call recording files:

<?xml version='1.0'  encoding='UTF-8' ?>
<recordings>
  <file>
    <startDate>2007-12-19T19:16:36-08:00</startDate>
    <agentID>bill</agentID>
    <phoneNumber>bill</phoneNumber>
    <channel>5027780</channel>
    <caseID>0</caseID>
    <duration>27</duration>
    <filename>S20071220/R2007122003163601000.wav</filename>
    <queueID>fernandez~~queue~~phone~~102</queueID>
    <queueName>phoneq1</queueName>
    <accountNumber>0</accountNumber>
    <transactionID>1</transactionID>
    <extVar1>0</extVar1>
    <extVar2>0</extVar2>
    <outDialCode />
    <wrapUpCode>
    <transactionCodes>
    <transactionCode>
    <listName>Gauffre</listName>
    <name>Gauffre 1</name>
    </transactionCode>
    </transactionCodes>
    </wrapUpCode> 
  </file>
</recordings>

To get a recording file for a completed call, use the parameters supplied in the post-call screen pop:

https://vcc-naX.8x8/api/recordings/files?agentID=bill&channel=8005557780&phoneNumber=4155551234&finish-date=2007-12-19 19:16:58Z

The type of data returned for each recording could be one of the following:

Outbound
Inbound
Direct Agent Access

To interpret the type of recording, use the value provided in the channel field. For different call types, the value in the phone number field represents different attributes of the call.

Call Type	Channel	Phone Number	Queue ID	Queue Name
Busy (Inbound/Outbound)	Channel of the call dialing to (for inbound only)	Caller ID of the caller	Queue ID of the queue	Queue Name of the queue
Outbound	#virtual_outbound#	Dial-out number	QUEUE_OUTBOUND	QUEUE_OUTBOUND
Direct Agent Access	#virtual_daa#	Caller ID of the caller	QUEUE_DIRECT_AGENT_ACCESS	QUEUE_DIRECT_AGENT_ACCESS

Delete a Call Recording File

/files/S20071220/R200712200316361000[.wav]

Chat Transcripts

You can either get a list of your existing chat transcripts, or examine the messages in a specific chat transcript.

List All Chat Transcripts

/transcripts

The above query returns a list of all chat transcripts:

<?xml version='1.0'  encoding='UTF-8' ?>
<recordings>
  <transcript>
    <startDate>2007-12-19T19:16:36-08:00</startDate>
    <agentID>bill</agentID>
    <agentName>Bill,Jackson</agentName>
    <contactID>guest_at_dev6chatrec@vm05dev187.dev.whitepj.net/CtlGuest191gafdDQNAStnY7DaKuDKwPwd5jYsoh</contactID>
    <contactName>Jeff Waugh</contactName>
    <queueID>104</queueID>
    <queueName>chat_recording_2</queueName>
    <channelID>103</channelID>
    <channelName>chatrec_channel</channelname>
    <caseID>24482</caseID>
    <targetIP>10.191.210.31</targetIP>
    <transactionID>11</transactionID>
    <interactionGUID>int-14a0febe466-bLfK0EF6BKKvFMZmhhFdW14v0-chat-03-tenant</interactionGUID>
    <transcriptType>A2C</transcriptType>
    <duration>54</duration>
    <metaDatas>
      <metaData>
        <fieldName>Color</fieldName>
        <fieldValue>Blue</fieldValue>
      </metaData>
      <metaData>
        <fieldName>Fruit</fieldName>
        <fieldValue>Cherry</fieldValue>
      </metaData>
    </metaDatas>
  </transcript>
</recordings>

List All Messages in a Specified Transcript

/transcripts/{interactionGUID}

The above query returns a list of all messages in the specified interaction:

<?xml version='1.0'  encoding='UTF-8' ?>
<transcript>
  <startDate>2007-12-19T19:16:36-08:00</startDate>
  <agentID>bill</agentID>
  <agentName>Bill,Jackson</agentName>
  <contactID>guest_at_dev6chatrec@vm05dev187.dev.whitepj.net/CtlGuest191gafdDQNAStnY7DaKuDKwPwd5jYsoh</contactID>
  <contactName>Jeff Waugh</contactName>
  <queueID>104</queueID>
  <queueName>chat_recording_2</queueName>
  <channelID>103</channelID>
  <channelName>chatrec_channel</channelname>
  <caseID>24482</caseID>
  <targetIP>10.191.210.31</targetIP>
  <transactionID>11</transactionID>
  <interactionGUID>int-14a0febe466-bLfK0EF6BKKvFMZmhhFdW14v0-chat-03-tenant</interactionGUID>
  <transcriptType>A2C</transcriptType>
  <duration>54</duration>
  <metaDatas>
    <metaData>
      <fieldName>Color</fieldName>
      <fieldValue>Blue</fieldValue>
    </metaData>
    <metaData>
      <fieldName>Fruit</fieldName>
      <fieldValue>Cherry</fieldValue>
    </metaData>
  </metaDatas>
  <messages>
    <message>
      <messageTime>2007-12-19T19:16:36-08:00</messageTime>
      <messageFrom>C</messageFrom>
      <originalLanguage>en</originalLanguage>
      <originalMessage>Hi How r u</originalMessage>
      <translatedLanguage/>
      <translatedMessage/>
    </message>
  </messages>
</transcript>

Remove Transcripts of an Interaction

The following query removes all messages of a specified transcript.

DELETE 
/transcripts/{interactionGUID}

Notes:

All messages will be removed, but the interaction continues to exist (with a dummy message).
If the interaction does not exist, the return code will be 204 (No content).

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. You can include an optional time zone parameter:

https://vcc-naX.8x8.com/api/recordings/files?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. To view a list of valid time zones, click here, and look through the "TZ" column of the table. To specify a date range, separate the dates with a comma.

https://vcc-naX.8x8.com/api/recordings/files?d=2007-08-05,2007-08-07

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

https://vcc-naX.8x8.com/api/recordings/files?d=2007-08-05%2013:15Z,2007-08-07%2014:30Z

The time zone designator ("Z" in the URI) signifies 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:

https://vcc-naX.8x8.com/api/recordings/files?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 recordings:

https://vcc-naX.8x8.com/api/recordings/files?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

In the query, "-08:00″ represents the offset with the UTC time zone (Coordinated Universal Time). A negative offset typically represents time zones west of UTC.

Keep in Mind

When entering dates:

start-date should be used to find voice recordings that started within 5 seconds (plus or minus) of a given date(/time). If no time is provided, the API will default to midnight (+-5 seconds).
finish-date should be used to find voice recordings that ended within 5 seconds (plus or minus) of a given date(/time). If no time is provided, the API will default to midnight (+-5 seconds).
start-date and finish-date cannot be used together to emulate a date range. You should use a date range in reference to the "d" variable, as shown in the section above. If you still try to use both variables in a same query, only "start-date" will be used.

Pagination

Requests that would return a large number of records 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:

https://vcc-naX.8x8.com/api/recordings/files?n=101

Query Variables

Queries that return interaction data may be further constrained by supplying query variables. These take the form of field=value, in which field is any field normally returned by the query (such as agentID, phoneNumber, channel, and so on). There are two exceptions worth mentioning:

start-date: "start-date" should be used instead of "startDate"
finish-date: "finish-date" is not one of the output fields

Note that query variables are case-sensitive (use "start-date" instead of "Start-Date"). For example, to return only the set of recordings for a particular channel:

https://vcc-naX.8x8.com/api/recordings/files?channel=8005551234

Metadata Variables

Queries that return interaction data may be further constrained by supplying the metadata field name and/or field value. These parameters are provided as metaData_fieldName=val and metaData_fieldValue=val. The metadata field name and value can have the value of a complete sentence. Since it could be difficult for user to provide the exact value, we have provisioned to match the sub-string as well. Let's say that the metadata field name is "Number of alphabets in your native language"; if the user only provides the fragment "alphabets in", the query still searches the record. Note that search remains case-sensitive.

Responses

Each resource may be returned in either XML, JSON, or CSV format. To specify, add ".xml", ".json", or ".csv" to the URL:

https://vcc-naX.8x8.com/api/recordings/files.csv

If you do not specify the file type, the default is XML.

For compatibility reasons, .../transcripts/{interactionGUID} API does not give a CSV response.

Response Codes

Code Number	Code Label	Description
200	OK	The request was successful.
400	Bad request	The syntax of the request was wrong.
401	Unauthorized	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.