Call routing

You can manage how your inbound calls are directed with Call Routing. Call Routing uses predefined routes and configurable failover strategies to ensure reliability, flexibility, and an optimized caller experience.

Call Routing operates with predefined routes, where each route can include up to 10 destinations that are attempted in a sequence until a successful call connection is made.

Call Routing supports two methods for selecting which route to execute:

1. Static routing: A fixed route is assigned to each inbound number or source. Every call received on that number consistently follows the same predefined sequence of destinations.
2. Dynamic routing: Routes are determined based on configurable filters, such as caller origin or other call attributes. When a call is received, the system evaluates the filters and selects the route that best matches the defined criteria.

Call routing can be triggered on inbound traffic from:

• Phone
• SIP trunk
• WebRTC
• WhatsApp Business Calling
• Viber Business Calls

Destinations in routes 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, supporting dynamic routing scenarios

Create routes

You can create routes from the Infobip web interface with Call Routing in the Voice channel application or by using the Call Routing API (opens in a new tab).

Route definitions include:

• One to 10 destinations, with their respective priority, and optional weight and destination parameters.
• (Optional) Inbound traffic filter criteria.

When a route is created, it is assigned a route priority. The first route created is given a priority of 1, and each subsequent route receives a priority that increases by 1. You can change route priorities through the Call Routing user interface or by using call routing APIs.

For more details on filter criteria and route priorities, refer to the Filter-based route selection section.

Destination priorities and weights

Each entry or destination on a route must be assigned a priority, with values ranging from 1 (highest) to 100 (lowest). You can set priorities in a way that best fits your implementation. 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.

• Weight is used to determine the share of the load to each route entry with the same priority.

• Priority is used to 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 preserved when the call is triggered on the SIP trunk.
	timeOut	(Optional) 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 or 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	(Optional) Define the time to wait for the call to be established when this destination is triggered. The timeOut may trigger a route advance, for example, 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	(Optional) 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	(Optional) 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 want to opt your recordings to your own SFTP server instead of our cloud storage, you can 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

Use the Allowed Time Window to control when a route destination is eligible for call routing. This feature gives you precise 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 are:

• 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.

Inbound traffic route selection

Call Routing determines which route applies to inbound traffic in two ways:

1. Static Direct Inward Dialing (DID) route selection: Call Routing always applies the same designated route for incoming traffic on a designated Infobip DID number.
2. Filter-based route selection: Call Routing selects the route applied to inbound traffic based on filter criteria.

Static DID route selection

A route is statically assigned to an Infobip DID route. Every single call that reaches this DID will always result in the selection of the same designated route.

Supported DID or number types are:

• Infobip VLN (opens in a new tab) or TFN that are voice-enabled.
• WhatsApp senders with the WhatsApp Business Calling capability enabled.
• Viber voice numbers.

This configuration can be done either on the web interface (opens in a new tab) or through the voice number setup API (opens in a new tab).

To setup up DID using the web interface (opens in a new tab):

1. Log in to your account.
2. Go to Channels and Numbers > Channels > Voice and WebRTC.
3. 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.
• Choose the route from the drop-down list to assign to this number.

To set up the routing action for inbound calls over API, use the following API methods:

• Retrieve the numberKey of your purchased number. You can use the List resource (opens in a new tab) method to retrieve this reference.

• Create a voice setup, specifying:
  • the retrieved numberKey.
  • the action type FORWARD_TO_CALL_ROUTING.
  • the routeId of the route you want to assign to this number.

Filter-based route selection

Filters allow for assigned routes to become even more granular by only evaluating calls matching with these criteria. Filter criteria 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 will be combined using a logical AND operation.

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

• A route with a PHONE filter with 13124567890 as the 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 the 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. You can assign the Forward to Call Routing action on the number, and the system will evaluate all route definitions. The first route with a matching filter is triggered.

For example, suppose you have the Infobip number 13124567890. You want calls from Chicago area codes (312, 773, and 872) routed to one destination, and calls from Naperville’s area code (630) routed to another destination. Here’s how:

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 a few 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\d{10}$	^: Asserts position at start of a line. 44: Matches the characters 44 literally. \d: Matches a digit (equivalent to [0-9]). $: 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)\d{7}$	^: Asserts position at start of a line. 1: Matches the character 1 literally. 1st Capturing Group (312|773|872): 1st Alternative 312: matches 312 literally. 2nd Alternative 773: matches 773 literally. 3rd Alternative 872: matches 872 literally. \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: ^\d*1234\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:

• The reference of the trunk from which traffic is coming: You want all traffic coming from a designated trunk to trigger this exact route. If no specific SIP trunk is designated, the filter will be activated for inbound SIP traffic coming from any of your active SIP trunks.
• The value of the from field.
• The value of the to field.
• The value of designated custom headers.

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

Regular expression	Objective	Regular expression explained
To / From filter criteria	Similar to phone filter examples above. NOTE Some of these values are non-numerical, such as a specific username, for example, 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

This filter triggers route execution for traffic originating from Web Real-Time Communication (WebRTC). In your WebRTC client application, an applicationCall should be made 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 Down status 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 not 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), the timeout will have no effect and route execution and 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.

Rerouting with SIP REFER

Call Routing supports dynamic rerouting of active connected calls using the SIP REFER method. This feature is useful when you need to transfer a call to a new destination without disconnecting the original caller.

The typical flow is as follows:

• An inbound call is received on your Infobip number (Party A), triggering a predefined route in Call Routing.
• The route bridges the inbound call to an outbound call via a SIP trunk specified in the route’s destination list (Party B).
• At any point during the call, instead of ending the session, the remote SIP user agent (Party B) can initiate a SIP REFER request to Infobip, specifying a new destination (Party C).
• Call Routing maintains the original inbound call and seamlessly bridges it to the newly requested destination (Party C), ensuring uninterrupted communication.

This rerouting capability allows for flexible call handling scenarios, such as transferring callers to different departments, agents, or external numbers, all while keeping the original call leg active.

When Call Routing receives a SIP REFER message, it will only consider routes that have a filter with the criteria type set to SIP. The To value specified in this filter should match the new destination requested in the SIP REFER.

(Optional) You may set specific SIP trunk IDs in your filter definition to further refine your execution logic.

Retrieving call logs

Call logs are created for every call leg processed by Call Routing, including:

• The inbound call leg.
• Each outbound call leg that Call Routing attempts to bridge to, except for SIP trunk destinations that are in a disabled state.

Log entries for successfully bridged call legs can be matched together by a shared identical correlation identifier.

Retrieving detailed reports

To retrieve detailed Call Routing reports, follow these steps:

1. Log in (opens in a new tab) to your account.
2. 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, and cost for the calls. Detailed reports also include the SIP trunk name, SIP trunk ID, correlation identifier, and dialogId.

Once downloaded, filter the Feature column on CALL_ROUTING.

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 (opens in a new tab).

To find and download your Call Routing recordings from the Infobip web interface (opens in a new tab):

1. Go to the recording tab under the Voice channel application.
2. Select Call Routing on the sub-navigation bar.
3. Expand a recording entry and review the list of related files (composed or non-composed).
4. Download the available files from our cloud storage as well as their related metadata JSON file.

Call Routing recordings can be search by route or participant type or identity (such as username and phone number).