Отправка событий вебсокета
С помощью API происходит обмен информацией между сторонним сервисом и Сипуни. Это нужно, если вам необходимо в «прямом эфире» получать данные из телефонии и автоматически передавать их в стороннюю программу, например в CRM, собственную систему учета или сервис для аналитики.
В этой статье разберем, как включить вебсокет--сервер, пройти аутентификацию и какие события Сипуни передает во внешнюю систему.
Все запросы к серверу и ответы от него будут в формате JSON.
Как подключить WebSocket API
- Перейдите в раздел «Интеграции» → «Интеграция по API» → «События на АТС».
- Пополните баланс в «Услугах связи». В настройках включите параметр «Использовать вебсокет-сервер» → нажмите «Сохранить».
Аутентификация
Для аутентификации используйте запрос:
{"type":"auth","body":{"key":"<код аутентификации>"}}
Чтобы найти код аутентификации, разверните вкладку «URL, которые уже используются» и скопируйте его из поля «Ключ интеграции вебсокет-сервера».
Пример запроса:
{"type":"auth","body":{"key":"e03988888888a1c88888888e88888888"}}
Если авторизация прошла успешно, сервер вернет ответ:
{"action": "auth", "status": 1}
Если ответ не вернулся, значит, авторизация не прошла.
После успешной аутентификации сервер начнет отправлять сообщения о событиях на АТС.
Периодически сервер будет отправлять служебные сообщения keepalive:
{"type":"keepalive"}
Это нормально и нужно, чтобы поддерживать активное соединение.
В каком формате приходят уведомления от сервера
Когда происходит событие в телефонии (например, начало звонка, ответ оператора или завершение разговора), Сипуни отправляет на ваш сервер уведомления с такой структурой:
{
"action": "notify",
"request": {
<тело запроса>
}
},
Основная информация о звонке находится внутри поля request. Именно эти данные необходимо обрабатывать во внешней системе — например, чтобы создать запись о звонке в CRM.
Обязательные параметры
Каждое уведомление содержит обязательные параметры, которые описывают состояние звонка:
event — тип события.
call_id — уникальный идентификатор вызова. Сохраняется неизменным при переводе звонка. Передается строкой произвольного формата (в URL-кодировке).
src_num — адрес абонента, который инициировал вызов. Значение сохраняется при переводе звонка.
src_type — тип адреса инициатора вызова:
- 1 — внешний (от клиента).
- 2 — внутренний (от сотрудника).
dst_num — номер, на который поступил звонок. Здесь может быть как номер телефона, так и внутренний номер сотрудника. Поле может быть пустым, если переадресация настроена через сторонний сервис.
dst_type — тип номера, на который поступает звонок:
- 1 — внешний (клиенту).
- 2 — внутренний (сотруднику).
timestamp — время события (начало, ответ, перевод или завершение вызова). Передается в формате Unix timestamp (UTC).
channel — канал соединения, который создается при ответе на вызов или при инициировании внешнего звонка. В старой версии API этот канал использовался при переводе и завершении вызова.
Адрес может быть:
- телефонным номером,
- строкой произвольного формата.
Если сотрудник звонит клиенту, то адрес всегда передается как телефонный номер.
Если клиент звонит в компанию или сотрудник звонит на внутренний номер, то адрес может быть как номером, так и строкой в URL-кодировке (например, SIP-аккаунт).
В каком формате приходят ответы на запросы через вебсокет
Call — начало звонка
event = 1
Событие event = 1 отправляется в момент, когда вызов поступает на устройство. Это может происходить во время дозвона или при переводе звонка. При переводе сохраняются значения src_num и call_id текущего вызова.
Для каждого события Call обязательно должно быть отправлено событие Hang-up, которое сообщает о завершении звонка.
Обязательные параметры:
is_inner_call — значение, которое показывает, является ли звонок внутренним. Появляется, когда вызов направляют абоненту.
Например, если is_inner_call = 1/true — звонок внутри системы. Если параметр отсутствует / false — звонок поступил извне системы (например, с городского номера).
Hang-up — окончание звонка
event = 2
Обязательные параметры
status — статус завершения вызова:
- ANSWER — вызов отвечен.
- BUSY — абонент занят.
- NOANSWER — абонент не ответил за отведенное время.
- CANCEL — вызов сброшен.
- CONGESTION — перегрузка сети.
- CHANUNAVAIL — абонент недоступен (например, SIP-устройство не зарегистрировано).
call_start_timestamp — время начала вызова.
call_answer_timestamp — время ответа на вызов. Если вызов не был принят, значение параметра равно 0.
Дополнительные параметры:
call_record_link — ссылка на файл записи разговора (в URL-кодировке).
Answer — ответ на вызов
event = 3
Событие посылается при ответе на вызов. Дополнительные параметры отсутствуют.
Secondary hang-up — промежуточное завершение вызова
event = 4
Событие отправляется, когда сотрудник завершает разговор при условном переводе, то есть с предварительной консультацией. После этого вызов полностью передается на номер, который выбрали для перевода.
Обязательные параметры
status — статус завершения вызова:
- ANSWER — вызов отвечен.
- BUSY — абонент занят.
- NOANSWER — абонент не ответил за отведенное время.
- CANCEL — вызов сброшен.
- CONGESTION — перегрузка сети.
- CHANUNAVAIL — абонент недоступен (например, SIP-устройство не зарегистрировано).
call_start_timestamp — время начала вызова.
call_answer_timestamp — время ответа на вызов. Если вызов не был принят, значение параметра равно 0.
Дополнительные параметры
call_record_link — ссылка на запись разговора (в URL-кодировке).
Пример
Внешний звонок:
Клиент 89104846817 звонит в компанию.
{
"call_id": "1429019739.49501",
"event": "1",
"dst_type": "1",
"dst_num": "4999678420",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019739",
"channel": "SIP/0123451004996479797-0000bcf9",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}
Система направляет вызов на сотрудника 262.
{
"call_id": "1429019739.49501",
"event": 1,
"dst_type": "2",
"dst_num": "012345262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019747",
"is_inner_call": true, // Это логика АТС
"channel": "SIP/0123451004996479797-0000bcf9",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}
Сотрудник 262 отвечает на звонок.
{
"call_id": "1429019739.49501",
"event": "3",
"dst_type": "2",
"dst_num": "012345262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019750",
"channel": "SIP/012345262-0000bcfb", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
Сотрудник 262 делает условный перевод звонка на 261.
{
"call_id": "1429019739.49501",
"event": "1",
"dst_type": "2",
"dst_num": "012345261",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019769",
"channel": "Local/261@transfer_vats-000001e9;2", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
Внутренняя обработка вызова АТС на номер 261.
{
"call_id": "1429019739.49501",
"event": 1,
"dst_type": "2",
"dst_num": "012345261",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019769", "is_inner_call": true,
"channel": "Local/000987601@vatsl-000001ea;2", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
В этот момент 261 разговаривает с 262, а клиент находится на удержании.
{
"call_id": "1429019739.49501",
"event": "3",
"dst_type": "2",
"dst_num": "012345261",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019776",
"channel": "SIP/039803261-0000bcfc", "treeName": "Тестирование CRM","treeNumber": "000960393"
}
Схема пользователя 261 ответила (в этом контексте этот ответ не так важен).
{
"call_id": "1429019739.49501",
"event": "3",
"dst_type": "2",
"dst_num": "000987601",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019776",
"channel": "Local/000987601@vatsl-000001ea;1", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
Сотрудник 262 завершает разговор, после чего клиент соединяется напрямую с 261.
{
"call_id": "1429019739.49501",
"event": "4",
"dst_type": "2",
"dst_num": "012345262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019780",
"channel": "Transfered/SIP/0123451004996479797-0000bcf9", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
Звонок завершен.
{
"call_id": "1429019739.49501",
"event": "2",
"dst_type": "2",
"dst_num": "012345261","src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019790", "status": "ANSWER",
"call_start_timestamp": "1429019739",
"call_answer_timestamp": "1429019750",
"call_record_link": "
