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 (см. Компоненты)

Компоненты

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

По умолчанию используется формат 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.

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

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"
 }
}

Общее

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

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

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

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

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

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

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