Отправка событий HTTP
Порядок взаимодействия
Чтобы включить услугу, перейдите в Настройки > API > События на АТС: и нажмите кнопку «Подключить услугу».
В настройках системы укажите 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 аккаунт).
short_src_num - внутренний номер инициатора звонка.
Пример - вызов поступает с мобильного номера зафиксированного за одним из наших сотрудников в конструкторе или идет исходящий звонок с SIP-устройства сотрудника.
short_dst_num - внутренний номер назначения.
Пример - идет исходящий звонок на мобильный номер зафиксированный за одним из наших сотрудников в конструкторе или на SIP-устройства сотрудника.
user_id - номер кабинета Sipuni с которым связан поступивший запрос.
transfer_from - номер сотрудника который осуществляет перевод во время звонка. В случае пустого значения, вызов поступает только при переводе звонка сотрудником.
last_called - последний сотрудник на которого поступал звонок по схеме. Если звонок был отправлен на несколько сотрудников одновременно, то придет несколько внутренних номеров сотрудников.
treeName - название схемы на которую поступил звонок.
treeNumber - номер схемы на которую поступил звонок.
Виды запросов
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_
Начало звонка с внешнего номера 89555555555 на внутренний номер 101
http://example.com:9090/?event=1&is_inner_call=1&call_id=1419783130.15593&src_num=89555555555
Номер 101 поднял трубку
http://example.com:9090/?event=3&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_
Вызов
переведён
на
номер
102
http://example.com:9090/?event=1&is_inner_call=1&call_id=1419783130.15593&src_num=89555555555
Номер
102
поднял
трубку
(разговаривают
101
и
102
номер)
http://example.com:9090/?event=3&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_
Номер 101 положил трубку (разговаривают уже 89555555555 и 102):
http://example.com:9090/?event=4&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_
Переведённый вызов завершён:
http://example.com:9090/?event=2&call_id=1419783130.15593&src_num=89555555555&src_type=1&dst_c
Примечание
Короткие и
длинные номера
Логины
номеров
в
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 находится на стадии расширения функционала.
