SIP-telephony provider (provider)

Description

The SIP telephony provider account through which the "Incoplax" system connects to external SIP networks.
This can be an external telephone network connected through providers, or corporate PBXs, above or at the same hierarchical level in the number plan as the system «Incoplax».
ESG role registers and maintains a communication channel with the external equipment specified in the provider account. Any call that results in a call to the outside is always through her. Any call coming from the outside into the system can only be answered, authorized, and serviced by the ESG role that is defined in the provider account.

The determination of which account an externally received call corresponds to is determined by a set of conditions:
- account with registration in the "To:" or "Contact:" header of the SIP request INVITE contains "username@domain", where "username" corresponds to the value of the "username" field of the account, and "domain" corresponds to one of the addresses of the account;
- unregistered account in the "Contact:" header of the SIP request INVITE contains "username@domain", where "username" corresponds to the value of the "username" field of the account, and "domain" corresponds to one of the addresses of the account;
- unregistered account in the "Contact:" header of the SIP request INVITE contains "username@domain", where "domain" corresponds to one of the addresses of the account and the value of the "username" field of the account is empty.

In any case, the address of the sender where the request came from on the SIP port of the ESG role must be known from the account description (a set of fields "domain", "proxyaddr"/"alternative_proxies", "extaddrs").

Read more about working with telephony providers.

Limitations

  • The collection is not available in the master domain.

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

  • Licensed by a quantitative parameter: a license is consumed for the allowed simultaneous number of active trunks.

Fields

Entity structure
{
  "id": uuid,
  "code": str,
  "enabled": intbool,
  "username": str,
  "login": str,
  "pwd": str,
  "domain": str,
  "proxyaddr": str,
  "proxyport": int,
  "transport": str,
  "alternative_proxies": str,
  "extaddrs": array<str>,
  "serveridx": int,
  "reg": bool,
  "expires": int,
  "pingmode": str,
  "pingsrv": str,
  "pingtimeout": int,
  "localdomain": str,
  "media": intbool,
  "reinvite": intbool,
  "translit": intbool,
  "lic": object,
  "trunksout": int,
  "opts": {
    "title": str,
    "comment": str,
    "agat_port_id": uuid,
    "agat_chassis_id": uuid,
    "agat_lm_id": uuid
  },
  "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

Account Code.
Used to specify in routing rules.

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

Account Switch.
When disabled, the role esg does not possess account data and does not handle calls on the account.

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

Username.
Substituted into the From header when registration is used.
Used as a key to associate an externally received INVITE request with a provider account.
Read more about tying.

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

Login for authorization.

If absent, authorization is based on username.
In this case, the username from the From URI of the current request is substituted as username during INVITE and re-INVITE, which may cause unexpected failure.

To avoid getting rejected in response to INVITE and re-INVITE requests, you can use one of the methods:

  • Set 'login' to the same value as the account’s 'username'. This will ensure correct provider-initiated authorization during the INVITE.

  • Use the 'reinvite'=0 mode and the oppositional 'media'=1 mode with the addition of bgmg instances to the configuration. This will prevent sending reinvite with a changed value From URI.

  • Configure normalization rule for this ISP account, where 'dir' = 'inner' and in 'modfromnumber' a value identical to the account’s 'username'. This will ensure that the same username is always substituted in the From header of INVITE requests to the ISP, which will ensure correct ISP-initiated authorization during the INVITE.

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

Password for authorization.
Mandatory field if account with registration.
Also used in non-registered accounts when external equipment requires authorization by sending 401 or 407.

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

SIP Server. Domain name substituted in the To header when sending requests from the system to external equipment.
Also used to identify the account when receiving external requests.

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

The address of the Outbound Proxy server where requests from the system to external equipment are actually sent.
If not specified, the address is the result of address determination by the value of the domain field, including DNS-servers.
Also used to identify the account when receiving external requests.

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

The Outbound Proxy server port where requests from the system to external equipment are actually sent to

Field: transport
Mode: in
Type: str
Default: "udp"

Transport protocol for the primary proxy. Valid values "udp", "tcp", "tls".

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

List of alternative Proxy servers.
Format: Proto:IP-address:Port separated by commas, where Proto – tcp | udp | tls, IP-address – IPV4, Port – natural number up to 65535.
For example tcp:192.168.220.135:5060, udp:187.12.124.55:33985

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

Additional possible ISP addresses or address masks to identify the account when receiving external requests, separated by commas.
Values in /reg/REGEX formats can be used as masks, as well as target values with special characters ?, * to specify an arbitrary digit and a greedy combination of one to three digits, respectively.
For example, /reg/^*.*.*.*$, 144.76.?0?.*
The use of masks incurs additional computational overhead.

Field: serveridxs
Mode: in
Type: array(int)
Default: empty

A list of role instances esg in descending order of priority that are responsible for handling the account. Roles are specified using RoleId values from the role configuration.
After the priority server becomes unavailable, the next server in the list starts working with the account within 30 seconds. If a higher-priority server is restored, the account may be served (registered) by both servers.
If there is only one value in the list, it is the server responsible for the account and the account is inactive if it is unavailable.
If the list is empty (default), the account operation is determined by the rules set in the domain settings (settings.ext.default_provider_serveridxs), it is expected that the number of RoleId or a list of them is there.
If the specified key is missing, the server with the lowest RoleId value in the sites where the domain is served starts working with the account.

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

Operating mode with registration (true) or without registration (false)

Field: expires
Mode: in
Type: int
Default: 3600

Re-registration period in seconds

Field: pingmode
Mode: in
Type: str
Default: `"none"`","Availability check mode

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

Address of external equipment to check availability.
If not specified, the availability check is performed at the same address selected to send INVITE requests.

Field: pingtimeout
Mode: in
Type: int
Default: 10

Availability check period, in seconds

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

Value of the domain field in the From header when sending requests from the system to external equipment

Field: media
Mode: in
Type: intbool
Default: 0

Frontier Media Gateway Usage Mode Switch.
When enabled, the sender address, contact address, and media processing server address are the same and the system can be treated as a single point of contact by external equipment.
It is also used to solve the problem of docking with another subnet.

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

Switch of the mode of transparent forwarding re-INVITE outward. Can be turned off only if the mode is enabled media.
Possible options:

  • 0 (none) - Reinvite Rollout is turned off. When a media session is changed, processing is done on the bgmg instance serving this dialog under esg. The mode can only be activated if the option is enabled media.

  • 1 (keep_from) - Reinvite upstream pass-through is enabled, in every re-INVITE request sent, the value of the From header is stored from the primary transaction INVITE.

  • 2 (update_from) - Upstream reINVITE forwarding is enabled, in each re-INVITE request sent, the value of the From header is redefined based on the subscriber on the new shoulder of the internal side.

Field: refer_mode
Mode: in
Type: str
Default: `"terminate"`", "REFER processing mode switch on the border gateway serving the ISP account.
Possible options:

  • terminate - REFER requests result in the initiation of a call by the ESG microservice toward the same number plan from which the request originated.

  • forward - REFER requests with appropriate modification of Refer-To, Referred-By header values are forwarded further, to the oppositional shoulder and another number plan.

The 'forward' mode is used for test cases of emulation by the subscriber system.
It can only be enabled if the reinvite mode is not set to 'none'.
If a Refer with spoofing is made, the 'forward' mode applies only the spoofed call also goes through this esg instance and the same provider account. Otherwise, the processing of this particular Refer request takes place in 'forward' mode 'terminate'.

Field: translit
Mode: in
Type: intbool
Default: 0

Disable transliteration of the displayed name when sending requests and responses outward

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

Set of licenses transferred from the domain. Among the parameters, the maximum number of simultaneous calls using the account is expected, for example {"siptrunks":5}.

Field: trunksout
Mode: in
Type: int
Default: -1

Maximum number of trunks used for outgoing calls.
-1 – is not restricted, i.e. limited only by the license.
In any other case, an outgoing call from the system to external equipment is rejected routing rule unless the number of active trunks on that account is less than the number specified in the field.

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.extusernames
Mode: in
Type: str
Default: empty

List of additional provider names identifying the account.
Applies when searching for a provider account on an incoming INVITE request when the provider specifies different values from the destination pool that do not match the enrollment name.

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

Account support for soft server decommissioning.

If an account with enrollment, esg microservice instances switched to soft decommissioning mode stop enrolling.
According to the defined list of esg instances authorized for maintenance (parameter serveridxs), the registration is transferred to the active instance (or multiple instances, parameter 'instance_count').
The system aims to support the specified number of registrations, primarily from esg instances executing on active servers.
If no active instances are among those authorized for maintenance, registrations will be maintained on the decommissioned servers.

If the account is unregistered, esg microservice instances switched to soft decommissioning mode reject initial INVITE calls from the provider with a response code of 'deservice_sipcode'.
According to the defined list of esg instances allowed to be served (parameter serveridxs), chaining service is passed to the active instance (or several, parameter 'instance_count').
If no active instances are among those allowed to be serviced, the soft de-maintenance mode is not applied to this account until at least one active microservice is available.

Field: opts.deservice_sipcode
Mode: in
Type: int
Default: 503

Response code sent by the esg microservice to initial INVITE requests from the ISP.
Sent if the server executing the esg instance is in soft decommissioning mode and the provider account is unregistered and has the 'deservice_response'.
Possible values: 400-699.

Field: opts.instance_count
Mode: in
Type: int
Default: 1

Number of ESG microservice instances serving the account at the same time.
If part of the servers are in soft decommissioning mode, then the behavior and distribution of the service instances corresponds to the description of the parameter 'deservice_response'.

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

Turns off the application of Diversion on upstream calls forwarded or routed back to the upstream (RFC-5806).

If the call did not come from upstream, or the account has Diversion disabled, the INVITE request parameters are generated on a generic basis on behalf of the system account according to normalization rules.

When a call is received from upstream subscriber A within a Diversion enabled account to number B, each INVITE request sent upstream to number C through any Diversion enabled account places the URI of subscriber A as the From URI, and additionally places a Diversion header with the URI of the number B.

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

Turns off the application of billing to calls made to either party through the current account.
If there are external subscribers in both arms in a dialog, billing is applied to each arm according to the account settings.
Billing connection parameters are placed in the master domain settings (billing_options).

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

Time of last modification of the object

Availability check modes

Table 2. Availability check modes
Value Description

"none"

Disable accessibility checks

"rn"

Send an empty CR LF request, expecting a response of CR LF CR LF

"options"

Send a SIP request to OPTIONS, expecting a SIP response in return 200 OK

"register"

Send an unscheduled SIP REGISTER request, waiting for a SIP response in return 200 OK

"stun"

Send STUN request

See also

API

  • Personalization
  • Increase font size
  • Decrease font size