Правила входящего вызова (/incom_rule/)

Owned by Dmitri Savolainen
Last updated: Aug 28, 2020 by Asia Khalitova (Unlicensed)
4 min read

Мы обновили документацию, актуальная версия страницы доступна по ссылке: Правила входящего вызова (/incom_rule/)

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

На входящий вызов можно создавать несколько правил (максимальное количество определяется ресурсом limits).

Ресурсы

РесурсМетодПараметры ПутиТело запросаОписание
extension/{extension_id}/incom_rule/POST

extension_id (integer) уникальный идентификатор добавочного, может принимать значение @me в случае пользователя типа "экстеншен"

поля Правила входящего вызова (/incom_rule/)#IncomingRule, за исключением IncomingRule.id(генерируется автоматически)Добавить правило входящего вызова
extension/{extension_id}/incom_rule/GETextension_id (integer) уникальный идентификатор добавочного, может принимать значение @me в случае пользователя типа "экстеншен"  
Получить список входящих правил для добавочного
extension/{extension_id}/incom_rule/{rule_id}PUT

extension_id (integer) уникальный идентификатор добавочного, может принимать значение @me в случае пользователя типа "экстеншен"

rule_id (integer) идентификатор   IncomingRule.id 

обновленные поля Правила входящего вызова (/incom_rule/)#IncomingRule , за исключением IncomingRule.idОбновляет правила входящего вызова
extension/{extension_id}/incom_rule/{rule_id}DELETE
Удаляет правило входящего вызова
extension/{extension_id}/incom_rule/{rule_id}GET
Получить правило входящего вызова
extension/{extension_id}/incom_rule/order/PUTextension_id (integer) уникальный идентификатор добавочного, может принимать значение @me в случае пользователя типа "экстеншен" Правила входящего вызова (/incom_rule/)#IncomingRuleOrderИзменить порядок правил входящего вызова
extension/{extension_id}/incom_rule/order/GETextension_id (integer) уникальный идентификатор добавочного, может принимать значение @me в случае пользователя типа "экстеншен"
Получить порядок правил входящего вызова


Описание структур данных

Правило входящего вызова (IncomingRule) 

ИмяТипОбязательное

Значение По

Умолчанию

Описание

id

integer

-


Уникальный идентификатор правила (в пределах добавочного). Поле только для чтения.

typestringда

Определяет тип действия со входящим вызовом. Реализованы следующие типы:

  • busy - ответить на входящий вызов сигналом "занято" (SIP/2.0 486 Busy Here)
  • transfer - выполнить перевод вызова (сделать переадресацию) на номер(а) из Правила входящего вызова (/incom_rule/)#transfer_dst.
  • simple_transfer - выполнить перевод вызова (сделать переадресацию) на номер(а) из Правила входящего вызова (/incom_rule/)#transfer_dst. При данном типе переадресации правила входящего вызова для перечисленных в transfer_dst добавочных номеров не выполняются.
  • hangup - сбросить вызов (sip code 480)
  • playfile - проиграть файл (задается параметром Правила входящего вызова (/incom_rule/)#playfile_sound)
  • voicemail - сделать перевод вызова на голосовую почту. Актуально для добавочных типа "phone" (настраивается в ресурсе /phone/)
  • cascade - переадресация с последовательным добавлением вызываемых номеров. Например, для добавочного 100 можно указать 20 секунд вызывать сам добавочный, потом подключить к вызову мобильный, чтобы они вызывались одновременно и т.д. Последовательность каскада задается параметром Правила входящего вызова (/incom_rule/)#cascade_numbers
  • simple_cascade - работает также, как и cascade, но правила входящего вызова добавочных, указанных в cascade_numbers не выполняются
namestringнетnullИмя правила, не обязательно уникальное.
playfile_sound
integerпри type playfilenullИдентификатор звукового файла для правила типа playfile.
transfer_dst
stringпри type transfernullОбязателен для "type": "transfer". Переадресация на указанный номер. Если нужна переадресация на несколько номеров одновременно (одновременный вызов), то эти номера перечисляются через пробел.

transfer_timeout

integer

нет

60

Обязателен для "type": "transfer" и "type": "cascade". Время в секуднах, в течении которого будет пытаться осуществиться перевод. Если время истекло, а перевода не произошло, то происходит переход к обработке следующего правила

cascade_numbers
arrayпри type cascade[ ]

Обязателен для "type": "cascade". Задает последовательность подключаемых к вызову номеров и время подключения каждого нового номера в виде массива cascade_number элементов:

 cascade_number:

  • delay - (integer) определяет момент подключения номера к вызову. Отсчитывается от начала вызова в секундах
  • number - (string) номер, подключаемый к вызову

Например:
"cascade_numbers": [ { "delay": 0, "number": "097" }, { "delay": 5, "number": "00018966" } ]
Сначала будет вызываться номер "097", а через 5 секунд будут одновременно вызываться номера "097" и "00018966"

Примечание: при каскадном вызове сразу начинает звонить номер с минимальным delay, независимо от его фактического значения. Например:
"cascade_numbers": [ { "delay": 3, "number": "097" }, { "delay": 5, "number": "00018966" } ]
идентично последовательности 
"cascade_numbers": [ { "delay": 0, "number": "097" }, { "delay": 5, "number": "00018966" } ] 

allow_public_transferbooleanнетfalseЕсли переадресация была на внешний номер (не добавочный внутри сети), то указывает, можно ли с него будет делать трансфер звонка.  
caller_id
stringнетnullПравило будет работать только для вызовов, источник которых определяется этим полем. Поле заполняется в виде регулярного выражения PCRE. Например: "^(\+|)7812" будет соответствовать всем источникам, начинающимся на "+7812" или "7812"

caller_id_action

string

нет

'any'

определяет метод анализа источника вызова caller_id:

  • 'matches' должен совпадать (caller_id должен быть задан)
  • 'not_matches' должен не совпадать (caller_id должен быть задан)
  • 'anonymous' источник скрыт
  • 'any' любой источник

call_status

string

нет

'any'

Правило отработает только в случае, если статус предыдущего вызова (самого добавочного либо предыдущего правила переадресации) соответствует значению, переданному в этом параметре

  • 'no_answer' - не было ответа (по таймауту или какая-либо ошибка, кроме "SIP/2.0 486 Busy Here")
  •  'busy' - номер занят (получен SIP/2.0 486 Busy Here)
  • 'any' - любой результат
extension_call_status

string

нет

'any'

Правило отработает только в случае, если статус вызова добавочного (если он вызывался) соответствует значению, переданному в этом параметре.

  • 'no_answer' - не было ответа (по таймауту или какая-либо ошибка, кроме "SIP/2.0 486 Busy Here")
  •  'busy' - номер занят (получен SIP/2.0 486 Busy Here)
  • 'any' - любой результат

extension_status

string

нет

'any'

Правило отработает лишь при таком статусе добавочного. Принимает одно из значений:

  •  'registered' добавочный зарегистрирован
  •  'unreachable' добавочный недоступен (например, потеряна регистрация, или добавочный не отвечает из-за проблем с сетью)
  • 'any' статус не имеет значения

interval

integer

нет

null

Правило отработает при попадании во временной интревал

enabled

boolean

нет

true

Опция позволяет включать/выключать существующие правила

ignore_early_media

boolean

нет

true

Не транслировать вызывающему абоненту "early media". Может быть полезно, если происходит серия последовательных переадресаций на разные номера и вызывающий абонент может слышать автоответчик вида "номер не доступен"

final

boolean

нет

true

Это правило является последним и последующие обрабатывать не нужно

enable_call_screeningbooleanнетfalseВключение функции call_screening для данного правила переадресации. Параметр применим только к правилами типа transfer и cascade.

Последовательность правил (IncomingRuleOrder) 

ИмяТипОбязательное

Значение По

Умолчанию

Описание

rules_ids

array [integer]

да


Полный список правил в нужном порядке


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

Настроим правила для добавочного типа "phone"с идентификатором 54. Для начала убедимся, что на данный момент нет никаких настроек

метод
ресурс
данные
ответ
GET
/extension/54/incom_rule/


[]

Переадресация

Настроим отправку всех не отвеченных вызовов   на  номер 00018966 ("type:" "transfer"). Правило должно будет действовать только с 10:00 до 20:00 и распространяться на вызовы с номеров, начинающихся на "+7812" или "000". Номер 00018966 должен звонить 15 секунд.

Время, после которого вызов на добавочный считается не отвеченным (hangup-timeout) является свойством самого добавочного типа 'phone' и настраивается ресурсом phone.

Для начала нужно создать (или выбрать из имеющихся) временной интервал.  Пусть это будет интервал с идентификатором 32. Создание правила:

метод
ресурс
данные
ответ
POST
/extension/54/incom_rule/

{
"caller_id": "^(\\+7812|000)",
"caller_id_action": "matches",
"interval": 32,
"transfer_dst": "00018966",
"transfer_timeout": 15,
"type": "transfer",
"call_status": "no_answer",
"final": false 

}

{
"allow_public_transfer": false,
"caller_id": "^(\\+7812|000)",
"call_status": "no_answer",
"extension_status": "any",
"interval": 32,
"enabled": true,
"name": null,
"ignore_early_media": true,
"id": 1,
"transfer_dst": "00018966",
"transfer_timeout": 15,
"playfile_sound": null,
"caller_id_action": "matches",
"cascade_numbers": null,
"type": "transfer",
"final": false
}

Каскадный вызов

Теперь нужно, чтобы после выполнения правил в предыдущем разделе, если ответа так и не последовало, вызов перешел на добавочный 000*099 и через 5 секунд к нему  подключился 00026821 и все правило отрабатывало не более 20 секунд

метод
ресурс
данные
ответ
POST
/extension/54/incom_rule/

{
"caller_id": "^(\\+7812|000)",
"caller_id_action": "matches",
"interval": 32,
"transfer_timeout": 20,
"type": "cascade",
"call_status": "no_answer",
"cascade_numbers": [
{
"delay": 0,
"number": "000*099"
},
{
"delay": 5,
"number":"00026821"
}

  "final": false

]
}

{
"allow_public_transfer": false,
"caller_id": "^(\\+7812|000)",
"call_status": "no_answer",
"extension_status": "any",
"interval": 32,
"enabled": true,
"name": null,
"ignore_early_media": true,
"id": 2,
"transfer_dst": null,
"transfer_timeout": 20,
"playfile_sound": null,
"caller_id_action": "matches",
"cascade_numbers": [
{
"delay": 0,
"number": "000*099"
},
{
"delay": 5,
"number": "00026821"
}
],
"type": "cascade",
"final": false
}


Реорганизация правил

Чтобы поменять предыдущие правила местами достаточно выполнить:

метод
ресурс
данные
ответ
PUT
/extension/54/incom_rule/order/

{
"rules_ids": [
2,1
]
}

{
"rules_ids": [
2,
1
]
}

Ресурсы раздела "Добавочный"

POST /extension/{extension_id}/incom_rule/

Добавить правило входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

Параметры JSON

Имя

Тип

Обязательный

allow_public_transfer

boolean

нет

extension_call_status

string

нет

call_status

string

нет

transfer_dst

string

нет

enable_call_screening

boolean

нет

enabled

boolean

нет

interval

integer

нет

caller_id_action

string

да

ignore_early_media

boolean

нет

caller_id

string

нет

extension_status

string

нет

transfer_timeout

integer

нет

playfile_sound

integer

нет

cascade_numbers

array [cascade_number]

нет

type

string

да

final

boolean

нет

name

string

нет

Поля ответа

Имя

Тип

allow_public_transfer

boolean

extension_call_status

string

call_status

string

transfer_dst

string

enable_call_screening

boolean

enabled

boolean

interval

integer

caller_id_action

string

ignore_early_media

boolean

caller_id

string

id

integer

extension_status

string

transfer_timeout

integer

playfile_sound

integer

cascade_numbers

array [cascade_number]

type

string

final

boolean

name

string

GET /extension/{extension_id}/incom_rule/

Получить список правил входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

Поля ответа

Имя

Тип

allow_public_transfer

boolean

extension_call_status

string

call_status

string

transfer_dst

string

enable_call_screening

boolean

enabled

boolean

interval

integer

caller_id_action

string

ignore_early_media

boolean

caller_id

string

id

integer

extension_status

string

transfer_timeout

integer

playfile_sound

integer

cascade_numbers

array [cascade_number]

type

string

final

boolean

name

string

PUT /extension/{extension_id}/incom_rule/order/

Обновить порядок правил входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

Параметры JSON

Имя

Тип

Обязательный

rules_ids

array [integer]

да

Поля ответа

Имя

Тип

rules_ids

array [integer]

GET /extension/{extension_id}/incom_rule/order/

Получить порядок правил входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

Поля ответа

Имя

Тип

rules_ids

array [integer]

PUT /extension/{extension_id}/incom_rule/{rule_id}

Обновить правило входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

rule_id

integer

Параметры JSON

Имя

Тип

Обязательный

allow_public_transfer

boolean

нет

extension_call_status

string

нет

call_status

string

нет

transfer_dst

string

нет

enable_call_screening

boolean

нет

enabled

boolean

нет

interval

integer

нет

caller_id_action

string

нет

ignore_early_media

boolean

нет

caller_id

string

нет

extension_status

string

нет

transfer_timeout

integer

нет

playfile_sound

integer

нет

cascade_numbers

array [cascade_number]

нет

type

string

нет

final

boolean

нет

name

string

нет

Поля ответа

Имя

Тип

allow_public_transfer

boolean

extension_call_status

string

call_status

string

transfer_dst

string

enable_call_screening

boolean

enabled

boolean

interval

integer

caller_id_action

string

ignore_early_media

boolean

caller_id

string

id

integer

extension_status

string

transfer_timeout

integer

playfile_sound

integer

cascade_numbers

array [cascade_number]

type

string

final

boolean

name

string

GET /extension/{extension_id}/incom_rule/{rule_id}

Получить правило входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

rule_id

integer

Поля ответа

Имя

Тип

Имя

Тип

allow_public_transfer

boolean

extension_call_status

string

call_status

string

transfer_dst

string

enable_call_screening

boolean

enabled

boolean

interval

integer

caller_id_action

string

ignore_early_media

boolean

caller_id

string

id

integer

extension_status

string

transfer_timeout

integer

playfile_sound

integer

cascade_numbers

array [cascade_number]

type

string

final

boolean

name

string

DELETE /extension/{extension_id}/incom_rule/{rule_id}

Удалить правило входящего вызова добавочного

Параметры URL

Имя

Тип

extension_id

string

rule_id

integer

Похожие разделы