Общие рекомендации и правила

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

Процесс подключения интеграции пользователем - автоматизированный процесс, который должен быть понятен пользователю без дополнительных обращений за помощью.

Обычно в CRM доступны виджеты (приложения) через которые пользователь может подключить себе интеграцию с той или иной платформой телефонии.

При выборе нужного виджета (приложения) CRM сама сообщает пользователю какие шаги нужно выполнить для совершения интеграции, либо интегратор самостоятельно выполняет процесс интеграции без участия пользователя, получив у пользователя авторизационные данные.

Определение базовых параметров интеграции

Интеграция должна понимать, какие номера добавочных относятся к обычным телефонным добавочным, а какие к служебным (ИВР и Очередь).

Эти данные можно узнать путем запроса этих данных, например, ресурсом:

get /client/{client_id}/extension/ ( поле type ссылка на документацию).

Префикс АТС и длину добавочного можно узнать с помощью ресурса:

get /client/{client_id}/client/ ( поле extension_len и prefix ссылка на документацию)

Номер добавочного с префиксом АТС пользователя имеет формат регулярного выражения (regex):

[0-9]{3,6}*[0-9]{2,4}

События на добавочных

Всем обычным телефонным добавочным (type = phone ) рекомендуется добавлять полный набор событий:
dial-in - входящий вызов на добавочный, отправитель события
dial-out - исходящий вызов с добавочного, отправителя события
answer - снятие трубки на добавочном, отправитель события(возможно в какой-то интеграции это событие будет неактуально)
hangup - прекращение вызова на добавочном, отправителе события

В данной рекомендации всем спец.добавочным (type = IVR или queue) рекомендуется добавлять только событие hangup.

Документация событий добавочного.

Документация событий агента очереди ( данные события необходимы для отображения готовности агента очереди принять вызов - могут использоваться в реал-тайм мониторинге)

Добавление/удаление событий на добавочных.

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

Количество событий на одном добавочном согласно стандартным допускам - 16. Потому при невозможности добавить событие нужно сообщить пользователю данную информацию с тем, чтобы он либо удалил неиспользуемые события на добавочном, либо отправил запрос администратору АТС на расширения лимита событий на добавочных.

Правило по запросам к API:

Более одного запроса на одно действие совершать не нужно, если при предыдущей попытке совершить запрос была получена ошибка, то значит что-то пошло не так и повторить запрос нужно только после каких-либо действий.

Ошибки серии 4xx значает, что нужно что-либо изменить, либо предпринять какие-либо меры, подробнее об 4xx ошибках можно прочитать в документации.

Ошибки API - серия 5xx. Эти ошибки нужно отправлять администратору для принятия соответствующих мер.

Повторная отправка запроса должна быть инициирована только пользователем (при инициации запроса пользователем), либо через определенное время (при автоматических запросах), но ни в коем случае не в бесконечном цикле. Об ошибке пользователь должен узнать в соответствующем уведомлении.

Количество запросов к API в час также лимитировано, поэтому нежелательно лишний раз что-либо обновлять/синхронизировать. Документация по лимитам.

Пример события (рекомендуемый url)

url в событии может быть таким:

http://myintegration.com:8080/cid/807/queue/33334

где

807 - порядковый номер приложения РингМи для данной интеграции. В дальнейшем данный номер можно использовать для того, чтобы отфильтровать в логе сервера интеграций все события, относящиеся к данному пользователю.
queue - тип добавочного, на котором задано url события. Позволяет удобно разделять события разных типов добавочных ( phone или queue или IVR)

33334 - id добавочного, упрощает анализ событий

Но, с точки зрения безопасности в общеиспользуемых интеграциях такие url в событиях лучше не создавать. При таком url можно, подобрав client_id и ext_id, спамить других пользователей событиями. Рекомендуем указывать такой url:

http://myintegration.com/ext-event/f2a8vdrfae0s1ku5d2rj3iximjf3twyz

Где:

ext-event - тип события

f2a8vdrfae0s1ku5d2rj3iximjf3twyz - уникальный идентификатор, который однозначно соответствует записи добавочного в таблице добавочных вашей интеграции

Фильтрация событий, полученных от АТС.

Ознакомьтесь с описанием, в частности с разделом “Данные события (EventData)”

Если хотите фиксировать только внешние вызовы (на внешний номер/с внешнего номера), то нужно исключить из обработки:

Cобытия, относящиеся к звонкам c добавочного на добавочный

В поле CallerNum: Номер добавочного в формате [0-9]{3,6}*[0-9]{2,4}

В поле CalledNum: Номер добавочного в формате [0-9]{3,6}*[0-9]{2,4}

События, относящиеся к внутренним переадресациям

В поле Transfered: "yes"

Присутствует поле CalledExtensionID с числовым id

Присутствует поле CallerExtensionID с числовым id