Call API

Знакомство

Введение

Настоящий документ описывает 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 структурой метода