Call API

Знакомство

Введение

Настоящий документ описывает Call API, которое позволяет совершать звонки и управлять ими.

Управлять можно так же звонками, которые поступили на виртуальную АТС. Для этого необходимо получить уникальный идентификатор сессии звонка. Его можно получить с помощью сервера уведомлений, DATA API.

API реализован на основе спецификации JSON-RPC 2.0 без поддержки групповых операций.

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

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

Соглашения

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

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

Добавить IP-адрес в список разрешенных

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

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

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

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

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

Используется аутентификация по логину и паролю пользователя, в ответе будет получен ключ доступа к Call API

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

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

В настройках пользователя есть возможность включить доступ по ключу, для этого необходимо в настройках пользователя поставить галку "Доступ по ключу". При этом, будьте внимательны: ключ виден в интерфейсе и доступен для копирования только в момент генерации, после сохранения настроек вы сможете его увидеть только в коде своего приложения или другом месте, куда вы сохранили этот ключ.

Ключи могут действовать до определенной даты или быть бессрочными, в зависимости от ваших настроек.

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

В личном кабинете "Отчеты" -> "Служебные" -> "Запросы к API" можно видеть все запросы к API, кроме запросов, которые закончились ошибками:

Если возвращются ошибки валидации JSON или структуры запроса - мнемоника "parse_error" или "invalid_request";
Если возвращается ошибка на вызов метода, который не существует - мнемоника "method_not_found";
Если возвращается ошибка связанная с аутентификацией - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";
Если возвращается ошибка при запросе с IP адреса, который не в белом списке - мнемоника "ip_not_whitelisted".

Полную информацию по звонку можно найти в "Отчеты" -> "Обращения" -> "Звонки" с фильтрацией по параметру "Индентификатор сессии звонка"

Если в фильтрах отсутствует параметр "Идентификатор сессии звонка", то его нужно добавить в доступные столбцы отчета

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

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

По умолчанию запрещено международное направление, остальные направления разрешены.

Разрешения для направлений звонка разбиты по компонентам Call API (см. Компоненты)

Компоненты

Название для клиента	Список методов	Описание
Call API Базовый набор	start.employee_call, start.vnumber_call, start.simple_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	Пакет, который позволяет совершать вызовы клиенту с использованием одного виртуального номера и набора сценариев.

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

Формат	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 или идентификатор сессии звонка

Лимиты привязаны к компоненту Call API Базовый набор (см. Компоненты) и учитываются в зависимости от стоимости метода в баллах

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

Если возвращются ошибки валидации JSON или структуры запроса - мнемоника "parse_error" или "invalid_request";

Если возвращается ошибка на вызов метода, который не существует - мнемоника "method_not_found";

Если возвращается ошибка связанная с аутентификацией - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";

Если возвращается ошибка при запросе с IP адреса, который не в белом списке - мнемоника "ip_not_whitelisted".

Информация о лимитах возвращается в мета-параметрах (см. Мета-параметры)

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

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

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

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

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

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

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

Параметр api_version возвращается только для версий которые deprecated.

Описание параметров

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

JSON структура

Копировать

"metadata": {
 "api_version": {
  "current_version_depricated": "boolean",
  "current_version": "string",
  "latest_version": "string"
 },
 "limits": {
  "day_limit": "number",
  "day_remaining": "number",
  "day_reset": "number",
  "minute_limit": "number",
  "minute_remaining": "number",
  "minute_reset": "number"
 }
}

Общее

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

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

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

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

Метод	Описание
"login.user"	Вход
"logout.user"	Выход и удаление ключа сессии аутентификации

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

Метод	Описание
"start_employee_call"	Метод создает прямой звонок абонента с сотрудником без использования сценария.
"start.scenario_call"	Метод создает звонок согласно настроенному сценарию. Для использования метода достаточно одного виртуального номера и N сценариев.
"start.vnumber_call"	Вызов на виртуальный номер.
"start.informer_call"	Информационный вызов с возможностью проиграть абоненту файл или текстовое сообщение. После окончания проигрывания сообщения вызов завершается автоматически.
"start.simple_call"	Звонок на любые номера кроме собственных виртуальных. Это не звонок сотрудника на любой номер.

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

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

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

Код ошибки	Описание
-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`	IP адрес, с которого идет запрос не находится в белом списке (см. личный кабинет "Аккаунт" -> "Call API" вкладка "IP адреса"
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`	Невалидный JSON
Batch operations not supported	-32099	`batch_opreations_not_supported`	Групповые операции не поддерживаются (см. JSON-RPC 2.0)
Notifications not supported	-32099	`notifications_not_supported`	Уведомления не поддерживаются (см. JSON-RPC 2.0)
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 структурой метода

Оборудование

Call API

Знакомство

Введение

Соглашения

Добавить IP-адрес в список разрешенных

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

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

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

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

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

Компоненты

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

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

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

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

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

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

Общее

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

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

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

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

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

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

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