Conversation Records (/record/)

Owned by esnata (Unlicensed)
Last updated: Oct 24, 2022 by Ilya Titaev
6 min read

You can test API methods on the interactive API browser page and without writing code
Some of the resources described on the page may not be available by default due to the type of application (see Creating and authorizing applications).

Description of Data Structures 

The fields of the resource "Conversation Record" are the same as the fields of the resource "Call Date Record (/cdr/)", but, unlike CDRs, the fields record_uuid and record_file_size may never be null.

Name 

Type 

Description 

Name 

Type 

Description 

ani_number  

string 

Number from the list of incoming client numbers 

application  

string 

Application describing the call type. May have value callcenter, callback, intercept, or null 

call_uuid 

string 

Unique call identifier 

client_owner_id 

long 

Identifier of the client that is the message owner 

dest_domain 

string 

Call destination domain 

dest_number 

string 

Call destination number 

did_domain 

string 

External number domain 

did_number 

string 

External number 

duration 

long 

Call duration 

ext_number_reg 

string 

Registered external number 

extension_group_owner_id 

long 

Identifier of the extension number group that owns the message 

extension_id 

long 

Identifier of extension number 

extension_name 

string 

Extension number name 

extension_type 

string 

Extension number type 

flow 

string 

Call direction. May take the value in or out 

from_domain 

string 

Caller original domain 

from_screen_name 

string 

Caller original display name 

from_username 

string 

Caller original username 

hangup_cause 

string 

Call end reason 

hangup_disposition  

string 

Used to determine the disconnection initiator:  
callee_bye: the callee hung up;
callee_bye: the caller hung up;
caller_cancel: the caller refused to wait for an answer; 
callee_refuse: the callee refused to answer (was busy, there was no registration, etc.);
internal_cancel: the call was terminated by the server (usually due to call timeout or if the call was answered by another extension number);
'' (empty): failed to determine

hangup_time_gmt 

string 

Call end time 

init_time_gmt 

string 

Call initialization time 

record_file_size 

long 

Message file size in bytes 

record_uuid 

string 

Identifier of the voice mail message 

result 

string 

Call result 

source_domain 

string 

Call source domain 

source_number 

string 

Call source number 

start_time_gmt 

string 

Call start time 

to_domain 

string 

Destination original domain 

to_username 

string 

Destination original username 

file_name 

string 

Name of the conversation record file  

record_transfer 

bool 

Sign of record during forwarding. In case of "false", the extension number channel is recorded, in case of "true", the channel that is opposite to the extension number is recorded

storage_url

string

Link to the recording file

Retrieving List of Conversation Records

The interval to get and to delete a list is specified by the request options start_datetime and end_datetime. The datetime value in the option end_datetime should not exceed the last day of the month following the start_datetime value. To obtain data for a longer period, you should make several requests.  

When getting the list, you can specify the request parameter order that specifies the direction to sort the resulting list by the field init_time_gmt (in ascending or descending order). 

Request options 

Name 

Type 

Mandatory 

Default Value 

Name 

Type 

Mandatory 

Default Value 

start_datetime 

YYYY-MM-DD HH:MM:SS 

yes 

 

end_datetime 

YYYY-MM-DD HH:MM:SS 

yes 

 

order 

asc or desc 

no 

desc 

Retrieving Statistics of Conversation Records 

Request options 

Name 

Type 

Mandatory 

Default Value 

Name 

Type 

Mandatory 

Default Value 

start_datetime 

YYYY-MM-DD HH:MM:SS 

yes 

 

end_datetime 

YYYY-MM-DD HH:MM:SS 

yes 

 

Fields of Statistics of Conversation Records 

Name 

Type 

Description 

Name 

Type 

Description 

files_size 

long 

Total size of record files 

records_count 

long 

Number of record files 

Retrieving Files of Conversation Records from Storage 

If the system has an external storage of conversation records, then to get a link to a record in the storage, you must use the following method: 
GET /client/{client_id}/record/{record_uuid}/storage_url/. In response, the API will return a URL to get the record from the storage. Retrieving the record from the storage does not require authentication. The link is permanent. 

Retrieving the record files using a repository link is the preferred and most reliable method. 

Example  

Retrieving the link to the record from the storage: 

System response: 

{   "record_url": "https://storage.hostname.ru/bd7zzrXD5395gn7FMgzKtB8zhZnNoYx8BdkX_HgNdeE2lnJjPMLcOR_1hQprGf-dW94wuTCNRAY6MDjMZ0zWIg==" }

Retrieving Files of Conversation Records from API 

To directly receive a conversation record file from a REST API server, you need to make a GET request to the resource corresponding to the required user level, specifying the record identifier:
GET /client/{client_id}/record/{record_uuid}
GET /extension_group/{ext_group_id}/record/{record_uuid}
GET /extension/{extension_id}/record/{record_uuid}

The record file data will be returned in the request body, the file name is contained in the header Content-Disposition. 

Example

System response: 

HTTP/1.0 200 OK Content-Length: 1008 Content-Disposition: attachment; filename=2016-04-18-13-13-47_outbound_0000000000_300.mp3 Server: nginx/1.8.1 Date: Tue, 19 Apr 2016 11:56:19 GMT Content-Type: audio/mpeg
HTTP/1.0 200 OK Content-Length: 1008 Content-Disposition: attachment; filename=2016-04-18-13-13-47_outbound_0000000000_300.mp3 Server: nginx/1.8.1 Date: Tue, 19 Apr 2016 11:56:19 GMT Content-Type: audio/mpeg

Retrieving Files Using Basic HTTP Authentication 

You can access the conversation record files using Basic HTTP Authentication instead of transferring the OAuth2 token. You can see more information in the page "Retrieving Files Using Basic HTTP Authentication". 

Retrieving Archive of Files of Conversation Records 

You can get an archive with several record files for a time period. To do it, you need to use a special API resource:
POST /client/{client_id}/record/archive/
transferring the time range and email address to send the link to download the archive. The size of the files in the archive and the date range are limited. You cannot request a new archive within one hour without downloading the previous one. Possible error codes are listed in subsection "Returned codes and statuses". The conversation recordings for the link will be available for 12 hours. 

JSON Options 

Name 

Type 

Mandatory 

Default Value 

Name 

Type 

Mandatory 

Default Value 

start_datetime 

string (YYYY-MM-DD HH:MM:SS) 

yes 

Start of the range in the format YYYY-MM-DD HH:MM:SS 

end_datetime 

string (YYYY-MM-DD HH:MM:SS) 

yes 

End of the range in the format YYYY-MM-DD HH:MM:SS 

email 

string 

yes 

Email address to send the link to the archive. You may list several addresses separated by commas 

"Client" Section Resources 

GET /client/{client_id}/record/ 

Get the list of the client conversation records for the specified time interval 

URL Options 

Name 

Type 

Name 

Type 

client_id 

string 

Request Options 

Name 

Type 

Name 

Type 

start_datetime 

string 

end_datetime 

string 

order 

string 

Response Fields 

Name 

Type 

Name 

Type 

ani_number  

string 

application  

string 

call_uuid  

string 

client_owner_id 

long 

dest_domain 

string 

dest_number 

string 

did_domain 

string 

did_number 

string 

duration 

long 

ext_number_reg 

string 

extension_group_owner_id 

long 

extension_id 

long 

extension_name 

string 

extension_type 

string 

flow 

string 

from_domain 

string 

from_screen_name 

string 

from_username 

string 

hangup_cause 

string 

hangup_disposition  

string 

hangup_time_gmt 

string 

init_time_gmt 

string 

record_file_size 

long 

record_uuid 

string 

result 

string 

source_domain 

string 

source_number 

string 

start_time_gmt 

string 

to_domain 

string 

to_username 

string 

storage_url

string

DELETE /client/{client_id}/record/ 

Delete the client conversation records for the specified time interval.
If you specify an extension_id in the request parameters, then only those records that belong to this extension will be deleted.

URL Options 

Name 

Type 

Name 

Type 

client_id 

string 

Request Options 

Name 

Type 

Name 

Type 

start_datetime 

string 

end_datetime 

string 

extension_id

array[integer]

POST /client/{client_id}/record/archive/ 

Request the conversation record archive for the period 

URL Options 

Name 

Type 

Name 

Type 

client_id 

string 

JSON Options 

Name 

Type 

Mandatory 

Name 

Type 

Mandatory 

email 

string 

yes 

end_datetime 

string 

yes 

extension_id  

string 

no 

start_datetime 

string 

yes 

Response Fields 

Name 

Type 

Name 

Type 

archive_uuid 

string 

email 

string 

end_datetime 

string 

extension_id  

long 

start_datetime 

string 

GET /client/{client_id}/record/stats/ 

Get statistics for the call records for the specified time interval 

URL Options 

Name 

Type 

Name 

Type 

client_id 

string 

Request Options 

Name 

Type 

Name 

Type 

start_datetime 

string 

end_datetime 

string 

Response Fields 

Name 

Type 

Name 

Type 

files_size 

long 

records_count 

long 

"Extension Number Group" Section Resources 

"Extension Number" Section Resources