Establishing automatic failover for routing calls during failures (Final destination URI)

Edit: Effective February 23, 2022, Failover/Final Destination URIs are available in the Bandwidth App. Learn more here

What would happen to your calls if a failure prevented traffic from being routed to your usual inbound call routes? A great, albeit little-known, feature that Bandwidth offers provides increased reliability in call routing so that you’re able to failover to an alternative phone number to ensure that inbound calls get connected.

Through the Bandwidth App API, we provide an attribute called Final Destination URI. This option differs from our standard call forwarding feature, which you would establish if you need to forward calls from one of your Bandwidth numbers to an alternative number.

By setting a Final Destination, you are assured that in case of a failure of your usual call routes (Origination IPs or DNS host), your calls will be sent to a single location, either a SIP address or number, as backup. You can have peace of mind regarding your incoming calls in situations where otherwise you would miss your calls completely.

This attribute can be set on either on the Location or individual phone numbers to forward calls to another phone number as a failover.

How to establish automatic failover for a location

URI Format

Before we get into setting the Final Destination URI, let’s talk about formatting the Final Destination at the Location-level. You have two options, a SIP address or a Public Switched Telephone Network (PSTN) number.

To set the Final Destination URI to a SIP address: 

sip:{address}@{host}

If you are setting the Final Destination to a PSTN number, the format varies. For example, if you wanted to see the Final Destination URI to PSTN number (333) 222-1111, you would set this at the Location-level using the format:

+13332221111@PSTN

API Request to Set Final Destination URI at Location-Level

This is an example of an API call that sets the Final Destination URI at the location-level. Keep in mind that within the API, subaccounts are referred to as sites and locations are called sippeers.

Needed items:

• Your basic auth credentials for using the API
• Your accountId
• The siteId for the subaccount where the location is located
• The sippeerId for the location where you want to set the Final Destination URI
• The name of the location where the Final Destination URI is being set. The PeerName has to be specified. It is up to you if you want to keep the name the same or change it.
• The Final Destination URI. See above for formatting.

PUT https://api.bandwidth.com/api/account/{accountId}/sites/{siteId}/sippeers/{sippeerId} HTTP/1.1

Authorization: Basic {base64_encoded_credentials)
Content-Type: application/xml

<SipPeer>
 <PeerName>{location_name}</PeerName>
 <FinalDestinationUri>{final_destination}</FinalDestinationUri>
</SipPeer>

Note: You should get a 200 OK response from Bandwidth. If you don’t, there should be a message attached to the response explaining where the problem is. After you receive a 200 response, feel free to perform a GET request at the same URL you used to set the Final Destination URI to confirm that the Final Destination URI was set properly, in addition to other location-level settings.

How to establish automatic failover for a phone number

URI Format

Before we get into setting the Final Destination URI, let’s talk about formatting. For example, if you wanted to set the Final Destination URI to phone number (333) 222-1111, the format would be:

3332221111

API Request to Set Final Destination URI on a Phone Number

You can set a Final Destination URI for individual numbers by creating a TnOptions order, just as if you wanted to update the telephone number line features. Below is an example.

Needed items:

• Your basic auth credentials for using the API
• Your accountId
• The phone number(s) where you want to set the Final Destination URI
• The Final Destination URI. See above for formatting.

POST https://api.bandwidth.com/api/accounts/{accountId}/tnoptions HTTP/1.1

Authorization: Basic {base64_encoded_credentials}
Content-Type: application/xml

<TnOptionOrder>
    <TnOptionGroups>
        <TnOptionGroup>
            <FinalDestinationURI>{final_destination}</FinalDestinationURI>
            <TelephoneNumbers>
                <TelephoneNumber>{TN_1}</TelephoneNumber>
                <TelephoneNumber>{TN_2}</TelephoneNumber> 
                                                             .
                                                             .
                                                             .
                <TelephoneNumber>{TN_last}</TelephoneNumber>
            </TelephoneNumbers>
        </TnOptionGroup>
    </TnOptionGroups>
</TnOptionOrder>

Feel free to include as many TnOptionGroup fields as needed. You may update up to 5,000 phone numbers at a time.

Note: You should get a 201 Created response from Bandwidth. If you receive an error, a message will be attached that shows what the problem is to help you figure out how to correct the issue.

Note 2: This feature is not available in the UI for the Bandwidth App at this time. It can only be inserted via the Bandwidth App API.