Webhooks

Webhooks - это механизм оповещения пользователей системы о звонках и SMS.

При изменении статуса очередного звонка или приеме SMS платформа ТелеСтор отправляет HTTP-запрос (POST), в теле которого в формате JSON содержится информация о звонке или SMS.

Список HTTP/HTTPS URL, на которые необходимо отправить этот запрос, пользователь с правами администратора задает в своем Личном кабинете услуги ТелеВАТС, на странице Настройки - Дополнительно.

Пример запроса для звонка:

$ cat <<EOF > body.json
{
  "call": {
    "a_account": "",
    "a_name": "",
    "a_number": "79112223344",
    "b_account": "0231",
    "b_number": "78123332332",
    "id": "1592-294330-60361",
    "r_number": "",
    "start_timestamp": "2020-06-16T07:59:03.734126894Z",
    "type": "incoming"
  },
  "event":"invite",
  "source":"account",
  "vpbx":"000001"
}
EOF
$ curl -v -X POST -H "Content-Type: application/json" --data @body.json "http://localhost:8080/webhooks"

Пример запроса для SMS:

$ cat <<EOF > body.json
{
  "sms": {
    "a_number": "79112223344",
    "b_number": "78123332332",
    "start_timestamp": "2020-06-16T07:59:03.734126894Z",
    "type": "outgoing",
    "message": "Тестовое сообщение"
  },
  "event":"sms",
  "vpbx":"000001"
}
EOF
$ curl -v -X POST -H "Content-Type: application/json" --data @body.json "http://localhost:8080/webhooks"

Информация о звонке

В каждом запросе платформа ТелеСтор передает информацию о звонке в формате JSON:

Ключ Тип Описание Обязательный Значения
event строка имя события да invite - поступление вызова, answer - ответ абонента, hangup - завершение вызова, begin - начало разговора, end - конец разговора
source строка источник события (см. раздел Источники событий о звонках) да number - городской номер, neighbour - "свой" номер, sip-number - SIP-адрес, account - внутренний аккаунт, talk - разговор
vpbx строка код клиента да
call объект параметры звонка да
call.id строка идентификатор звонка да
call.type строка тип вызова да incoming - входящий, outgoing - исходящий, missed - пропущенный, internal - внутренний, fax - принятый факс, voicemail - принятое голосовое сообщение
call.a_name строка имя вызывающего абонента
call.a_number строка номер вызывающего абонента в формате Е.164 да
call.b_number строка номер вызываемого абонента в формате Е.164 да
call.r_number строка номер абонента, который переадресовал вызов, в формате Е.164
call.a_account строка идентификатор аккаунта, который инициировал вызов
call.b_account строка идентификатор аккаунта, на который поступил вызов
call.r_account строка идентификатор аккаунта, который переадресовал вызов
call.a_def строка номер мобильного абонента, который инициировал вызов (в случае инициации вызова с SIM-карты)
call.b_def строка номер мобильного абонента, на который поступил вызов (в случае завершения вызова на SIM-карту)
call.neighbour строка идентификатор "своего" номера в формате user@domain.com
call.first_start_timestamp временная метка для source=talk - момент создания первого плеча разговора
call.start_timestamp временная метка момент поступления вызова (для source=talk - момент создания второго плеча разговора) да
call.answer_timestamp временная метка момент ответа абонента на вызов
call.hangup_timestamp временная метка момент завершения вызова
call.hangup_cause строка причина завершения вызова (см. раздел Причины завершения вызова)
call.hangup_cause_code число код причины завершения вызова (см. раздел Причины завершения вызова)
call.record строка URL файла с записью разговора
call.record_stereo строка URL файла с записью разговора в стерео (срок хранения 1 неделя)
call.fax строка URL файла с принятым факсимильным документом
call.voicemail строка URL файла с записью, оставленной в голосовой почте

Информация о SMS

В каждом запросе платформа ТелеСтор передает информацию о SMS в формате JSON:

Ключ Тип Описание Обязательный Значения
event строка имя события да sms - отправка или получение SMS
vpbx строка код клиента да
sms объект параметры SMS да
sms.type строка тип SMS да incoming - входящее, outgoing - исходящее
sms.a_number строка номер вызывающего абонента в формате Е.164 да
sms.b_number строка номер вызываемого абонента в формате Е.164 да
sms.start_timestamp временная метка момент поступления вызова да
sms.message строка содержимое сообщения да

Источники событий о звонках

В платформе ТелеСтор есть 5 источников событий о звонках:

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

Причины завершения вызова

Код Причина
0 Unspecified (unknown)
1 Unallocated Number
2 No Route Transit Net
3 No Route Destination
6 Channel Unacceptable
7 Call Awarded Delivered
16 Normal Clearing
17 User Busy
18 No User Response
19 No Answer
20 Subscriber Absent
21 Call Rejected
22 Number Changed
23 Redirection To New Destination
25 Exchange Routing Error
27 Destination Out Of Order
28 Invalid Number Format
29 Facility Rejected
31 Normal Unspecified
30 Response To Status Enquiry
34 Normal Circuit Congestion
38 Network Out Of Order
41 Normal Temporary Failure
42 Switch Congestion
43 Access Info Discarded
44 Requested Chan Unavail
50 Facility Not Subscribed
52 Outgoing Call Barred
54 Incoming Call Barred
57 Bearer Capability Not Auth
58 Bearer Capability Not Avail
63 Service Unavailable
65 Bearer Capability Not Impl
66 Chan Not Implemented
69 Facility Not Implemented
79 Service Not Implemented
81 Invalid Call Reference
88 Incompatible Destination
95 Invalid Msg Unspecified
96 Mandatory IE Missing
97 Message Type Non Exist
98 Wrong Message
99 IE Non Exist
100 Invalid IE Contents
101 Wrong Call State
102 Recovery On Timer Expire
103 Mandatory IE Length Error
111 Protocol Error
127 Interworking
487 Originator Cancel
601 Attended Transfer

Внешнее управление вызовами

Запросы с событиями отправляются асинхронно. В связи с этим для внешнего управления вызовами необходимо в настройках телефонного номера устанавливать голосовое приветствие, чтобы за время его проигрывания успеть получить ответ на запрос.

При отправке запроса с событием о поступлении входящего вызова на городской или "свой" номер платформа ТелеСтор учитывает последний непустой ответ.

Перед тем, как переадресовать вызов в соответствии с настройками номера, заданными через Личный кабинет, она выполняет следующие действия при наличии в полученном ответе непустых значений следующих ключей (в формате JSON):

Ключ Тип Действие
contact строка устанавливается имя вызывающего абонента
prompt строка URL к голосовому файлу, который необходимо проиграть перед выполнением переадресацией. Файл должен быть в формате WAV (Microsoft PCM, 16 bit, mono 8000 Hz)
dst строка переадресует входящий вызов на указанный в данном параметре номер (в формате E.164) или SIP-адрес (в формате user@domain.com), либо на внутренний аккаунт, последние 4 цифры которого указаны в данном параметре
number строка при отсутствии параметра dst, в первую очередь, переадресует входящий вызов на указанный в данном параметре номер (в формате E.164)
uri строка при отсутствии параметра dst, во вторую очередь, переадресует входящий вызов на указанный в данном параметре SIP-адрес (в формате user@domain.com)
accounts массив строк при отсутствии параметра dst, в третью очередь, направляет вызов одновременно на внутренние аккаунты, идентификаторы которых указаны в данном массиве
hangup булев завершить звонок после выполнения переадресации на номера, переданные в ответе
hangupTimeout число таймаут принудительного завершения звонка после ответа абонента, секунды

Пример ответа c параметром dst:

{
  "contact": "Иван Иванов",
  "dst": "78123332332"
}

Пример ответа без параметра dst:

{
  "contact": "Иван Иванов",
  "number": "78123332332",
  "uri": "user@provider.com",
  "accounts": [
    "1000",
    "1001"
  ]
}

Пример ответа c голосовым сообщением без переадресации:

{
  "prompt": "https://www.telestore.ru/files/verified/test_welcome.wav",
  "hangup": true
}

Пример ответа c параметром dst, с ограничением на длительность звонка в 10 минут:

{
  "contact": "Иван Иванов",
  "dst": "78123332332",
  "hangupTimeout": 600
}

Таймауты

При отправке запросов определены следующие таймауты: