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
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
SIP	`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`	When forwarding incoming calls to your Infobip DID number(s) to a SIP trunk, the destination `phoneNumber` should always be defined. In later evolutions of Call Routing, some scenarios may result in this parameter not being mandatory anymore.
PHONE	`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. This parameter is mandatory.
WEBRTC	`displayName`	Optionally, overwrite the name of the webRTC user to be displayed to the connected webRTC party.
URL	`url`	Your exposed URL must always be specified.
URL	`securityConfig`	Optionally, the security method to authenticate towards your exposed webhook.

Enable recording

For each entry in a route, you 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

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 criterias

Filters allow 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:

PHONE: 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. These filters can apply to full numbers or number prefixes. For example, a filter set for prefixes starting with 331 will activate the route for any call originating from such numbers. It is important to configure the FORWARD_TO_CALL_ROUTING action on your voice numbers for PHONE type filters, ensuring no specific route is mandated for execution.
SIP: This filter type enables route activation based on incoming Session Initiation Protocol (SIP) traffic. You can set it to respond to traffic from a specific SIP trunk or from all your SIP trunks. Additional optional filter parameters, like the destination username or custom headers, can also be set. For custom headers, the header name must be fully specified, whereas the header value may include regular expressions.
WEBRTC: 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. There's also an option to set an identity parameter, which means the route will only be triggered for calls from that specific WebRTC identity.

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.

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

You can filter logs by:

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

Retrieving detailed reports

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.

SIP trunking Cloud contact center