Routing rules

Routing rules allow developers to launch one or several scenarios, and make and receive calls. When a call arrives to the platform or you make a call via an SDK client, routing rules choose what scenario(s) to execute. Launching a routing rule executes all the attached scenarios.

In this article, you will learn how to create routing rules, attach scenarios, set up patterns for incoming calls, and execute routing rules and therefore, scenarios.

In your application, navigate to the Routing tab and either click Create in the center of the screen or New rule in the upper right corner:

This opens a New rule editor, where you can specify the rule name, properties, and attach one or several scenarios:

Enable the Video conference switch if you plan to use the scenario for video conferencing. Without this parameter, all video conferences fail with an error.

The Pattern field checks if the call's destination (the dialed number or username specified in the e.destination property of the incoming call) matches any rule's pattern. If the call's destination matches the pattern, the routing rule executes the attached scenario(s). If the call's destination does not match the pattern, the attached scenario(s) does not execute and the call passes to the next routing rule.

The application checks the routing rules from top to bottom. The higher routing rules have higher priority. When the call's destination matches one of the rules, the rule executes and the application ignores further rules, so only one rule executes.

The Pattern field uses regular expressions to create masks for phone numbers or usernames. There are the most common expressions:

You can read more of how to build a regular expression on Wikipedia.

The Available scenarios dropdown list allows you to attach one or more scenarios to execute when the rule is launched.

You can attach multiple scenarios to one rule. In this case, the rule executes all the attached scenarios one by one in one context, allowing code reuse. This allows you to write all the functions in one scenario, and use them in another scenario.

You can see all the attached scenarios in the Assigned scenarios field.

After you specify all the settings, click the Create rule button to create a rule.

To check if a certain phone number or a username matches any rule's pattern, click Testing tools at the top right corner, and choose Rule checker.

Enter a phone number or username and click Test. If the entered data matches any rule, the rule and its pattern appear below.

Additionally, you can use the integrated Softphone to make calls to your applications. To use it, click Testing tools at the top right corner, and choose Softphone. To make calls via the softphone, you need to authorize with the username and password.

There are several ways of launching a scenario.

Q: Can I execute a scenario without a routing rule?
A: No. Routing rules are necessary to execute incoming and outgoing scenarios.

Q: Can I attach more than one scenario to a routing rule?
A: Yes. If you attach more than one scenario to a routing rule, they execute in one context, allowing code reuse. This allows developers to write all the functions in one scenario, and use them in another scenario.

Q: Do patterns work for outgoing calls?
A: No. The patterns work for incoming calls only. For outgoing calls, it is enough to create a rule and attach a scenario.

Q: Do patterns work for SIP calls?
A: Yes, patterns also work for SIP usernames. You can create a special prefix or format for SIP usernames and route them to a specific scenario.

Q: Does a pattern check the caller ID or the destination number?
A: The destination number. The rule does not check the matching of your caller ID.

Q: What if a phone number matches several rule patterns?
A: Only the first rule will be executed. The application checks the number against all the rules from top to bottom, and when a suitable rule is found, it stops checking the number.

Q: What if I do not enable the "Video conference" switch in the routing rule settings?
A: All attempts to start a video conference with this rule will fail with an error.

Q: What if I enable the "Video conference" switch in the routing rule settings but will make only voice calls?
A: The voice calls will work without errors, but they will be billed as video conferences.

Q: How can I pass custom data to the scenario?
A: If you start a scenario via Management API, pass the data to the script_custom_data parameter. If you start the scenario manually via the control panel, pass the data to the "Custom data" window.

Q: How do I set up two different rules for incoming and outgoing calls?
A: You can create a rule for incoming calls with the .* pattern (accepts all calls) and place it above the rule for outgoing calls. As the incoming calls rule will intercept all the calls, you can launch the rules below the incoming calls rule only manually, for example with Management API.

Q: How do I prioritize the routing rules?
A: Reorder them. The highest rule has the highest priority.