Платформа аналитики маркетинга и продаж

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 структурой метода