Waiting list (hunt)

Description

Waiting queue descriptor. Queue resources are assigned as SIP users.

Served by the role huntq, which builds waiting queues based on descriptors, monitors the states of resources, and connects waiting objects to resources based on configured strategies.
Calls can be placed in the queue. The placement of calls in the queue is managed by the IVR role via a CAF (featurecode) with type 'hunt' and 'queue'.

For the organization of personal and group queues, you may not create entities separately, they are dynamically recreated by default with default settings for queue organization at the moment when a call arrives at the CAF of type 'queue'. If it is necessary to set specific properties for such a queue, it is enough to create an entity with the required parameters and specify in the 'phonenumber' field of the entity the number of the corresponding user or group.

The object can be a template based on which queue descriptors are dynamically built when a call to the subscriber function code is received "queue".
Thus, with one instance of the hunt entity, you can configure a single format of different queues for several (or all) objects - users or groups. An entity is treated as a template if the value of the 'opts.template_type' field is specified as 'personal' or 'group'.
When a call arrives on the queue, the postfix of the dialed number (extension) is treated as a number by which a specific hunt entity is first searched, then a pattern is searched, then a dynamic descriptor with standard default values is built.
Whether a particular template will be applied to dynamically build a descriptor based on it depends on the specified type ('opts.template_type') and the number mask ('opts.filter_number'). Specifically, whether the mask specified in the 'opts.filter_number' (and optionally 'opts.tab') field satisfies the dialed number extension. If satisfied, the sipuser or sipgroup account with the investigated number is detected, depending on which template type is specified in the field 'opts.template_type'.

Limitations

  • The collection is not available 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
  }
}

Description of the specification’s characteristics

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.
Applies and mandatory field at type = sipuser.

Is a key when searching for an entity when a call is received on a CAF (featurecode) of type 'hunt'.
When using an entity as an explicitly specified personal or group queue descriptor (CAF of type 'queue'), the number must match the number of the corresponding sipuser account or sipgroup.

The field is not used when forming the template and is filled in automatically.

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

Queue priority.
Used when a resource (participant) is released to select the next object (subscriber) for service in case the number participates in several queues (spq).
The object (subscriber) is selected from the queue in which the priority is lower.

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

Queue Type

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

List of resources (members) in the queue with their priority. Composition of fields of the list element.

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

The strategy for adding participants for an object (subscriber). Field composition.

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

Strategy for selecting a resource (participant) from among the free resources when a new object arrives in an empty queue

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

Queue object selection strategy when the resource is released

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

Queue weight.
Used when the resource is released to select the next object (subscriber) to be serviced in case the number participates in several queues with the same priority (wfq).

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

Call Queue Greeting IVR Script Code.
Used in type = sipuser.

Field: qivrscript
Mode: in
Type: str
Default: "qivrscript"`", "IVR Call Queue Waiting Script Code.
Used in type = `sipuser.

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

IVR script code preplayed to the member of the call queue after their answer before connecting to the caller.
Used in type = sipuser.

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

Number of resources to be issued simultaneously.
0 – no special restriction is set, the behavior directly corresponds to the value of the strategy.
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 either case, the queue will not issue more than the specified number of initiatives per resource call, regardless of how the strategy is configured.
After reaching and failing on the last of the called resources, a drop from the queue will occur.
In the case of type = sipuser additionally a switch to the number can be performed maxattemptstrannumber.

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

Number to switch when attempts are exceeded maxattempts.
Used in type = sipuser.

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

Duration of dialing attempt in seconds.
0 – no special restriction has been imposed.
Applies only when type = sipuser, and only works to reduce the timeout relative to the timeout set in the SIP-user settings.

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

Maximum waiting time in queue in seconds

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

Number to switch when the maximum waiting time is exceeded.
After a timeout, a debounce from the queue occurs.
Used in type = sipuser.

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

DislpayName substituted into the call from the queue to the resource.
Used in type = sipuser.

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

Mode of applying a temporary ban on the use of the SIP user type resource after the call service is completed.
Optional fields in the structure:
- expires – time to set the state,
- reason – reason for setting the condition.

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

Used in type = sipuser.

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

The time in seconds for which the resource (member) becomes locked due to a connection failure.
The minimum permissible value is 10, the maximum value is – 86400.

Field: opts
Mode: in
Type: object
Composite field

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

Arbitrary header

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

Arbitrary comment

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

An indication that the wait is terminated when no resources are available

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

Switch off early-media mode while waiting in queue.
When this mode is enabled, a "183 Session Progress" reply is sent to the HUNT number when calling, and a SIP reply "200 OK" is sent only at the moment of connection with the called subscriber.
The exception is when the "200 OK" SIP response is sent in a hello or queue wait scenario, which can be configured by the administrator and assigned for use in a HUNT number.

For calls from outside the network, providers can limit the dwell time in the Early Media state to, for example, 20 seconds, after which it drops the session.
If the connected communications provider is known to be limiting, you should:

  • or keep the flag off for all cases;

  • or use an administrator-configured greeting or waiting in queue script, within which branching and timing are performed. This is necessary to ensure that all external calls received through the provider receive a SIP response of "200 OK" within the specified period and are not rejected by the provider.

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

Template Mode. Not used by default. Value options:

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

  • personal - is used as a template of the personal queue. The template is applied to numbers that match the mask specified in the 'opts.filter_number' field and at the same time belong to accounts sipuser.

  • group - is used as a template of the group queue. The template is applied to numbers that match the mask specified in the 'opts.filter_number' field and simultaneously belong to accounts sipgroup.

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

Filter mask of the number to which the forwarding rule belongs.
This can be a directly specified SIP user account number, in which case the rule is individualized.
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 a single entity search session.
Each object in the list contains arbitrary fields that can be used in the mask as a string {tab:some_field}.
For more details see Filter operation modes, item 'Table'.

Field: ext
Mode: inout
Type: object
Compound field

Allows you to extend 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

Types of queues

Table 2. Types of queues
Value Description

"user"

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

"sipuser"

All resources are identifiers of the object sipuser.
Used when routing to a CAF (featurecode) with a type = hunt

Composition of the fields of the resource list item

Table 3. Composition of the fields of the resource list item
Field Value Type Description

id

uuid

The resource (participant) identifier is sipuser or user

priority

int

Priority of the resource (participant) at the time of application resmode

Composition of strategy fields

Table 4. Composition of strategy fields
Field Value Type Description

mode

uuid

Strategy Title:

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

  • timers – one object can receive multiple resources at the same time.

seconds

array<int>

A list of time shifts of the start of the next resource (participant) call, starting from the second resource.
Applies only to mode = timers

Resource (participant) selection strategies

Table 5. Resource (participant) selection strategies
Value Description

"priorityrandom"

Selects the most prioritized resource from the free resources, and if there are several of them, selects among them randomly

"random"

Selects a random resource from the currently available resources

"cascade"

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

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 identical by weight

Filter operation modes

Table 7. Filter operation modes
Mode Description

Posymbolic

The value to be subjected to the conformance check is passed through the filter character by character.
The following special characters may be used:

  • X – any character;

  • * – all remaining characters;

  • ? - any character (if used for filtering by domain names, any character except dot - domain name separator).

  • $ – any number of characters to the nearest point.

If it is necessary to specify one of the service characters as a target character, it should be enclosed in square brackets, e.g. [X].

For example, XXX is any three-character value.

Table

The {tab:…​} substring can be used. It can be used to select a group of characters in the tested value and match them with the table embedded in the rule (opts.tab).
For example, {tab:a} - select a substring and map it to the a field of all objects/rows in the table.
The table serves as a bundle of several filter fields and modifiers. Based on the sequential check of filters, there are fewer rows in the table, taking into account the detected matches.
The first of the remaining rows is used for application in modifiers. If there are no rows left in the table, the rule is rejected.
Capturing characters from the mask-based value being checked can be done automatically, or with strict specification of the substring length:

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

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

Field values in the table can be used as field values:

  • constants;

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

  • mapping with other fields of the table (for this purpose it is necessary to specify the value in /tab/FIELD format, for example /tab/a). The mode is used to bind values of different fields. For example, to allow calls only to your own voice mailbox. The binding order must be strictly observed: if the referenced table field has not been checked yet and has not been filled with the real value of another entity field, the matching will fail. The order of checking entity fields: filter_number, filter_fromnumber.

  • any value applied without a regular expression (for this purpose /any must be set). The mode is useful only when organizing direct comparisons with values of other fields without additional filters.

The tabular modifier may be used in combination with other character mode control commands.
Multiple specification of fields in one modifier, repetition, specification of non-existent fields are allowed.

For example, {tab:a:3}XXXXX{tab:b} - allows you to highlight the 3-character city code in the number and map it to the a field in the table, and simultaneously highlight the tail starting at the 9th character and map it to the b field in the table.

Regex

The pattern is applied to the original value Pattern.

The structure of a regex pattern value:
/reg/Pattern1.

For example,- significance: "302"
- mask: "/reg/0"
- Result: true.

  • significance: "302"

  • mask: "/reg/^0$"

  • Result: false.

  • significance: "302"

  • mask: "/reg/^302$"

  • Result: true.

  • significance: "302"

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

  • Result: true.

All standard regular expression rules can be applied when forming Pattern patterns.

Range

The value subject to compliance checking is a numeric integer and is within the specified numeric range.

The structure of the dia-template value:
/dia/FromValue+N - fall under the pattern of N+1 values from FromValue to FromValue+N.

For example,- significance: "302"
- mask: "/dia/300+10"
- Result: true.

See also

API

Logical roles

  • huntq performs queue processing.

  • ivr performs placement in the queue, playing a melody to the subscriber while waiting in the queue, calling the SIP user account that is a queue resource, and connection.

  • Personalization
  • Increase font size
  • Decrease font size