Media Playback APIs
Use the Media Playback APIs to access Recording Management (CXone) media and metadata when extracting call segments and contacts.
-
Use of these APIs may require additional fees. Consult your contract or contact your NiCE CXoneAccount Representative for more information.
-
Default API performance is set to 150 requests per five minutes. If you require a different performance rate, contact your NiCE CXone Technical Account Representative to request an update. There may be an additional fee.
-
When extracting an interaction:
-
For voice-only and voice-and-screen media types, the API provides the interaction metadata. The link to the media file can be found under the fileToPlayUrl field in the Success response.
-
For chat and email media types, the API provides the interaction metadata and the transcript. In the Success response, you can find the transcript under the messages field and the link to the media file under the filetoplayurl field.
If the media type is set to all (and not specifically set to chat or email), then if there is a screen recording, you will also get a link to the media file for digital interactions. You can use this API to access CXone Recording media and metadata.
-
-
When downloading, the API transfers a link to the media file.
The Media Playback APIs are available in the DEVone Developer Community portal.
Before You Start
Before you can start using the Media Playback API, you must set up user permissions, generate an access key, and follow the registration and authentication process explained on the developer portal. Required permissions:
-
If you're searching for recordings that are not under your account, then you need the Search & Playback > Player > Play/download recordings: Play Any permission.
-
If you want the request to return Sentiments and Categories, then you also need the Search & Playback > Player > View sentiments and categories permission.
GET Contacts
Access the full contact (the entire interaction with all segments) based on ACD Call ID. The ACD Call ID depends on the ACD solution, for example, this is the same as the NiCE CXone Master Contact ID.
You can find the correct ACD Call ID in the following ways:
-
Use the Master Contact ID from the Contact History Report.
-
Use the ACD Call ID from the output of Data Extraction API Metadata entity.
Keep in mind that using the ACD Call ID GET method, you can play back or download interactions recorded from December 13, 2018. Accessing an interaction recorded before December 13, 2018 will give an Interaction Not Found error.
Sample requests and responses
Playback
Sample request for playback
https://na1.nice-incontact.com/media-playback/v1/contacts?acd-call-id=123456&media-type=all&exclude-waveforms=true200 OK
{
"value": {
"contactId": "11e766de-4ace-33d0-9ff6-0242ac110004",
"Interactions": [
{
"Interaction": {
"mediaType": "voice-and-screen",
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"data": {
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"acwEndTime": "2018-11-20T08:27:09.643Z",
"fileToPlayUrl": "https://test-mcrplaybackmanager-4b5e-9234-54cbe7855ca1.mp4",
"videoImageUrl": null,
"waveformDataList": [
{
"channel": 0,
"normalizedPcmData": [
0.001,
0.001,
0.001
]
}
],
"participantDataList": [
{
"participantType": "AGENT",
"agentName": "Mary Walker",
"participantId": "271863",
"userId": "11e846d2-dd9f-6f10-9aef-0242ac110002",
"voiceStages": [
{
"stageType": "ACTIVE",
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"segmentID": "e079511b-c077-489e-85a3-24b1b147d3c7",
"displays": null
}
],
"screenStages": [
{
"stageType": "ACTIVE",
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"segmentID": "e7621f2c-32e4-47cd-bfc5-29a48343f7e0",
"displays": [
{
"width": 1680,
"height": 1050,
"topLeftX": -1680,
"topLeftY": 0
},
{
"width": 1680,
"height": 1050,
"topLeftX": 0,
"topLeftY": 0
},
{
"width": 1366,
"height": 768,
"topLeftX": 1680,
"topLeftY": 0
}
]
}
],
"channel": 0
},
{
"participantType": "CUSTOMER",
"agentName": null,
"participantId": "68367118",
"userId": null,
"voiceStages": [
{
"stageType": "ACTIVE",
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"segmentID": "e079511b-c077-489e-85a3-24b1b147d3c7",
"displays": null
}
],
"screenStages": [],
"channel": 0
}
],
"segmentsDataList": [
{
"startTime": "2018-11-20T08:20:31.941Z",
"endTime": "2018-11-20T08:25:56.957Z",
"acwEndTime": "2018-11-20T08:27:09.643Z",
"openReasonType": "SEGMENT",
"closeReasonType": "SEGMENT",
"directionType": "OUTBOUND",
"source": null
}
],
"categoryMatchesList": [
{
"categoryHierarchy": [
"Account Inquiries",
"Account Problems"
],
"secondsOffsets": [
24
],
"confidence": 95
}
],
"sentiments": [
{
"overallSentiment": "POSITIVE",
"segmentStartTime": "2018-11-20T08:20:31.941Z",
"channel": 1
},
{
"overallSentiment": "POSITIVE",
"segmentStartTime": "2018-11-20T08:20:31.941Z",
"channel": 0
}
]
}
}
},
{
"Interaction": {
"mediaType": "chat",
"startTime": "2018-11-21T08:27:09.643Z",
"endTime": "2018-11-21T18:20:31.941Z",
"data": {
"startTime": "2018-11-21T08:27:09.643Z",
"endTime": "2018-11-21T18:20:31.941Z",
"transferPoints": [
"2018-11-21T10:34:23.433Z"
],
"participants": [
{
"participantType": "AGENT",
"participantName": "Kevin Allen"
},
{
"participantType": "CUSTOMER",
"participantName": ""
}
],
"messages": [
{
"participantType": "AGENT",
"participantName": "Kevin Allen",
"text": "agent 1",
"timeStamp": "2018-11-21T10:35:23.643Z"
},
{
"participantType": "CUSTOMER",
"participantName": "",
"text": "Betty Alexander"
}
]
}
}
},
{
"Interaction": {
"mediaType": "email",
"startTime": "2018-11-21T18:30:09.643Z",
"endTime": "2018-11-21T18:36:36.347Z",
"data": {
"startTime": "2018-11-21T18:30:09.643Z",
"endTime": "2018-11-21T18:34:56.957Z",
"acwEndTime": "2018-11-21T18:36:36.347Z",
"participants": [
{
"participantType": "AGENT",
"participantName": "Angela Bryant",
"actions": [
{
"timeStamp": "2018-11-21T18:30:09.643Z",
"action": "NewOutbound"
},
{
"timeStamp": "2018-11-21T18:34:56.957Z",
"action": "Send"
}
]
}
],
"content": {
"sentTime": "2018-11-21T18:34:56.957Z",
"from": "doNotAnswer@ourcompany.com",
"to": [
"angelab@yourcompany.com"
],
"cc": [],
"bcc": [],
"subject": "Hello",
"body": "Hi"
}
}
}
}
]
}
}Download
Sample request for download
https://na1.nice-incontact.com/media-playback/v1/contacts?acd-call-id=123456&media-type=all&exclude-waveforms=true&isDownload=true{
"redirectUrl" : "https://na1-mcrplaybackmanager-12345ABCDEF.s3.us-west-2.amazonaws.com/tenant/output_12345ABCDEF.mp4?X-Amz-Security-Token=12345ABCDEF12345X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200820T114056Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=12345ABCDEFus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=12345ABCDEF"
}Responses
-
200 Success
-
400 Invalid Request
-
401 Not Authorized to Play Back
-
403 Permission Required
-
404 Interaction Not Found
-
500 Internal Server Error
A 500 Internal Server Error response with internal error code 8401 indicates a technical limitation in the API. You can play back and download all recordings in the NiCE CXone Player.
GET Statements
Access a recording statement based on ACD Contact ID and Statement ID. The ACD Contact ID depends on the ACD solution, for example, here the acdContactId is the Master Contact ID The master or parent ID for one or more related contacts. A new master contact ID is assigned if a contact is transferred three or more times..
The URL returned by the API is valid for 30 minutes or the duration of the call, whichever is longer.
Sample requests and responses
Responses
-
200 Success
-
400 Invalid Request
-
401 Not Authorized to Play Back
-
403 Permission Required
-
404 Interaction Not Found
-
500 Internal Server Error
GET Segment IDs
Access a recording segment using the Segment ID, independent of the associated contact ID. Segment IDs can be found in Interaction Search or by using the Data Extract API. Only segments in active storage can be accessed. Segments in long-term storage must be moved to active storage before they can be accessed.
Responses
-
Status 200—Successful operation.
-
Status 202—Operation is in process.
-
Status 400—Bad request.
-
Status 401—The requesting user failed to authenticate.
-
Status 403—The requesting user is not authorized to perform the operation.
-
Status 404—Not found. No active interactions were found.
-
Status 425—The interaction is locked while processing a previous request.
-
Status 500—Internal server error.
-
Status 504—The request timed out.