Inbound Calls

This section explains how 3CX handles Inbound Calls, call routing criteria and how information is extracted from incoming INVITE messages.

Source Identification (SI)

Source Identification (SI throughout the document) of incoming calls is a critical part of 3CX, as 3CX attempts to match each incoming INVITE message to a configured SIP Trunk, or reject the call if matching fails. This is especially important on a 3CX system with multiple SIP Trunk accounts configured, from the same or different providers.

Source Identification Matching Criteria

Source Identification Matching Criteria & Methods

3CX employs multiple methods of matching incoming INVITE messages to a SIP Trunk, illustrated in the above flow chart and explained in more detail below.

The way 3CX does the decision-making is that on each incoming INVITE, at every colored shape in the above flowchart, 3CX iterates through every configured SIP Trunk in random order and checks if the specific SI matching criteria is met. If not, then it will move onto the next colored shape repeating the same process. 3CX will stop at the first match it finds.

“rinstance” match

3CX tries first to find an “rinstance” parameter in the RURI SIP field in an INVITE to match against a SIP Trunk, only present in Register-based providers. If this exists, then 3CX checks if this “rinstance” value was used to register one of the configured SIP Trunks and if found, match it with that specific Trunk. This hard-coded function cannot be disabled.

How the “rinstance” parameter is generated is explained in Registration / Authentication.

“Contact : User Part” matches “Auth ID”

This matching function was mainly designed for PSTN Gateways, but also applies to SIP Trunks as well. In this case 3CX checks the “Contact : User Part” value of the INVITE and compares it with the “Auth ID” value of each SIP Trunk. If found, it is matched with the corresponding SIP Trunk.

This hard-coded behavior cannot be disabled.

Note: This is also one of the reasons why 3CX will not allow multiple SIP Trunks to have the same “Auth ID” value.

“Call Source Identification” criteria match

Call Source Identification in SIP Trunk settings > Inbound Parameters tab

“Call Source Identification” can be enabled and configured in the 3CX SIP Trunk settings, in the “Inbound Parameters” tab.

These options enable user-defined criteria matching. Once enabled, you can configure which SIP field in the incoming INVITE message should be compared with which option in the SIP Trunk settings.

If 3CX finds a match, the 3CX associates that specific INVITE with the matched SIP Trunk.

This SI option may return multiple matching SIP Trunks, so 3CX associates the INVITE with a random SIP Trunk. This scenario, with only the “Call Source Identification” checkbox selected is often referred to as “loose SI”.

To handle this possible issue, an extra option that can be enabled is “Use both ‘Source Identification’ rules and ‘Caller Number/Name’ field mappings”. So if an incoming INVITE matches the “loose SI” criteria, it additionally checks if the destination number is in the list of DIDs of the SIP Trunks that matched the “loose SI” criteria and if that also matches, then the INVITE is associated with the specific SIP Trunk. The SIP field from which 3CX reads the destination number is configured by setting the “CalledNum” variable, also located in the “Inbound Parameters” tab. When this option is enabled, it is referred to as “Strict SI”.

If “strict SI” is enabled, there can only be a single match among all the SIP Trunks on the 3CX System. If more than one “Strict SI”- enabled SIP Trunks match the incoming INVITE criteria, then the call is rejected.

Finally, “Strict SI” has one more caveat: When enabled, 3CX does not check the specific SIP Trunk for any other SI matching methods explained in the next sections.

Note: When “Strict SI” is enabled, the number format of the specified DIDs is important, as they need to match the format in the INVITE message.

“CalledNum” matches DID

This SI matching method attempts to match the destination number in the incoming INVITE message with a DID in the list of DIDs of each Trunk. Each SIP Trunk can be configured to read the destination number from a different SIP field, by adjusting the “CalledNum” variable in the “Inbound Parameters” tab.

<b>“CalledNum”</b> variable in <b>“SIP Trunk”</b> settings > <b>“Inbound Parameters”</b> tab.

If a match is found, the INVITE message is associated with the SIP Trunk that has the DID listed. If 3CX finds more than one matching SIP Trunks, then the call is rejected.

“CalledNum” matches Main Trunk

This SI matching method is identical with the one described in section “‘CalledNum’ matches DID” of this document with only two differences:

  • Instead of checking the list of DIDs, it tries to match the “CalledNum” variable with the Main Trunk Number of the SIP Trunk, configured in SIP Trunk settings > “General” tab.
  • his method does not reject the call if multiple matches are found, but instead routes the call randomly among the SIP Trunks that matched the criteria.

Source Identification Best Practises

The purpose of SI is for 3CX to correctly identify which SIP Trunk each incoming INVITE message must be associated with. As explained in section “Source Identification Matching Criteria” of this document, multiple methods can be employed, however as best practice,all SIP Trunks are recommended to ensure that one of the following SI matching methods is used:

  • “rinstance” parameter match:
  • Unique “Call Source Identification” criteria match

The “rinstance” parameter, whenever a SIP Trunk Provider supports it, is by far the best option as it ensures that 3CX immediately knows which SIP Trunk to associate an incoming call with, and because this value is unique per SIP Trunk, it allows users to add multiple instances of the same SIP Trunk providers in 3CX without causing an issue. The limitation of this however is that it requires the SIP Trunk provider to be registration-based, as this is not available for IP-based providers.

For IP-based SIP Trunk providers, or for Registration-based providers that don’t return the “rinstance” parameter, the second best option is to make use of the “Call Source Identification” options, that provide the flexibility to choose any SIP field and compare it either with a static value found in the SIP Trunk, e.g. the Registrar FQDN or IP, or a static value that can be entered manually (“Custom Field”).

Using the “Call Source Identification” options may however result in disabling multiple SIP Trunks of the same provider to be configured in a 3CX system. This can be determined using the information explained in section “Source Identification Matching Criteria” and following a logical approach, depending on the information an INVITE message contains from a provider.

Also note, that when the “Call Source Identification” option is enabled and “Strict SI” is used, all DID numbers associated with a SIP Trunk account must be listed in the SIP Trunk settings > “DIDs” tab, as unless this is done, the SI mechanism never matches this SIP Trunk. The on-screen message for the “SIP Trunk settings” > “Strict SI” option warns that “Catch All routing” capabilities are disabled when this option is enabled. More on “Catch All” routing will be explained in section “Inbound Call Routing” further in this document.

Overall, the SI options ensure that 3CX can identify the SIP Trunk to associate with each INVITE and ideally through SI, only one SIP Trunk is matched.

Inbound Parameters

Once an incoming INVITE is matched with a SIP Trunk through the SI process explained above, 3CX extracts information from the INVITE message, including:

  • The Dialed/Destination number
  • The Caller ID of the person calling
  • The Callers Name

Caller Number/Name Field Mapping in SIP Trunk settings > <b>“Inbound Parameters”</b>.

In SIP Trunk settings > “Inbound Parameters” tab you can configure 3CX to read the information from specific SIP fields that are found in the INVITE message and store them in “variables”. Consider the example screenshot above based on the following description of each variable is used for in 3CX.

“CalledNum” variable

The “CalledNum” variable holds the dialed/destination number, an important value as this determines the routing for the incoming. It is common for incoming INVITE messages to have the dialed/destination number in multiple SIP fields in possibly different formats. Typically the dialed number is found in the RURI : User Part or “To : User Part”, but this may vary. See Inbound Call Routing section for further info.

“CallerName” variable

The “CallerName” variable holds the Name of the Caller (CNAM), used by 3CX to present the Caller’s identity provided by the SIP Trunk Provider to 3CX extensions. Typically this variable is read from the “From : Display Name” but this may vary.

In cases where SIP Trunk Providers don’t send the CNAM,  even though acceptable, the “CallerName” variable should be set to a SIP field with a non-empty value, even if the field contains the Callers Number (explained below).

“CallerNum” variable

The “CallerNum” variable holds the Caller ID of the calling party (CNUM or CLI), used by 3CX as the incoming call Caller ID presented to extensions, used in reports and in Number Blacklist to reject calls, and more. Typically this variable is read from the “From : User Part” but this may vary.

Inbound Call Routing

Once 3CX associates an incoming INVITE with a SIP Trunk (see Source Identification section) and extracts the information from the INVITE message (see Inbound Parameters section), it then decides how to route the call based on two factors:

3CX incoming call routing flowchart.

The flowchart above depicts 3CX incoming call routing, described in detail below.

Routing when “CalledNum” matches a SIP Trunk DID

To route an incoming call, 3CX first checks if the “CalledNum” variable matches one of the DIDs listed in the SIP Trunk settings. It requires an exact match, so the format of numbers entered in the list, must match that of the SIP field set as the “CalledNum” variable (see “CalledNum” variable section).

If a match is found, 3CX proceeds to check if an Inbound Rule is configured for this DID. If yes, the call is routed to the destination defined by the Inbound Rule. If not, 3CX proceeds to check as if there was no DID, explained below.

Routing when “CalledNum” does not match a SIP Trunk DID

"Route calls to" section in SIP Trunk settings > <b>“General”</b> tab.

If the “CalledNum” variable does not have a match in the list of DIDs in SIP Trunk settings, 3CX routes the call to the general routing option that is configured for the SIP Trunk. The general routing option of a SIP Trunk (the “Catch All” rule), can be configured in SIP Trunk settings > “General” tab.

Last Updated

This document was last updated on 7 June 2019

https://www.3cx.com/docs/sip-trunk-inbound-calls/