Back to Virtual Contact Center Documentation >
Virtual Contact Center Recordings API
Overview
The Virtual Contact Center recordings API is composed of a set of URIs
that identify and request recordings data from the Virtual Contact Center
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, etc.
All API requests are authenticated using a token that is issued to a valid
Virtual Contact Center 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.
Testing Using A Browser
The Recordings 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 promted 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://mycontactual.com/api/recordings/files/
will return information about all recording files, in XML format.
Review your query URL based on the login URL of your Tenant:
https://na1.mycontactual.com/api/recordings/files
https://na2.mycontactual.com/api/recordings/files
https://na3.mycontactual.com/api/recordings/files
https://na4.mycontactual.com/api/recordings/files
https://vcc-na7.8x8.com/api/recordings/files
For tenants in Cananda: https://www.mycontactual.ca/api/recordings/files
For tenants in UK: https://www.mycontactual.co.uk/api/recordings/files
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://mycontactual.com/api/recordings/files.csv
will return 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
List files
Returns a list of all 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</>
<accountNumber>0</accountNumber>
<transactionID>1</transactionID>
<extVar1>0</extVar1>
<extVar2>0</extVar2>
<outDialCode />
<wrapUpCode />
</file>
%lt;/recordings>
To get a recording file for a completed call, use the parameters supplied in
the post-call screen pop:
http://mycontactual/api/recordings/files?agentID=bill&channel=8005557780&phoneNumber=4155551234&finish-date=
2007-12-19%2019:16:58Z"
The return data of each recording could be either of the following types:
- Outbound
- Inbound
- Direct Agent Access
To interpret the type of the recording, use the value provided in the channel field. For different type of call, the value in the phone number field represents different attribute of the call.
| Call Type |
Channel |
Phone Number |
Queue ID |
Queue Name |
| Inbound |
Channel of the call dialing to |
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 |
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. This
generates a new private token for your tenant. You will use this token
in all requests to the Recordings 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://mycontactual.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.
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://mycontactual.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):
http://mycontactual.com/api/recordings/files?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://mycontactual.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:
http://mycontactual.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
where "-08:00" represents the offset with the UTC timezone (Coordinated Universal Time). A negative offset typically represents timezones west UTC.
Caveats
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 directly with the d variable. 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 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://mycontactual.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
where
field is any field normally returned by the query
(such as agentID, phoneNumber, channel, ...).
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
Query variables are case-sensitive. It is start-date and not Start-Date.
For example, to return only the set of recordings for a particular channel:
http://mycontactual.com/api/recordings/files?channel=8005551234
Responses
Each resource may be returned in either XML or CSV format.
To specify, add ".xml" or ".csv" to the URL:
http://mycontactual.com/api/recordings/files.csv
The default is XML.
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 |