С помощью API вы можете получать события, происходящие на вашей ATC Sipuni, такие как начало звонка, ответ оператора, перевод звонка, завершение звонка. Благодаря API вы сможете интегрировать Sipuni в любую вашу систему.
(Вы также можете реализовать запросы от сервиса к АТС, такие как заказ вызова, обратившись к соответствующему API)
Чтобы включить услугу, перейдите в Настройки > API > События на АТС:
https://sipuni.com/ru_RU/settings/integration/crm_http_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
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.