Functional group (sipkit)

Description

Defines a group of SIP user accounts whose calls are serviced according to the group algorithm.

The following functional types are available: redirect group, reject group, call option setting group, parallel call group, chief-secretary group.

Limitations

  • The collection is unavailable in the master domain.

Fields

Entity structure
{
  "id": uuid,
  "name": str,
  "type": str,
  "enabled": bool,
  "cascade": bool,
  "priority": int,
  "details": object,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Fields
Specification Description

Field: id
Mode: inout
Type: uuid
Default: generated

Identifier. Can be specified at creation, otherwise generated by the system.

Field: name
Mode: in
Type: str
Default: required

Group name. Displayed during tracing.

Field: type
Mode: in
Type: str
Default: required

Group type. Specific settings are defined for each type in the 'details' field.
The following types are available:

  • redirect - call redirect.

  • reject - call rejection.

  • options - setting call parameters.

  • parallel - call parallelization.

  • chief - chief-secretary.

  • custom - used to implement project logic.

Field: enabled
Mode: in
Type: bool
Default: true

Group switch.

Field: cascade
Mode: in
Type: bool
Default: false

Cascade mode switch.
If disabled, when a higher-priority group is applied to the same number, a lower-priority group of the same type is not applied.
However, if forwarding or parallelization occurs while the group is applied, the application of groups of this type to other numbers is not blocked.

Field: priority
Mode: in
Type: int
Default: 1000

Group application priority.

Field: details
Mode: in
Type: object
Default: ``

Object with typed settings.
If typed settings are not specified when creating a group, they are formed and filled with default values.

More in Group types.

Field: opts
Mode: in
Type: object

Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Arbitrary title

Field: opts.comment
Mode: in
Type: str
Default: empty

Arbitrary comment

Default: empty"

Arbitrary comment

Field: ext
Mode: inout
Type: object

Compound field allowing extension with arbitrary keys and values

Field: ext.ct
Mode: out
Type: date
Default: generated

Object creation time

Field: ext.lwt
Mode: out
Type: date
Default: generated

Time of last modification of the object

Group types

Depending on the configured group type, a special 'details' parameter is set and the corresponding logic is implemented on a call.

Redirect group (redirect)

Call redirect group.

The 'filter_from' filter is applied to the original initiating subscriber number without regard to forwarding and transfers. The number of the subscriber who forwarded the call can be filtered by the 'filter_by' field.

Table 2. Parameters
Field: filter_from
Mode: in
Type: str
Default: *
Source number filter mask.
The result of modification by routing rules applied at previous steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

Field: filter_by
Mode: in
Type: str
Default: *

Filter mask for the number of the subscriber who forwarded the call.
Filter operation modes.

Field: numbers_to
Mode: in
Type: array<str>
Default: []

List of numbers on whose call the group is activated.

Field: redirect_number
Mode: in
Type: str
Default: empty

Number for redirect.

Example
{
  "filter_from": "*",
  "filter_by": "*",
  "redirect_number": "122"
}

Reject group (reject)

Call rejection group.

The 'filter_from' filter is applied to the original initiating subscriber number without regard to forwarding and transfers. The number of the subscriber who forwarded the call can be filtered by the 'filter_by' field.

Table 3. Parameters
Field: filter_from
Mode: in
Type: str
Default: *
Source number filter mask.
The result of modification by routing rules applied at previous steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

Field: filter_by
Mode: in
Type: str
Default: *

Filter mask for the number of the subscriber who forwarded the call.
Filter operation modes.

Field: numbers_to
Mode: in
Type: array<str>
Default: []

List of numbers on whose call the group is activated.

Field: sip_code
Mode: in
Type: int
Default: 403

Response code.

Field: sip_reason
Mode: in
Type: str
Default: Rejected by kit

Rejection reason.

Example
{
  "filter_from": "*",
  "filter_by": "*",
  "sip_code": 603,
  "sip_reason": "Some reason"
}

Call option setting group (options)

The group forms a change of call options for the leg and child legs (calls initiated by forwarding and/or parallel calls within the current routing process).
In particular, it allows setting:

  • dialog_timeoutsec - conversation duration limit (from 5 to 7200).

  • fork_timeoutsec - specific leg call time (from 3 to 180).

  • fork_fromuri - calling subscriber representation.

The set value applies to all child legs unless an individual setting from another group is applied to them later in the routing process.
The default value does not apply the group parameter. The value "undefined" resets a previously applied parameter.

The 'filter_from' filter is applied to the original initiating subscriber number without regard to forwarding and transfers. The number of the subscriber who forwarded the call can be filtered by the 'filter_by' field.

Table 4. Parameters
Field: filter_from
Mode: in
Type: str
Default: *
Source number filter mask.
The result of modification by routing rules applied at previous steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

Field: filter_by
Mode: in
Type: str
Default: *

Filter mask for the number of the subscriber who forwarded the call.
Filter operation modes.

Field: numbers_to
Mode: in
Type: array<str>
Default: []

List of numbers on whose call the group is activated.

Field: dialog_timeoutsec
Mode: in
Type: int
Default: 7200

Maximum dialog duration, seconds.

Value 0 or an incorrect value does not change the parameter.
Value undefined resets the value set by previously applied 'options' groups.
The set value is limited to the interval from 5 to 7200 seconds.

Field: fork_timeoutsec
Mode: in
Type: int
Default: 0

Leg call timeout, seconds.

Applied to all legs child relative to the current call within the current routing process.
Forwarded and parallel calls are taken into account.
It can be changed by subsequent application of a group of the same type to other child destinations.

Value 0 or an incorrect value does not change the parameter.
Value undefined resets the value set by previously applied 'options' groups.
The set value is limited to the interval from 3 to 180 seconds.

Field: fork_fromuri
Mode: in
Type: str
Default: empty

Calling subscriber representation.

Applied to all legs child relative to the current call within the current routing process.
Forwarded and parallel calls are taken into account.
It can be changed by subsequent application of a group of the same type to other child destinations.

Only username and displayname are used.
Value undefined resets the value set by previously applied 'options' groups.
An empty string or incorrect URI format does not change the parameter.

Example
{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "fork_timeoutsec": 3,
  "fork_fromuri": "\"DISPLAY NAME\" <sip:username@domain>"
}

Parallel call group (parallel)

Group for parallelizing a call depending on the call initiator mask and optionally the call transfer initiator.

Any call to an account number listed in 'numbers_to' causes simultaneous calling of the parallel numbers specified in 'numbers_parallel'.
Any means direct, group, transferred, forwarded, or from a script.
If such a number is called as a parallel one from another functional group, the application of its parallel numbers depends on the cascade property of the functional group.

It is a general alternative to configuring an individual parallel call in the SIP user account.
In this case the call in statistics is bound to the real owner of the destination number.

The 'filter_from' filter is applied to the original initiating subscriber number without regard to forwarding and transfers. The number of the subscriber who forwarded the call can be filtered by the 'filter_by' field.

Table 5. Parameters
Field: filter_from
Mode: in
Type: str
Default: *
Source number filter mask.
The result of modification by routing rules applied at previous steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

Field: filter_by
Mode: in
Type: str
Default: *

Filter mask for the number of the subscriber who forwarded the call.
Filter operation modes.

Field: numbers_to
Mode: in
Type: array<str>
Default: []

List of numbers on whose call the group is activated.

Field: numbers_parallel
Mode: in
Type: array<str>
Default: []

List of numbers used to initiate a parallel call. In any case, calls are sent to each destination number once.

Example
{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "numbers_parallel": ["205","206","207"]
}

Chief-secretary group (chief)

When a call arrives at the chief from numbers not in the direct access list, the secretaries are called.

The decision whether the initiator may call the chief directly is made based on a filter applied to the number of the subscriber who transferred or forwarded the call to the chief.

At the same time, the group allows call pickup, BLF subscription between the chief and secretaries, and places incoming call details in BLF notifications for display on device panels so that group subscribers can see the call initiator and pick up.
Thus there is no need to configure separate permissions between the chief and secretaries with featurerule rules for the following function types:
* pickup, callwaiting, blf, blf_details - in all directions;
* intercom, barge - in the direction from the chief to the secretaries.

For the mode to work fully, you must:
* enable the 'blf_details_enabled' option in domain settings;
* configure BLF subscriptions on the chief’s and secretaries' phones as needed (so that secretaries see the chief’s state and the chief sees the secretaries' states);
* configure the display of call initiator information on the chief’s and secretaries' phones upon receiving a BLF message (Yealink: account.X.dialoginfo_callpickup=1, features.pickup.blf_visual_enable=1);
* restrict the application of BLF visualization on the chief’s and secretaries' phones to a specific list of numbers (Yealink: features.pickup.blf_visual.list=101,102,103 or any);
* if audio notification of a call to the chief’s number is needed, configure the secretaries' phones to play a melody upon receiving a BLF message (Yealink: features.pickup.blf_audio_enable=1), set the melody, and specify restrictions on BLF audio notification for a specific list of numbers (Yealink: features.pickup.blf_audio.list=101,102,103 or any).

With the above settings, the subscriber’s phone displays incoming calls of the monitored subscriber, providing the ability to pick up the selected one.
Pickup is performed by sending an INVITE with a Replaces header (rather than by calling a subscriber feature code, since in this mode it is impossible to specify a specific call to pick up).

There is an alternative configuration with pickup via a subscriber feature code:
* create a subscriber feature code of type "pickup by number" and configure its availability in routing rules;
* configure pickup function support on the chief’s and secretaries' phones - set the corresponding feature code number (Yealink: account.x.direct_pickup_code);
* when configuring BLF subscriptions on the chief’s and secretaries' phones, specify the pickup number for each (the same subscriber feature code).

For the feature code pickup mode to work, the phone option must be disabled (Yealink: account.X.dialoginfo_callpickup=0).
When using a 'pickup' feature code, it is impossible to specify a specific call to pick up if several calls arrive at the monitored device.
Therefore, to improve performance, it is advisable not to use BLF notification details, disabling the 'blf_details_enabled' option in domain settings.

Table 6. Parameters
Field: mode
Mode: in
Type: str
Default: cascade
Operation algorithm. Possible variants:

* parallel - when the chief’s number is called from any number not mentioned in the group, the call is redirected to both assistants in parallel.
* cascade - when the chief’s number is called from any number not mentioned in the group, the call is redirected sequentially to the first assistant, then to the second.
* direct - when the chief’s number is called from any number, the call proceeds without redirection.

Field: chief_number
Mode: in
Type: str
Default: empty

Chief’s number.

Field: assistant1_number
Mode: in
Type: str
Default: empty

First assistant’s number.

Field: assistant2_number
Mode: in
Type: str
Default: empty

Second assistant’s number.

Field: direct_numbers
Mode: in
Type: array<str>
Default: []

List of numbers that go directly to the chief. Applied to the result of from/referred-by transformation by routing rules.

Field: chief_mobile
Mode: in
Type: str
Default: empty

Chief’s mobile number. The number is used to automatically publish the state of the subscriber participating in the dialog.
Thus secretaries can make a BLF subscription to the external number and receive notifications about dialog completion.
Permission to subscribe to the chief’s mobile number is granted to secretaries automatically.

Example case: a secretary connects the chief on a mobile number sequentially with several subscribers.

Extends the list of external numbers whose states are tracked, which is specified in domain settings.

Example
{
  "mode": "cascade",
  "chief_number": "101",
  "assistant1_number": "102",
  "assistant2_number": "103",
  "direct_numbers": ["115", "123"]
}

Custom group (custom)

Used to implement project logic.

Table 7. Parameters
Field: filter_from
Mode: in
Type: str
Default: *
Source number filter mask.
The result of modification by routing rules applied at previous steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

Field: filter_by
Mode: in
Type: str
Default: *

Filter mask for the number of the subscriber who forwarded the call.
Filter operation modes.

Field: numbers_to
Mode: in
Type: array<str>
Default: []

List of numbers on whose call the group is activated.

Field: type
Mode: in
Type: str
Default: empty

Project group type. Determines the set of other detail parameters.

Additionally

Filter operation modes

Mode Description

Per-character

The value being checked is passed through the filter character by character.
The following special characters and combinations can be used:

  • X – any character;

  • * – all remaining characters;

  • ? - any character (when used for domain name filtering, any character except the dot, the domain name separator).

  • $ - for domain filtering. Any sequence of characters except the dot, the domain name separator.

If one of the service characters must be specified as a target, it should be enclosed in square brackets, e.g. [X].

For example, XXX – any three-character value.

Table

The substring {tab:…​} can be used. It allows selecting a group of characters in the checked value and matching them against the table embedded in the rule (details.tab).
For example, {tab:a} selects a substring and matches it against the a field of all objects/rows in the table.
The table links several filter and modifier fields. Based on sequential filter checks, fewer rows remain in the table, taking detected matches into account.
The first remaining row is used in modifiers. If no rows remain in the table, the rule is rejected.
Character capture from the checked value based on the mask can occur automatically or with strict specification of the substring length:

  • {tab:KEY} - Automatic capture from the checked value.

  • {tab:KEY:LENGTH} - Capture the specified number of characters from the checked value.

The following can be used as table field values:

  • constants;

  • regular expressions (to do this, set the value in the format /reg/EXPRESSION, e.g. /reg/^1[1-4]$);

  • mappings to other table fields (to do this, set the value in the format /tab/FIELD, e.g. /tab/a). The mode is used to link values of different fields. The linking order must be strictly observed: if the referenced table field has not yet been checked and filled with the real value of another entity field, the match will not succeed. Entity field check order: filter_from, filter_by.

  • any value applied without a regular expression (to do this, set /any). The mode is useful exclusively for direct mappings to values of other fields without additional filters.

Using the table modifier is allowed in combination with other control commands of per-character mode.
Repeated specification of fields in one modifier, repetition, and specification of nonexistent fields are allowed.

For example, {tab:a:3}XXXXX{tab:b} allows selecting the 3-character city code in the number and matching it with field a in the table, and simultaneously selecting the tail starting from the 9th character and matching it with table field b.

Regex

The Pattern template is applied to the source value.

Structure of the regex template value:
/reg/Pattern1.

For example,- value: "302"
- mask: "/reg/0"
- result: true.

  • value: "302"

  • mask: "/reg/^0$"

  • result: false.

  • value: "302"

  • mask: "/reg/^302$"

  • result: true.

  • value: "302"

  • mask: "/reg/^(301|302|305)$"

  • result: true.

All standard regular expression rules can be used when forming Pattern templates.

Range

The value being checked is an integer and falls within the specified range of numeric values.

Structure of the dia template value:
/dia/FromValue+N - matches N+1 values from FromValue to FromValue+N.

For example,- value: "302"
- mask: "/dia/300+10"
- result: true.

See also

Logical roles

  • b2b performs routing and applies group logic.

  • mdc and sdc search for the group number.