Incoming Call Rules (/incom_rule/)

You can test API methods on the interactive API browser page and without writing code
Some of the resources described on the page may not be available by default due to the type of application (see Creating and authorizing applications).

This resource is used to set rules for processing incoming calls, for example, setting redirects. You can add rules for internal numbers of any type.

You can create several rules for an incoming call (the maximum number is determined by the resource "Limits (/limit/)”.

Description of data structures

Incoming call rule (IncomingRule) 

Name

Type

Mandatory

Default value

Description

Name

Type

Mandatory

Default value

Description

allow_public_transfer

boolean

none

true

If the call was forwarded to an external number (not an internal number within the network), this parameter indicates whether it will be possible to transfer the call from it

call_status

string

none

'any'

The rule will work only if the status of the previous call (the innermost number or the previous forwarding rule) matches the value passed in this parameter:

  • 'no_answer' – no response (on timeout or any error other than "SIP/2.0 486 Busy Here");

  •  'busy' - the number is busy (received by SIP/2.0 486 Busy Here);

  • 'any' – any result

caller_id

string

none

null

The rule will only work for calls whose source is determined by this field. The field is filled in as a PCRE regular expression. For example: "^(\+|)7812" will match all sources starting with "+7812" or "7812"

caller_id_action

string

none

'any'

Defines the method for analyzing the call source caller_id:

  • 'matches' – must match (caller_id must be set);

  • 'not_matches' – must not match (caller_id must be set);

  • 'anonymous' - the source is hidden;

  • 'any' – any source

cascade_numbers

Array[cascade_number]

with type cascade

[ ]

Required for "type": "cascade". Sets the sequence of numbers to be connected to the call and the connection time of each new number in the form of an array of cascade_number elements:

  • delay (integer) - determines when the number is connected to the call. Counts down from the start of the call in seconds;

  • number (string) – the number to connect to the call.

For example:
"cascade_numbers": [ { "delay": 0, "number": "097" }, { "delay": 5, "number": "00018966" } ]
First, the number "097" will be called, and after 5 seconds, the numbers "097" and "00018966" will be called simultaneously

Note: In a cascading call, the number with the minimum delay immediately starts ringing, regardless of its actual value. For example,
"cascade_numbers": [ { "delay": 3, "number": "097" }, { "delay": 5, "number": "00018966" } ]
is identical to sequence
"cascade_numbers": [ { "delay": 0, "number": "097" }, { "delay": 5, "number": "00018966" } ] 

enable_call_screening

boolean

none

true

Enabling the call_screening function for this forwarding rule. This parameter applies only to rules of the transfer and cascade types

enabled

boolean

none

true

This option allows you to enable/disable existing rules

extension_call_status

string

none

'any'

The rule will work only if the status of the internal number call (if it was called) matches the value passed in this parameter:

  • 'no_answer' – no response (on timeout or any error other than "SIP/2.0 486 Busy Here");

  • 'busy' - the number is busy (received by SIP/2.0 486 Busy Here);

  • 'any' – any result

extension_status

string

none

'any'

The rule will work only with this status of the internal number. Accepts one of the values:

  • 'registered' – internal number registered;

  • 'unreachable' – the internal number is not available (for example, registration is lost or the internal number is not responding due to network problems);

  • 'any' - status doesn't matter

final

boolean

none

true

This rule is the last one, and the subsequent ones do not need to be processed

id

long

none



Unique identifier of the rule (within the internal number). Read-only field

ignore_early_media

boolean

none

true

Do not broadcast "early media" to the caller. It can be useful if there is a series of consecutive redirects to different numbers and the caller can hear an answering machine of the type "number not available"

interval

long

none

null

The rule will work when it hits the time interval

name

string

none

null

The name of the rule, not necessarily unique

playfile_sound

long

with type playfile

null

ID of the sound file for the playfile type rule

transfer_dst

string

with type transfer

null

Required for "type": "transfer". Redirects to the specified number. If you need to forward to several numbers at the same time (simultaneous call), then these numbers are listed separated by a space

transfer_timeout

long

none

0

Required for "type": "transfer" and "type":" cascade". The time, in seconds, during which the transfer will be attempted. If the time has elapsed and the transfer has not occurred, then the next rule is processed

type

string

none



Defines the type of action with an incoming call. The following types are implemented:

  • busy - answer an incoming call with a busy signal (SIP/2.0 486 Busy Here);

  • transfer - transfer the call (make a redirect) to the number (s) from transfer_dst;

  • simple_transfer - transfer the call (make a redirect) to the number (s) from transfer_dst. With this type of forwarding, the incoming call rules for the internal numbers listed in transfer_dst are not executed;

  • hangup - reset the call (sip code 480);

  • playfile - play the file (set by the playfile_sound parameter);

  • voicemail - transfer a call to voicemail. Relevant for internal numbers of the "phone" type (configured in the resource “Phone terminal (/phone/)”);

  • cascade - forwarding with sequential addition of the called numbers. For example, for the internal number 100, you can specify 20 seconds to call the internal number itself, then connect a mobile phone to the call so that they are called simultaneously, etc. The cascade sequence is set by the cascade_numbers parameter;

  • simple_cascade - works the same as cascade, but the rules for incoming calls to internal numbers specified in cascade_numbers are not executed

control_code

string

нет

null

The control code is a 1 or 2 character long digit. like 11 or 6

This must be a unique number for each rule on one extension. And it is useful for controlling the rule from the telephone panel. See also: *74 Hotkeys (Hotkeys)

Rule sequence (IncomingRuleOrder) 

Name

Type

Mandatory

Default value

Description

Name

Type

Mandatory

Default value

Description

rules_ids

array [integer]

yes



Complete list of rules in the correct order

Examples 

Let's set up the rules for the internal number of the "phone" type with the ID 54. First, let's make sure that there are no settings at the moment:

System response:
[]

Redirection

Set up sending all unanswered calls to the number 00018966 ("type:" "transfer"). The rule will only be valid from 10:00 to 20:00 and will apply to calls from numbers starting with "+7812" or "000". The number 00018966 should ring for 15 seconds.

The time after which a call to an internal number is considered unanswered (hangup-timeout) is a property of the innermost number of the 'phone' type and is configured by the resource “Phone terminal (/phone/)”.

First, you need to create (or select from the available) time interval.  Let it be an interval with ID 32. Creating a rule:

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

Cascading call

Now, after executing the rules in the previous section, if there was no response, the call goes to the internal number 000*099, after 5 seconds 00026821 is connected to it, and the whole rule works for no more than 20 seconds:

{   "allow_public_transfer": false,   "caller_id": "^(\\+7812|000)",   "call_status": "no_answer",   "extension_status": "any",   "interval": 32,   "enable_call_screening": false,   "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"     }   ],   "control_code": null,   "extension_call_status": "any",   "type": "cascade",   "final": false }

Reorganizing the rules

To reverse the previous rules, just run:

System response:

{     "rules_ids": [         2,         1     ] }

Resources of the "Internal number" section

POST /extension/{extension_id}/incom_rule/

Add an internal number incoming call rule

URL Parameters

Name

Type

Name

Type

extension_id

string

JSON parameters

Name

Type

Mandatory

Name

Type

Mandatory

allow_public_transfer

boolean

none

call_status

string

none

caller_id

string

none

caller_id_action

string

yes

cascade_numbers

Array[cascade_number]

none

control_code 

string

none

enable_call_screening

boolean

none

enabled

boolean

none

extension_call_status

string

none

extension_status

string

none

final

boolean

none

ignore_early_media

boolean

none

interval

long

none

name

string

none

playfile_sound

long

none

transfer_dst

string

none

transfer_timeout

long

none

type

string

yes

cascade_number

Name

Type

Mandatory

Name

Type

Mandatory

delay

long

yes

number

string

yes

Response fields

Name

Type

Name

Type

allow_public_transfer

boolean

call_status

string

caller_id

string

caller_id_action

string

cascade_numbers

Array[cascade_number]

control_code 

string

enable_call_screening

boolean

enabled

boolean

extension_call_status

string

extension_status

string

final

boolean

id

long

ignore_early_media

boolean

interval

long

name

string

playfile_sound

long

transfer_dst

string

transfer_timeout

long

type

string

cascade_number

Name

Type

Name

Type

delay

long

number

string

GET /extension/{extension_id}/incom_rule/

Get a list of internal number incoming call rules

URL Parameters

Name

Type

Name

Type

extension_id

string

Response fields

Name

Type

Name

Type

allow_public_transfer

boolean

call_status

string

caller_id

string

caller_id_action

string

cascade_numbers

Array[cascade_number]

control_code 

string

enable_call_screening

boolean

enabled

boolean

extension_call_status

string

extension_status

string

final

boolean

id

long

ignore_early_media

boolean

interval

long

name

string

playfile_sound

long

transfer_dst

string

transfer_timeout

long

type

string

cascade_number

Name

Type

Name

Type

delay

long

number

string