Прямое подключение к голосовому роботу Twin – это тип интеграции, при которой вызов попадает сразу на робота, минуя АТС Twin. Такая интеграция может быть полезна компаниям с собственной настроенной телефонией, с особой логикой и большими мощностями. Если у вас нет своей телефонии, или вы пользуетесь услугами поставщиков АТС, то такую интеграцию реализовать невозможно.
¶ Преимущества прямой интеграции
- Максимальный уровень интегрированности робота в телефонную инфраструктуру.
- Предполагается поток звонков (более 40-50 одновременных разговоров), которые обслуживаются роботом.
- Полный контроль над сценарием прохождения вызова на стороне клиента.
- Подготовка сессий диалога с переменными, необходимыми для работы бота без дополнительных запросов к серверу из сценария.
¶ Ограничение платформы
- Система Twin при работе с вызовами работает с ограничением CPS. CPS (calls per second) – это количество звонков, которые компании можно запускать за секунду. При попытке запустить большее количество звонков, чем это дозволено компании, звонок будет отклоняться системой.
- Подключение производится исключительно через построенный туннель (L2TP, PPTP, IPSec, L2 и т.д.).
¶ Общая схема работы
¶ Работа с вызовами при прямой интеграции
Для отправки вызова на бота выполните три шага:
- Авторизуйтесь в системе (раз в определенный интервал).
- Прогрейте вызов.
- Отправьте звонок на бота по протоколу SIP.
¶ Авторизация в системе
Для начала работы авторизуйтесь в системе Twin и получите JWT-токен. Информация по API авторизации доступна в документации по сервису IAM.
¶ Прогрев вызова
Прогрев вызова – это уведомление системы Twin о грядущем соединении с роботом. Прогрев – это отправка HTTP-запроса с информацией о звонке или пачке звонков, которые в скором времени будут переданы на бота по протоколу SIP.
Срок жизни сессии составляет 3 минуты.
cURL запроса на прогрев вызова:
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, недоступны боту и отдаются в вебхуке в неизменном виде. |
Ответ на запрос возвращается в виде:
{
"CLIENT_CALL_ID1": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bb",
"CLIENT_CALL_ID2": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bc",
}
Значения CLIENT_CALL_ID1 берутся из поля callId элемента массива calls.
Стоит обратить внимание:
Если вместо идентификатора вы получили null, значит запрос на прогрев вызова отклонен. Откажитесь от запуска дозвона на абонента. Система не будет готова принять вызов по указанному звонку.
Если данный endpoint отвечает не 200 кодом, значит система Twin не готова принимать вызовы. Временно остановите дозвон и попробуйте через несколько минут.
¶ Отправка звонка на бота по протоколу SIP
После того, как клиент ответил на вызов и прогрев совершен, отправьте вызов на робота по адресу, предоставленному сотрудниками компании Twin.
Обязательными условиями для установки соединения являются проставления следующих заголовков в INVITE:
- X-TWIN-Access=ROBOT_SESSION_UUID (из п.2)
- X-TWIN-TransferMethod=refer
- X-RobotVer=2
Если необходимо включить запись вызова, то дополнительно отправьте заголовок X-TWIN-EnableRecord=1
При записи на стороне Twin будет записан только участок разговора с роботом. Весь диалог до перевода на робота и после перевода с робота на оператора на записи отражен не будет.
¶ Рекомендации по работе с прямой интеграцией
- Рекомендуется настроить АТС таким образом, чтобы при получении вызова от клиента сразу же начинался прогрев. При этом до момента окончания прогрева не нужно отправлять клиенту Answer (200 код по SIP), т.к. это может привести к задержке начала разговора на время прогрева.
- Меняйте местами callerId и number для систем дозвона. Если ваша система является инициатором вызова, то в callerId передавайте номер, куда вы звоните, а в number – откуда. Это позволит вам получить в сценарии номер телефона, куда вы позвонили для возможного принятия решения. Данная замена необходима, потому что при прямой интеграции система Twin считает все вызовы входящими и номер абонента берется из callerId.
- Не игнорируйте ответ от прогрева. Если вы не получили идентификатор при прогреве, откажитесь от запуска дозвона на абонента – такой вызов не будет успешным. Если вы получили не 200 код при запросе на прогрев, то временно остановите дозвон и попробуйте через несколько минут.
- Используйте асинхронный режим только при исходящем обзвоне. Если вызов будет направлен на робота по SIP до окончания процедуры прогрева сессии, то такой вызов будет отклонен системой. Учитывайте, что для прогрева вызова в среднем требуется 1 секунда.
- Не прогревайте сессии, если не собираетесь звонить клиенту в ближайшее время.
Срок жизни сессии составляет 3 минуты. Если между запросом на прогрев сессии и физическим установлением соединения с пользователем пройдет больше времени, то такой звонок на бота будет отклонен.