Conversation Records (/record/)

_{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}_).

The conversation record resource allows you to get a list of available records of a client or extension number for a certain period, to get the record files directly, and also to delete records in a range or per item.

1 Description of Data Structures
2 Retrieving List of Conversation Records
3 Retrieving Statistics of Conversation Records
4 Retrieving Files of Conversation Records from Storage
5 Retrieving Files of Conversation Records from API
6 Retrieving Files Using Basic HTTP Authentication
7 Retrieving Archive of Files of Conversation Records
8 "Client" Section Resources
9 "Extension Number Group" Section Resources
10 "Extension Number" Section Resources

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

Description of Data Structures

Retrieving List of Conversation Records

Retrieving Statistics of Conversation Records

Retrieving Files of Conversation Records from Storage

Retrieving Files of Conversation Records from API

Retrieving Files Using Basic HTTP Authentication

Retrieving Archive of Files of Conversation Records

"Client" Section Resources

"Extension Number Group" Section Resources

"Extension Number" Section Resources