Записи разговоров (/record/)

Owned by Asia Khalitova (Unlicensed)
Last updated: Oct 19, 2022 by Ilya Titaev
3 min read

Протестировать методы API можно на странице интерактивного обозревателя API и без написания кода
Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см. Создание и авторизация приложений)

Ресурс записи разговоров позволяет получить список доступных записей разговора клиента или внутреннего номера за определенный период, получить непосредственно файлы записи, а также удалить записи в диапазоне или поштучно.

Описание структур данных

Поля ресурса "Запись разговора" совпадают с полями ресурса “Информация о составных частях вызова (/cdr/)”, но, в отличие от CDR, поля record_uuid и record_file_size никогда не принимают значения null.

Имя

Тип

Описание

Имя

Тип

Описание

ani_number 

string

Номер из списка входящих номеров клиента

application 

string

Приложение, характеризующее тип вызова. Может иметь значение callcenter, callback, intercept или null

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

Направление вызова. Может принимать значение in или out

from_domain

string

Исходный домен вызывающего абонента

from_screen_name

string

Исходное отображаемое имя вызывающего абонента

from_username

string

Исходное имя пользователя вызывающего абонента

hangup_cause

string

Причина окончания вызова

hangup_disposition 

string

Используется для определения инициатора разрыва соединения:
callee_bye: трубку положила принимающая сторона;
caller_bye: трубку положила вызывающая сторона;
caller_cancel: вызывающая сторона отказалась ждать ответа;
callee_refuse: принимающая сторона отказалась отвечать (была занята, отсутствовала регистрация и т.п.);
internal_cancel: вызов завершен сервером (обычно по тайм-ауту вызова или если данный вызовов был принят другим внутренним номером);
'' (пустой вариант): не удалось определить

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

Исходное имя пользователя назначения

file_name

string

Имя файла записи разговора

record_transfer

bool

Признак записи при переадресации. В случае false записывается канал добавочного номера, в случае true- противоположный канал от добавочного.

storage_url

string

Ссылка на файл записи разговора

Получение списка записей разговора

Интервал получения и удаления списка указывается параметрами запроса start_datetime и end_datetime. Дата и время, содержащиеся в параметре end_datetime, не должны превышать последний день следующего за start_datetime месяца. Для получения данных за больший период следует делать несколько запросов. 

При получении списка возможно указать параметр запроса order, который задает направление, в котором результирующий список будет отсортирован по полю init_time_gmt (по возрастанию или по убыванию).

Параметры запроса

Имя

Тип

Обязательный

Значение по умолчанию

Имя

Тип

Обязательный

Значение по умолчанию

start_datetime

YYYY-MM-DD HH:MM:SS

да

 

end_datetime

YYYY-MM-DD HH:MM:SS

да

 

order

asc or desc

нет

desc

Получение статистики записей разговора

Параметры запроса

Имя

Тип

Обязательный

Значение по умолчанию

Имя

Тип

Обязательный

Значение по умолчанию

start_datetime

YYYY-MM-DD HH:MM:SS

да

 

end_datetime

YYYY-MM-DD HH:MM:SS

да

 

Поля статистики записей разговора

Имя

Тип

Описание

Имя

Тип

Описание

files_size

long

Суммарный размер файлов записей

records_count

long

Количество файлов записей

Получение файлов записей разговора из хранилища

Если в системе присутствует внешнее хранилища записей разговора, то для получения ссылки на запись в хранилище необходимо воспользоваться следующим методом:
GET /client/{client_id}/record/{record_uuid}/storage_url/. В ответ API вернёт URL для получения записи из хранилища. Получение записи из хранилища не требует аутентификации. Ссылка является постоянной.

Получение файлов записей с помощью ссылки на хранилище является наиболее предпочтительным и надёжным способом.

Пример

Получение ссылки на запись из хранилища:

Ответ системы:

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

Получение файлов записей разговора из API

Для непосредственного получения файла записи разговора с сервера REST API нужно совершить GET-запрос на соответствующий нужному уровню пользователя ресурс, указав идентификатор записи:
GET /client/{client_id}/record/{record_uuid}
GET /extension_group/{ext_group_id}/record/{record_uuid}
GET /extension/{extension_id}/record/{record_uuid}

Данные файла записи будут возвращены в теле запроса, имя файла содержится в заголовке Content-Disposition.

Пример

Ответ системы:

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-аутентификацию

Существует возможность получить доступ к файлам записей разговоров, используя базовую HTTP-аутентификацию, вместо передачи OAuth2-токена. Подробнее этот способ описан на странице “Получение файлов через базовую HTTP-аутентификацию”.

Получение архива файлов записей разговора

Существует возможность получить архив с множеством файлов записей за период времени. Для этого необходимо воспользоваться специальным ресурсом API:
POST /client/{client_id}/record/archive/
передав в него временной диапазон и адрес электронной почты, на которую будет отправлена ссылка для загрузки архива. В течение часа невозможно запросить новый архив, не загрузив предыдущий. Записи разговора по ссылке будут доступны в течение 12 часов.

Если при запросе на формирование архива вы получите ошибку “размер слишком большой, попробуйте уменьшить количество дней для формирования архива” - то уменьшите диапазон дат и попробуйте еще раз.

Коды возможных ошибок перечислены в подразделе “Возвращаемые коды и статусы”.

Параметры JSON

Имя

Тип

Обяза-тельный

Описание

Имя

Тип

Обяза-тельный

Описание

start_datetime

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

да

Начало диапазона в формате YYYY-MM-DD HH:MM:SS

end_datetime

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

да

Конец диапазона в формате YYYY-MM-DD HH:MM:SS

email

string

да

Адрес электронной почты для отправки ссылки на архив. Возможно перечисление нескольких адресов через запятую

Ресурсы раздела "Клиент"

GET /client/{client_id}/record/

Получить список записей разговора клиента в за заданный интервал времени

Параметры URL

Имя

Тип

Имя

Тип

client_id

string

Параметры запроса

Имя

Тип

Имя

Тип

start_datetime

string

end_datetime

string

order

string

Поля ответа

Имя

Тип

Имя

Тип

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/

Удалить записи разговора клиента за заданный интервал времени.
Если указать extension_id в параметрах запроса, то удалятся только те записи, которые относятся к этому добавочному.

Параметры URL

Имя

Тип

Имя

Тип

client_id

string

Параметры запроса

Имя

Тип

Имя

Тип

start_datetime

string

end_datetime

string

extension_id

array[integer]

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

Запросить архив записей разговора за период

Параметры URL

Имя

Тип

Имя

Тип

client_id

string

Параметры JSON

Имя

Тип

Обязательный

Имя

Тип

Обязательный

email

string

да

end_datetime

string

да

extension_id 

string

нет

start_datetime

string

да

Поля ответа

Имя

Тип

Имя

Тип

archive_uuid

string

email

string

end_datetime

string

extension_id 

long

start_datetime

string

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

Получить статистику по записям разговора за заданный интервал времени

Параметры URL

Имя

Тип

Имя

Тип

client_id

string

Параметры запроса

Имя

Тип

Имя

Тип

start_datetime

string

end_datetime

string

Поля ответа

Имя

Тип

Имя

Тип

files_size

long

records_count

long

Ресурсы раздела "Группа внутренних номеров”

Ресурсы раздела "Внутренний номер”