Знакомство

Введение

Настоящий документ описывает Call API, которое позволяет совершать вызовы и управлять ими. API реализован на основе спецификации JSON-RPC 2.0 без поддержки групповых операций.

При запросах к API в качестве транспортного протокола используется HTTP/1.1 с защитой соединения с помощью SSL/TLS, при этом соблюдая следующие требования:

  • Заголовок Content-Type должен быть application/json; charset=UTF-8
  • Заголовок Content-Length должен содержать корректную длину сообщения, следуя спецификации HTTP/1.1

Список методов

Название Стоимость в баллах для дневного ограничения Стоимость в баллах для минутного ограничения Описание
Аутентификация
login.user 1 1 Аутентификация: логин
logout.user 1 1 Аутентификация: логаут
Группа методов создания звонков
start.employee_call 1 1 Вызов на сотрудника
start.scenario_call 1 1 Вызов на сценарий
start.vnumber_call 1 1 Вызов на виртуальный номер
start.informer_call 1 1 Информационный вызов
Группа методов управления звонками
make.call 1 1 Создать звонок для трансфера или консультации
transfer.talk 1 1 Метод позволяет произвести трансфер звонка другому сотруднику (см. раздел "Диаграмма состояний звонка")
restore.talk 1 1 Метод позволяет вернуться в разговор с абонентом после получения консультации от другого сотрудника (см. раздел "Диаграмма состояний звонка")
hold.call 1 1 Постановка вызова на удержание
unhold.call 1 1 Снятие вызова с удержания
add.coach 1 1 Подключение тренера к звонку
tag.call 1 1 Простановка тега для текущего вызова
record.call 1 1 Управление записью разговора
Отключить запись разговора, настроенную через личный кабинет невозможно
disconnect.leg 1 1 Метод позволяет разъединять отдельных участников разговора. Уникальный идентификатор каждого участника разговора можно получить используя метод "list.calls" или Notification Server
send.dtmf 1 1 Отправка DTMF сотрудником
block.contact 1 1 Занести абонента в чёрный список
list.calls 1 1 Получить список активных разговоров
list.talk_options 1 1 Получение списка опций разговора настроенных в Личном кабинете виртуальной АТС
call.talk_option 1 1 Вызов опции разговора, которая настроена в Личном кабинете виртуальной АТС
release.call 1 1 Завершить сессию звонка

Соглашения

Приняты следующие соглашения:

  • Пустые поля всегда возвращаются в ответе со значением null. В случае массива возвращается пустой массив, в случае объекта возвращается пустой объект;
  • Все поля связанные с датой и временем передаются согласно ISO 8601 в формате YYYY-MM-DDT hh:mm:ssZ;
  • Запросы к API выполняются всегда с помощью метода POST;
  • Все параметры в запросах/ответах, а также в структурах данных в формате JSON и название методов именуются в стиле Snake Case - разделение слов через нижнее подчёркивание;
  • Данные возвращаются только в JSON формате согласно спецификации RFC 7159;
  • Кодировка данных UTF-8;

Формат возвращаемых данных

Формат MIME Type
JSON application/json
По умолчанию используется формат JSON. Заголовок Accept игнорируется

Базовый URL для доступа к API

Базовый URI для доступа к API:

https://callapi.uiscom.ru/<version>

или

https://callapi.comagic.ru/<version>

где

<version> - версия API (см. раздел Версионность)


Версионность

Call API поддерживает версионность. Версия указывается в базовом URL как vX.Y, где X - номер мажорной версии, Y - номер минорной версии

Версия должна указываться через точку, к примеру 4.0
Если была выпущена новая версия, то старая считается устаревшей и соответственно при обращении к старой версии API в мета-параметрах (см. раздел Мета-параметры) будет возвращаться параметр current_version_depricated со значением true. Это говорит о том, что в ближайшие пару месяцев старая версия может стать недоступна.

Пример:

https://callapi.comagic.ru/v4.0 \b https://callapi.comagic.ru/v4.0
Максимальное количество поддерживаемых версий - 2
Период поддержки устаревшей версии 2 месяца

Лимиты и ограничения

Баллы списываются только за успешные запросы, т.е в отчете по запросам он помечен как успешный. Успешным считается запрос, если в result был возвращен статус success = true или идентификатор сессии звонка

Лимиты привязаны к базовому компоненту callapi (см. Компоненты) и учитываются в зависимости от веса метода

Информация о лимитах возвращается во всех ответах в мета-парметрах (см. Мета-параметры), кроме случаев когда лимиты не учитываются;

Лимиты построены по бальной системе, т.е каждый метод имеет свой вес. Вызов метода уменьшает доступные дневные/минутные балы на размер веса вызываемого метода

Лимиты возвращаются на каждый успешный/ошибочный ответ в мета-параметрах, см. раздел "Мета-параметры"


Название параметра Описание
day_limit Текущие лимит запросов в день
day_remaining Какое количество запросов осталось до достижения дневного лимита
day_reset Время в секундах через которое дневной лимит будет сброшен
minute_limit Текущие лимит запросов за минуту
minute_remaining Какое количество запросов осталось до достижения минутного лимита
minute_reset Время в секундах через которое минутный лимит будет сброшен

Расширение лимитов

Название лимитов:

  • Баллов Call API в минуту;
  • Баллов Call API в день;
  • Длина TTS сообщения.

Лимитами можно управлять на странице "Аккаунт" -> "Тарифы и опции".

Управление безопасностью по направлениям звонка

Управление безопасностю для направления звонка сгенерированного Call API производится на странице
"Аккаунт" -> "Правила и настройки безопасности". По умолчанию запрещено международное направление, остальные направления разрешены.

Разрешения разбиты по компонентам Call API


Мета-параметры

Возвращаются в ответ на вызов метода. Присутствуют как в ошибочном, так и в успешном ответе
Параметр api_version возвращается только для версий которые deprecated.

JSON структура:

						"metadata": {
                            "api_version": {
                            "current_version_depricated": "boolean",
                            "current_version": "string", // Вызванная версия, example: 1.0
                            "latest_version": "string" // Последняя доступная версия, example 2.0
                            },
                            "limits": {
                            "day_limit": "number", // Текущие лимит запросов в день
                            "day_remaining": "number", // Какое количество запросов осталось до достижения дневного лимита
                            "day_reset": "number", // Время в секундах через которое дневной лимит будет сброшен
                            "minute_limit": "number", // Текущие лимит запросов за минуту
                            "minute_remaining": "number", // Какое количество запросов осталось до достижения минутного лимита
                            "minute_reset": "number" // Время в секундах через которое минутный лимит будет сброшен
                            }
                            }

Компоненты

Название для клиента Список методов Описание
Call API Базовый набор start.employee_call, start.vnumber_call, login.user, logout.user, release.call Базовый пакет Call API
Call API Управление вызовами hold.call, unhold.call, make.call, disconnect.leg, tag.call, record.call, add.coach, list.calls, send.dtmf, block.contact, restore.talk, transfer.talk, list.talk_options, call.talk_option Пакет позволяет управлять звонками.
Call API Информационный вызов start.informer_call Пакет, который позволяет обзванивать клиентов и проигрывать им TTS или какой-то предустановленный файл. После окончания информационного сообщения вызов завершается
Call API Вызов сценария start.scenario_call Пакет, который позволяет совершать вызовы клиенту с использованием одного виртуального номера и набора сценариев.

Пользователи Call API

В разделе "Управление пользователями" при подключённом компоненте callapi появляется возможность выбора нового набора прав доступа в виде чек-бокса "Доступ к Call API".

Все эти действия могут быть выполнены только администратором.

Доступ по ключу

В веб-интерфейсе, в разделе "Аккаунт"-> "Call API", есть вкладка "Ключи доступа". Доступ к вкладке имеет только администратор аккаунта. На данной вкладке можно сгенерировать постоянный ключ (access_token) для доступа к Call API. При генерировании постоянного ключа доступа можно выбрать уровень доступа к Call API. На текущий момент уровень доступа будет один "Доступ к Call API", т.е неограниченный доступ к методам Call API

Доступ по логину и паролю

Используется аутентификация с использованием сессий

Время жизни сессии по умолчанию 1 час.

Статистика и отчёты

Изменения в отчёте "Звонки"

В отчётах ЛК "Список обращений" -> "Звонки" в качестве доступных столбцов, помимо основных колонок, доступны следующие столбцы:

Название поля в методах Название поля в отчётах
callapi_external_id Идентификатор звонка во внешней системе
call_session_id Идентификатор сессии звонка

Общее

Общие поля для всех методов

Название Тип Обязательный Допустимые значения Описание
id string или number да

Уникальный идентификатор запроса к API.

Не передается в уведомлениях. Фигурирует только в "Отчет по запросам к API" параметр request_id
method string да Вызываемый метод (см. Список методов)
jsonrpc string да 2.0 Номер спецификации JSON-RPC
params object да Содержит тело запроса к API. В зависимости от вызываемого метода тело запроса меняется.

Диаграмма состояний звонка

Аутентификация

Логин

Метод login.user
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
login string да Логин пользователя
password string да Пароль пользователя

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
expire_at number да Timestamp когда выданный токен перестанет быть валидным
Время жизни полученного ключа сессии аутентификации после вызова метода login.user - 1 час. По истечению времени жизни ключа сессии его необходимо запрашивать заново, т.е. вызывать метод login.user.
Для совершения запросов к API возможно использование постоянного ключа аутентификации, который доступен в Личном кабинете.

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "method": "login.user",
                            "params": {
                            "login": "string",
                            "password": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "access_token": "string",
                            "expire_at": "number"
                            }
                            }
                            }

Логаут

Метод logout.user
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "method": "logout.user",
                            "params": {
                            "access_token": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Группа методов создания звонков

Вызов на сотрудника

Метод start.employee_call
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
first_call string да contact, employee

Определяет номер, на который нужно дозвониться в первую очередь:

  • employee - сотрудник;
  • contact - вызываемая сторона (обычно клиент);
switch_at_once boolean нет true, false

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

Если параметр first_call имеет значение employee и задан параметр employee_message, то звонок совершается сотруднику, сотрудник после поднятия трубки слушает сообщение до конца, потом совершается звонок на contact и если параметр switch_at_once имеет значение true и задана параметр contact_message, то для плеча contact проигрывание сообщения будет прервано. Во время дозвона до contact employee слушает сообщение заданное в параметре media_file_id. Соответственно, если switch_at_once имеет значение false и задан параметр contact_message, то для плеча contact сообщение будет проиграно до конца.

Если параметр first_call имеет значение contact и задан параметр contact_message, то звонок совершается клиенту, клиент после поднятия трубки начинает слушать сообщение и в это же время совершается звонок на employee и если параметр switch_at_once имеет значение true и задан параметр employee_message, то после поднятия трубки на employee проигрывание сообщений будет прервано для contact и employee.Соответственно, если switch_at_once имеет значение false, то для плеча contact и employee сообщение будет проиграно до конца. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.

Если параметр first_call имеет значение any и заданы параметры contact_message и employee_message, то звонок совершается одновременно на contact и employee, то после поднятия трубки на обоих плечах анализируется параметр switch_at_once. Если он имеет значение true, то проигрывание сообщения будет прервано на обоих плечах. Соответственно, если switch_at_once имеет значение false то сообщение будет дослушано на обоих плечах. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.
media_file_id number нет

Значение по умолчанию - системная мелодия "Музыка переадресации (dialing_music)".

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

В случает отсутствия файла возвращается ошибка -32602
(см. раздел Коды ошибок)
virtual_phone_number string да

Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, 74993720692). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре contact. Используется в качестве номера звонящего при звонке на номер, указанный в параметре employee, если параметр show_virtual_phone_number имеет значение true. Список виртуальных номеров можно получить с помощью REST API метода.

В случает ошибки возвращается код -32007
(см. раздел Коды ошибок)
В качестве виртуального номера запрещено использовать номер 8800
Динамические виртуальные номера запрещено использовать
show_virtual_phone_number boolean нет true, false

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

Показывать ли виртуальный номер, заданный параметром virtual_phone_number в качестве номера звонящего абонента для сотрудника заданного в параметре employee.
contact string да

Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, 79091234567).

В случает ошибки возвращается код -32602
(см. раздел Коды ошибок)
external_id string нет Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string string нет 0-9, *, # Задаёт цифры DTMF, которые будут отправлены абоненту, который задан в параметре contact. С помощью символа . = '1s' можно задать таймаут по истечению которого цифра будет отправлена, если таймаут не используется, то считается, что это один набор цифр. Пример: .12.1..4, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
direction string нет in, out Значение по умолчанию out. Определяет тип сессии звонка in - входящая, out - исходящая. Если задано значение in, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Входящий звонок, если задано значение out, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Исходящий звонок.
Сотрудник с которым будет соединён абонент из параметра contact
employee object да Сотрудник с которым будет соединён абонент, указанный в параметре contact.
id number да Уникальный идентификатор сотрудника. Данный идентификатор можно получить с помощью REST API метода. Если не указан параметр phone_number, то будет совершен последовательный обзвон всех активных номеров сотрудника.
phone_number string нет

Задаёт конкретный номер сотрудника с которым будет соединен абонент указанный в параметре contact. В качестве номера может быть указан SIP-номер, внутренний номер, номер в формате E.164. Номер должен иметь статус Активен в личном кабинете и принадлежать сотруднику заданному в параметре id.

Если номер не принадлежит сотруднику возвращается ошибка -32602 (см. раздел Коды ошибок)
Сообщение для проигрывания абоненту, который задан в параметре contact
contact_message object нет

Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре contact.

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech
Сообщение для проигрывания абоненту, который задан в параметре employee
employee_message object нет

Определяет параметры сообщение, которое необходимо проиграть абоненту, который задан в параметре employee

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - медиафайл или tts - текст для услуги синтеза речи Text-to-Speech

Проверять что компонент Text-to-Speech подключён у клиента. Если компонент не подключён возвращать ошибку с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "start.employee_call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "first_call": "string",
                            "switch_at_once": "boolean",
                            "media_file_id": "number",
                            "show_virtual_phone_number": "boolean",
                            "virtual_phone_number": "string",
                            "external_id": "string",
                            "dtmf_string": "string",
                            "direction": "string",
                            "contact": "string",
                            "employee": {
                            "id": "number",
                            "phone_number": "string"
                            },
                            "contact_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            },
                            "employee_message": {
                            "type": "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "call_session_id": "number"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника Описание
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found
Employee with id {employee_id} not found. It is not your employee. -32602 employee_not_found
The phone number does not exist or inactive -32602 no_active_phone_number
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Звонок на собственный виртуальный номер запрещён
The contact {contact} has been found in the blacklist -32002 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

См. также раздел Список ошибок общих для всех методов


Вызов на сценарий

Метод start.scenario_call
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
virtual_phone_number string да

Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, 74993720692). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре contact. Используется в качестве номера звонящего при звонке на номер, указанный в параметре employee, если параметр show_virtual_phone_number имеет значение true. Список виртуальных номеров можно получить с помощью REST API метода.

В случает ошибки возвращается код -32007
(см. раздел Коды ошибок)
В качестве виртуального номера запрещено использовать номер 8800
Динамические виртуальные номера запрещено использовать
external_id string нет Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string string нет 0-9, *, # Задаёт цифры DTMF, которые будут отправлены абоненту, который задан в параметре contact. С помощью символа . = '1s' можно задать таймаут по истечению которого цифра будет отправлена, если таймаут не используется, то считается, что это один набор цифр. Пример: .12.1..4, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
contact string да

Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, 79091234567).

В случает ошибки возвращается код -32602
(см. раздел Коды ошибок)
Если номер находится в чёрном списке возвращается -32002 (см. раздел Коды ошибок)
first_call string да contact, employee

Определяет номер, на который нужно дозвониться в первую очередь:

  • employee - сотрудник;
  • contact - вызываемая сторона (обычно клиент);
switch_at_once boolean нет true, false

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

Если параметр first_call имеет значение employee и задан параметр employee_message, то звонок совершается сотруднику, сотрудник после поднятия трубки слушает сообщение до конца, потом совершается звонок на contact и если параметр switch_at_once имеет значение true и задана параметр contact_message, то для плеча contact проигрывание сообщения будет прервано. Во время дозвона до contact employee слушает сообщение заданное в параметре media_file_id. Соответственно, если switch_at_once имеет значение false и задан параметр contact_message, то для плеча contact сообщение будет проиграно до конца.

Если параметр first_call имеет значение contact и задан параметр contact_message, то звонок совершается клиенту, клиент после поднятия трубки начинает слушать сообщение и в это же время совершается звонок на employee и если параметр switch_at_once имеет значение true и задан параметр employee_message, то после поднятия трубки на employee проигрывание сообщений будет прервано для contact и employee.Соответственно, если switch_at_once имеет значение false, то для плеча contact и employee сообщение будет проиграно до конца. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.

Если параметр first_call имеет значение any и заданы параметры contact_message и employee_message, то звонок совершается одновременно на contact и employee, то после поднятия трубки на обоих плечах анализируется параметр switch_at_once. Если он имеет значение true, то проигрывание сообщения будет прервано на обоих плечах. Соответственно, если switch_at_once имеет значение false то сообщение будет дослушано на обоих плечах. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.
show_virtual_phone_number boolean нет true, false

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

Показывать ли виртуальный номер, заданный параметром virtual_phone_number в качестве номера звонящего абонента для сотрудника заданного в параметре employee.
scenario_id number да Уникальный идентификатор сценария, который может быть получен/создан с помощью REST API метода.
direction string нет in, out Значение по умолчанию out. Определяет тип сессии звонка in - входящая, out - исходящая. Если задано значение in, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Входящий звонок, если задано значение out, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Исходящий звонок.
Сообщение для проигрывания абоненту, который задан в параметре contact
contact_message object нет

Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре contact.

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "start.scenario_call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "virtual_phone_number": "string",
                            "external_id": "string",
                            "dtmf_string": "string",
                            "contact": "string",
                            "first_call": "string",
                            "switch_at_once": "boolean",
                            "show_virtual_phone_number": "boolean",
                            "scenario_id": "number",
                            "direction": "string",
                            "contact_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "call_session_id": "number"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found
Scenario with id {scenario_id} not found -32602 scenario_not_found
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Звонок на собственный виртуальный номер запрещён
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

См. также раздел Список ошибок общих для всех методов


Вызов на виртуальный номер

Метод start.vnumber_call
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
virtual_phone_number string да

Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, 74993720692). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре contact. Используется в качестве номера звонящего при звонке на номер, указанный в параметре employee, если параметр show_virtual_phone_number имеет значение true. Список виртуальных номеров можно получить с помощью REST API метода.

В случает ошибки возвращается код -32007
(см. раздел Коды ошибок)
В качестве виртуального номера запрещено использовать номер 8800
Динамические виртуальные номера запрещено использовать
external_id string нет Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string string нет 0-9, *, # Задаёт цифры DTMF, которые будут отправлены абоненту, который задан в параметре contact. С помощью символа . = '1s' можно задать таймаут по истечению которого цифра будет отправлена, если таймаут не используется, то считается, что это один набор цифр. Пример: .12.1..4, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
direction string нет in, out Значение по умолчанию out. Определяет тип сессии звонка in - входящая, out - исходящая. Если задано значение in, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Входящий звонок, если задано значение out, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Исходящий звонок.
contact string да

Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, 79091234567).

В случает ошибки возвращается код -32602
(см. раздел Коды ошибок)
Если номер находится в чёрном списке возвращается -32002 (см. раздел Коды ошибок)
first_call string да contact, employee

Определяет номер, на который нужно дозвониться в первую очередь:

  • employee - сотрудник;
  • contact - вызываемая сторона (обычно клиент);
switch_at_once boolean нет true, false

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

Если параметр first_call имеет значение employee и задан параметр employee_message, то звонок совершается сотруднику, сотрудник после поднятия трубки слушает сообщение до конца, потом совершается звонок на contact и если параметр switch_at_once имеет значение true и задана параметр contact_message, то для плеча contact проигрывание сообщения будет прервано. Во время дозвона до contact employee слушает сообщение заданное в параметре media_file_id. Соответственно, если switch_at_once имеет значение false и задан параметр contact_message, то для плеча contact сообщение будет проиграно до конца.

Если параметр first_call имеет значение contact и задан параметр contact_message, то звонок совершается клиенту, клиент после поднятия трубки начинает слушать сообщение и в это же время совершается звонок на employee и если параметр switch_at_once имеет значение true и задан параметр employee_message, то после поднятия трубки на employee проигрывание сообщений будет прервано для contact и employee.Соответственно, если switch_at_once имеет значение false, то для плеча contact и employee сообщение будет проиграно до конца. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.

Если параметр first_call имеет значение any и заданы параметры contact_message и employee_message, то звонок совершается одновременно на contact и employee, то после поднятия трубки на обоих плечах анализируется параметр switch_at_once. Если он имеет значение true, то проигрывание сообщения будет прервано на обоих плечах. Соответственно, если switch_at_once имеет значение false то сообщение будет дослушано на обоих плечах. Если у кого-то плеча проигрывание сообщения закончилось раньше, то он слушает промт, заданный в параметре media_file_id.
show_virtual_phone_number boolean нет true, false

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

Показывать ли виртуальный номер, заданный параметром virtual_phone_number в качестве номера звонящего абонента для сотрудника заданного в параметре employee.
Сообщение для проигрывания абоненту, который задан в параметре contact
contact_message object нет

Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре contact.

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "start.vnumber_call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "virtual_phone_number": "string",
                            "external_id": "string",
                            "dtmf_string": "string",
                            "direction": "string",
                            "contact": "string",
                            "first_call": "string",
                            "switch_at_once": "boolean",
                            "show_virtual_phone_number": "boolean",
                            "contact_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "call_session_id": "number"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found
Virtual phone number does not have a scenario -32007 scenario_not_found
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Звонок на собственный виртуальный номер запрещён
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

См. также раздел Список ошибок общих для всех методов


Информационный вызов

Метод start.informer_call
Версия API v4
Статус Реализован
Вернуться к списку методов
После окончания сообщения для проигрывания абоненту вызов завершается.

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
virtual_phone_number string да

Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, 74993720692). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре contact. Используется в качестве номера звонящего при звонке на номер, указанный в параметре employee, если параметр show_virtual_phone_number имеет значение true. Список виртуальных номеров можно получить с помощью REST API метода.

В случает ошибки возвращается код -32007
(см. раздел Коды ошибок)
В качестве виртуального номера запрещено использовать номер 8800
Динамические виртуальные номера запрещено использовать
external_id string нет Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string string нет 0-9, *, # Задаёт цифры DTMF, которые будут отправлены абоненту, который задан в параметре contact. С помощью символа . = '1s' можно задать таймаут по истечению которого цифра будет отправлена, если таймаут не используется, то считается, что это один набор цифр. Пример: .12.1..4, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
direction string нет in, out Значение по умолчанию out. Определяет тип сессии звонка in - входящая, out - исходящая. Если задано значение in, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Входящий звонок, если задано значение out, то для отслеживания таких вызовов через уведомления необходимо создать уведомление Исходящий звонок.
dialing_timeout number нет до 120 секунд Значение по умолчанию 30. Время дозвона до номера (до получения answer), заданного в параметре contact. Время задаётся в секундах.
contact string да

Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, 79091234567).

В случает ошибки возвращается код -32602
(см. раздел Коды ошибок)
Если номер находится в чёрном списке возвращается -32002 (см. раздел Коды ошибок)
Сообщение для проигрывания абоненту, который задан в параметре contact
contact_message object нет

Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре contact.

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "start.informer_call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "virtual_phone_number": "string",
                            "external_id": "string",
                            "dtmf_string": "string",
                            "direction": "string",
                            "dialing_timeout": "number",
                            "contact": "string",
                            "contact_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "call_session_id": "number"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Звонок на собственный виртуальный номер запрещён
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

См. также раздел Список ошибок общих для всех методов

Группа методов управления звонками

Создать звонок для трансфера или консультации

Метод make.call
Версия API v4
Статус Реализован
Вернуться к списку методов
Метод доступен только после использования метода "hold.call", см. раздел "Диаграмма состояний звонка"

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
to string да

Номер абонента на который совершаем звонок. Формат номера должен соответствовать международному стандарту E.164

Может быть внутренний номер, внешний номер, номер сотрудника, sip-номер
Номер не может быть виртуальным номером.
Сообщение для проигрывания абоненту, который задан в параметре to
to_message object нет

Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре to.

Абонент (А) будет ожидать ответа, пока не будет прослушано сообщение до конца
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "make.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "to": "string",
                            "to_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state Метод может быть вызван только после метода hold.call
The media file with id {media_file_id} not found -32602 media_file_not_found
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The character encoding must be UTF-8 -32602 character_encoding_not_allowed
The phone number does not exist or inactive -32602 no_active_phone_number

См. также раздел Список ошибок общих для всех методов


Сделать трансфер звонка

Метод transfer.talk
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "transfer.talk",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state Метод может быть вызван, только после метода hold.call и в состоянии dialing или operator_talk (см. Диаграмма состояний звонка)

См. также раздел Список ошибок общих для всех методов


Возвращение в разговор

Метод restore.talk
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "restore.talk",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state Метод может быть вызван, только после метода hold.call и в состоянии dialing или operator_talk (см. Диаграмма состояний звонка)

См. также раздел Список ошибок общих для всех методов


Постановка вызова на удержание

Метод hold.call
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
to string да

Номер абонента на который совершаем звонок. Формат номера должен соответствовать международному стандарту E.164

Может быть внутренний номер, внешний номер, номер сотрудника, sip-номер
Номер не может быть виртуальным номером.
Проигрывание сообщения вызывающему абоненту
contact_message object нет

Определяет настройки для проигрывания вызывающему абоненту.

После окончания проигрывая сообщения будет проигрываться музыка переадресации
type string да media, tts

Тип сообщения. media - файл или tts - текст для услуги синтеза речи Text-to-Speech.

Если компонент не подключён возвращается ошибка с кодом -32008 (см. раздел Коды ошибок)
value string да

Если поле type имеет значение media, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью REST API метода.

Если поле type имеет значение tts, то в качестве значения принимается текст для синтезирования его в голосовое сообщение.

Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
В случает отсутствия файла возвращается ошибка -32602 (см. раздел Коды ошибок)
language string нет ru

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

Задаёт языковую схему для функционала Text-to-Speech

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "hold.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "contact_message": {
                            "type" "string",
                            "value": "string",
                            "language": "string"
                            }
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state Метод может быть вызван только в состоянии Talk (см. Диаграмма состояний звонка)
The media file with id {media_file_id} not found -32602 media_file_not_found
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

См. также раздел Список ошибок общих для всех методов


Снятие вызова с удержания

Метод unhold.call
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "unhold.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state Метод может быть вызван только в состоянии hold (см. Диаграмма состояний звонка)

См. также раздел Список ошибок общих для всех методов


Простановка тэга

Метод tag.call
Версия API v4
Статус Реализован
Вернуться к списку методов
Метод позволяет проставить тег существующему звонку

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
tag_id number да Уникальный идентификатор тега, который можно получить с помощью REST API метода

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "tag.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "tag_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
Tag with {tag_id} not found -32602 tag_not_found
Duplicate tag -32602 duplicate_tag

См. также раздел Список ошибок общих для всех методов


Завершение разговора отдельного участника

Метод disconnect.leg
Версия API v4
Статус Реализован
Вернуться к списку методов
Завершение плеча contact (см. методы start.employee_call, start.scenario_call, start.informer_call, start.vnumber_call) приводит к завершению всей сессии звонка

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
leg_id number да Уникальный идентификатор участника разговора, который может быть получен по средствам Notification Server

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "disconnect.leg",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "leg_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The call's leg not found -32602 leg_not_found

См. также раздел Список ошибок общих для всех методов


Подключение тренера к звонку

Метод add.coach
Версия API v4
Статус Реализован
Вернуться к списку методов
Метод позволяет подключить тренера к звонку, который задан в личном кабинете или просто по указанному номеру

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
phone_number string нет Номер тренера, если не используется тренер указанный в личном кабинете.
Если номер тренера не задан, то подключается тренер указанный в личном кабинете в настройках сотрудника

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "add.coach",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "phone_number": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The coach not found in your settings -32602 coach_not_found
The phone number does not exist or inactive -32602 no_active_phone_number

См. также раздел Список ошибок общих для всех методов


Управление записью разговора

Метод record.call
Версия API v4
Статус Реализован
Вернуться к списку методов
Метод позволяет управлять записью существующего разговора

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
action string да on, off Действие над записью разговора. on - включение записи разговора, off - выключение записи разговора

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "record.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "action": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
Permission denied -32003 forbidden Невозможно отключить глобальную запись разговора на уровне настройки сотрудника
The call record is already started -32602 record_already_started Запись разговора уже включена
The call record is not enabled -32602 record_already_stopped Запись разговора не была включена

См. также раздел Список ошибок общих для всех методов


Занести абонента в чёрный список

Метод block.contact
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "block.contact",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The contact with phone number {contact_phone_number} already exists -32602 duplicate_contact

См. также раздел Список ошибок общих для всех методов


Использование опций разговора

Повторный вызов отдельных опций разговора отключает их, примерами таких опций являются Диктофон, Позвонить тренеру (см. метод list.talk_options)
Метод call.talk_option
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
button string да Клавиша, вызывающая опцию разговора.

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "call.talk_option",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "button": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
This method can not be called in this state -32004 invalid_state
Internal error, contact the support service -32603 internal_error
Permission denied -32003 forbidden Невозможно отключить глобальную запись разговора на уровне настройки сотрудника
Call session not found -32602 call_session_not_found
Talk option not found -32602 talk_option_not_found Клавиша не назначена

См. также раздел Список ошибок общих для всех методов


Отправка DTMF сотрудником

Метод send.dtmf
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
dtmf_string string да 0-9, *, # Задаёт цифры DTMF, которые будут отправлены абоненту, который задан в параметре contact.
leg_id number нет В данном параметре указывается уникальный идентификатор участника разговора, который может быть получен по средствам Notification Server, в который будет отправлен dtmf. Если данный параметр не указан, то dtmf будет отправлен от имени сотрудника в сторону абонента, который указан в параметре contact.

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "send.dtmf",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number",
                            "dtmf_string": "string",
                            "leg_id": "number"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Список возвращаемых ошибок

Текст ошибки Код ошибки Мнемоника ошибки Описание
The call's leg not found -32602 leg_not_found

См. также раздел Список ошибок общих для всех методов


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

Метод list.talk_options
Версия API v4
Статус Реализован
Вернуться к списку методов

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

Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации

Параметры ответа

Название Тип Обязательный Допустимые значения Описание
button string да Клавиша, которая вызывает опцию разговора
mnemonic string да Мнемоническое имя опции разговора
name string да Название опции разговора
Значение опции
button_value object нет Некоторые опции могут содержать название тега, название сценария и т.д. Данный объект содержит дополнительную информацию об опции разговора
id number да Уникальный идентификатор объекта, котрый активируется при вызове опции разговора. К примеру, идентификатор сценария
value string да Название объекта, который активируется при вызове опции разговора. К примеру, название сценария

JSON структура запроса

						{
                            "jsonrpc": "2.0",
                            "method": "list.talk_options",
                            "id": "number",
                            "params": {
                            "access_token": "string"
                            }
                            }

JSON структура ответа

						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": [
                            {
                            "button": "string",
                            "mnemonic": "string",
                            "name": "string",
                            "button_value": {
                            "id": "number",
                            "value": "string"
                            }
                            }
                            ]
                            }
                            }

Получить список активных разговоров

Метод list.calls
Версия API v4
Статус Реализован
Вернуться к списку методов
Параметры запроса
Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
direction string нет in, out Указывает какие сессии выводить - входящие, исходящие. Если параметр не задан, то выводятся все сессии
virtual_phone_number string нет Указывает с каким виртуальным номер сессии выводить.
Номер должен начинаться с 7
Параметры ответа
Название Тип Обязательный Допустимые значения Описание
call_session_id number да Уникальный идентификатор сессии звонка
direction string да in, out Направление сесси звонка
start_time string да Время начала вызова. Формат YYYY-MM-DD hh:mm:ss
virtual_phone_number string да Виртуальный номер, который был использован как номер представления.
contact_phone_number string да Номер абонента
external_id string да Уникальный идентификатор запроса во внешней системе клиента
Список проставленных тегов
tags array да Массив проставленных тегов
tag_id number да Уникальный идентификатор тега
tag_name string да Имя тега
Участники сессии звонка
legs array да Список участников сессии звонка
leg_id number да Уникальный идентификатор плеча
calling_phone_number string да Номер вызывающего абонента
called_phone_number string да Номер вызываемого абонента
is_operator boolean да true, false Признак, который идентифицирует плечо, у которого есть права на выполнение опций разговора
employee_id number да Уникальный идентификатор сотрудника
employee_full_name string да Ф.И.О сотрудника
record_call_enabled boolean да true, false

Включена/Выключена запись разговора.
true - включена, false - выключена

Событие Состояние
record_started true
record_finished false
state string да

Состояние участника разговора

Событие Состояние
call_accepted, call_enqueued Необходимо учитывать direction сессии звонка. Если direction = in, то состояние На очереди, если direction=out, то состояние Дозвон
talk_started Разговор
call_placed, call_proceeding Дозвон
call_disconnected Разъединено
transfer_talk_started Разговор операторов
call_held На удержании
call_transferred Перевод вызова
dtmf Отправка dtmf
fax_receive_started Получение факса
fax_receive_finished Факс получен
fax_send_started Отправка факса
fax_send_finished Факс отправлен
JSON структура запроса
						{
                            "jsonrpc": "2.0",
                            "method": "list.calls",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "direction": "string",
                            "virtual_phone_number": "string"
                            }
                            }
JSON структура ответа
						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": [
                            {
                            "call_session_id": "number",
                            "direction": "string",
                            "start_time": "string",
                            "virtual_phone_number": "string",
                            "contact_phone_number": "string",
                            "external_id": "string",
                            "tags": [
                            {
                            "tag_id": "number",
                            "tag_name": "string"
                            }
                            ],
                            "legs": [
                            {
                            "leg_id": "number",
                            "calling_phone_number": "string",
                            "called_phone_number": "string",
                            "is_operator": "boolean",
                            "employee_id": "number",
                            "employee_full_name": "string",
                            "record_call_enabled": "boolean",
                            "state": "string"
                            }
                            ]
                            }
                            ]
                            }
                            }

Завершение сессии звонка

Метод release.call
Версия API v4
Статус Реализован
Вернуться к списку методов
Параметры запроса
Название Тип Обязательный Допустимые значения Описание
access_token string да Ключ сессии аутентификации
call_session_id number да Уникальный идентификатор сессии звонка
JSON структура запроса
						{
                            "jsonrpc": "2.0",
                            "method": "release.call",
                            "id": "number",
                            "params": {
                            "access_token": "string",
                            "call_session_id": "number"
                            }
                            }
JSON структура ответа
						{
                            "jsonrpc": "2.0",
                            "id": "number",
                            "result": {
                            "data": {
                            "success": "true"
                            }
                            }
                            }

Сообщения об ошибках

Название Тип Обязательный Допустимые значения Описание
error object да Объект с содержимым ошибки
code number да Код ошибки (см. раздел Коды ошибок)
message string да Сообщение об ошибке (см. раздел Коды ошибок)
data object да Объект с деталями ошибки
mnemonic string да Уникальный текстовый код ошибки
field string нет

Название параметра, с которым связана ошибка

Вложенные параметры отображаем через разделитель "точка": .

К примеру: employee.phone_number
value string нет

Содержит то, что передал пользователь без изменений

В некоторых случаях может отсутствовать. К примеру, обязательный параметр вообще не был заполнен.
params object нет Карта подстановок параметров для шаблона с текстом об ошибке. Т.е. содержит динамически изменяемые значения, к примеру, лимиты, длина TTS сообщения. Значения указанные в этом параметре могут быть использованы в сообщениях об ошибках в интерфейсе над Call API (рабочее место оператора).
extended_helper string нет Ссылка на более подробное описание ошибки и возможные решения

JSON структура ошибки

						{
                            "jsonrpc": "2.0",
                            "id": null,
                            "error": {
                            "code": "number",
                            "message": "string",
                            "data": {
                            "mnemonic": "string",
                            "field": "string",
                            "value": "string",
                            "params": {
                            "object": "string"
                            },
                            "extended_helper": "string"
                            }
                            }
                            }

Группы кодов ошибок

Код ошибки Описание
-32700 Ошибки связанные с валидацией JSON
-32600 Ошибки связанные с валидацией параметров запроса - id, jsonrpc
-32601 Ошибки связанные с методом
-32602 Ошибки связанные с валидацией параметров в вызываемом методе
-32603 Внутренние ошибки JSON RPC сервера
-32001 Ошибки аутентификации и ошибки с ключами
-32002 Ошибки связанные с: правила безопасности запрещают звонок по указанному направлению (см. раздел Правила безопасности) и черным списком
-32003 Ошибки с правами доступа - ip адрес не в белом списке, нет прав у пользователя
-32004 Ошибки связанные с неверной последовательностью вызываемых методов
-32007 Ошибки связанные с виртуальным номером
-32008 Ошибки связанные с компонентами
-32009 Ошибки связанные с аккаунтом заказчика
-32029 Ошибки связанные с лимитами
-32099 Ошибки связанные с поддержкой различных частей спецификации JSON RPC 2.0 - Групповые операции, Уведомления

Список ошибок общих для всех методов

Текст сообщения Код Мнемоника Описание
Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Ошибки связанные с валидацией параметров запроса - id, jsonrpc
Access token has been expired -32001 access_token_expired Применяется только к постоянному токену. Если время жизни постоянного токена истекло, то возвращается указанная ошибка
Access token has been blocked -32001 access_token_blocked Если постоянный токен заблокирован, то возвращается указанная ошибка
Access token is invalid -32001 access_token_invalid Указанная ошибка возвращается, если постоянный/временный токен не найден
Limit per {limit_type} has been exceeded. Value of current limit per {limit_type} is {limit_max_value} -32029 limit_exceeded
Component {component_name} has been disabled -32008 component_disabled
Your IP {ip} is not whitelisted -32003 ip_not_whitelisted
Login or password is wrong -32001 auth_error
Your account has been disabled, contact the support service -32009 account_inactive Аккаунт заблокирован
Call session not found -32602 call_session_not_found Если передали ID сессии, который неизвестен
Internal error, contact the support service -32603 internal_error
Data supplied is of wrong type -32602 data_type_error К примеру, если ожидаем string а передали int
The method does not exist / is not available -32601 method_not_found
Permission denied -32003 forbidden Нет прав на доступ к методу или API, или запрещено выполнять какое-либо действие
Invalid JSON was received by the server. -32700 parse_error
Batch operations not supported -32099 batch_opreations_not_supported
Notifications not supported -32099 notifications_not_supported
The required parameter has been missed -32602 required_parameter_missed Обязательный параметр не передали
Invalid parameter value -32602 invalid_parameter_value Возвращается во всех случаях, если было передано некорректное значение параметра или переданное значение не соответствует требуемому формату ввода
Unexpected method parameter(s) -32602 unexpected_parameters Если в params были переданы параметры, которые не предусмотрены JSON структурой метода