Advanced Call Routing

Advanced Call Routing (ACR) offers greater flexibility and control over how you route calls to Bandwidth. Whether you want to simply forward a call to another person or set up multiple failovers to IPs and SIP URIs, ACR is designed to be configured in a way that meets all your call routing needs. Before walking through the steps on how you can use this feature in the Bandwidth Dashboard, let’s go over some key terms. 

Key terminology

What is a route?

A route defines how we route the calls to you. Each route has to have at least one endpoint to which the phone call can be directed. You can add a route on a Location or on an individual number. 

What is an endpoint?

An endpoint is a construct that represents something a phone call can be directed to. You can think of it as an address that tells a phone call where to go. Currently, there are four types of endpoints that can be used for ACR:

• Route to Domain Name – an endpoint that routes to a fully qualified domain name (FQDN). This FQDN can be an SRV Record or A-Record. 
• Route to IP & Port – an endpoint that routes to an IP address and port. Please note that if you don’t add a port, it will automatically default to 5060
• Route to SIP URI – an endpoint that routes to a SIP URI
• Forward to Phone Number – an endpoint that routes to a different phone number

What is a distribution?

Distribution determines the approximate percentage of calls directed to each endpoint on a route. You can adjust these percentages at any time but please note that the total for all endpoints on a route must add up to 100. 

How do I add a route on a Location?

If you want your ACR settings to apply to all numbers on a Location, you need to add the route and endpoint at the Location level:

1. Log into the Bandwidth Dashboard.
2. In the top navigation bar, select Account and click Locations.
3. Select the Location from the list on the left-hand side and click Voice.
4. Navigate to the Routing section located under Origination Settings and click Create Primary Route. 

Note: The Create Primary Route button won’t display if you already have a primary route. To create a second or subsequent route, you’ll need to click Add Route.

5. In the Action field, select the endpoint type and enter the endpoint.

6. Click Save. You should now see the route and its endpoint.  

How do I add a route on a number?

If you want your ACR settings to only apply to a particular number, you need to add the route and endpoint on that number’s Phone Number Details page:

1. Log into the Bandwidth Dashboard.
2. Find the phone number you want to set up ACR on. You can either locate it using the Search Telephone Numbers section on the homepage or select Numbers and then click My Numbers in the top navigation bar to search it by its Sub-account and Location.
3. Once you click on the number and land on its Phone Number Details page, scroll down to the Routing section. 
4. Click Create Primary Route.

5. In the Action field, select the endpoint type and enter the endpoint. 

6. Click Save. You should now see the route and its endpoint.  

Important: Routes set at the number level always take priority over routes set at the Location level. For example, if the primary route on the Phone Number Details page is set to route to the domain name “test.test.com” but the primary route on the Locations page (belonging to the Location of that number) is set to route to the domain name “example.example.com”, all calls to that number will be routed to “test.test.com”. If you’d like the number and the Location settings to match, please remove all routes at the number level or check that each number level route setting matches with its respective location level route setting. 

Can I have more than one route and endpoint?

Yes! You can have up to 10 routes with up to 100 endpoints across them. Once you add your primary route, you can click Add Route to add an additional one.  If you want to add an additional endpoint, click Add Endpoint next to the route you want to add it to. 

Each endpoint on a route is assigned a distribution percentage that determines how calls are distributed. For example, in the image below each endpoint on the primary route is at 50 percent, meaning that half the time the call will be first routed to “test.test.com” and the other half the time it will be first routed to “1112223333”. If the call is first routed to “test.test.com” and it fails, ACR will attempt to route it to “1112223333”. If it also fails, ACR will move on to the second route and try to complete the call via “example.example.com”. If that option fails as well, the call won’t complete. 

Note: You can adjust distribution percentages at any time but please keep in mind that the total percentage for all endpoints on a route must add up to 100.

Example call flows

Now that we’ve covered the basics, let’s go over a few examples of how to set up actual call flows.

Call forwarding

Call forwarding is used to route a call from one phone number to something else, such as a domain name, IP, SIP URI, or another number. While it’s a simple concept, ACR lets you use it in powerful ways beyond the basic setup. Let’s say you want to forward an existing number to 1112223333. To do that, you need to complete the following steps:

1. On the Locations page (if you want to forward from all numbers on the Location) or the Phone Number Details page (if you only want to forward from a particular number), click Create Primary Route.
2. In the Action field, select Forward To Phone Number.
3. In the Phone Number field, enter 1112223333 and click Save. 

Note: Forwarding to international phone numbers is not supported. Please enter only 10-digit NANPA phone numbers. 

4. Now, all phone calls to all numbers on the Location (if you added this route on the Locations page) or to a particular number (if you added this route on the Phone Number Details page) will be forwarded to 1112223333. 

Things to think about

What else could be done with this? For instance, we could add more routes to load balance our calls across different numbers. Or we could add ten failovers if the call doesn’t work for the first number. There are lots of possibilities and we encourage you to try them out! 

Final Destination and Call Forwarding 

Final destination comes into play when you want to specify the final fallback option to use when all previous failovers fail. Expanding on the previous example, let’s say you want to add a second route so that whenever calls can't be forwarded to 1112223333, they can be directed to 9998887777 instead. To do that, you need to complete the following steps:

1. Click Add Route.
2. In the Action field, select Forward To Phone Number.
3. In the Phone Number field, enter 9998887777 and click Save. 

4. Now, whenever the call can’t be forwarded to 11122333, the ACR will try to forward it to 9998887777.

Things to think about

This is a basic example but a lot can be done with this. For instance, in our first group, you can add other endpoints that you want ACR to attempt before trying to forward the call to 9998887777. You could also add a third route with a new number 2223334444. If you did this, the call would try to connect to 111222333, then 9998887777, and finally 2223334444. Since you can have up to 100 endpoints across 10 routes, you have a lot of flexibility in terms of attempting to route the call before it fails!

Rewriting a SIP URI user

In this example, we’ll go over a bit more complex call flow that involves changing the user portion of the rURI on a call to a customer. Let’s say the destination host on a Location is set to 1.1.1.1, the domain is test.test.com, and the number is 2421112222. This means the SIP URI in the SIP invite would show up as sip: 2421112222@1.1.1.1 or sip:2421112222@test.test.com. But what if you want to replace the phone number with the word “sara”? 

First, you need to add a route with a couple of endpoints at the Location level:

1. In the top navigation bar, select Account and click Locations.
2. Select the Location that the number 2421112222 belongs to and click Voice. 
3. In the Action field, select Route to IP & Port.
4. In the IP Address field, enter 1.1.1.1
5. Optional: In the Port field, enter the port number. If you don’t enter anything, it will automatically default to 5060.
6. Click Save.

7. Click Add Endpoint on the Primary Route. 

8. In the Action field, select Route to Domain Name.
9. In the Domain Name field, enter test.test.com and click Save.

Next, you need to add a route with a couple of endpoints at the number level:

10. Navigate to number 2421112222’s Phone Number Details Page and click Create Primary Route.
11. In the Action field, select Route to SIP URI.
12. In the IP Address field, enter sip:sara@1.1.1.1 and click Save.

13. Click Add Endpoint on the Primary Route. 

14. In the Action field, select Route to SIP URI.
15. In the Domain Name field, enter sip:sara@test.test.com and click Save.

16. Now, on any SIP invites in the SIP, you’ll see the username “sara” overwrite what you’d normally have in the SIP URI after the colon and before the @ symbol. 

Things to think about

As you can see, ACR gives you the flexibility to mix and match different combinations. The Bandwidth Dashboard will display an error if something hasn’t been entered correctly, so feel free to experiment with various setups as you see fit!

Failover behavior

Finally, if you’re setting up endpoints for redundancy and performing failover testing, it’s helpful to know how the failover behavior works from the call delivery standpoint.

In a standard setup, you have one SBC pair that delivers your inbound calls. Let’s say you have a primary route with endpoint 1.1.1.1 and a secondary route with endpoint 7605558959, and the calls are delivered from SBC-A and SBC-Z. A hard-down scenario where the server at 1.1.1.1 doesn’t respond at all may look like this:

1. SBC-A tries to deliver the call to 1.1.1.1 but that IP doesn’t respond. 
2. By default, 3 INVITE messages are sent and all 3 receive no response.
3. We try to deliver the call to 1.1.1.1 from SBC-Z (it takes about 1.5 seconds to failover after waiting for a response), but it also gets no response.
4. The call is then failed-over to the second endpoint, which is a PSTN number, and is finally received at 7605558959. 

Note: It takes about 3 seconds before the call to the PSTN number is invoked. If the server responds with an error, the failover is instant. 

For more questions on failover or changing behaviors, please open a ticket with your Bandwidth Support Team or hit us up at (855) 864-7776!