Отправка событий АТС на скрипт. Websocket API


С помощью API вы можете получать события, происходящие на вашей ATC Sipuni, такие как начало звонка, ответ оператора, перевод звонка, завершение звонка. Благодаря 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/0398031004996479797-0000bcf9",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}


АТС направила звонок на короткий номер 262 (номер 262 звонит)

{
"call_id": "1429019739.49501",
"event": 1,
"dst_type": "2",
"dst_num": "039803262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019747",
"is_inner_call": true, // Это логика АТС
"channel": "SIP/0398031004996479797-0000bcf9",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}


Номер 262 поднял трубку.

{
"call_id": "1429019739.49501",
"event": "3",
"dst_type": "2",
"dst_num": "039803262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019750",
"channel": "SIP/039803262-0000bcfb", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}


Идёт перевод с консультацией на 261, идёт звонок на схему пользователя 261.

{
"call_id": "1429019739.49501",
"event": "1",
"dst_type": "2",
"dst_num": "039803261",
"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": "039803261",
"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": "039803261",
"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": "039803262",
"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019780",
"channel": "Transfered/SIP/0398031004996479797-0000bcf9", "treeName": "Тестирование CRM",
"treeNumber": "000960393"
}


Звонок полностью завершен.

{
"call_id": "1429019739.49501",
"event": "2",
"dst_type": "2",
"dst_num": "039803261",

"src_type": "1",
"src_num": "89104846817",
"timestamp": "1429019790", "status": "ANSWER",
"call_start_timestamp": "1429019739",
"call_answer_timestamp": "1429019750",
"call_record_link": "https://sipuni.com/api/crm/record?
id=1429019739.49501&hash=abcdefghijklmnopqrstuvwxyzabcdef&user=012345", "channel": "Local/261@transfer_vats-000001e9;2",
"treeName": "Тестирование CRM", "treeNumber": "000960393"
}


Внутренний звонок:


Внутренний звонок с номера 262 на 261

{
"call_id": "1429021671.49573",
"event": 1,
"dst_type": "2",
"dst_num": "039803261",
"src_type": "2",
"src_num": "039803262",
"timestamp": "1429021671", "is_inner_call": true,
"channel": "SIP/039803262-0000bd3c"
}


АТС обработала схему номера 261 и звонит на короткий номер

{
"call_id": "1429021671.49573",
"event": 1,
"dst_type": "2",
"dst_num": "039803261",
"src_type": "2",
"src_num": "039803262",
"timestamp": "1429021672", "is_inner_call": true,
"channel": "Local/000987601@vatsl-000001eb;2","treeName": "Боря персональная", "treeNumber": "000987601"
}


261 поднял трубку и разговаривает с 262

{
"call_id": "1429021671.49573",
"event": "3",
"dst_type": "2",
"dst_num": "039803261",
"src_type": "2",
"src_num": "039803262",
"timestamp": "1429021674",
"channel": "SIP/039803261-0000bd3d"
}


262 переводит на 238

{
"call_id": "1429021671.49573",
"event": "1",
"dst_type": "2",
"dst_num": "039803238",
"src_type": "2",
"src_num": "039803262",
"timestamp": "1429021686",
"channel": "Local/238@transfer_vats-000001ec;2"
}


    238 поднял трубку и разговаривает с 261 (консультация, 262 ждёт)

    {
    "call_id": "1429021671.49573",
    "event": "3",
    "dst_type": "2",
    "dst_num": "039803238",
    "src_type": "2",
    "src_num": "039803262",
    "timestamp": "1429021690",

    "channel": "SIP/039803238-0000bd3e"
    }


    261 положил трубку (262 разговаривает с 238)

    {
    "call_id": "1429021671.49573",
    "event": "4",
    "dst_type": "2",
    "dst_num": "000987601",
    "src_type": "2",
    "src_num": "039803262",
    "timestamp": "1429021697",
    "channel": "Transfered/SIP/039803262-0000bd3c"
    }


    Звонок завершен

    {
    "call_id": "1429021671.49573",
    "event": "2",
    "dst_type": "2",
    "dst_num": "039803238",
    "src_type": "2",
    "src_num": "039803262",
    "timestamp": "1429021703", "status": "ANSWER",
    "call_start_timestamp": "1429021672",
    "call_answer_timestamp": "1429021674",
    "call_record_link": "https://sipuni.com/api/crm/record?
    id=1429021671.49573&hash=abcdefghijklmnopqrstuvwxyzabcdef&user=012345", "channel": "Local/238@transfer_vats-000001ec;2",
    "treeName": "Боря персональная",
    "treeNumber": "000987601"
    }


    Трансферы


    Наша система позволяет инициировать перевод звонков с консультацией и без, а также завершать вызов. Для трансферов используются идентификатор звонка.

    Трансферы для отвеченного звонка:


    crmTransfer - безусловный перевод,

    {
    "type": "command", "body": {
    "command": "crmTransfer",
    "callId": "1429191664.53595",
    "toNumber": "261"
    },
    "requestId": "3ad7b153c"
    }


    crmAtxTransfer - перевод с консультацией,

    {
    "type": "command", "body": {
    "command": "crmAtxTransfer", "callId": "1429191664.53595",
    "toNumber": "261"
    },
    "requestId": "3ad7b153c"
    }


    crmHangupCall — завершение вызова,

    {
    "type": "command", "body": {
    "command": "crmHangupCall",
    "callId": "1429191664.53595",
    },
    "requestId": "3ad7b153c"
    }


    Трансфер для неотвеченного звонка:


    crmRedirectCall

    {
    "type": "command", "body": {
    "command": "crmRedirectCall", "callId": "1429191664.53595",
    "toNumber": "261"
    },
    "requestId": "3ad7b153c"
    }


    Параметры:


    command – тип команды callId – идентификатор звонка

    toNumber – для команд перевода короткий номер на который переводится звонок

    requestId — опциональный параметр, позволяющий понять к какоми за запросов относится ответ.


    На все запросы приходит ответ вида


    в случае успеха:

    {"success":true,"requestId":"3ad7b153c"}


    в случае ошибки:

    {"success":false,"error":"can't find the channel for this call id","requestId":"3ad7b153c"}


    Пример трансфера:


    Звонок пришел в систему

    {
    "call_id": "1429191664.53595",
    "event": "1",
    "dst_type": "1",
    "dst_num": "4999678420",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191664",
    "channel": "SIP/0398031004996479797-0000cc65",
    "treeName": "Тестирование CRM",

    "treeNumber": "000960393"
    }


    Звонок обработан системой, звонит 262

    {
    "call_id": "1429191664.53595",
    "event": 1,
    "dst_type": "2",
    "dst_num": "039803262",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191675", "is_inner_call": true,
    "channel": "SIP/0398031004996479797-0000cc65",
    "treeName": "Тестирование CRM", "treeNumber": "000960393"
    }


    Звонок обработан системой, 262 поднял трубку

    {
    "call_id": "1429191664.53595",
    "event": "3",
    "dst_type": "2",
    "dst_num": "039803262",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191679",
    "channel": "SIP/039803262-0000cc66",
    "treeName": "Тестирование CRM", "treeNumber": "000960393"
    }


    команды будут отправляться с callId 1429191664.53595


    Трансферы с использованием каналов (устаревшее)


    Для трансферов используются каналы, которые берутся из событий. Это устаревшая система и менее удобная система, описание оставлено для обратной совместимости.

    Трансферы работают только для отвеченного звонка,


    crmTransfer - безусловный перевод, в параметре надо указывать channel сообщения с event = 1 и is_inner_call

    = true.

    conn.send(JSON.stringify( {'type': "command", body: {'command': 'crmTransfer', 'channel': '', 'toNumber': }}) );


    crmAtxTransfer - перевод с консультацией, в параметре надо указывать channel из сообщения с event=3



    crmHangupCall — завершение вызова. Для завершения вызова используется канал из сообщения с event = 1


    Пример трансфера с использованием канала


    Звонок пришел в систему

    {
    "call_id": "1429191664.53595",
    "event": "1",
    "dst_type": "1",
    "dst_num": "4999678420",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191664",
    "channel": "SIP/0398031004996479797-0000cc65",
    "treeName": "Тестирование CRM", "treeNumber": "000960393"
    }


    Звонок обработан системой, звонит 262

    {
    "call_id": "1429191664.53595",
    "event": 1,

    "dst_type": "2",
    "dst_num": "039803262",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191675", "is_inner_call": true,
    "channel": "SIP/0398031004996479797-0000cc65",
    "treeName": "Тестирование CRM", "treeNumber": "000960393"
    }


    Звонок обработан системой, 262 поднял трубку

    {
    "call_id": "1429191664.53595",
    "event": "3",
    "dst_type": "2",
    "dst_num": "039803262",
    "src_type": "1",
    "src_num": "89104846817",
    "timestamp": "1429191679",
    "channel": "SIP/039803262-0000cc66",
    "treeName": "Тестирование CRM", "treeNumber": "000960393"
    }


    Тогда команды будут:


    conn.send(JSON.stringify( {'type': "command", body: {'command': 'crmTransfer', 'channel':'SIPconn.send(JSON.stringify( {'type': "command", body: {'command': 'crmAtxTransfer', 'channel':'

    conn.send(JSON.stringify( {'type': "command", body: {'command': 'crmHangupCall', 'channel':'S



    Короткие и длинные номера

    Логины номеров в SIPUNI имеют вид <номер пользователя><короткий номер>.


    И в полях src_num и dst_num приходят именно логины. Для пользователя с номером в системе 012345, короткий номер 101 будет обозначаться 012345101.


    Некоторым пользователям достаточно только самого короткого номера, поэтому в запросах дополнительно добавлены поля short_src_num и short_dst_num, куда записываются не логины, а сами короткие номера.


    Например, если src_num = 012345101, то short_src_num = 101. Поля различаются только короткими номерами SIPUNI. Для внешних номеров они полностью одинаковы, например, если src_num = 79031234567, то

    и short_src_num = 79031234567.