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.
![DataRequest.png](documents/7595/attachments/10154)
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. |