SIP telephony provider (provider)

Description

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 located above or at the same level in the number plan as the «Incoplax» system.
The ESG role registers and maintains the communication channel with external equipment specified in the provider account. Any call that results in an outside call always goes through it. Any call arriving from outside into the system can be accepted, authorized, and serviced only by the ESG role defined in the provider account.

Determining which account an incoming call belongs to is based on a set of conditions:
- an account with registration in the "To:" or "Contact:" header of the SIP INVITE request contains "username@domain", where "username" matches the account’s "username" field value and "domain" matches one of the account addresses;
- an account without registration in the "Contact:" header of the SIP INVITE request contains "username@domain", where "username" matches the account’s "username" field value and "domain" matches one of the account addresses;
- an account without registration in the "Contact:" header of the SIP INVITE request contains "username@domain", where "domain" matches one of the account addresses and the account’s "username" field value is empty.

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

Read more about working with telephony providers.

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 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>,
  "serveridxs": array<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
  }
}
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 for reference in routing rules.

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

Account switch.
When disabled, the esg role has no account data and does not process calls for it.

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

Username.
Substituted into the From header when registration is used.
Used as a key to bind an incoming INVITE request to the provider account.
More about binding.

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 the username during INVITE and re-INVITE, which may cause an unexpected rejection.

To avoid rejection in response to INVITE and re-INVITE requests, use one of the following methods:

  • Set 'login' to a value matching the account 'username'. This ensures correct authorization initiated by the provider during INVITE.

  • Use 'reinvite'=0 and the opposite 'media'=1 with bgmg instances added to the configuration (bgmg). This eliminates sending a re-INVITE with a changed From URI.

  • Configure a normalization rule for this provider account where 'dir' = 'inner' and 'modfromnumber' equals the account 'username'. This ensures the same username is always substituted into the From header of INVITE requests toward the provider, ensuring correct authorization initiated by the provider during INVITE.

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

Password for authorization.
Required if the account has registration.
Also used in accounts without registration if external equipment requires authorization by sending 401 or 407 responses.
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: domain
Mode: in
Type: str
Default: required

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

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

Address of the Outbound Proxy server to which requests from the system to external equipment are actually sent.
If not specified, the address is resolved from the domain field value, including by DNS servers.
Also used to identify the account when receiving requests from outside.

When using parallel account servicing on several esg instances, the value applies only to redundant instances that have no values in the opts.edge_proxies list.

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

Port of the Outbound Proxy server to which requests from the system to external equipment are actually sent.
Value 0 means the default port: 5060 for udp and tcp, and 5061 for tls.

When using parallel account servicing on several esg instances, the value applies only to redundant instances that have no values in the opts.edge_proxies list.

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

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

When using parallel account servicing on several esg instances, the value applies only to redundant instances that have no values in the opts.edge_proxies list.

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

Certificate for connecting to the provider over TLS.
Contents of a PEM file with a trusted chain, or a macro path to a PEM file (e.g. ':SYNC_DOMAIN_DATA/files/certificates/provider1.pem').
If the value is not specified, then before version 1.9.0 no client-side certificate chain verification is performed, and from version 1.9.0 trusted certificates from the operating system are used.
Secret (private key body, if present in the value): when read, the plaintext value; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

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

List of alternative Proxy servers.
Format: Proto:Address:Port, comma-separated, where Proto is tcp | udp | tls, Address is IPv4 or a domain name, Port is the port (1-65535).
For example tcp:192.168.220.135:5060, udp:187.12.124.55:33985.
The formats Proto:Address, Address:Port, and Address may also be used. Default protocol is udp, default port is 5060 or 5061 for tls.

Used:
* during registration as backup connection points, and consequently as points for sending subsequent requests;
* in the algorithm for binding an incoming request to the provider account: when checking the sender address of an incoming INVITE request.

When using parallel account servicing on several esg instances, the value applies only to redundant instances that have no values in the opts.edge_proxies list.

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

Additional possible addresses or address masks for account identification and sender validation when receiving requests from outside, comma-separated.

The following value formats can be used as masks:

  • 192.168.0.112 - arbitrary constant IP address values;

  • 192.168.0.0/24 - subnets;

  • /dia/IpAddrStart+Count - several consecutive IP addresses starting from IpAddrStart (via conversion to Int32), e.g. /dia/172.27.1.10+80;

  • /reg/REGEX - an arbitrary regular expression, e.g. /reg/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$;

  • * - a special value; when used alone it covers any value;

  • target IPv4 address values with the special characters ?, * to denote an arbitrary digit and a greedy combination of one to three digits, e.g. 10.76.?0?.&#42 (the * character only together with other characters masks 1-3 digits);

  • arbitrary constant values (fqdn names), e.g. sip1.provider1.com.

Using masks (rather than constants) incurs additional computational cost. Therefore, in all cases masks are checked only if other simpler checks do not pass:

  • when searching for an account - direct match with the domain, proxy, allowed addresses of the domain and proxy, server external NAT addresses, exact addresses in the extaddrs list;

  • when checking the sender address - match with the allowed addresses of the domain, proxy, alternative_proxies, exact addresses in the extaddrs list.

From a performance standpoint, specifying one or more subnets or ranges is most efficient, compared with regular expressions or masks with special characters, as well as long lists of constants.

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

List of esg role instances in descending priority order that are responsible for working with the account. Roles are specified by RoleId values from the role configuration.
After the priority server becomes unavailable, the next server in the list starts working with the account within a few seconds. When a higher-priority server is restored, servicing is transferred to it within a few seconds. Enable/disable processing on different servers is parallel.
If the list contains only one value, that server is responsible for the account, and if it is unavailable the account is inactive.
If the list is empty (default), work with the account is determined by the rules set in domain settings (settings.ext.default_provider_serveridxs), which is expected to contain a RoleId or a list of them.
If the specified key is absent, the server with the lowest RoleId value on the sites serving the domain starts working with the account.

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

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"

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

Address of external equipment for availability checking.
If not specified, availability is checked at the same address selected for sending INVITE requests.

When using parallel account servicing on several esg instances, the value applies only to redundant instances that have no values in the opts.edge_proxies list.

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.
Applied only to accounts without registration. Default is empty, in which case a domain identical to To is used.

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

Switch for using the border media gateway.
When enabled, the sender address, contact address, and media traffic processing server address match, and external equipment can treat the system as a single point.
Also used to solve interconnection with another subnet.

The configuration must contain at least one bgmg instance on the servers running esg instances allowed to service the provider account.

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

Switch for transparent re-INVITE pass-through to the outside. Can be disabled only if media mode is enabled.
Possible variants:

  • 0 (none) - re-INVITE pass-through disabled. When the media session changes, processing is performed on the bgmg instance servicing this dialog under the control of esg. The mode can be activated only if the media option is enabled.

  • 1 (keep_from) - re-INVITE pass-through upstream enabled; in each sent re-INVITE request the From header value is preserved from the initial INVITE transaction.

  • 2 (update_from) - re-INVITE pass-through upstream enabled; in each sent re-INVITE request the From header value is determined anew based on the subscriber in the new internal-side leg.

Field: refer_mode
Mode: in
Type: str
Default: "terminate"

Switch for REFER processing mode on the border gateway servicing the provider account.
Possible variants:

  • terminate - REFER requests cause the ESG microservice to initiate a call toward the same number plan from which the request arrived.

  • forward - REFER requests with corresponding modification of Refer-To and Referred-By header values are forwarded further to the opposite leg and another number plan.

The 'forward' mode is used for test cases of subscriber emulation by the system.
It can be enabled only if reinvite mode is not set to 'none'.
If a Refer with substitution is performed, the 'forward' mode applies only if the substituted call also passes through this esg instance and the same provider account. Otherwise, that particular Refer request is processed in 'terminate' mode.

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

Switch for transliteration of the display name when sending requests and responses outside

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

Set of licenses transferred from the domain. The parameters are expected to include the maximum number of simultaneous calls using the account, e.g. {"siptrunks":5}.

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

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

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

CoS (class of service) group code.

Used to configure group access restriction policies.
Determines the restriction policy for incoming external calls through this account.

More in the article CoS/CoR group access restriction.

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

List of additional provider names identifying the account.
Used when searching for the provider account by an incoming INVITE request if the provider specifies different values from a finite pool that do not match the registration name.

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

Account support for the graceful server decommissioning mode.

If the account has registration, esg microservice instances switched to graceful decommissioning stop registration.
According to the configured list of esg instances allowed to service (the serveridxs parameter), registration is transferred to the active instance (or several, the 'instance_count' parameter).
The system strives to maintain the specified number of registrations, preferably from esg instances running on active servers.
If there is no active instance among those allowed to service, registrations will be maintained on servers being decommissioned.

If the account has no registration, esg microservice instances switched to graceful decommissioning reject primary INVITE requests from the provider with the 'deservice_sipcode' response code.
According to the configured list of esg instances allowed to service (the serveridxs parameter), servicing is transferred in a chain to the active instance (or several, the 'instance_count' parameter).
If there is no active instance among those allowed to service, graceful decommissioning is not applied to this account until at least one active microservice appears.

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

Response code sent by the esg microservice to primary INVITE requests from the provider.
Sent if the server running the esg instance is in graceful decommissioning mode, and the provider account has no registration and has the 'deservice_response' parameter enabled.
Possible values: 400-699.

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

Number of ESG microservice instances simultaneously servicing the account.

For example, the parameter can be used if a P2P account (without registration) needs to receive INVITE at one of several addresses in a multi-server system.
For accounts with registration, using several instances provides several simultaneous parallel registrations, whose contact will include the '+sip.instance' and 'reg-id' options per RFC-5626. This can be significant for registration through various external SIP proxies.

If some servers are in graceful decommissioning mode, the behavior and distribution of servicing instances correspond to the 'deservice_response' parameter description.

Field: opts.edge_proxies
Mode: in
Type: array(string)
Default: empty

List of alternative Proxy servers for parallel esg instances when servicing the account simultaneously on several instances (instance_count).

Each list element is a string in the format: Proto:Address:Port, comma-separated, where Proto is tcp | udp | tls, IP-address is IPv4, Port is the port (1-65535).
For example tcp:192.168.220.135:5060, udp:187.12.124.55:33985.
The formats Proto:Address, Address:Port, and Address may also be used. Default protocol is udp, default port is 5060 or 5061 for tls.

The first list element applies to the first parallel instance, the second to the second, etc.
If the list is empty, the set of values from the main fields transport, proxyaddr/domain, proxyport, alternative_proxies applies to all parallel instances.
If the list contains fewer values than instance_count, the set of values from the main fields also applies to all redundant instances.
Extra list values are not used.

The specified address is also used:

  • in the algorithm for binding an incoming request to the provider account: when checking the sender address of an incoming INVITE request;

  • for sending ping requests regardless of the pingsrv value.

Each parallel esg instance servicing the account may have a different composition and number of edge proxies.

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

Switch for applying Diversion on calls from upstream that are forwarded or smart-routed back to upstream (RFC-5806).

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

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

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

Switch for applying billing to calls made in either direction through the current account.
If both legs of the dialog are external subscribers, billing is applied to each leg according to account settings.
Billing connection parameters are placed in master domain settings (billing_options).

Field: opts.sip_restore_mode
Mode: in
Type: str
Default: replace

Switch for dialog recovery mode when a node with the esg microservice servicing call signaling fails.

Possible variants:

  • replace - an INVITE with a Replaces header is sent toward the uplink. The uplink must support replacement. The new call automatically replaces the previous call.

  • regular - a new INVITE is sent toward the uplink. It is expected that the subscriber will be called in parallel and will independently switch to the new call and end the previous one.

  • disabled - dialogs for this account are not recovered.

The recovery service is activated in the sip_restore_enabled configuration setting of the callstore microservice.

Field: opts.invite_filter
Mode: in
Type: array | false
Default: false

Additional filter for incoming INVITE requests.

The value format matches the 'filter' parameter format when reading a collection (more).

The filter is applied to an object formed from the key parameters of the INVITE request and the current account object.

{
  "ruri": {
    "user": username from INVITE's request line,
    "domain": domain from INVITE's request line
  },
  "from": {
    "user": username from INVITE's From header,
    "domain": domain from INVITE's From header
  },
  "to": {
    "user": username from INVITE's To header,
    "domain": domain from INVITE's To header
  },
  "contact": {
    "user": username from INVITE's Contact header,
    "domain": domain from INVITE's Contact header,
    "port": port from INVITE's Contact header
  },
  "proto": "tcp" | "udp" | "tls",
  "remote": {
    "addr": ip-address of INVITE's sender,
    "port": port of INVITE's sender
  },
  "local": {
    "addr": ...,
    "port": ...
  },
  "account": {
     "id": ...,
     "code": ...,
     ...
  }
}

The additional filter can solve, for example, the following task.

Several accounts are serviced by one esg instance.
These accounts are P2P (without registration) for the same provider but with different credentials.
Each account is multi-number, that is, it can supply calls to a large number of different numbers.
The provider server address is the same, but the ports on the provider server are different for different accounts.

One way to solve this task is to write the entire list of possible numbers into the opts.extusernames property of these accounts.
This solution is not optimal, since entering thousands of numbers into an account is inconvenient, and iterating through all of them on every invite to find the right account is not very performant.

The second way is to bind these accounts to different esg instances. Then incoming INVITEs from the provider will not overlap. However, if there are dozens or hundreds of such accounts rather than two or three, multiplying roles for them becomes inconvenient and stops being optimal to maintain during modifications.

With an additional filter

[
  "equals",
    ["property", "remote", "port"],
    ["property", "account", "proxyport"]
]

accounts can be distinguished by matching the sender port with the port specified in the account. In this case it is not necessary to split across different esg instances, nor to list the entire pool of numbers in 'opts.extusernames'. It is enough to leave username empty so that each of these accounts, according to the binding algorithm (step 2.2.), satisfies the basic check conditions, and the filter does the rest.

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

Switch for sending a set of codecs in responses to INVITE.
Applied only when using media call servicing through bgmg.

  • false – no more than one codec from those received in the Offer SDP is sent in the response.

  • true – a subset of codecs from those received in the Offer SDP may be sent in the response.

Field: opts.payloads_audio
Mode: in
Type: array(string)
Default: empty

List of audio codec names used for traffic exchange with the provider.
Applied only when using media call servicing through bgmg.

If the list is empty:

  • If the reinvite field is not 0, SDP is passed unchanged in both directions and the media gateway does not transcode.

  • If reinvite = 0: the provider’s offer is passed into the platform with its codecs (unknown to the platform are discarded), the offer to the provider is supplemented according to the payloads_audio_offer parameter of the current esg instance; in the response to the provider, one or several codecs depending on the opts.allow_ac_set field value.

If the list is not empty:

  • For incoming calls, re-INVITE and INVITE with Replaces from the provider, the codecs specified in this value and simultaneously in the incoming request SDP are used; if there are none, esg responds 488 Not Acceptable Here (re-INVITE is rejected without dropping the call). For example, when solving the task of forced and explicit selection of format 8 (PCMA/8000) if the SDP contains the format list "96 97 98 9 8 18". In the 200 response SDP the server places one or several codecs depending on the opts.allow_ac_set field value and the size of the intersection of codec lists (in the SDP and in the current value).

  • For outgoing calls, codecs from this value are offered in its order; telephone-event/8000 is added at the end unless excluded by the -telephone-event/8000 or -* element.

  • The offer into the platform contains the provider’s codecs from this value in the provider’s order (telephone-event/8000 — if not excluded). The codecs must be supported by the mg media gateways servicing b2b calls. Internal legs are not limited by the list; the media gateway transcodes if necessary.

The value is a list of audio codec names in "Name/Freq" format.
The following codecs are supported (case-insensitive):

  • telephone-event/8000 - DTMF signals (added automatically even if not specified, unless excluded by the -telephone-event/8000 or -* element; the list must contain at least one codec),

  • CN/8000,

  • PCMU/8000,

  • PCMA/8000,

  • GSM/8000,

  • G722/8000,

  • G729/8000,

  • speex/8000,

  • speex/16000,

  • speex/32000,

  • G726-16/8000,

  • G726-24/8000,

  • G726-32/8000,

  • G726-40/8000,

  • iLBC/8000,

  • opus/48000/2.

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

Availability check modes

Table 2. Availability check modes
Value Description

"none"

Disable availability check

"rn"

Send an empty CR LF request, expecting CR LF CR LF in response

"options"

Send a SIP OPTIONS request, expecting a 200 OK SIP response

"register"

Send an unscheduled SIP REGISTER request, expecting a 200 OK SIP response

"stun"

Send a STUN request