SIP user (sipuser)

Description

Internal telephony subscriber account. Used for registration, authentication, routing, determining call parameters, and organizing queues. Each SIP user account has an internal number in the domain; dialing it calls all devices registered under this account.

Allows registering several devices under one account. In this case, dialing the account number calls all devices registered under it at once. The number of devices that can be registered simultaneously is determined by the 'lic.devices' parameter. When a new registration arrives after the entire volume of licensed connections is exhausted, the availability of registered devices is checked by sending an OPTIONS request. If an unresponsive device is found, the registration is made in its place. Devices can register under an account using the same or different credentials (login and password).

The primary login for authentication matches the account’s logical username (the 'login' field), and the primary password (the 'pwd' field) applies to them. If necessary, additional authentication data can be specified in the 'credentials' field.

Limitations

  • The collection is unavailable in the master domain.

  • If the license field is changed in the DB, after the domain reload the object will not be loaded; a hash check applies.

  • Licensed by a quantitative parameter: a license is consumed for the number of devices simultaneously registered under the account.

Fields

Entity structure
{
  "id": uuid,
  "name": str,
  "login": str,
  "pwd": str,
  "credentials": array<object>,
  "phonenumber": str,
  "reg": intbool,
  "devices": array<object>,
  "iduser": uuid,
  "timezone": float | "default",
  "lic": object,
  "opts": {
    "title": str,
    "comment": str,
    "ap_device_model": str,
    "ap_mac_address": str,
    "calltimesec": int,
    "modextout": str,
    "modextin": str,
    "trunks": int,
    "minexpires": int,
    "maxexpires": int,
    "dlgtimesec": int
  },
  "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: login
Mode: in
Type: str
Default: required

Logical name (username) and primary login for authorization.
Substituted into the username URI of the To and From headers in SIP requests.
Can be used for Digest authorization together with the password in the 'pwd' field.
May contain the characters A-Za-z0-9_-.~!. Length must not exceed 100 characters.

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

Password for the primary login.
Used for Digest authorization together with the primary login from the 'login' field.
May contain any characters.
Secret: when read, the plaintext value is available only to a user with the admin or crud role (otherwise the field is not returned); via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

Field: credentials
Mode: in
Type: array<object>
Default: '[]'

Additional authentication data.
Can be used to:

  • separate the logical name (username) from the login used for authorization,

  • separate authorization data for different devices registering under one account.

Used exclusively for Digest authorization.
Specified as a list of objects:

[
  {
    "login": ...
    "pwd": ...
  },  ...
]

The same requirements as for the primary entity’s 'login' and 'pwd' fields apply to the values.

To use specific authorization data when configuring a device, both the primary logical name must be entered in the corresponding field and the specific login and password in the authorization data fields.

Secret (element pwd): when read, the plaintext value; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

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

Display name. Substituted into the username URI of the From header in SIP requests.
May contain the characters A-Za-z0-9_-.~!. Length must not exceed 1000 characters.

A DisplayName modifier may be specified,
more.

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

Subscriber phone number within the domain.
May contain the characters 0-9, *, and #, no more than 100.

If the phone number is empty, the account cannot be called in any way.
At the same time, an outgoing call from a device is possible if routing rule filters do not block the possibility of a call by a subscriber with an empty number.

Accounts with empty numbers can be used for Hot-Desk.
When logging out using the built-in Hot-Desk service, the account is also assigned an empty number.

Field: reg
Mode: in
Type: intbool
Default: 1

Registration mode:
true – with registration,
false – without registration; additionally, a list of devices must be specified in the devices field.

Field: devices
Mode: in
Type: array<object>
Default: '[]'

List of devices connected without registration and their connection points, more.
Required only when reg = false; in this case the value must contain at least one device.

Field: iduser
Mode: in
Type: uuid
Default: empty

Identifier of the system user. One user can have several sipuser accounts.

Linking the user to the device account can be done both statically and within the Hot-Desk subscriber feature.

Field: timezone
Mode: in
Type: float | "default"
Default: "default"

User time zone.
From -12 to 12, for example 3.5, or "default" to use the server time zone.
Used when building forwarding, call routing, etc.

Field: lic
Mode: in
Type: object
Default: empty

Set of licenses transferred from the domain. The parameters are expected to include the number of allowed devices for registration, for example {"devices":5}.

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.ap_devices
Mode: in
Type: array(obj)
Default: []

Devices to connect for autoprovision.
A list alternative to the fields
* opts.ap_mac_address
* opts.ap_device_model
* ext.ap_blf
* ext.ap_override

Object fields in the list:
* mac - string with the MAC address (12*HEX).
* device_model - string with the device model (e.g. "Yealink SIP-T21 E2").
* blf - list of objects, each defining one subscription element. Fields correspond to the "*.blf" model template.
* override - list of "key = value" strings that must replace or supplement the template (text or xml).

Each element represents a separate device with a unique MAC address and additional settings for the autoprovision service.

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

Device MAC address for autoprovision.
When a TFTP or PNP request arrives, the device model is determined, a template is found (masterdomain.settings.ap_options.masks), filled with values from the account based on the paths specified in the template, and returned to the device for auto-configuration.
The combination of fields opts.ap_mac_address, opts.ap_device_model, ext.ap_blf, ext.ap_override is used to configure one specific device having the MAC address specified here. An alternative is to specify the list field opts.ap_devices.

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

Device model for determining the autoprovision template.
Applied when a TFTP request arrives.
The combination of fields opts.ap_mac_address, opts.ap_device_model, ext.ap_blf, ext.ap_override is used to configure one specific device having the MAC address specified here. An alternative is to specify the list field opts.ap_devices.

If the template directory contains the file "Yealink SIP-T20.cfg", then "Yealink SIP-T20" must be specified in the field to use it directly.
The template search will then be: "Yealink SIP-T20.cfg", "yealink sip-t20.cfg", "Yealink.cfg", "yealink.cfg".

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

CoS (class of service) group code.

Used to configure group access restriction policies.
Determines the restriction policy when this subscriber makes a call as the initiator.

More in the article CoS/CoR group access restriction.

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

CoR (class of restrictions) group code.

Used to configure group access restriction policies.
Determines the restriction policy for an incoming call to this subscriber as the receiver.

More in the article CoS/CoR group access restriction.

Field: opts.calltimesec
Mode: in
Type: int
Default: 30

Account call duration in seconds when a call arrives to it

Field: opts.dlgtimesec
Mode: in
Type: int
Default: 0

Maximum conversation duration in seconds. 0 – no individual limit set

Field: opts.internal_representative
Mode: in
Type: bool | str
Default: false

Sets the representation mode for internal calls within the domain (user → user).
In such calls, representation rules are not applied by default, and the call is always represented by the initiator user’s number.
To represent the user in such internal calls in some cases, for example by a group number, this field can specify:

  • true — a suitable representation rule will be searched in the current domain (by the calling and called user numbers), and the result of its application will be substituted as the username in the From header.

  • any string — forcibly applied as the username in the From header.

  • any number — converted to a string and forcibly applied as the username in the From header.

  • empty string — the call is sent without a username in the From header.

Field: opts.trunks
Mode: in
Type: int
Default: -1

Maximum number of simultaneous calls. Affects the ability to make a call to this account when there are other active calls.

  • -1 – no limit,

  • 0 – incoming calls prohibited,

  • 1 – incoming allowed only if the account is not busy in another conversation,

  • 2, 3, etc. – incoming allowed only if the number of active conversations involving the account is less than the specified value.

Field: opts.minexpires
Mode: in
Type: int
Default: 30

Minimum allowed registration time

Field: opts.maxexpires
Mode: in
Type: int
Default: 3600

Maximum allowed registration time

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

Extension calculator modifier before accepting a call for processing.
Applied when accepting a call from the account.
Calculates the call initiator’s extension for further routing and representation.
The username from the Contact:, From: header of the SIP request, or from the phonenumber field of the account under which the incoming call is authorized, is passed to the modification.
More.

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

Extension modifier for an outgoing call.
Applied when sending a call to the account during application of a routing rule with type "insidepbx". The connected device is treated as a PBX with many subscribers behind it.
The value passed to the modification is the remainder of the number dialed by the initiator after removing from its beginning the number of the called SIP user account, which in turn is found based on the longest occurrence of its number in the number dialed by the initiator.
More.

Field: opts.parallel
Mode: in
Type: array<str | object>
Default: empty

List of parallel call numbers.
Any call to the account number causes simultaneous calling of the specified parallel numbers.
Any means direct, group, transferred, forwarded, or from a script.
If the account number is used as a parallel one in a functional group, the application of its parallel numbers depends on the cascade property of the functional group.

Each number can be specified as an object with number and optional calltimesec fields, or as a string with the number.
If the call timeout for a parallel number is not set, the timeout of the primary account of the called subscriber is applied to it.

Applied when sending a call to the account, provided absolute forwarding did not trigger.
If the device is not registered, along with the parallel numbers, the number set as forwarding due to lack of registration will also be called.

The following number types can be specified as parallel:
* external,* internal user numbers,* internal group numbers,* internal numbers behind a PBX,* service numbers such as ivr (IVR scripts), voicemail_send (voicemail placement), hunt (hunt groups).
Other number types are filtered out.
A parallel call to an IVR script excludes the record_ivr option from the role configuration settings.
If another service function must be called in parallel, use forwarding (because all other service functions answer instantly, making it equivalent).

Cascade mode when expanding parallel numbers is disabled.

When calling parallel numbers, information about the primary account is set in CDR and Remote-Party. The primary account number is also used when calculating recording and transcription rules.

Field: opts.redirect_allowed_masks
Mode: in
Type: array<str>
Default: ["/default"]

List of number masks allowed to be set in the device as the forwarding number.
If a 3xx forwarding to a disallowed number is configured in the device, it is not processed by the server. The information is written to the log.
There is a special mask "/default"; specifying it applies the masks configured in the domain properties (the 'redirect_allowed_masks' parameter of the same name).

The following can be used as a mask:

  • constants. For example, "414".

  • the predefined mask "*" - any number, processed efficiently.

  • special characters. For example "12XX", "8843*".

  • ranges. For example "/dia/1240+10".

  • regular expressions. For example "/reg/^(7|8)[0-8].*$".

Evaluating a large number of regular expressions reduces overall system performance.

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

Switch allowing simultaneous registrations from several directions.

By default it is disabled, meaning that when a new registration from the same device is detected (mainly TCP, contact option +sip.instance), the previous registration is automatically removed.
This helps cut off dead registrations and avoid initiating parallel calls to them. Relevant for phones that do not support SIMULTANEOUS REGISTRATIONS or are not configured for this mode.

When configuring a client device for SIMULTANEOUS REGISTRATIONS mode, this option should be enabled; then registrations will exist simultaneously.

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

Field: ext.ap_blf
Mode: in
Type: array(object)
Default: generated

Parameters for substitution into the BLF section of the autoprovision configuration.
The combination of fields opts.ap_mac_address, opts.ap_device_model, ext.ap_blf, ext.ap_override is used to configure one specific device having the MAC address specified here. An alternative is to specify the list field opts.ap_devices.

Example:

[
  {
    "key": 1,
    "label": "asdf",
    "pickup": "**",
    "value": "Test"
  },
  {
    "key": 2,
    "label": "qwer",
    "module": 2,
    "value": "Abc"
  }
]

Field: ext.ap_override
Mode: in
Type: str
Default: generated

String with override data.
The combination of fields opts.ap_mac_address, opts.ap_device_model, ext.ap_blf, ext.ap_override is used to configure one specific device having the MAC address specified here. An alternative is to specify the list field opts.ap_devices.

A line separator is supported. Each line is a key and an overridden value:

"aaa.def = 3\naaa.asd = 4\naaa.qwe = 5\nbbb.zxc = 6"

DisplayName modifier modes

Table 2. DisplayName modifier modes
Mode Description

Per-character

The source value passes through the specified modifier character by character with accumulation.
The following special characters and combinations are allowed:

  • {D} – substitute the source DisplayName from the incoming request.

  • {d} – the same in lowercase.

  • {U} – substitute the source UserName from the incoming request.

  • {u} – the same in lowercase.

  • {N} and {n} – substitute the generated full initiator number (concatenated sipuser and extension numbers).

  • {A} – substitute displayname from the address book contact account found by the full initiator number with extension. If the contact is not found, an empty value is substituted. Implemented under task #366.

  • {a} – the same in lowercase.

  • {E} – substitute an empty value.

  • any other character is captured into the result at its corresponding position.

For example,- value: "123456"
- From username: "SIP011"
- AddressBook contact displayname: "Vasily Ivanov"
- modifier: "a - {u} - {A}"
- result: "a - sip011 - Vasily Ivanov".

Regex

The Pattern template with Opts options is applied to the source value, and the found block(s) are replaced with the Replace template.
The result can again be passed to the next Regex modification operation, and so on a finite number of times.

General structure of the regex modifier value:
/reg/Pattern1/Replace1/Opts1 /reg/Pattern2/Replace2/Opts2 …​.

Options can be omitted or contain any combination of the characters:

  • i – case-insensitive

  • g – global.

For example,- value: "qwerty,qwerty"
- modifier: "/reg/t/E/g /reg/qwer/a/"
- result: "aEy,qwerEy".

When forming the Pattern and Replace templates, all standard regular expression rules can be used, including capture groups, backreferences, named group substitution, etc.

Extension modifier modes

Table 3. Extension modifier modes
Mode Description

Per-character

The source value passes through the specified modifier character by character with accumulation.
The following special characters and combinations are allowed:

  • ? – capture the current character;

  • * – capture all remaining characters;

  • X – capture the current character;

  • / combined with ? or X – exclude the current character from the result, e.g. /XXX/ excludes 3 current characters;

  • [ combined with ] – include the service character located between the brackets in the result, e.g. [X];

  • {U} – substitute the source UserName from the incoming request.

  • {u} – the same in lowercase.

  • {N} and {n} – substitute the generated full initiator number (concatenated sipuser and extension numbers).

  • {F} and {f} – include the username from the From: header of the SIP INVITE request in the result;

  • {C} and {c} – include the username from the Contact: header of the SIP INVITE request in the result;

  • {E} and {e} – include an empty value in the result;

  • any other character is captured into the result at its corresponding position.

For example,- value: "123456"
- modifier: "00/XXX/XXX"
- result: "00456".

Regex

Identical to the DisplayName "Regex" modifier mode described above

See also

Logical roles

  • b2b performs routing and applies the account to organize forks to its associated devices.