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

Подписаться

С помощью API вы можете получать события, происходящие на вашей ATC Sipuni, такие как начало звонка, ответ оператора, перевод звонка, завершение звонка. Благодаря API вы сможете интегрировать Sipuni в любую вашу систему.

(Вы также можете реализовать запросы от сервиса к АТС, такие как заказ вызова, обратившись к соответствующему API)

Чтобы включить услугу, перейдите в Настройки > API > События на АТС: 

https://sipuni.com/ru_RU/settings/integration/crm_http_api

и нажмите кнопку «Подключить услугу».

mceclip0.png

 

В настройках системы поставьте галочку “Использовать вебсокет-сервер”, обратите внимание на код аутентификации, он потребуется для подключения. Нажмите кнопку «Сохранить».

Теперь вы можете использовать вебсокет сервер для получения событий. Все запросы к
серверу и ответы от него производятся в формате 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

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

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

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

 

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

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

{
 "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':'SIP/0398031004996479797-0000cc65', 'toNumber': 261}}) );
 
conn.send(JSON.stringify( {'type': "command", body: {'command': 'crmAtxTransfer', 'channel':'SIP/039803262-0000cc66', 'toNumber': 261}}) );
conn.send(JSON.stringify( {'type': "command", body: {'command': 'crmHangupCall', 'channel':'SIP/0398031004996479797-0000cc65'}}) );

 

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

Логины номеров в 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.

 

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 1 из 2