Hunt group (hunt)

Description

Hunt group descriptor with a waiting queue. SIP users are assigned as queue resources.

Serviced by the huntq role, which builds waiting queues from descriptors, monitors resource states, and connects waiting objects with resources based on configured strategies.
Calls can be placed in the queue. Call placement in queues is managed by the IVR role through feature codes (featurecode) of type 'hunt' and 'queue'.

To organize personal and group queues, entities need not be created separately; they are dynamically recreated with default settings when a call arrives at a 'queue' feature code. If specific properties are needed for such a queue, it is enough to create an entity with the required parameters and specify the corresponding user’s or group’s number (or number filter mask) in the hunt entity’s 'opts.filter_number' field.

The object can be a template from which queue descriptors are dynamically built when a call arrives at the "queue" subscriber feature code.
Thus, one hunt entity instance can configure a unified format of different queues for several (or all) objects - users or groups. The entity is treated as a template if the 'opts.template_type' field is set to 'personal' or 'group'.
When a call arrives at the queue, the dialed number’s postfix (extension) is treated as the number for which a specific hunt entity is first searched, then a template, then a dynamic descriptor with standard default values is built.
Whether a specific template is applied for dynamic descriptor construction depends on the specified type ('opts.template_type') and number mask ('opts.filter_number'). Specifically, whether the mask specified in 'opts.filter_number' (and optionally 'opts.tab') matches the extension of the dialed number. If it matches, a sipuser or sipgroup account with the examined number is discovered, depending on the template type specified in 'opts.template_type'.

Limitations

  • The collection is unavailable in the master domain.

  • Licensed by a quantitative parameter: a license is consumed for the number of resources of the selected type.

Fields

Entity structure
{
  "id": uuid,
  "code": str,
  "phonenumber": str,
  "priority": int,
  "type": str,
  "resourses": array<object>,
  "strategy": object,
  "resmode": str,
  "objmode": str,
  "weight": int,
  "wivrscript": str,
  "qivrscript": str,
  "preivrscript": str,
  "reslimit": int,
  "maxattempts": int,
  "maxattemptstrannumber": str,
  "resdialtimeout": int,
  "timeout": int,
  "timeouttrannumber": str,
  "displayname": str,
  "huntblock": object,
  "resbansec": int,
  "opts": {
    "title": str,
    "comment": str,
    "exit_no_resource": bool
  },
  "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: code
Mode: in
Type: str
Default: required

Code. Used to associate with other entities. Unique value.

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

Phone number.
Used and required when type = sipuser.

It is the key when searching for the entity when a call arrives at a feature code of type 'hunt'.
When the entity is used as an explicitly specified personal or group queue descriptor ('queue' feature code), the number must match the corresponding sipuser or sipgroup account number.

When forming a template, the field is not used and is filled automatically.

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

Queue priority.
Used when releasing a resource (participant) to select the next object (subscriber) for servicing if the number participates in several queues (spq).
The object (subscriber) is selected from the queue with the lower priority value.

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

Field: resources
Mode: in
Type: array<object>
Default: required

List of queue resources (participants) with their priorities. Composition of list element fields.

Field: strategy
Mode: in
Type: object
Default: {"mode": "simple"}

Strategy for adding participants for the object (subscriber). Field composition.

Field: resmode
Mode: in
Type: str
Default: "random"

Resource (participant) selection strategy from free resources when a new object arrives in an empty queue

Field: objmode
Mode: in
Type: str
Default: "spq"

Queue object selection strategy when a resource is released

Field: weight
Mode: in
Type: int
Default: 1

Queue weight.
Used when releasing a resource to select the next object (subscriber) for servicing if the number participates in several queues with equal priority (wfq).

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

IVR greeting script code in the call queue.
Used when type = sipuser.

Field: qivrscript
Mode: in
Type: str
Default: "qivrscript"

IVR waiting script code in the call queue.
Used when type = sipuser.

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

IVR pre-playback script code for a call queue participant after their answer before connecting to the subscriber.
Used when type = sipuser.

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

Number of simultaneously issued resources.
0 – no special limit; behavior directly matches the strategy value.
Any positive value sets strategy to timers with the specified number of zeros.

Field: maxattempts
Mode: in
Type: int
Default: 1

Maximum allowed number of resource (participant) calls.
In any case, the queue will not issue more than the specified number of resource call initiations, regardless of how the strategy is configured.
After reaching the limit and a failure on the last called resource, the queue hangs up.
For type = sipuser, a switch to the maxattemptstrannumber number can additionally be performed.

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

Number to switch to when maxattempts is exceeded.
Used when type = sipuser.

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

Dial attempt duration in seconds.
0 – no special limit.
Applied only when type = sipuser, and only reduces the timeout relative to the one set in the SIP user settings.

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

Maximum queue waiting time in seconds

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

Number to switch to when the maximum waiting time is exceeded.
After the timeout, the queue hangs up.
Used when type = sipuser.

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

DisplayName substituted into the call from the queue to the resource.
Used when type = sipuser.

Field: huntblock
Mode: in
Type: object
Default: {"enabled": false}

Mode for applying a temporary ban on using a SIP user resource after call servicing ends.
Optional fields in the structure:
- expires – state setting time,
- reason – reason for setting the state.

Example:
{
  "enabled": false,
  "expires": 20,
  "reason": "Post-call"
}

Used when type = sipuser.

Field: resbansec
Mode: in
Type: int
Default: 20

Time in seconds for which the resource (participant) becomes blocked due to a connection failure.
Minimum allowed value is 10, maximum is 86400.

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

Field: opts.exit_no_resource
Mode: in
Type: bool
Default: true

Flag for stopping waiting when no resources are available

Field: opts.use_early_media
Mode: in
Type: bool
Default: false

Switch for early-media mode while waiting in the queue.
When enabled, a call to a HUNT number receives a "183 Session Progress" response, and the "200 OK" SIP response is sent only when connecting to the called subscriber.
The exception is when the "200 OK" SIP response is sent by the greeting or queue waiting script, which the administrator can configure and assign for use in the HUNT number.

For calls from an external network, providers may limit the time spent in Early Media state, for example 20 seconds, after which they terminate the session.
If the connected provider is known to limit it, you should:

  • either keep the flag disabled in all cases;

  • or use a greeting or queue waiting script configured by the administrator, with branching and timing inside it. This is necessary so that all external calls arriving through the provider receive the "200 OK" SIP response within the established period and are not dropped by the provider.

Field: opts.template_type
Mode: in
Type: str
Default: "none"

Template mode. Not used by default. Value variants:

  • none - not used as a template. Used directly as a static descriptor.

  • personal - used as a personal queue template. The template applies to numbers matching the mask specified in 'opts.filter_number' and simultaneously belonging to sipuser accounts.

  • group - used as a group queue template. The template applies to numbers matching the mask specified in 'opts.filter_number' and simultaneously belonging to sipgroup accounts.

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

Number filter mask for the number the redirect rule belongs to.
This can be a directly specified SIP user account number, in which case the rule applies individually.
But a search filter mask can also be specified.
Filter operation modes.

Field: opts.tab
Mode: in
Type: array<object>
Default: []

Tabular data for using filters within one entity search session.
Each object in the list contains arbitrary fields that can be used in the mask as the string {tab:some_field}.
More in Filter operation modes, item 'Table'.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending the compound 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

Queue types

Table 2. Queue types
Value Description

"user"

All resources are identifiers of the user object.
Used in the chat center.

"sipuser"

All resources are identifiers of the sipuser object.
Used when routing to a feature code with type = hunt

Composition of resource list element fields

Table 3. Composition of resource list element fields
Field Value type Description

id

uuid

Resource (participant) identifier – sipuser or user

priority

int

Resource (participant) priority at the time resmode is applied

Composition of strategy fields

Table 4. Composition of strategy fields
Field Value type Description

mode

uuid

Strategy name:

  • simple – one object receives only one resource at a time,

  • timers – one object can receive several resources at a time.

seconds

array<int>

List of time offsets for starting the next resource (participant) call, starting from the second.
Applied only for mode = timers

Resource (participant) selection strategies

Table 5. Resource (participant) selection strategies
Value Description

"priorityrandom"

Selects the highest-priority resource from the free ones, and if there are several, selects among them randomly

"random"

Selects a random resource from those currently free

"cascade"

Selects free resources exactly in the order they are listed in the resources field

Object (subscriber) selection strategies

Table 6. Object (subscriber) selection strategies
Value Description

"spq"

(Strict Priority Queueing) – queue selection mode based on priority

"wfq"

(Weighted Fair Queueing) – queue selection mode based on weight

"spqwfq"

queue selection mode based on priority, and among equal priority based on weight

Filter operation modes

Table 7. Filter operation modes
Mode Description

Per-character

The value being checked is passed through the filter character by character.
The following special characters 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).

  • $ – any number of characters up to the nearest dot.

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 (opts.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. For example, to allow calls only to one’s own voicemail box. 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_number, filter_fromnumber.

  • 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

  • huntq processes queues.

  • ivr places calls in the queue, plays waiting music to the subscriber, calls the SIP user account that is a queue resource, and connects.