Message Box | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Информация |
---|
Вебхук приходит с 87.251.83.190 (в вайт лист лучше добавлять весь диапазон TWIN: 87.251.83.160/27) |
У хука есть 3 типа событий и отправка идет по каждому их них:
"event": "
Тип события | Значение | Описание |
---|---|---|
event | CALL_REDIRECTED |
...
Вебхук, с информацией о звонке, переведенном на оператора. Отправляется только тогда, когда в диалоге бота настроен перевод на оператора.<br>Событие отправляется самым первым хуком, чтобы проинформировать стороннюю систему о переводе звонка в КЦ. Отправляется и для входящих и для исходящих звонков, если в сценарии настроен перевод на оператора. Если перевода не было или он не предусмотрен - событие отправляться не будет. |
...
event |
...
CALL_ENDED |
...
Вебхук, с информацией о попытке дозвона. Отправляется всегда, по итогам завершения звонка. Отправляется и для входящих и для исходящих звонков. |
...
event |
...
CANDIDATE_CHANGED |
...
Вебхук,с информацией |
...
об итоге обработки кандидата. Отправляется в качестве сигнала, что данный кандидат полностью обработан системой и больше звонков по кандидату не будет. На него можно опираться для снятия блокировки с кандидата в CRM или дайлера. Отправляется только для исходящих звонков. Для входящих событие отправляться не будет. |
Примеры кейсов и описание для них логики отправок хуков
...
Звонок 1 кандидату (1 номер, без перевода на оператора):1.
- Получаем хук CALL_ENDED.
...
- Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (1 номер, перевод на оператора):1.
- Получаем хук CALL_REDIRECTED.
...
- Получаем хук CALL_ENDED.
...
- Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (2+ номеров, без перевода на оператора):1.
- Получаем хук CALL_ENDED.
...
- Получаем хук CALL_ENDED.
...
- Получаем хук CANDIDATE_CHANGED.
Звонок 1 кандидату (2+ номеров, перевод на оператора):1.
- Получаем хук CALL_REDIRECTED.
...
- Получаем хук CALL_ENDED.
...
- Получаем хук CALL_REDIRECTED.
...
- Получаем хук CALL_ENDED.
...
- Получаем хук CANDIDATE_CHANGED.
Информация |
---|
На нашей платформе реализована система гарантированной доставки хуков. Система ожидает в ответ по каждому отправленному хуку |
...
200-й код. В противном случае мы |
...
будем делать повторные отправки сообщений в течение 24 часов с увеличением интервалов повторной отправке по |
...
экспоненциальной формуле (чем больше попыток |
...
тем больше будет интервал попыток). Меж серверное взаимодействие ожидает подтверждения в получении отправленных данных. Если вам нужен только один тип хука, вы можете отвечать |
...
200-м кодом на все остальные передачи и ничего не делать с полученными данными. Решение что обрабатывать, а что игнорировать, находится на стороне бизнес-логики компании заказчика. |
Описание хука по событию
...
«CALL_
...
REDIRECTED» (Только для ботов с переводом на оператора)
...
Пример Тело запроса:Тело webHook в формате Json:
...
1
2
3
4
5
6
7
8
9
10
...
Блок кода | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "event": |
...
"CALL_REDIRECTED", |
...
"id": |
...
" |
...
bce7d22e- |
...
dde6- |
...
4427- |
...
b391- |
...
ebbdfda44de6", |
...
"redirectAdditional": null, |
...
"redirectAnons": null, |
...
"redirectDestination": |
...
"ch", |
...
"redirectDestinationId": |
...
"10103", |
...
"callbackData": [] |
...
} |
Описание полей:
Поле | Тип | Обязательно | Описание |
---|
Соответствие с полем из метода старой телефонии
event | string | да | Тип события. |
Возможные значения:
|
|
| |||
id | string | да | Идентификатор вызова |
. | |||
redirectAdditional | string | да | Дополнительные данные, которые идут в SIP обмене. |
redirectAnons | string | да | Текст сопровождения перевода, указанный в настройках бота при переводе звонка. |
redirectDestination | string | да | Тип перевода (настраивается в сценарии бота):
|
|
|
int (внутренний номер, вроде не используем)
-
| |||
redirectDestinationId | string | да | Значение конечного номера, для выбранного типа перевода (номер канала, номер произвольного перевода, внутренний номер) |
. | |||
| callbackData | Object | да (может быть пустым) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Описание хука по событию
...
«CALL_ENDED»
Тело Пример запроса:Тело webHook в формате Json:
1 |
|
Описание полей:
...
Поле
...
Тип
...
Обязательно
...
Описание
...
Соответствие с полем из метода старой телефонии
...
event
...
Тип события.
Возможные значения:
- 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
...
да (может быть пустым)
...
Произвольный словарь типа ключ-значения, который был передан перед инициализацией вызова.
Содержит исходные переменные
...
result
...
Object
...
да
...
Произвольный словарь типа ключ-значения.
Результаты разговора робота
...
| initialVariables
...
Object
...
да (может быть пустым)
...
Исходные переменные
...
| markers
...
Array[string]
...
да (может быть пустым)
...
Маркеры
...
| confirmation
...
да (может быть пустым)
...
Подтверждение
...
| nps
...
да (может быть пустым)
...
NPS
...
| ключ_1
...
нет
...
Произвольный результат.
Задается в блоке "Результат" с типом "Произвольный результат"
...
string
...
да (пустой для первого хука)
...
Путь к аудиофайлу.
Для получения ссылки нужно добавить в начале пути
https://minio.twin24.ai/twin-cis-production/records
...
Array[Object]
...
да
...
Массив фрагментов разговора
...
string
...
да
...
Идентификатор сценария
...
string
...
да
...
Время начала части диалога
...
string
...
да
...
Время окончания части диалога
...
Array[Object]
...
да
...
Массив сообщений по диалогу
...
string
...
да
...
Текст сообщений
...
string
...
да
...
Кто произнес сообщение (BOT, CLIENT)
...
string
...
да
...
Время отправки сообщения
...
int
...
да
...
смещение в минутах от UTC часового пояса клиента
...
string
...
да (пока всегда null)
...
Кто положил трубку (пока всегда null)
...
int
...
да
...
Общая длительность разговора
...
float
...
да
...
Общая стоимость разговора
...
int
...
да
...
Длительность разговора робота
...
float
...
да
...
Стоимость разговора робота со скидкой
...
float
...
да
...
Стоимость разговора (транк клиента)
...
float
...
да
...
Скидка за разговор (транк клиента)
...
int
...
да
...
Длительность разговора (транк клиента)
...
float
...
да
...
float
...
да
...
int
...
да
...
float
...
да
...
float
...
да
...
float
...
да
...
float
...
да
...
float
...
да
...
Скидка за перевод звонка
...
int
...
да
...
Длительность звонка после перевода
...
float
...
да
...
Стоимость звонка после перевода со скидкой
...
Object
...
да (может быть пустым)
...
Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата)
...
Описание хука по событию "CANDIDATE_CHANGED" (Только для исходящих):
Пример запроса:
Тело webHook в формате Json:
...
1
2
3
4
5
6
7
8
9
10
11
12
...
Блок кода | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"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 | да | Тип события. Возможные значения:
|
type | string | да | Тип звонка. Возможные значения:
|
companyId | int | да | Идентификатор компании. |
botId | string | да | Идентификатор сценария. |
id | string | да | Идентификатор вызова. |
externalId | string | да | Переданный в запросе на инициализацию идентификатор (callId). |
taskId | string | да | Идентификатор задания на обзвон. |
candidateId | string | да | Идентификатор кандидата на обзвон |
status | string | да | Статус вызова. Возможные значения:
|
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 | да | Результат работы определителя автоответчика. Возможные значения:
|
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 | да (может быть пустым массивом []) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Описание хука по событию «CANDIDATE_CHANGED» (Только для исходящих)
Тело запроса:
Блок кода | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"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 | да | Тип события. Возможные значения:
|
id | string | да | Идентификатор кандидата. |
clientExternalId | string | да (может быть null) | Переданный в запросе на инициализацию идентификатор (callId). |
taskId | string | да | Идентификатор задания на обзвон. |
lastCallId | string | да | Идентификатор кандидата на обзвон. |
status | string | да | Статус вызова. Возможные значения:
|
callbackData | Object | да (может быть пустым массивом []) | Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата). |
Описание хука по событию «RECALL_SCHEDULED»
Тело запроса:
Блок кода | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "event":"RECALL_SCHEDULED", "id":"bce7d22e-dde6-4427-b391-ebbdfda44de6", "date":"2024-01-31T13:25:00+00:00", "callbackData":[] } |
Описание полей:
Поле | Тип | Обязательно | Описание |
---|
Соответствие с полем из метода старой телефонии
Поле
Тип
Обязательно
Описание
Соответствие с полем из метода старой телефонии
event
Тип события.
Возможные значения:
CANDIDATE_CHANGED (Обновление статуса по кандидату)
id
string
да
Идентификатор вызова
clientExternalId
string
да
Переданный в запросе на инициализацию идентификатор (callId)
taskId
string
да
Идентификатор задания на обзвон
candidateId
string
да
Идентификатор кандидата на обзвон
status
string
да
Статус вызова.
Возможные значения:
FINISHED (Обработка кандидата завершена, больше звонков совершено не будет)
| callbackData
Object
да (может быть пустым)
Информация о кандидате, переданная в момент добавления кандидата (см. метод добавления кандидата)
event | string | да | Тип события RECALL_SCHEDULED — указывает на запланированный перезвон в рамках текущего звонка (через блок Результат). |
id | string | да | ID звонка. |
date | string | да | Дата и время, на которые запланирован звонок. |
callbackData | Array | да | Поле для дополнительной информации. |
Описание хука по событию «EFFICIENCY_REACHED»
Тело запроса:
Блок кода |
---|
{
"event": "EFFICIENCY_REACHED",
"id": "4f29df1c-1026-43b7-a60f-15b6b0d441b2",
"state": true,
"callbackData": []
} |
Описание полей:
Поле | Тип | Обязательно | Описание |
---|---|---|---|
event | string | да | Тип события EFFICIENCY_REACHED — указывает на изменение результативности. |
| string | да | ID звонка. |
state | boolean | да | Состояние результативности. Если true — результативный, если false — не результативный. |
callbackData | Array | нет | Дополнительные данные, связанные с событием. |