Routing
- General
- Chapter 2. Routing architecture: who is responsible for what
- Chapter 3. What happens to a call at each stage
- Chapter 4. End-to-end examples
- Which entity solves which problem
- Where to direct the call? → route + vectorrule
- How to adapt numbers between internal and external plans? → provider_callerid and representative
- Which number to show in another domain? → representative
- How to create a service feature? → featurecode
- How to prohibit a user from using a feature? → featurerule
- How to manage access to directions for groups? → CoS/CoR/TollLists
- How to call several devices simultaneously? → sipgroup
- How to add modifying logic to a call? → sipkit
- How to organize a waiting queue? → hunt
- How to configure redirection for a user? → redirectrule
- Summary table
- How to design routing so it does not turn into hell
- Pitfalls and common mistakes
- Where the initiator number in the outgoing INVITE comes from
- If rules have the same priority — order is random
- Priority in external: if esg is unavailable — there will be fallback
- CoS works only if set explicitly
- representative is not always applied
- Redirection: server vs client
- On transfers and redirections the transferring subscriber becomes the routing initiator
- Normalization is not always mandatory
- 3xx response from the device is processed by the server
- IVR can initiate calls with any number
- Summary of typical mistakes
General
Routing is the process of deciding what to do with an incoming call. Every call enters the platform as a SIP INVITE request containing information about the source (From), destination (To), and other parameters. Based on this data the platform determines further actions.
The main question routing answers: where to send the call? The answer may differ: an internal subscriber, an external network via a provider, a service feature, another domain. There may be several directions — a call can branch into forks, servicing several devices, parallel numbers, or groups simultaneously.
During routing the question of presenting the calling subscriber to the called one is additionally resolved: which number and display name the call recipient will see.
The result of routing may be not only sending an INVITE to the called subscriber but also refusing call servicing.
Configured redirections influence routing. Call pickup also uses routing mechanisms but is initiated by a separate action.
Routing applies to all call types without exception: internal, external, cross-domain, service, as well as calls initiated by the system — from IVR, conferences, and other service components.
The routing pipeline can leave the original domain and continue searching for a solution in other domains. On redirections and the next action, routing is restarted with modified parameters. On forks of any type (groups, parallel calls, multiple registrations), routing branches and continues independently for each direction.
In this platform routing is a full pipeline involving several microservices, many entities, and filters. Understanding this pipeline is the foundation for configuring routing of any complexity.
Chapter 2. Routing architecture: who is responsible for what
The routing process is distributed across several microservices. Each performs its part at different call processing stages.
Microservice roles
| Microservice | Description |
|---|---|
esg |
External gateway. Processes calls arriving from external networks (providers, PSTN). Performs border filtering (borderrule), provider account binding, limit control, and number normalization — converting the external number plan to internal and back. |
sg |
Internal gateway. Accepts calls from authorized internal devices. Performs border filtering and address and domain substitution for devices that do not use domain names in SIP URI. |
sr |
Registrar. Stores contacts of devices registered under internal subscriber accounts. A call to an internal subscriber is possible only if their device is registered and contact information is present in the registrar. |
sts |
Storage of SUBSCRIBE subscriptions and BLF states. Subscriptions also pass routing but with significant limitations. When calls are made, subscribers receive notifications about state changes and dialog composition. |
b2b |
The main router. This is where the call direction decision is made. It searches vectors and routing rules, applies modifications, checks group access policies, processes redirections, and forms forks. |
ivr |
Interactive voice response service. Services calls directed to IVR scripts. Can initiate calls on request via CTI, call manager API, or from scripts. IVR can substitute any numbers and names as the initiator, and all such calls pass routing on a common basis. |
conf |
Conference service. Processes calls directed to conference rooms, manages participants and audio mixing. |
prompt |
Conversation connection service. Provides listening, whisper, and connection to existing dialogs. |
dc |
Storage of domain static collections. Contains main domain and telephony settings, including routing vectors, rules, representations, redirections, and other entities determining routing behavior. |
Number plans
The system has an internal number plan — numbers by which routing is performed inside the platform. These are user, group, and service feature numbers. All routing configuration is performed in the internal number plan.
However calls may arrive from external networks or be directed to them. The external number plan is a concept the administrator must keep in mind during configuration. For example, a connected PSTN provider may address 10-digit numbers with a region code, while an external PBX may use 6-digit addressing.
The administrator’s task is to configure the transition from the internal number plan to the external one and back so that the expected number values enter the next processing stage. For this, normalization rules converting numbers between plans are applied on esg.
Call flow
An external call passes through esg, where border filtering, provider binding, and number normalization to the internal plan are performed. An internal call from a device arrives at sg, where authorization and call preparation occur. A call from a system service (ivr, conf, prompt) arrives at b2b with the full initiator context. Each of these flows is ultimately directed to b2b.
On b2b routing is performed: searching a suitable vector and rule, applying modifiers, checking permissions. Based on the routing result the call is either directed for execution or rejected.
For an internal direction the call returns to sg and then to the called subscriber device (provided a contact exists in the registrar). For an external direction the call is directed to esg, where reverse number normalization to the external plan is performed, after which it is sent to the provider.
For a cross-domain direction the routing process continues in the target domain. After the destination subscriber is found in the target domain, the initiator representation for this called subscriber is applied.
For a direction to a service the call is passed to the corresponding microservice (ivr, conf, prompt) for processing.
Routing entities
Routing configuration operates with the following entity classes:
| Entity | Description |
|---|---|
sipuser |
Internal subscriber accounts. Define internal user numbers, parallel call numbers, number restrictions for redirections, and other call options. |
route |
Routing vectors. Group rules by meaning, set common filters and schedules. |
vectorrule |
Routing rules. Define the general call direction: internal, external, cross-domain, service, repeat with modification, or refusal. |
featurecode |
Subscriber feature codes. Define service numbers and their behavior (IVR, conferences, voicemail, pickup, parking, and others). |
featurerule |
Feature permission rules. Restrict access to service features defined in featurecode. |
representative |
Representation rules. Define which number and name the called subscriber will see on cross-domain calls. Can also supplement normalization rules on external calls. Not applied to calls to internal subscribers of the domain. |
provider_callerid |
Normalization rules. Convert numbers between external and internal number plans on esg. |
redirectrule |
Redirection rules. Configure server-side redirection for specific subscribers under various conditions. Not to be confused with redirection configured on the user device itself: such redirections are processed by the server after receiving SIP 301 or 302 response. |
sipgroup |
Group numbers. Combine several accounts into one number with various call modes. |
sipkit |
Feature groups. Add modifying logic to calls to existing accounts. |
hunt |
Hunt groups. Organize PBX-level queues with resource distribution. Unlike call center queues, statistics are not tracked for them. |
CosProfile, CorProfile, CorPolicy, TollList, TollLink |
Group policies. Manage access to directions and features at group level. |
All these entities work together, and their combination determines routing behavior in the domain.
Chapter 3. What happens to a call at each stage
The routing process can be represented as a sequence of stages a call passes through. Understanding this sequence is the foundation for conscious configuration. Each stage solves its task, and skipping or misconfiguring any of them results in the call not reaching its target or reaching it in the wrong form.
The stages are described in the order they are passed. Some may repeat (for example, routing on the next action or on redirections), but the general logic remains unchanged.
3.1. Incoming control
At this stage the platform determines who initiated the call, where it came from, and whether servicing is allowed. The control method depends on which side the call arrived from.
External call (via esg) — a call arriving from a provider or PSTN. Processing sequence:
-
borderrule — border filter checking sender IP address and port. Can allow, reject, or ignore (drop).
-
sipmodrule — full-text SIP message modifier allowing modification of arbitrary INVITE fields before its parsing begins.
-
sip-alg — address substitution: local addresses in the packet are replaced with external ones according to settings. Performed before request parsing and header analysis.
-
Provider account binding — matching incoming INVITE parameters with account fields using several search stages.
-
Limit check — number of active trunks, registration state (if provided), ping results.
-
Number normalization — conversion of the external number to the internal number plan using provider_callerid rules.
After all these transformations the call is directed to b2b for routing.
Internal call (via sg) — a call from a device registered in the system. Such a call has already passed authorization, and the platform knows which account the device belongs to. Processing sequence:
-
borderrule — border filter (optional).
-
sipmodrule — full-text SIP message modifier (optional).
-
sip-alg — address substitution if enabled.
-
Domain substitution — for devices that do not support domain names in SIP URI.
After that the call is directed to b2b for routing.
Call from a system service (ivr, conf, prompt) — a call initiated by the platform itself. Such a call arrives at b2b directly, bypassing external gateways. It contains the full initiator context — number and name can be set arbitrarily by the service. This allows, for example, organizing a callback on behalf of a subscriber or a system notification.
3.2. Route selection
This is the central routing stage. Here b2b decides what to do with the call. The process consists of two steps: vector search and rule search.
Vector search is performed over the route collection. Vectors are checked in priority order: the smaller the priority value, the earlier the vector is checked. For each vector filters are applied: source number (fromnumber), destination number (tonumber), source domain (fromdomain), provider account code (fromextaccount), and initiator environment (dir). If all filters pass and the vector schedule (schedule) allows its use at the current time, the vector is considered suitable.
If several vectors have the same priority, their check order is random. This is important to consider in design: one cannot rely on random order to ensure deterministic behavior.
After the vector is selected, rule search begins within this vector. Rules (vectorrule) are checked in priority order within the vector. For each rule the same filters as for the vector are applied, but with additional fields: todomain (destination domain) and routecode (service code). If the rule passes all filters, the rule schedule allows its use, and the group policy check (CoS/CoR) does not prohibit the call, the rule is considered suitable.
If the rule has the fallback_next = true option, then on execution failure (for example, esg unavailability for an external call) the search continues from the next priority rule.
With equal priorities rules are checked in random order. This property can be used to distribute load between several routes.
3.3. Call modification
At this stage the platform changes call parameters according to the settings of the found rule. Modifications apply to numbers used in the following steps.
The source number (modfromnumber), destination number (modtonumber), or service code (modroutecode) can be changed. Similar mechanisms are used for modification: character mode, regular expressions, ranges, and tables.
If the rule action is next, then after applying modifications routing is restarted with new parameters. This allows organizing multi-stage processing when one call sequentially passes through several rules. The key goal of next is compactness through timely canonicalization of parameters (initiator and called numbers).
3.4. Permission check
Before executing the selected action the platform checks whether the initiator has the right to this call. The check is performed at two levels: group policies and feature permission rules.
Group policies (CoS/CoR/TollLists) check access to call directions. CoS (Class of Service) determines what is allowed to the initiator. CoR (Class of Restriction) determines who can reach the destination object. CosProfile sets the set of allowed directions and features for the group. CorPolicy is a matrix determining whether CoS can call CoR. TollList and TollLink allow flexible linking of directions to groups.
This mechanism is intended for large installations where uniform permission settings for a large number of subscribers become obviously costly. For small and medium systems it may be excessive. By default everything is allowed, and group policies apply only when the administrator explicitly configures them.
The check is performed by the following algorithm. The initiator CoS is determined in the call context (for a user — from sipuser, for a provider — from provider, for IVR — empty CoS meaning "everything allowed"). If restriction_level is set in the rule, CosProfile is checked to have a not lower access level. If call_type is set in the rule, intersection with allowed directions from CosProfile is checked (via call_types or toll_lists). If the called subscriber is a system user and has cor set, the CorPolicy matrix is checked for the src_cos — dst_cor pair with the call function.
Feature permission rules (featurerule) check access to service features. They work at the level of specific users and numbers, checking the from—to pair and feature type.
3.5. Execution
The found rule determines the action to be performed with the call. Available actions and their specifics:
| Action | Description |
|---|---|
internal |
Direct the call to an internal subscriber. The platform searches the sipuser account or sipgroup group number by destination number. If the subscriber is found, their redirections are checked, forks to registered devices and parallel numbers are formed. The call is directed to sg and then to the device. |
internalpbx |
Same as internal but accounting for extension — an additional number passed to the called subscriber. Used to organize a PBX behind a subscriber. |
external |
Direct the call to an external provider. The platform checks the availability of the specified provider account: whether esg is active, whether trunk limits are exceeded, whether the account is registered (if required), whether it responds to pings. If the account is unavailable and fallback_next is set in the rule, the search continues from the next rule. If available, the call is directed to esg with the account specified. |
cross |
Direct the call to another domain. At the input the initiator number and called number parameters are the result of modification from the previous rule. The routing process continues in the target domain. Initiator representation for the called subscriber is applied later when the target subscriber is determined. |
featurecode |
Execute a service feature. The call is passed to the corresponding service (ivr, conf, prompt) depending on featurecode type, or a service action is performed (for example, pickup). |
next |
Repeat routing with modified parameters. Allows organizing rule chains. The key goal is compactness through timely parameter canonicalization. |
denied |
Reject the call. |
3.6. Outgoing control
After the call is prepared for sending, the platform performs final transformations so that the outgoing INVITE looks correct to the recipient.
For an external call (via esg) reverse normalization is performed: the internal number plan is converted to the external one using provider_callerid rules.
For a cross-domain call representation rules (representative) are applied, determining which number and name the called subscriber will see in another domain. Representation is applied for each fork independently, allowing one call to be represented differently for different recipients.
At this stage address substitution (sip-alg) and full-text SIP message modification (sipmodrule) may also be applied.
After all transformations the outgoing INVITE is sent to the next link — device, provider, or service.
Chapter 4. End-to-end examples
Routing theory becomes understandable only when it manifests in real calls. In this chapter we will sequentially analyze several end-to-end examples — from incoming INVITE to outgoing. Each example shows how call parameters change at each stage, which entities and filters participate, and how routing turns the original request into the final one.
The examples are built from simple to complex. It is recommended to study them in the order presented.
All examples use a single convention: INVITE is shown in abbreviated form, highlighting key fields — From, To, Request-URI, and additional parameters if important for understanding.
Example 1. Internal call
User A with internal number 101 calls user B with internal number 102. Both are in the same domain.
Incoming INVITE (from device A to sg):
INVITE sip:102@domain.local SIP/2.0 From: <sip:101@domain.local> To: <sip:102@domain.local>
Stage 1. Incoming control (sg).
The call arrives at sg from a registered device. The platform knows the device belongs to account 101. After processing the call is directed to b2b.
Parameters at b2b input: * fromnumber: 101 * tonumber: 102 * fromdomain: domain.local * dir: inner (initiator — internal subscriber)
Stage 2. Route selection (b2b).
Vector search: a vector with filter dir=inner and tonumber=10* is found, suitable for number 102.
Rule search within the vector: a rule with action=internal and filters fromnumber=* and tonumber=* is found (suitable for any numbers).
Stage 3. Permission check.
Initiator CoS — empty (everything allowed). The rule has no restriction_level and call_type. Group policies are not applied.
Stage 4. Execution (internal).
Subscriber search by number 102: sipuser account with phonenumber=102 is found. Redirections are checked: no absolute ones, device is registered. A fork to the registered device is formed. No parallel numbers configured.
Stage 5. Outgoing control.
The call is not external and not cross-domain. Representation is not applied (internal call within the domain). Normalization is not required.
Outgoing INVITE (from b2b to sg, then to device B):
INVITE sip:102@device-b-ip:5060 SIP/2.0 From: <sip:101@domain.local> To: <sip:102@domain.local>
Result: the call is delivered to user B. The initiator number remained 101, the destination number — 102.
Example 2. External outgoing call
User A with internal number 101 calls external number 84951234567. The domain has provider1 configured, requiring outgoing calls to have a federal number in the From field. Internal number 101 must be converted to company external number 7654321 with federal prefix 7495.
Incoming INVITE (from device A to sg):
INVITE sip:84951234567@domain.local SIP/2.0 From: <sip:101@domain.local> To: <sip:84951234567@domain.local>
Stage 1. Incoming control (sg).
The call arrives at sg from a registered device. The platform knows the device belongs to account 101. The call is directed to b2b.
Parameters at b2b input: * fromnumber: 101 * tonumber: 84951234567 * fromdomain: domain.local * dir: inner
Stage 2. Route selection (b2b).
Vector search: a vector with filter tonumber=8495* is found (external numbers).
Rule search within the vector: a rule with action=external and toextaccount=provider1 is found. Filters: fromnumber=, tonumber=8495 (suitable). The rule has fallback_next=true.
Stage 3. Permission check.
Initiator CoS — empty. restriction_level and call_type are not set in the rule. Group policies are not applied.
Stage 4. Execution (external).
The platform checks provider1 account availability: esg active, trunk limits not exceeded, registration active. The call is directed to esg with provider1 account specified.
Parameters at esg input: * fromnumber: 101 * tonumber: 84951234567 * provider: provider1
On esg reverse normalization is performed using provider_callerid. The normalization rule converts fromnumber 101 → 74957654321 (federal company number). The to parameter remains unchanged.
Stage 5. Outgoing control (esg).
sip-alg and sipmodrule are applied (if configured). The domain field receives the domain from the provider account.
Outgoing INVITE (from esg to provider):
INVITE sip:84951234567@pstn-provider.net SIP/2.0 From: <sip:74957654321@pstn-provider.net> To: <sip:84951234567@pstn-provider.net>
Result: the call is directed to the provider. The federal company number 74957654321 is substituted in the From field.
Example 3. External incoming call
A call arrives at the platform from a provider to the federal company number 74957654321. Internal routing must direct it to an IVR script with internal number 555.
Incoming INVITE (from provider to esg):
INVITE sip:74957654321@pstn-provider.net SIP/2.0 From: <sip:74950000000@pstn-provider.net> To: <sip:74957654321@pstn-provider.net>
Stage 1. Incoming control (esg).
The call arrives at esg. borderrule is applied (IP allowed). Provider1 account binding is performed (by From/To/Contact).
On esg normalization is performed using provider_callerid. The rule converts: * to: 74957654321 → 555 (internal IVR script number) * from: 74950000000 → (no conversion required, number remains for internal use)
The call is directed to b2b.
Parameters at b2b input: * fromnumber: 74950000000 * tonumber: 555 * fromdomain: domain.local * fromextaccount: provider1 * dir: outer (initiator — external provider)
Stage 2. Route selection (b2b).
Vector search: a vector with filter dir=outer and tonumber=5* is found.
Rule search within the vector: a rule with action=featurecode and filters fromnumber=* and tonumber=555 is found.
Stage 3. Permission check.
Initiator (provider) CoS — empty. The rule passes.
Stage 4. Execution (featurecode).
featurecode search with number 555. A code with type=ivr and extension=main_ivr (IVR script code) is found. The call is directed to the ivr service.
Outgoing INVITE (from b2b to ivr):
INVITE sip:ivr-555@ivr-service SIP/2.0 From: <sip:74950000000@domain.local> To: <sip:ivr-555@domain.local> X-Era-...: ...
The ivr service receives the call context and starts the main_ivr script to process the incoming call.
Result: the call is directed to the main_ivr IVR script. Special headers pass context for the script.
Example 4. Cross-domain call with representation
User A from domain1 with number 101 calls user B from domain2 with number 102 (number 102 does not exist in domain1 but exists in domain2). The number plan is arranged so that to call subscriber 102 in domain2 from domain1 one must dial 2102 (prefix 2 means "call to domain2"). The initiator number must be represented for domain2 as 1101 (prefix 1 means "call from domain1").
Incoming INVITE (from device A to sg domain1):
INVITE sip:2102@domain1.local SIP/2.0 From: <sip:101@domain1.local> To: <sip:2102@domain1.local>
Stage 1. Incoming control (sg domain1).
Call from a registered device. Parameters at b2b input: * fromnumber: 101 * tonumber: 2102 * fromdomain: domain1.local * dir: inner
Stage 2. Route selection (b2b domain1).
Vector with filter tonumber=2XXX (calls to domain2). Rule with action=cross, todomain=domain2.local, modtonumber=/X/XXX (removes the first digit 2, leaving 102).
Stage 3. Permission check.
Initiator CoS — empty.
Stage 4. Execution (cross).
The call is passed to domain2. Parameters at b2b domain2 input: * fromnumber: 101 (initiator number from domain1) * tonumber: 102 (destination number in domain2 after prefix removal) * fromdomain: domain1.local * dir: cross
Stage 5. Route selection in domain2.
In domain2 routing by number 102 is performed. Internal user 102 is found. When forming the call, representative is applied, converting fromnumber 101 → 1101 (external appearance of the number for domain2).
Stage 6. Outgoing control (domain2).
Representation applied. The call is directed to user 102 device.
Outgoing INVITE (from b2b domain2 to sg, then to device):
INVITE sip:102@device-b-ip:5060 SIP/2.0 From: <sip:1101@domain2.local> To: <sip:102@domain2.local>
Result: user B sees an incoming call from number 1101, not 101. Redial will work with number 1101, which can be directed back to domain1.
Example 5. Two-step transfer with leg substitution
User A (101) calls user B (102). B answers. Then B makes a consultation call to user C (103). After C answers, B sends REFER with Replaces to A, specifying C contact and its leg identifiers. As a result A and C connect directly, and B leaves the dialog.
Original dialog (already established):
A (101) <→ B (102) — dialog active, dialog identifier D1.
Step 1. Consultation call (B → C)
B initiates a new call to C. This call passes routing as a normal internal call (see Example 1).
Outgoing INVITE from B to C:
INVITE sip:103@domain.local SIP/2.0 From: <sip:102@domain.local> To: <sip:103@domain.local>
C answers. Dialog D2 between B and C is established.
Step 2. REFER with Replaces (B → A)
B sends REFER to A with a replaces parameter in Refer-To pointing to dialog D2 (between B and C).
REFER from B to A:
REFER sip:101@domain.local SIP/2.0 From: <sip:102@domain.local> To: <sip:101@domain.local> Refer-To: <sip:103@domain.local?Replaces=dialog-id-D2>
Step 3. REFER processing (device A)
Device A processes REFER. According to Refer-To and the replaces parameter, device A initiates a new INVITE to C with a Replaces header pointing to dialog D2.
INVITE from A to C (with Replaces):
INVITE sip:103@domain.local SIP/2.0 From: <sip:101@domain.local> To: <sip:103@domain.local> Replaces: <dialog-id-D2>
This INVITE passes routing as a normal internal call (see Example 1).
Step 4. Completion of old dialogs
After successful establishment of the new dialog D3 between A and C, dialog D1 (A-B) completes, and dialog D2 (B-C) completes. B no longer participates in the dialog.
Result: A and C are connected directly. C sees a call from A (101), A sees C (103).
Example 6. Service call (featurecode) — conference
User A (101) dials *10512 to join a conference with room number 12.
Incoming INVITE (from device A to sg):
INVITE sip:*10512@domain.local SIP/2.0 From: <sip:101@domain.local> To: <sip:*10512@domain.local>
Stage 1. Incoming control (sg).
Call from a registered device. Parameters at b2b input: * fromnumber: 101 * tonumber: *10512 * dir: inner
Stage 2. Route selection (b2b).
Vector with filter tonumber=105 (service numbers). Rule with action=featurecode and filter tonumber=105.
Stage 3. Permission check.
Initiator CoS — empty. featurerule check: if conference prohibitions are configured for user 101, the call will be rejected. In this case there are no rules.
Stage 4. Execution (featurecode).
featurecode search with prefix *105. A code with type=conference and extension=12 (room number) is found. The call is directed to the conf service.
Outgoing INVITE (from b2b to conf):
INVITE sip:12@conf-service SIP/2.0 From: <sip:101@domain.local> To: <sip:*10512@domain.local> X-Era-...: ...
The conf service processes the request: connects user A to the conference with room number 12.
Result: user A is connected to the conference with number 12. The INVITE to the conf service is formed with the room specified in Request-URI. Special headers pass context for the service.
Which entity solves which problem
Routing operates with a large number of entities. It is easy for a beginner to get confused about what is responsible for what. Below is not a reference but a navigator: which entity is intended for which task and when to use it.
Where to direct the call? → route + vectorrule
This is the heart of routing. Used always.
route (vector) — grouping of rules. Allows combining rules by meaning (for example, "internal calls", "mobile calls", "international") and setting common filters and schedules for them. The main goal of vectors is reducing the number of iterated rules through grouping and preliminary filtering.
vectorrule (rule) — specific action. It decides what to do with the call: direct inside, outside, to another domain, to a service, or reject.
When to use: - Always. Without route and vectorrule the call will not be processed.
How to adapt numbers between internal and external plans? → provider_callerid and representative
This is an adapter between two worlds: the platform internal number plan and the provider/PSTN external number plan.
Inside the platform numbers may be short (101, 102), while the provider requires a full federal number (74957654321). Or vice versa — the provider sends a number in one format and the platform expects another.
When to use provider_callerid: - When the internal number plan does not match the external one - When the provider requires a constant number substitution (for example, always substitute the company head number) - When a "carousel" is needed — random selection of a number from a pool for outgoing calls - When a prefix (city code, country code) must be removed or added - When the internal number plan operates with different external provider accounts, each with its own company number, and adaptation to a specific provider is required
When to use representative: - On cross-domain calls when a number in one domain must look different in another - On external calls when a specific number must be shown to the outside world - To assign different external company numbers to different subscribers or domains
When not to use conversions (neither provider_callerid nor representative): - If the internal number plan already fully matches what is expected at the next stage (the provider expects exactly the number already in the system). In this case conversion is simply not required.
Difference: - provider_callerid — adapter between internal and external number plans, bound to a specific provider and executed on esg - representative — representation of the number in another domain or for an external call, bound to the number and executed on b2b
|
provider_callerid works on esg — on input and output. representative works on b2b and is applied for each fork independently. |
Which number to show in another domain? → representative
This is about representation. When a call goes from one domain to another (cross-domain call), the calling subscriber may have one number in one domain while the other domain must see them differently.
Example: - In domain A the user has number 101 - In domain B they must be seen as 1101
When to use: - On cross-domain calls - On external calls when a specific number must be shown to the outside world - For Redial, when the subscriber direct number in another domain is unreachable from the current domain
When not to use: - For internal calls within one domain
|
representative is applied on b2b, for each fork independently. This means one call can be represented differently for different recipients. |
How to create a service feature? → featurecode
This is about service numbers. featurecode determines which number corresponds to which service feature: IVR, conference, voicemail, pickup, parking, and others.
When to use: - When a service number is needed (for example, *105 — conferences) - When users must be able to access system services by short numbers
When not to use: - For regular calls between users — internal exists for this - For external calls — external exists for this
How to prohibit a user from using a feature? → featurerule
This is about access to service features. featurerule checks whether a user with a specific number (from) can use a specific feature (featurecode type) for a specific number (to).
What can be prohibited: - Connection to a conversation (monitor, prompt, mesh) - Barge - Intercom - Pickup - Leg substitution (replace) - Other featurecode types
When to use: - When a specific user must be prohibited from using a specific feature - When a feature must be allowed only for specific destination numbers - When without prohibition configuration routing rules multiply uncontrollably. If the same rule is repeated many times with minor changes, this is a clear marker that it is time to introduce featurerule. - When configuration compactness must be preserved through number masks rather than introducing new abstract entities
When not to use: - For group prohibition management through introducing new abstract entities (prohibition and permission classes) — CoS/CoR exists for this. This is a higher abstraction level that requires additional entities but provides structural compactness at large scale
|
featurerule works on b2b, at the featurecode application stage. |
How to manage access to directions for groups? → CoS/CoR/TollLists
This is about mass access management. Not for each user but for groups.
CoS (Class of Service) — what is allowed to the initiator. CoR (Class of Restriction) — who can reach the destination object. CosProfile — profile with a set of allowed directions and features. CorPolicy — matrix saying "Can CoS A call CoR B?"
To provide even greater compactness and structure, the system offers an additional abstraction level: - TollList — list of simultaneously allowed call directions. Allows collecting several directions into one named group and reusing it in different CosProfiles. - TollLink — matrix of links between TollList and specific directions (CallType). Allows flexibly adding or excluding directions from TollList without changing the profiles themselves.
Thus direction access configuration can be organized at three levels: direct enumeration in CosProfile, using TollList, or using TollList with additional filtering via TollLink. This allows adapting configuration complexity to real needs.
When to use: - In large corporations with many users and groups - When centralized management of direction access is needed (international, long-distance, local, internal) - When access must be separated between departments/user groups - When the number of uniform settings becomes obviously costly
When not to use: - In small installations (up to 50-100 users) — excessive - If direction access is easier to control via vectorrule - If the configuration seems too abstract — then it really is complex
|
CoS/CoR is an optional mechanism. By default everything is allowed. Do not use it unless you are sure it is needed. It is a tool for large systems, not for everyone. |
Difference from featurerule: - CoS/CoR manages access to directions and services at group level - featurerule manages access to features at specific user/number level - These are complementary mechanisms, not alternatives
How to call several devices simultaneously? → sipgroup
This is a simple group number. sipgroup has a number, and when someone calls this number, the call is directed to several devices/accounts.
Modes: - cascade — sequential - parallel — simultaneous - random — sequential but in random order
When to use: - When a simple group number without complex logic is needed - When the call must reach several subscribers
When not to use: - When complex logic is needed (boss-secretary, call option setting) — sipkit exists for this - When a waiting queue is needed — hunt exists for this
How to add modifying logic to a call? → sipkit
This is about modifying logic. sipkit has no number — it is not an addressee. It changes call behavior to existing accounts.
Types: - redirect — redirection - reject — refusal - options — setting call options (timeouts, duration) - parallel — parallel call (alternative to sipuser setting) - chief — boss-secretary
When to use: - When modifying logic must be applied to calls to certain numbers - Boss-secretary is one of the most common cases - When call options (fork_timeoutsec, dialog_timeoutsec) must be set for a call group
When not to use: - For a simple group number — sipgroup is enough - For pointwise behavior change of one user — can be configured in sipuser
|
sipkit works invisibly to the call initiator. It is applied to existing accounts and does not create a new addressee. |
How to organize a waiting queue? → hunt
This is an alternative to sipgroup with a local waiting queue. Hunt is a more complex alternative to sipgroup using a local waiting queue that is not tracked in overall call statistics.
When to use: - When a waiting queue for a resource group is needed - When call statistics are not critical and do not require centralized accounting
When not to use: - When a simple group without a queue is needed — use sipgroup - When full statistics and reporting are needed — use the call center
How to configure redirection for a user? → redirectrule
This is about server-side redirection. redirectrule configures redirection for specific subscribers under various conditions.
Types: - absolute — always - unregistered — on absence of registration - busy — busy - timeout — timeout - decline — refusal - dnd — do not disturb - error — error - other — other cases
When to use: - When redirection must be configured for a specific user - When different redirection conditions must be distinguished (busy, timeout, refusal)
|
Not to be confused with redirection configured on the user device itself. Such redirections are processed by the server after receiving SIP 301 or 302 response to the sent INVITE. |
Summary table
| What needs to be done | Entity |
|---|---|
Direct the call |
route + vectorrule |
Create a service feature |
featurecode |
Prohibit a user from using a feature |
featurerule |
Manage access to directions for groups |
CoS/CoR/TollLists |
Adapt numbers between internal and external plans |
provider_callerid and/or representative |
Show a number differently in another domain |
representative |
Create a group number |
sipgroup |
Add modifying logic to a call |
sipkit |
Organize a queue with resources (with local waiting queue) |
hunt |
Configure redirection for a user |
redirectrule |
How to design routing so it does not turn into hell
Routing is a living system. It evolves with the business: new subscribers, new directions, new requirements, new providers appear. Without discipline such evolution leads to inevitable degradation: the number of rules grows, their logic becomes tangled, exceptions multiply, and at some point the system becomes unmanageable. A new employee cannot change anything without risk of breaking everything — and simply adds new rules on top of the old ones.
This can be avoided. A systematic approach to routing design and maintenance is needed. This chapter contains not strict rules but principles and practices developed on real installations. They will help keep routing understandable, modifiable, and safe throughout the system lifecycle.
Design before configuring
Routing begins not with creating rules but with answering questions about how calls should be processed. Without this answer any configuration will be random.
Define call types: - Internal (user → user) - External incoming (PSTN → platform) - External outgoing (platform → PSTN) - Cross-domain (domain A → domain B) - Service (subscriber feature codes)
Define subscriber groups: - Regular users - Managers - Secretaries - External users (via provider) - Groups by department or function
Define call directions: - Internal - Local - Long-distance - International - To specific providers
Define how you will manage exceptions: - Which users have special rights? - Which numbers require special processing? - Which features should not be available to everyone?
The answers to these questions are the foundation for routing architecture. Without them configuration becomes guesswork.
Design from general to specific
Always start with a general solution, then add exceptions. This is a fundamental principle that keeps the system understandable.
Even exceptions can and should be generalized to routing principle level. Instead of prohibiting each specific user from connecting to a manager conversation monitor, one can formulate a general principle: prohibition of certain service features with respect to a certain subscriber group. One rule configured via featurerule or CoS/CoR covers different features and different subscribers at once.
Bad (many specific rules):
Rule 1: prohibit user 105 from monitoring manager 101 Rule 2: prohibit user 106 from monitoring manager 101 Rule 3: prohibit user 107 from monitoring manager 101 Rule 4: prohibit user 105 from barging into manager 101 Rule 5: prohibit user 106 from barging into manager 101 ...
Good (generalized principle):
featurerule: filter_from=10*, filter_to=101, types=monitor,prompt,mesh,barge, action=deny
Even better (group policy):
CosProfile: {code: "no_supervisor_access", feature_access: []}
CorProfile: {code: "supervisor"}
CorPolicy: {src_cos: "no_supervisor_access", dst_cor: "supervisor",
feature: "monitor,prompt,mesh,barge", action: deny}
Signal to act: If you see the same rule repeated 3+ times with minor changes — this is a signal that grouping or principle generalization is needed.
Create groups, not rules
Grouping is the main tool against rule proliferation. Instead of many similar rules, create one general rule and apply it to a group.
| If you see… | Do… |
|---|---|
Same access rights for many users |
CoS/CoR |
A large number of rules requiring CPU-intensive iteration |
route (reduces iteration) |
Many routes with similar logic but different numbers |
common masks in vectorrule, tables ( |
Many rules with prohibitions |
featurerule or CoS/CoR instead of denying vectorrules |
Many representation rules for different domains |
move representative to the root domain or destination domain |
Same number conversions |
provider_callerid with masks or service scripts for complex logic |
Same feature restrictions |
featurerule with masks |
Grouping example via next:
Problem: 7-, 9-, and 10-digit numbers from different domains must be sent to an external number, and one of the domains has a centralized provider.
Solution: first convert different variants to canonical form using modifiers in several rules with the next action, then send all canonicalized numbers to the provider with one rule.
Rule 1 (priority 100): tonumber=7* -> modtonumber=7495XXXXXXX, next Rule 2 (priority 100): tonumber=9* -> modtonumber=7495XXXXXXX, next Rule 3 (priority 200): tonumber=7495* -> action=external, toextaccount=central_provider
Add exceptions consciously
Exceptions are the main source of chaos in routing. Every exception must have a reason and be documented.
When adding an exception:
1. Record the reason in a comment (opts.comment or comment)
2. Check whether the exception can be described by a mask rather than enumeration
3. Check whether the exception can be added through grouping rather than a new rule
4. If the exception is temporary — specify the date when it can be removed
Good comment example:
"comment": "Temporary exception for sales department until transition to the new number plan. Remove after 01.06.2026"
Bad comment example:
"comment": "for Ivanov"
Review rules regularly
Review is not a one-time action but a regular process. Routing tends to get "polluted": rules that were once needed stop being used but remain in the system.
What to check during review: 1. Rules that never trigger (can be determined from logs or tracing) 2. Rules with the same priority and same actions 3. Rules created more than a year ago 4. Rules with the comment "temporary" 5. Rules duplicating each other’s functionality
Criteria for deletion: - The rule did not trigger for 3 months → delete (unless there is a good reason to keep it) - The rule duplicates a higher-priority one → delete - The rule was created "just in case" → delete - The rule has an expired validity period → delete
|
The current system version has no rule usage counters, so review relies on logs, tracing, and documentation. If necessary, external accounting can be kept — for example, a change journal indicating the creation date and purpose of each rule. |
Use tracing to understand
Tracing is a tool showing which route would be selected for a call with the specified parameters. It is available through the administrator interface and allows seeing the decision-making process without sending a real call.
What tracing shows: - Which vectors and rules were checked - Which filters matched or did not match - Which modifications would be applied - Which action would be selected
When to use tracing: - When configuring a new route — check that it triggers as expected - When diagnosing a problem — understand why the call goes the wrong way - During review — check that old rules still work
Tracing shows the decision-making flow — which entities participated, which filters matched, what was rejected. This is the main tool for understanding how routing actually works.
Summary principles
| Principle | Essence |
|---|---|
Design |
Before configuring, answer the questions: which calls, which groups, which directions |
General to specific |
Start with a general solution and add exceptions consciously. Generalize exceptions to principles |
Grouping |
Instead of enumeration — masks, tables, next, CoS/CoR, featurerule |
Comments |
Every non-trivial rule should have a comment with the reason |
Review |
Once a quarter check which rules are used and which are not |
Tracing |
Use for diagnostics and understanding |
Documentation |
Keep a change record — what, when, and why was added |
Pitfalls and common mistakes
Even with a correct understanding of routing theory, situations arise in practice that stump people. This chapter collects typical mistakes, non-obvious moments, and misconceptions administrators encounter when configuring routing. Understanding these pitfalls helps avoid problems before they manifest in a working system.
Where the initiator number in the outgoing INVITE comes from
This is one of the most common sources of confusion. The initiator number in the outgoing INVITE can come from different sources, and it is important to understand which one works in each specific case.
Sources of the initiator number:
-
From the initiator (original number) — the number with which the call entered the system. For an internal call — the account number of the calling subscriber. For an external call — the number specified by the provider in the From header.
-
Representation (representative) — applied on b2b for cross-domain or external calls. Replaces the initiator number with the one the called subscriber should see.
-
Normalization (provider_callerid) — applied on esg for external calls. Converts the internal number to the external number plan (and back).
What is not a source of the initiator number: - modfromnumber in vectorrule — this modifier changes the source number for subsequent routing steps (rule search, filter checks) but does not substitute it into the outgoing INVITE. This is a critical difference that is often missed.
Example:
Rule: modfromnumber = 7495101
This modifier affects which next rules are found (for example, by the new fromnumber), but the number 7495101 itself will not get into the outgoing INVITE unless representative or provider_callerid is applied.
Correct sequence for changing the number in the outgoing INVITE: 1. Routing with modfromnumber (determines direction) 2. If the call is external — provider_callerid on esg (substitutes the number into the external plan) 3. If the call is cross-domain — representative on b2b (substitutes the number for the other domain)
If rules have the same priority — order is random
When several vectors or rules have equal priority, their check order is random within one routing session. This is not an error or a bug — it is a conscious design decision.
What it gives: - Ability to distribute load between several routes without additional mechanisms - Natural fallback: if one route is unavailable, the next will be selected randomly
What must not be done: - Rely on check order to ensure deterministic behavior - Use equal priorities when strict application order matters
Recommendation: If order matters — assign different priorities. If order does not matter and distribution is needed — use equal priorities consciously.
Priority in external: if esg is unavailable — there will be fallback
For rules with the external action a special mechanism applies: even if the rule matched all filters but the provider account is unavailable (esg inactive, trunk limits exceeded, registration lost, ping not responding), routing does not stop but continues searching from the next priority rule.
This works only with fallback_next = true (default value).
Typical mistake: The administrator creates one rule for an external call and assumes that if the provider is unavailable the call will be rejected. In fact, if another suitable rule with lower priority exists, the call will go through it.
Example:
Rule 1 (priority 100): external, provider1 -- provider temporarily unavailable
Rule 2 (priority 200): external, provider2 -- works
Result: the call will go through provider2 and will not be rejected.
Recommendation: If a strict refusal is required when a specific provider is unavailable, either create a rule with denied for the unavailability case or use fallback_next = false.
CoS works only if set explicitly
Group policies CoS/CoR are an optional mechanism. By default everything is allowed.
Important consequence:
- Empty CoS = everything allowed
- Absence of CosProfile with a set cos = all directions for which call_type or non-zero restriction_level is set are prohibited
Typical mistake: The administrator sets cos = "managers" for a user but does not create a CosProfile with such code. As a result the user cannot call directions where call_type or restriction_level is set in rules, and the administrator searches for the cause for a long time.
Recommendation: When using CoS/CoR always create the corresponding profiles. If a profile is not needed — do not set cos at all.
representative is not always applied
Representation rules (representative) are applied only in certain scenarios:
-
On cross-domain calls (cross)
-
On external calls (external) — can supplement normalization rules
Where not applied: - On internal calls within one domain — the initiator number remains unchanged
Typical mistake: The administrator configures representative expecting it to change the initiator number on an internal call. This does not work.
Recommendation: To change the initiator number on internal calls use other mechanisms (for example, display setting on the device itself). For cross-domain and external calls — representative.
Redirection: server vs client
There are two types of redirection in the system, and it is important to distinguish them.
Server redirection (redirectrule): - Configured in the platform - Applied by the server before sending INVITE to the device - Supports various conditions: absolute, no registration, call result
Client redirection (on the device): - Configured on the user device itself (for example, through the phone interface) - Applied after receiving SIP 301 or 302 response to the sent INVITE - The server does not participate in the decision, only relays the response
Important difference: In client redirection the server does not check the correctness of the destination number but simply sends INVITE to the address specified in the response.
Typical mistake: The administrator tries to restrict redirection numbers via redirectrule, but the user configured redirection on the device, and the restriction does not work.
Recommendation: To restrict numbers to which calls can be redirected, use the opts.redirect_allowed_masks setting in the sipuser account. It works for both redirection types.
On transfers and redirections the transferring subscriber becomes the routing initiator
This is an important and non-obvious point that often leads to misunderstanding of routing logic.
On transfer (REFER): When user A transfers a call to user B, routing for the new call (A → B) is performed on behalf of user A, not on behalf of the original call initiator.
On redirection: Similarly, when a call is redirected from number A to number B, routing is performed on behalf of the redirection owner (subscriber A).
Why this matters: - Access rights are checked for the subscriber initiating the transfer/redirection - CoS/CoR are applied on behalf of the transferring subscriber - Outgoing call restrictions apply to the transferring party, not the original initiator
Example:
User A (101) calls user B (102).
B transfers the call to user C (103).
The new call (from B to C) passes routing on behalf of B:
- B permissions to call C are checked
- CoS/CoR restrictions for B are applied
- Outgoing call settings for B are used
Typical mistake: The administrator expects that on transfer the original initiator (A) permissions are checked and is surprised why the transfer does not work as expected.
Recommendation: When designing routing, consider that transfers and redirections are always performed on behalf of the subscriber performing the transfer or redirection. This affects permission checks, CoS/CoR, and restrictions.
Normalization is not always mandatory
Normalization rules (provider_callerid) are not a mandatory element. They are needed only when the internal number plan does not match the external one.
When normalization is mandatory: - Internal number (101) must be converted to external (74957654321) - The provider requires a specific number substitution - A number "carousel" must be organized
When normalization is not needed: - The internal number plan already matches the external one - Conversion is performed on the provider side
Typical mistake: The administrator creates normalization rules "just in case" even when they are not needed, which complicates the system and increases processing time.
Recommendation: Use provider_callerid only where truly necessary. If calls pass without normalization — do not add it.
3xx response from the device is processed by the server
When the called device returns a SIP 3xx response (redirection), the server does not ignore it or pass it to the initiator "as is". It processes this response:
-
Extracts the destination number from the Contact header
-
Checks whether this number is allowed for redirection
-
Forms a new INVITE to the specified number
Restrictions on redirection numbers:
Allowed redirection number configuration can be set at two levels:
-
Domain level — the
redirect_allowed_masksparameter in domain settings. Sets a common mask list for all domain subscribers. -
Subscriber level — the
opts.redirect_allowed_masksparameter in the sipuser account. Allows setting individual restrictions for a specific user.
Application rule:
- If a mask list is set in the subscriber account (non-empty and not "/default"), only those are used.
- If the subscriber account specifies "/default", the masks set at domain level are applied.
- If nothing is set in the subscriber account (field absent or empty), there are no restrictions for this subscriber (all numbers allowed).
Example:
Domain settings: redirect_allowed_masks = ["1XX", "2XX"]
Subscriber A: opts.redirect_allowed_masks = ["10X"] -> only 10X numbers allowed
Subscriber B: opts.redirect_allowed_masks = "/default" -> 1XX and 2XX allowed (from domain)
Subscriber C: opts.redirect_allowed_masks = [] -> all numbers allowed
This allows controlling where calls can be redirected even if redirection is configured on the device.
Typical mistake: The administrator does not configure redirect_allowed_masks and is surprised that device redirection does not work.
Recommendation: Configure redirect_allowed_masks at domain level for basic restrictions and use /default in accounts to inherit these restrictions. Apply individual settings only for exceptions.
IVR can initiate calls with any number
IVR scripts can initiate calls on behalf of any subscriber. This is a powerful mechanism but requires caution.
How it works: - In an IVR script an arbitrary number and name can be specified for the From field - Such a call passes routing on a common basis
Risks: - If the script is misconfigured, it can call on behalf of a non-existent subscriber - This can lead to confusion in statistics and logs
Recommendation: Control which numbers IVR can use to initiate calls. Document such scripts.
Summary of typical mistakes
| Mistake | Consequence | Solution |
|---|---|---|
Expecting modfromnumber to change the number in INVITE |
The number in INVITE does not change |
Use representative (for cross-domain) or provider_callerid (for external) |
Equal priorities when order matters |
Unpredictable behavior |
Assign different priorities |
Expecting refusal when provider is unavailable |
The call goes by another route |
Use fallback_next=false or denied |
Setting cos without creating CosProfile |
Unexpected prohibitions |
Always create profiles or do not set cos |
Expecting representative for internal calls |
Does not work |
Use other mechanisms |
Expecting redirectrule to work for client redirection |
Does not work |
Use redirect_allowed_masks |
Ignoring that on transfer the transferring party permissions are checked |
Unexpected refusals on transfer |
Consider during design |
Creating provider_callerid "just in case" |
System complication |
Use only when necessary |
Absence of redirect_allowed_masks |
Device redirection does not work |
Configure for all accounts or at domain level |
IVR with arbitrary number without control |
Confusion in statistics |
Document and control |