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

Преимущества прямой интеграции

Ограничение платформы

Общая схема работы


Работа с вызовами при прямой интеграции

Для отправки вызова на бота  выполните три шага:

  1. Авторизуйтесь в системе (раз в определенный интервал).

  2.  Прогрейте вызов.

  3. Отправьте звонок на бота по протоколу SIP.

Авторизация в системе

Для начала работы авторизуйтесь в системе Twin и получите JWT-токен. Информация по API авторизации доступна в документации по сервису IAM.

Прогрев вызова

Прогрев вызова – это уведомление системы Twin о грядущем соединении с роботом. Прогрев – это отправка HTTP-запроса с информацией о звонке или пачке звонков, которые в скором времени будут переданы на бота по протоколу SIP.

Срок жизни сессии составляет 3 минуты.

curl --location 'https://cis.twin24.ai/api/v1/calls' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
    "returnAnswerAsync": false,
    "calls": [
        {
            "clientExternalId": "CLIENT_EXTERNAL_ID",
            "callId": "CLIENT_CALL_ID",
            "callerId": "7**********",
            "number": "7**********",
            "botSettingsId": "BOT_ID",
            "variables": {
                "variable_name1": "variable_value1",
                "variable_name2": "variable_value2"
            },
            "callback": [
                {
                    "url": "URL",
                    "data": {
                        "key1": "key2"
                    }
                }
            ]
        }
    ]
}'

 

ПараметрЗначение
returnAnswerAsyncРежим осуществления прогрева: синхронный (false) и асинхронный (true). При синхронном прогреве ответ от сервера придет после окончания прогрева и это означает, что бот готов к приему вызова. При асинхронном режиме ответ возвращается сразу же, прогрев происходит в фоновом режиме.
CLIENT_EXTERNAL_IDИдентификатор клиента в системе заказчика. По данному параметру можно получить все вызовы, связанные с клиентом из сервиса аналитики. Бизнес-смысл данного параметра – уникальность в рамках человека/лида/сделки (в зависимости от типа системы заказчика).
CLIENT_CALL_IDИдентификатор вызова в системе заказчика – отражение совершаемого вызова в системе заказчика. Данный параметр возвращается в ответе на запрос.
callerIdНомер телефона звонящего.
numberНомер получателя вызова.
variablesНабор переменных для сценария бота.
botSettingsIdИдентификатор бота, который начнет общение с пользователем.
callbackМассив адресов, которые нужно уведомлять о результате разговора с роботом. Каждый элемент состоит из двух полей: URL и DATA. Данные, переданные в DATA, недоступны боту и отдаются в вебхуке в неизменном виде.


Стоит обратить внимание, что :

  1.  Ответ на запрос возвращается в виде :

    {

  "CLIENT_CALL_ID1": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bb",

  "CLIENT_CALL_ID2": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bc",

}
    Значения CLIENT_CALL_ID1 берутся из поля callId элемента массива calls.

  2. Если вместо идентификатора вы получили null, значит запрос на прогрев вызова отклонен. Откажитесь от запуска дозвона на абонента. Система не будет готова принять вызов по указанному звонку.

  3. Если данный endpoint отвечает не 200 кодом, значит система Twin не готова принимать вызовы. Временно остановите дозвон и попробуйте через несколько минут.

Отправка звонка на бота по протоколу SIP

После того, как клиент ответил на вызов и прогрев совершен, отправьте вызов на робота по адресу, предоставленному сотрудниками компании Twin.

Обязательными условиями для установки соединения являются проставления следующих заголовков в INVITE:

Если необходимо включить запись вызова, то дополнительно отправьте заголовок X-TWIN-EnableRecord=1

При записи на стороне Twin будет записан только участок разговора с роботом. Весь диалог до перевода на робота и после перевода с робота на оператора на записи отражен не будет.

Рекомендации по работе с прямой интеграцией

  1. Рекомендуется настроить АТС таким образом, чтобы при получении вызова от клиента сразу же начинался прогрев. При этом до момента окончания прогрева не нужно отправлять клиенту Answer (200 код по SIP), т.к. это может привести к задержке начала разговора на время прогрева.

  2. Меняйте местами callerId и number для систем дозвона. Если ваша система является инициатором вызова, то в callerId передавайте номер, куда вы звоните, а в number – откуда. Это позволит вам получить в сценарии номер телефона, куда вы позвонили для возможного принятия решения. Данная замена необходима, потому что при прямой интеграции система Twin считает все вызовы входящими и номер абонента берется из callerId.

  3. Не игнорируйте ответ от прогрева. Если вы не получили идентификатор при прогреве, откажитесь от запуска дозвона на абонента – такой вызов 100% будет неуспешным. Если вы получили не 200 код при запросе на прогрев, то временно остановите дозвон и попробуйте через несколько минут.

  4. Используйте асинхронный режим только при исходящем обзвоне. Если вызов будет направлен на робота по SIP до окончания процедуры прогрева сессии, то такой вызов будет отклонен системой. Учитывайте, что для прогрева вызова в среднем требуется 1 секунда.

  5. Не прогревайте сессии, если не собираетесь звонить клиенту в ближайшее время.

    Срок жизни сессии составляет 3 минуты.

    Если между запросом на прогрев сессии и физическим установлением соединения с пользователем пройдет больше времени, то такой звонок на бота будет отклонен.