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

Подписаться

Порядок взаимодействия:

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

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

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

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

mceclip0.png

 

В настройках системы вы указываете URL адрес, например:

http[s]://example.com:[port]/[pbx_prefix]/

и нажимаете кнопку «Сохранить», после этого на него начинают приходить сообщения с
АТС в случае различных событий.

Ваш адрес должен отвечать в случае успеха корректной JSON строкой, содержащей
обязательное поле success. В случае успешной обработки success будет true, в противном случае — false.

В целях безопасности, в случае если корректный ответ не получен, отправка сообщений может быть приостановлена.

Также в JSON могут быть любые другие параметры ответа.
Минимальный корректный ответ:

{“success”: true}

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

 

HTTP запросы:

Входные параметры передаются, используя методы GET или POST. Все строки имеют кодировку символов UTF-8, если не указано иное, и передаются в запросе после применения URL кодирования.

Порядок параметров в запросе является произвольным.

Обязательные параметры для всех видов запросов:

  • event – тип запроса
  • call_id – уникальный идентификатор вызова (сохраняется неизменным при переводе), является строкой произвольного формата (с использованием URL кодировки)
  • src_num – адрес абонента инициализировавшего вызов (сохраняется при переводе)
  • src_type – тип адреса ( 1 - внешний, 2 - внутренний)
  • dst_num – адрес назначения – может быть пустым при запросе на «умную» переадресацию».
  • dst_type – тип адреса назначения ( 1 - внешний, 2 - внутренний)
  • timestamp – время события (начала/завершения вызова, перевода, ответа), представляет собой Unix timestamp (UTC).

Адрес (в определении параметров, перечисленных выше и далее по тексту в данном документе) является телефонным номером либо строкой. Адрес для внешних номеров обязательно должен быть номером, внутренний адрес может являться как номером так и строкой произвольного формата в URL кодировке (например SIP аккаунт).

 

Виды запросов:

Call – событие начала звонка event = 1

Событие генерируется при инициировании, либо при переводе вызова. При переводе
сохраняется src_num и call_id текущего вызова.

Как только вызов поступает на устройство, приходит event=1.

Для каждого события Call, используемого как оповещение о начале/переводе вызова должно
обязательно генерироваться событие Hang-up.

Обязательный параметр:

  • is_inner_call – флаг определяет, пришел ли данный вызов из вне системы (например, с городского номера) (если звонок внутри системы приходит is_inner_call=1, если извне этот флаг не приходит).
    По сути, можно рассматривать как 2 разных события:
    (event = 1 – иницализация звонка, обычно первое событие звонок приходит в систему)
    (event = 1, is_inner_call=0 – звонок внутри системы, например идет дозвон на короткий номер)

Дополнительные параметры:

Если подключен колтрекинг Roistat и системе удается отследить звонок, то приходят также
следующие параметры:

  • roistat – ид посетителя roistat_visit_id
  • roistat_number – (подмененный) номер на который звонил посетитель
  • roistat_market – метка вида source_medium_campaign_keyword

 

Hang-up – событие окончания звонка event = 2

Обязательные параметры:

  • status:
    • ANSWER, - вызов отвечен
    • BUSY, - абонент занят
    • NOANSWER, - абонент не ответил после определённого таймаута
    • CANCEL, - вызов сброшен
    • CONGESTION, - перегрузка сети
    • CHANUNAVAIL – абонент недоступен (например sip абонент не зарегистрирован в сети)
  • call_start_timestamp – время начала вызова
  • call_answer_timestamp – время ответа на вызов, в случае отсутствия ответа, значение данного параметра должно быть равно 0.

Дополнительные параметры:

  • call_record_link – URL на файл записи разговора (в URL кодировке).

Если подключен колтрекинг Roistat и системе удается отследить звонок, то приходят также
следующие параметры:

  • roistatgoogleid – ид gooole_client_id (если доступен)

 

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 кодировке)

 

Пример:

Прямой вызов с переводом (это то, что отправляет АТС)

Звонок пришел в систему (на номер компании 84999999999)

http://example.com:9090/?event=1&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num=84999999999&dst_type=1&timestamp=1378296000

 

Начало звонка с внешнего номера 89555555555 на внутренний номер 101

http://example.com:9090/?event=1&is_inner_call=1&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num=012345101&dst_type=2&timestamp=1378296000

 

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

http://example.com:9090/?event=3&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num=012345101&dst_type=2&timestamp=1378296010

 

Вызов переведён на номер 102

http://example.com:9090/?event=1&is_inner_call=1&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num= 012345102&dst_type=2&timestamp=1378296020

 

Номер 102 поднял трубку (разговаривают 101 и 102 номер)

http://example.com:9090/?event=3&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num= 012345102 &dst_type=2&timestamp=1378296030

 

Номер 101 положил трубку (разговаривают уже 89555555555 и 102):

http://example.com:9090/?event=4&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num=012345102&dst_type=2&call_start_timestamp=1378296000&call_answer_timestamp=1378296040&timestamp=1378296040&status=ANSWER

 

Переведённый вызов завершён:

http://example.com:9090/?event=2&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_num=012345102&dst_type=2&call_start_timestamp=1378296000&call_answer_timestamp=1378296025&timestamp=1378296050&status=ANSWER&call_record_link=ftp%3a%2f%2fmyhost.info%2faccount%2frecords%2f354435435436.wav

 

Примечание. Короткие и длинные номера:

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

 

* API находится на стадии расширения функционала.

 

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