Вебхук — это способ оповещения клиента о произошедшем в системе событии с помощью обратных вызовов по HTTP.
На платформе реализована система гарантированной доставки хуков.
Система ожидает в ответ по каждому отправленному хуку 200-й код. В противном случае будут производиться повторные отправки сообщений в течение 24 часов с увеличением интервалов повторной отправке по экспоненциальной формуле (чем больше попыток, тем больше будет интервал попыток).
Межсерверное взаимодействие ожидает подтверждения в получении отправленных данных.
Если вам нужен только один тип хука, вы можете отвечать 200-м кодом на все остальные передачи и ничего не делать с полученными данными. Решение что обрабатывать, а что игнорировать, находится на стороне бизнес-логики компании заказчика.
Вебхук приходит с адреса 87.251.83.190. Во избежание ошибок в вайтлист лучше добавлять весь диапазон TWIN: 87.251.83.160/27.
Вебхук с информацией о звонке, переведенном на оператора. Для отправки необходима настройка перевода на оператора в диалоге бота. Отправляется для входящих и для исходящих звонков.
Событие отправляется первым хуком, чтобы проинформировать стороннюю систему о переводе звонка в КЦ.
Тело запроса:
{
"event": "CALL_REDIRECTED",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"redirectAdditional": null,
"redirectAnons": null,
"redirectDestination": "ch",
"redirectDestinationId": "10103",
"callbackData": []
}
Описание полей:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| event | string | да | Тип события. Возможные значения: - CALL_REDIRECTED (Вызов переведен). |
| id | string | да | Идентификатор вызова. |
| redirectAdditional | string | да | Дополнительные данные, которые идут в SIP обмене. |
| redirectAnons | string | да | Текст сопровождения перевода, указанный в настройках бота при переводе звонка. |
| redirectDestinationId | string | да | Тип перевода (настраивается в сценарии бота): - ch (канал перевода); - custom (произвольный перевод). |
| | callbackData | Object | да (может быть пустым) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Вебхук с информацией о попытке дозвона. Отправляется по итогам завершения звонка для входящих и для исходящих вызовов.
Тело запроса:
{
"event": "CALL_ENDED",
"type": "OUTGOING",
"companyId": 5,
"botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"externalId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"taskId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"candidateId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"status": "ANSWERED",
"callFrom": "74992868344",
"callTo": "74992868344",
"startedAt": "2023-06-13T10:49:36+00:00",
"finishedAt": "2023-06-13T10:49:38+00:00",
"billedAt": "2023-06-13T10:49:55+00:00",
"variables": {
"age": "35",
"name": "Иван Иванов",
"tryNumber": 0,
"recordPath": "https://tcl.twin24.ai/record/bce7d22e-dde6-4427-b391-ebbdfda44de6/download",
"humanNumber": 0,
"resultNumber": 0,
"tryCandidate": 0,
"answeredNumber": 0,
"humanCandidate": 0,
"resultCandidate": 0,
"answeredCandidate": 0
},
"result": {
"nps": "test",
"date": "Дата",
"evaluation": "Оценка",
"confirmation": "Подтверждение",
"markers": [
"Маркер 1",
"Маркер 2",
"Маркер 3"
],
"initialVariables": {
"customVariable1": "Значение первой пользовательской переменной.",
"customVariable2": "Значение второй пользовательской переменной.",
"phone": "74992868344",
"tryNumber": 0,
"recordPath": "https://tcl.twin24.ai/record/bce7d22e-dde6-4427-b391-ebbdfda44de6/download",
"humanNumber": 0,
"resultNumber": 0,
"tryCandidate": 0,
"answeredNumber": 0,
"humanCandidate": 0,
"resultCandidate": 0,
"answeredCandidate": 0
},
"ключ_1": "его значение 1",
"ключ_2": "его значение 2"
},
"amd": "MACH",
"recordPath": "/180/2023/6/13/1000000000.0000000_74992868344_180.mp3",
"flow": [
{
"botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"start": "2023-06-13 13:49:37.016654+03",
"end": "2023-06-13 13:49:37.016654+03",
"messages": [
{
"text": "Привет и пока",
"author": "BOT",
"time": "2023-06-13 13:49:37.016654+03"
}
]
}
],
"gmtOffset": 0,
"hungUpBy": null,
"duration": 2,
"totalCost": 0.09,
"robotCallDuration": 1,
"robotCallTotalCost": 0.05,
"mainCallCost": 1.45,
"mainCallDiscount": 0,
"mainCallDuration": 2,
"mainCallTotalCost": 0.05,
"autoCallCost": 0,
"autoCallDiscount": 0,
"autoCallDuration": 0,
"autoCallTotalCost": 0,
"robotCallCost": 2.5,
"robotCallDiscount": 0,
"transferCallCost": 0,
"transferCallDiscount": 0,
"transferCallDuration": 0,
"transferCallTotalCost": 0.05,
"clientExternalId":null,
"callbackData": []
}
Описание полей:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| event | string | да | Тип события. Возможные значения: - CALL_ENDED (Вызов завершен). |
| type | string | да | Тип звонка. Возможные значения: - INCOMING (Входящий); - OUTGOING (Исходящий). |
| companyId | int | да | Идентификатор компании. |
| botId | string | да | Идентификатор сценария. |
| id | string | да | Идентификатор вызова. |
| externalId | string | да | Переданный в запросе на инициализацию идентификатор (callId). |
| taskId | string | да | Идентификатор задания на обзвон. |
| candidateId | string | да | Идентификатор кандидата на обзвон. |
| status | string | да | Статус вызова. Возможные значения: - CANCEL (Вызов отменен); - ANSWERED (Вызов принят); - NOANSWER (Нет ответа); - BUSY (Занято); - CONGESTION (Оператор отклонил вызов); - CHANUNAVAIL (Транк недоступен); - FAILED (Ошибка системы при обработке вызова); - SCHEDULED (Вызов запланирован); - BLACKLIST (Телефон в черном списке); - DIAL (Набор номера); - INPROGRESS (Идет диалог); - FZ230 (Запрет вызова по 230-ФЗ); - INVALID (Номер не корректный); - UNAVAILABLE (Удаленная АТС не доступна); - EXPIRED (Соединение не установлено за таймаут). |
| callFrom | string | да | Вызывающий номер. |
| callTo | string | да | Вызываемый номер. |
| startedAt | string | да | Дата начала вызова. |
| finishedAt | string | да | Дата окончания вызова. |
| billedAt | string | да | Дата биллинга вызова. |
| variables | Object | да | Произвольный словарь типа ключ-значения, который был передан перед инициализацией вызова. Содержит исходные переменные. |
| | customVariable | string | нет | Пользовательские переменные, переданные при старте звонка. |
| | tryNumber | int | да | Количество попыток дозвона в рамках задания на обзвон. |
| | recordPath | string | да | Ссылка на скачивание аудиозаписи звонка. |
| | humanNumber | int | да | Количество дозвонов по номеру кандидата, где ответивший был НЕ автоответчик, считается с 0. |
| | resultNumber | int | да | Количество результативных дозвонов по номеру кандидата, считается с 0. |
| | tryCandidate | int | да | Количество попыток дозвона до кандидата, считается с 0. |
| | answeredNumber | int | да | Количество дозвонов по номеру кандидата, считается с 0. |
| | humanCandidate | int | да | Количество дозвонов до кандидата, где ответивший был НЕ автоответчик, считается с 0. |
| | resultCandidate | int | да | Количество результативных дозвонов до кандидата, считается с 0. |
| | answeredCandidate | int | да | Количество дозвонов до кандидата, считается с 0. |
| result | Object | да (может быть пустым массивом []) | Произвольный словарь типа ключ-значения. Результаты разговора робота. |
| | nps | string | нет | Информация из поля NPS в блоке Результат. |
| | date | string | нет | Информация из поля Дата в блоке Результат. |
| | evaluation | string | нет | Информация из поля Оценка в блоке Результат. |
| | confirmation | string | нет | Информация из поля Подтверждение в блоке Результат. |
| | markers | Array[string] | нет | Маркеры. |
| | initialVariables | Object | нет | Исходные переменные. |
| | | customVariable | string | нет | Пользовательские переменные, переданные при старте звонка. |
| | | phone | string | нет | Вызываемый номер. |
| | | tryNumber | int | нет | Количество попыток дозвона в рамках задания на обзвон. |
| | | recordPath | string | нет | Прямая ссылка на скачивание аудиозаписи звонка. |
| | | humanNumber | int | нет | Количество дозвонов по номеру кандидата, где ответивший был НЕ автоответчик, считается с 0. |
| | | resultNumber | int | нет | Количество результативных дозвонов по номеру кандидата, считается с 0. |
| | | tryCandidate | int | нет | Количество попыток дозвона до кандидата, считается с 0. |
| | | answeredNumber | int | нет | Количество дозвонов по номеру кандидата, считается с 0. |
| | | humanCandidate | int | нет | Количество дозвонов до кандидата, где ответивший был НЕ автоответчик, считается с 0. |
| | | resultCandidate | int | нет | Количество результативных дозвонов до кандидата, считается с 0. |
| | | answeredCandidate | int | нет | Количество дозвонов до кандидата, считается с 0. |
| | ключ_1 | string | нет | Произвольный результат. Задается в блоке Результат с типом Произвольный результат. |
| amd | string | да | Результат работы определителя автоответчика. Возможные значения: - HUMN (человек); - MACH (автоответчик); - NOT_DEF (не определялось). |
| recordPath | string | да (может быть пустой строкой) | Ссылка на аудиофайл. |
| flow | Array[Object] | да (может быть пустым массивом []) | Массив фрагментов разговора. |
| | botId | string | да | Идентификатор сценария. |
| | start | string | да | Время начала части диалога. |
| | end | string | да | Время окончания части диалога. |
| | messages | Array[Object] | да | Массив сообщений по диалогу. |
| | | text | string | да | Текст сообщений. |
| | | author | string | да | Кто произнес сообщение (BOT, CLIENT). |
| | | time | string | да | Время отправки сообщения. |
| gmtOffset | int | да | Смещение в минутах от UTC часового пояса клиента. |
| hungUpBy | string | да (может быть null) | Кто положил трубку (BOT, HUMAN). |
| duration | int | да | Общая длительность разговора. |
| totalCost | float | да | Общая стоимость разговора. |
| robotCallDuration | int | да | Длительность разговора робота. |
| robotCallTotalCost | float | да | Стоимость разговора робота со скидкой. |
| mainCallCost | float | да | Стоимость разговора (транк клиента). |
| mainCallDiscount | float | да | Скидка за разговор (транк клиента). |
| mainCallDuration | int | да | Длительность разговора (транк клиента). |
| mainCallTotalCost | float | да | Стоимость разговора со скидкой (транк клиента). |
| autoCallCost | float | да | Всегда равен 0. |
| autoCallDiscount | float | да | Всегда равен 0. |
| autoCallDuration | int | да | Всегда равен 0. |
| autoCallTotalCost | float | да | Всегда равен 0. |
| robotCallCost | float | да | Стоимость разговора робота. |
| robotCallDiscount | float | да | Скидка за разговор робота. |
| transferCallCost | float | да | Стоимость перевода звонка. |
| transferCallDiscount | float | да | Скидка за перевод звонка. |
| transferCallDuration | int | да | Длительность звонка после перевода. |
| transferCallTotalCost | float | да | Стоимость звонка после перевода со скидкой. |
| clientExternalId | string | да (может быть null) | Идентификатор, который добавлен самостоятельно при добавлении кандидата. В случае, если идентификатор не был добавлен, вернется значение null. |
| callbackData | Object | да (может быть пустым массивом []) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Вебхук с информацией об итоге обработки кандидата. Отправляется в качестве сигнала, что данный кандидат полностью обработан системой и больше звонков по кандидату не будет. Отправляется только для исходящих звонков.
На этот вебхук можно опираться для снятия блокировки с кандидата в CRM или дайлера.
Тело запроса:
{
"event": "CANDIDATE_CHANGED",
"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"clientExternalId": null,
"taskId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"status": "FINISHED",
"lastCallId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"callbackData": []
}
Описание полей:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| event | string | да | Тип события. Возможные значения: - CANDIDATE_CHANGED (Обновление статуса по кандидату). |
| id | string | да | Идентификатор кандидата. |
| clientExternalId | string | да (может быть null) | Переданный в запросе на инициализацию идентификатор (callId). |
| taskId | string | да | Идентификатор задания на обзвон. |
| lastCallId | string | да | Идентификатор кандидата на обзвон. |
| status | string | да | Статус вызова. Возможные значения: - FINISHED (Обработка кандидата завершена, больше звонков совершено не будет). |
| callbackData | Object | да (может быть пустым массивом []) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Вебхук с информацией о запланированном перезвоне. Отправляется после планирования перезвона на определенное время из сценария бота только для исходящих вызовов.
Тело запроса:
{
"event":"RECALL_SCHEDULED",
"id":"bce7d22e-dde6-4427-b391-ebbdfda44de6",
"date":"2024-01-31T13:25:00+00:00",
"callbackData":[]
}
Описание полей:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| event | string | да | Тип события RECALL_SCHEDULED — указывает на запланированный перезвон в рамках текущего звонка (через блок Результат). |
| id | string | да | ID звонка. |
| date | string | да | Дата и время, на которые запланирован звонок. |
| callbackData | Array | да | Поле для дополнительной информации. |
Вебхук с информацией об изменении результативности. Отправляется в качестве сигнала об изменении эффективности звонка для исходящих и входящих вызовов.
В сценарии бота результативность звонка настраивается в поле Значение эффективности блока Результат.
При создании Задания на обзвон результативность звонка настраивается в поле Длительность результативного вызова, более, а также в сценарии перезвона Не результативен.
Настройки в сценарии бота имеют приоритетное значение над настройками в задании на обзвон.
Тело запроса:
{
"event": "EFFICIENCY_REACHED",
"id": "4f29df1c-1026-43b7-a60f-15b6b0d441b2",
"state": true,
"callbackData": []
}
Описание полей:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| event | string | да | Тип события EFFICIENCY_REACHED — указывает на изменение результативности. |
| id | string | да | ID звонка. |
| state | boolean | да | Состояние результативности. Если true — результативный, если false — не результативный. |
| callbackData | Array | да | Дополнительные данные, связанные с событием. |
Звонок 1 кандидату (1 номер, без перевода на оператора):
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (1 номер, перевод на оператора):
Получаем хук CALL_REDIRECTED.
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (2+ номеров, без перевода на оператора):
Получаем хук CALL_ENDED.
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (2+ номеров, перевод на оператора):
Получаем хук CALL_REDIRECTED.
Получаем хук CALL_ENDED.
Получаем хук CALL_REDIRECTED.
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (1 номер, запланирован перезвон):
Получаем хук RECALL_SCHEDULED.
Получаем хук CALL_ENDED.
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (1 номер, запланирован перезвон, изменение результативности):
Получаем хук RECALL_SCHEDULED.
Получаем хук CALL_ENDED.
Получаем хук EFFICIENCY_REACHED.
Получаем хук CALL_ENDED.
Получаем хук CANDIDATE_CHANGED.
Настройте получение информации по вебхукам в разделе управления хуками.