Call routing

Call routing is a route management system that lets you decide how to handle incoming calls to your Infobip Direct Inward Dialing (DID) numbers, which helps you achieve strong resiliency.

With call routing, you can define as many routes as required, each with up to 10 entries. Entries in a route can be of the following types:

Entry Type	Definition
SIP	Any predefined SIP trunk you have already created on your account
PHONE	Any fixed or mobile phone number that can be reached over Infobip's global network
WEBRTC	A user identity from your WebRTC application
WEBSOCKET	A Websocket media streaming configuration
WHATSAPP	The MSISDN (phone number) of the WhatsApp end user to be called with WhatsApp Business Calling
VIBER	The MSISDN (phone number) of the Viber end user to be called with Viber Business Calls
URL	A webhook exposed by your backend application

When a call reaches your DID number, which has been configured to use a specific route, each entry in that route is evaluated in this sequence:

• if a defined entry can be successfully reached, the inbound call is connected to that destination
• if a defined entry cannot be reached, the next entry in the route list is evaluated

The following schema diagram shows how call routing enables your calls to be directed to the specified destination.

Create routes

You can create routes either from the Infobip web interface with Call Routing in the voice channel application or by using the API.

Priorities and Weights

Each entry or destination on a route must be assigned a priority, ranging from 1 to 100 (1 being the highest priority). You are free to set your priorities as required and meaningful for your implementation. Each destination in a route can have a priority value ranging from 1 to 100. When routes are executed, entries are evaluated according to their priority.

Entries in a route that share the same priority must be assigned a weight. The weight is used to determine the share of the load to each route entry with the same priority.

Priorities basically define the hunt sequence.

Destinations specifics

For each destination type in a route, you can define optional elements that produce different results. The following table shows the parameter settings that affect the outcomes.

Destination type	Parameter	Effect
SIP	username	When defined, the original destination of the call (to) is overwritten with this value when the call is triggered on the SIP trunk. When not defined, the original destination of the call is not overwritten and will be preserved when the call is triggered on the SIP trunk
	timeOut	Optionally, define the time to wait for the call to be established when the call is triggered on the SIP trunk. The timeOut may trigger a route advance (that is, go to the next entry in the destination list) if it is the first reason to fail the route, next to other internal criteria, such as SIP trunk availability.
PHONE	phoneNumber	A phone number in the E.164 format. When not specified, this value defaults to the to value used in the inbound call.
	timeOut	Optionally, define the time we should wait for the call to be established when this destination is triggered. The timeOut may trigger a route advance (that is, go to the next entry in the destination list) if it is the first reason to fail the route, next to other internal criteria, such as the destination phone operator's availability.
WEBRTC	identity	The identity of the webRTC user this call must be forwarded to. When not specified, this value defaults to the to value used in the inbound call.
	displayName	Optionally, overwrite the name of the webRTC user to be displayed to the connected webRTC party.
WEBSOCKET	endpoint configuration	A previously defined Websocket media streaming configuration.
WHATSAPP	phoneNumber	A phone number in the E.164 format. When not specified, this value defaults to the to value used in the inbound call.
	from	The WhatsApp sender that must be used for this outbound WhatsApp Business Calling call.
VIBER	phoneNumber	A phone number in the E.164 format. When not specified, this value defaults to the to value used in the inbound call.
	from	The number that should be used as callerId for this outbound Viber call. If specified, it should reflect your Viber Business Call number.
URL	url	Your exposed URL must always be specified.
	securityConfig	Optionally, the security method to authenticate towards your exposed webhook.

Enable recording

For each entry in a route, you may choose to record the audio of the resulting conversation.

Recordings can be either:

• composed (one single audio file with all participants' audio mixed together), or
• non-composed (one audio file per participant in the call)

If you don't wish to use our cloud storage for recordings and opt to transfer them to your SFTP server, you may specify an optional text string in filePrefix. The text string is used in the zip file names that are pushed to your server.

Allowed Time Window

The Allowed Time Window allows you to define specific time windows during which a route destination is eligible for call routing. It offers granular control over call flows, ensuring that calls are routed based on both the day of the week and specific hour periods. Example use cases for this feature could be:

• Business Hour Routing: Ensure calls are routed to office numbers only during business hours and redirected to voicemail or alternate destinations after hours
• Special Event Handling: Route calls to special event hotlines only during the event times
• Global Operations: Manage call routing for global offices in different time zones using UTC time to maintain uniformity

For each destination in a route, administrators can configure one or more Allowed Time Windows. These time windows determine when the destination is valid for routing calls. Multiple time windows can be assigned to a single destination. For example, a destination can be configured to be available:

• From Mondays to Fridays, 8 AM to 5 PM
• On Fridays, 8 AM to 6 PM
• On Saturdays, 9 AM to 1 PM

When multiple time windows are defined for a single destination, the system automatically checks for coherence among these windows to avoid conflicts and overlaps.

When a call triggers a route execution, the system evaluates the current time against the defined Allowed Time Windows for each destination in the route. If the current time falls outside the defined Allowed Time Windows for a destination, that destination is skipped, and the call is routed to the next eligible destination.

Assign a route to a DID number

You can assign routes to Infobip DID numbers using either the Infobip web interface or over API.

Assign a route to a DID number in the web interface

Log in to your account, and go to Channels and Numbers > Voice and WebRTC.

Click on any of your acquired voice numbers and a new tab opens the voice configuration settings for that number. Edit the inbound configuration as follows:

• Select the action type Forward to Call Routing and optionally select the route from the drop-down list to assign to this number.
• If you specify a route with the action, this route will systematically be executed for each incoming call to the voice number.
• If you don't specify a route with the action, you need to ensure you have at least one route that includes matching filter criteria (see Matching routes with filtering criteria). Note that if you have multiple routes with matching criteria, the first route found with such matching criteria will be used.

Assign a route to a DID number over API

To set up a routing action for inbound calls over API, use the Number management (opens in a new tab) methods.

The typical flow is as follows:

• Retrieve the numberKey of your purchased number. You can use the List purchase numbers (opens in a new tab) method to retrieve this reference.
• Create a voice setup (opens in a new tab), specifying the following:
  • retrieved numberKey
  • action type FORWARD_TO_CALL_ROUTING
  • routeId of the route you want to assign to this number

Match routes with filtering criteria

Filters allow for assigned routes to become even more granular by only evaluating calls matching with these criterias. Filter criterias are optionally defined when creating a route.

Different types of incoming traffic can be managed using specific filters. When you define multiple filters on the same route, they are linked by a logical OR operation, meaning the route will be triggered if any one of the filters' conditions are met.

PHONE filters

Filters can be designated using either a from or to number, or both. If both from and to numbers are specified, they are combined using a logical AND operation.

Values specified for both from and to numbers can be either fully defined numbers, either a regular expression. For instance:

• A route with a PHONE filter with 13124567890 as from value will only trigger if a call is received from this exact number
• A route with a PHONE filter with ^1(312|773|872)\d{5}90$ as from value will only trigger for any inbound call coming from a number in the USA having a Chicago prefix and ending with the digits 90

When using filters in call routing, you no longer need to assign a specific route to your Infobip DID. Select Forward to Call Routing on the number, and the system evaluates all route definitions. The first route with a matching filter is triggered. For example, if you have the Infobip number 13124567890, and you want calls from Chicago area codes (312, 773, and 872) to be routed to one destination, and calls from Naperville’s area code (630) routed to another destination:

1. Create a route with a From filter: ^1(312|773|872).* and set your desired destination(s) in the route.
2. Create a second route with a From filter: ^1(630).* and set your desired destination(s) in the route.
3. Assign Forward to Call Routing to 13124567890 without specifying any route.

When an inbound call arrives, call routing automatically applies the first route filter that matches the caller’s number.

The following table illustrates some examples of PHONE filter definitions using regular expressions:

Objective	Regular expression	Regular expression explained
I want the route to be triggered for any call coming from UK numbers	Set the following regex on the from number: ^44\d10$	^ asserts position at start of a line 44 matches the characters 44 literally \d matches a digit (equivalent to [0-9]) 10 matches the previous token exactly 10 times $ asserts position at the end of a line
I want this route to be triggered for incoming calls coming from callers in Chicago	Set the following regex on the from number: ^1(312|773|872)\d7$	^ asserts position at start of a line 1 matches the character 1 literally (312|773|872) is a capturing group matching one of the area codes: 312, 773, or 872 \d matches a digit (equivalent to [0-9]) 7 matches the previous token exactly 7 times $ asserts position at the end of a line
I want this route to be triggered for an inbound call reaching my Infobip USA toll-free numbers	Set the following regex on the to number: ^1(800|888|877|866|855|844|833)\d{7}$	Uses the same structure explanation as above.
I want this route to be triggered for any inbound call that has the sequence of number "1234" in it, at any place	Set the following regex on the "from" number: ^\d1234\d$	^ asserts position at start of a line \d*: Matches any number of digits (including zero digits) before the sequence "1234" 1234: Matches the specific sequence "1234" \d*: Matches any number of digits (including zero digits) after the sequence "1234" $: Anchors the match to the end of the string

SIP filters

This filter type enables route activation based on incoming Session Initiation Protocol (SIP) traffic. SIP filters can be defined based on:

• reference of the trunk from which traffic is coming: you want all traffic coming from a designated trunk to trigger this exact route
• value of the from field
• value of the to field
• value of designated custom headers - note that the header name must be fully specified, whereas the header value may include regular expressions

The following table depicts some examples of SIP filters using regular expressions:

Objective	Regular expression	Regular expression explained
To / From filter criterias	Similar to phone filter examples above - Note that some of these values could be non-numerical, such as a specific "username", such as a string like oliverjones
Header value - I want to activate this route if a header X-IB-AGENTCONTEXT includes "sales"	Set header value filter to .*sales.*	.* matches any number of any characters (including none) before the substring "sales", sales: matches the exact substring "sales", .* matches any number of any characters (including none) after the substring "sales".
Header value - I want to activate this route if a header X-IB-WHATEVER starts with "xyz" and ends with "001"	Set the header value to ^xyz.*001$	^: Anchors the match to the start of the string. xyz: Matches the exact substring "xyz" at the beginning. .*: Matches any number of any characters (including none) in between. 001: Matches the exact substring "001" at the end. $: Anchors the match to the end of the string.

WEBRTC filters

The WEBRTC filters trigger route execution for traffic originating from Web Real-Time Communication (WebRTC). In your WebRTC client application, make an applicationCall towards the CALL_ROUTING application. You can optionally set a value (full or regular expression) for the from parameter (identity if using Call Routing APIs), which means the route will only be triggered for calls from that specific WebRTC identity.

Route execution

Destinations in a route are tried sequentially, based on their priorities and weights, until a destination can be successfully connected to or until the end of the destination list is reached.

The route execution advances from one destination to the next one based on error conditions and timeouts.

SIP trunk destinations

The following table summarizes how route advance is handled for both UDP and TLS SIP trunk.

A SIP trunk destination is immediately skipped if it is in Administrative Downstatus or considered to be out of service (the trunk was configured to use SIP OPTIONS and the SIP OPTIONS polling determined that the trunk is out of service).

Transport type	End user state	SIP OPTIONS enabled	Re-routing delay	Duration to consider the trunk out of service
UDP	SIP trunk reachable	False	N/A	N/A
UDP	SIP trunk not reachable	False	4s every call	Never
UDP	SIP trunk not reachable	True	4s every call	Minimum : 32s (SIP timer)Maximum : 32s + SIP OPTIONS ping-interval (60s)
UDP	SIP trunk not reachable	True	0s	N/A
TLS	SIP trunk reachable	False	N/A	N/A
TLS	SIP trunk not reachable	False	4s every call	Never
TLS	SIP trunk not reachable	True	4s every call	Minimum : 28s (TCP timer)Maximum : 28s + SA configuration for ping-interval (30s)
TLS	SIP trunk not reachable	True	0s	N/A

Destination timeouts

When setting destinations to be a SIP trunk, a PHONE number, or a WebRTC user, you can define a time out on that destination. This parameter comes in to action only for destinations that can be reached, and therefore must be understood as an "answering timeout" rather than a "connection timeout".

As an example, consider a SIP trunk destination with a timeout set to 15 seconds:

• if the trunk cannot be reached (see "SIP trunk destinations" section above), the timeout will have no effect and route execution will advance to the next destination based on priorities and weights
• if the trunk can be reached and answers to our SIP INVITE then the route execution will advance after 15 seconds if the call is not being answered.

Call status

In the high-level schema diagram above, call logs are created for each call leg that is part of the scenario. In the schema, this means:

• a call log for the incoming call from the external phone user to your Infobip DID number
• a call log for the first destination entry (to "SIP Trunk A"), unless this trunk is set to be administratively disabled. In this example, this entry will reflect a failed call tentative.
• a call log for the second destination entry (to "SIP Trunk B"), unless this trunk is set to be administratively disabled. In this example, this entry will reflect a failed call tentative.
• a call log for the third destination entry (to "SIP Trunk C"), unless this trunk is set to be administratively disabled. In this example, this entry will reflect a failed call tentative.
• a call log for the final destination entry (to external phone). In this example, this entry will reflect a successful answered call.

Successfully connected call leg logs include a correlation reference, dialogId, which matches the connected call legs that participated in the same communication.

Retrieving call logs

Log in (opens in a new tab) to your account, and go to Analyze> L (opens in a new tab)ogs (opens in a new tab).

You can filter logs by:

• date range
• Origin (From) and Destination (To)
• SIP Trunk name

Retrieving detailed reports

Log in (opens in a new tab) to your account, and go to Analyze> Reports (opens in a new tab) .

Infobip recommends that you request a new Detailed report, which includes all details about your calls, including direction, duration and billed duration, cost for the calls, and so on. Detailed reports also include the SIP Trunk name, SIP Trunk Id, correlation identifier, and dialogId.

For more details about using Infobip Reports, see Analyze Reports.

Accessing Call Routing recordings

Recordings performed by Call Routing can be accessed either via API or on the Infobip web interface.

To find and download your Call Routing recordings from the Infobip web interface:

1. Go to the recording tab under the Voice channel application.
2. Select Call Routing on the sub-navigation bar.
3. When expanding a particular recording entry, you see the list of related files, whether composed or non-composed. You can download the files that are stored on our cloud storage, as well as their related metadata json file.

You can also search Call Routing recordings by route or participant type or identity (such as username, phone number).