Отправка событий Websocket
Настройка
С помощью API происходит обмен информацией между сторонним сервисом и Sipuni.
События в телефонии (начало, перевод, завершение звонка,
ответ
оператора) передаются на сторонний сервис для дальнейшей обработки. В свою очередь, сторонний сервис также отправляет запросы в телефонию (заказ
вызова) с помощью API.
Чтобы
включить
услугу,
перейдите
в меню "Интеграции" - "API" и откройте закладку "События
на АТС". Нажмите
кнопку
«Подключить
услугу».
В настройках включите параметр “Использовать вебсокет-сервер”.
Нажмите кнопку «Сохранить».
Вебсокет сервер доступен для получения событий. Все запросы к серверу и ответы от него производятся в формате JSON.
Аутентификация
Для аутентификации используйте запрос:
{"type":"auth","body":{"key":"<код аутентификации>"}}
Пример:
{"type":"auth","body":{"key":"b3762fc77dd7ca44c643a7a730152bfb"}}
В
случае
успешной
авторизации
сервер
ответит:
{"action": "auth", "status": 1}
Теперь сервер будет присылать сообщения о событиях на АТС.
Серверу
высылаются запросы keepalive для поддержания соединения.
{"type":"keepalive"}
Оповещения от сервера
Оповещения передаются в формате JSON в виде:
{
"action": "notify", "request": {
<тело запроса>
}
},
Обязательные параметры для всех видов запросов:
event
–
тип
запроса.
call_id – уникальный идентификатор вызова (сохраняется неизменным при переводе), является строкой произвольного формата (с использованием URL кодировки).
src_num – адрес абонента инициализировавшего вызов (сохраняется при переводе).
src_type – тип адреса ( 1 - внешний, 2 - внутренний).
dst_num – адрес назначения – при запросе на «умную» переадресацию» допускается пустое значение.
dst_type – тип адреса назначения ( 1 - внешний, 2 - внутренний).
timestamp – время события (начала/завершения вызова, перевода, ответа), представляет собой Unix timestamp (UTC).
channel – канал, открываемый при ответе, либо генерируемый внешним вызовом. Этот параметр нужен был для API перевода вызова и завершения звонка в старой версии API.
Адрес (в определении параметров, перечисленных выше и далее по тексту в данном документе) является телефонным номером либо строкой. Адрес для внешних номеров обязательно номер, внутренний адрес допускается как номером, так и строкой произвольного формата в URL кодировке (например SIP аккаунт).
Виды запросов
Call
событие начала звонка event = 1
Событие генерируется при инициировании, либо при переводе вызова. При переводе сохраняется src_num и call_id текущего вызова. Как только вызов поступает на устройство, приходит event=1.
Для каждого события Call, используемого как оповещение о начале/переводе вызова должно обязательно генерироваться событие Hang-up.
Обязательные параметры:
is_inner_call – флаг определяет, пришел ли данный вызов из вне системы (например, с городского номера)
Hang-up
событие окончания звонка event = 2
Обязательные параметры
status:
ANSWER - вызов отвечен BUSY, - абонент занят
NOANSWER - абонент не ответил после определённого таймаута CANCEL, - вызов сброшен
CONGESTION - перегрузка сети
CHANUNAVAIL – абонент недоступен (например sip абонент не зарегистрирован в сети)
call_start_timestamp – время начала вызова
call_answer_timestamp – время ответа на вызов, в случае отсутствия ответа, значение данного параметра должно быть равно 0.
Дополнительные параметры:
call_record_link
–
URL
на
файл
записи
разговора
(в
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 на файл записи разговора (в URL кодировке)
Примеры запросов
Внешний звонок:
Звонок пришел в систему
{
"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 (номер 262 звонит)
{
"call_id": "1429019739.49501",
"event": 1,
"dst_type": "2",
"dst_num": "0123453262",
"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": "0123453262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019750",
"channel": "SIP/012345262-0000bcfb", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}
Идёт перевод с консультацией на 261, идёт звонок на схему пользователя 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 поднял трубку (сейчас идёт консультация, номер 261 говорит с номером 262, внешний номер 89104846817 на ожидании).
{
"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": "<a href="https://sipuni.com/api/crm/record">https://sipuni.com/api/crm/record</a>?
id=1429019739.49501&hash=abcdefghijklmnopqrstuvwxyzabcdef&user=012345", "channel": "Local/261@transfer_vats-000001e9;2",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}
