BYOC for Twilio on the Legacy North American Platform

David Preo

Updated

Important: This article contains steps specific to our Legacy North American Platform. If you're using our Universal Platform, see BYOC for Twilio on the Universal Platform. 

We believe setting up business communications should be a straightforward, painless process. That’s why we build our SIP services to play well with whichever communications platform you might use – whether it’s hardware-based or hosted in the cloud, built internally, or bought from a third-party vendor. 

You can utilize Twilio products such as Flex (Contact Center) or Programmable Voice with a BYOC trunk, which enables you to Bring Your Own Carrier (Bandwidth) to your communications provider. 

Why is this better than paying for a bundled service from one provider? Because it allows you to benefit from Bandwidth’s fully compliant, reliable voice infrastructure and the improved connectivity and scalability of our network while continuing to use your existing apps. It’s a win-win for you!

What you need to get started

  1. A registered Bandwidth account with assigned numbers. Please contact your Account Manager to ensure your account is enabled for “SIP Authentication”.
  2. A registered account with Twilio (create it here).

How it works

integration-diagram-enterprise.png

Twilio Flex and Programmable Voice both leverage what Twilio calls their Super Network, a collection of carriers that Twilio uses to make and receive calls. The protocol used to connect to these carriers is SIP. 

BYOC allows you to choose Bandwidth as the carrier behind your Twilio application. This is made possible through communicating with Twilio via SIP and can be done in two steps:

  1. Setting up inbound call routing
  2. Setting up outbound call routing

Setting up inbound call routing

To set up inbound calls, you need to configure some settings in the Twilio platform. Once the destination address is set up there, you can set up a number and direct traffic to this source within the Bandwidth platform.

Twilio: Setting up Access Control List (inbound IP whitelisting)

First, you need to create an Access Control List (ACL) for the Bandwidth IPs for your Twilio app. This allows your Twilio application to receive incoming phone calls from the Bandwidth network. Your Bandwidth account manager will provide you with the necessary IP addresses to complete this step. 

Once you've obtained the IP addresses, complete the following steps:

  1. Log into your Twilio account.
  2. In the dashboard, go to Voice > Manage > IP access control lists or, if you’re already logged in, click here to go there directly.
  3. Create a New Access Control List (ACL) by clicking the + sign. You can use Bandwidth as the friendly name for this ACL. The pop-up only allows you to enter one IP before you save.

create-new-access-control-list.png

  1. After saving, you'll be taken to the newly created ACL page. Keep adding all the IPs by clicking the + sign under IP Address Ranges. 
  2. All set! Now you can create a SIP interface and link this ACL to it.

Twilio: Setting up a SIP domain

Next, define the path/domain by which you can access Twilio from Bandwidth.

  1. In the Twilio dashboard, go to Voice > Manage > SIP domains or, click here and then click the + sign to create a new SIP domain.
  2. Under Properties, specify your new SIP domain, which will be used to send inbound calls from the Bandwidth network. While you can enter any name in the SIP URI field, we recommend using something that you’ll remember (in this example, it's bandwidth-interface.sip.twilio.com).
  3. Under the Voice Authentication, add your ACL in the IP Access Control Lists drop-down list. 
  4. Under Call Control Configuration, specify the TwiML app for your Call Control Configuration. The Voice Request URL is the same as the existing TwiML app you’re using today for incoming calls. For testing purposes, you can use https://demo.twilio.com/welcome/voice/. When you’re done, your SIP domain should look like the one in the image below.

new-sip-domain.png

Bandwidth: Configuring Locations

Next, you need to create a Location within your Bandwidth account that directs incoming calls to your newly made Twilio SIP Endpoint. Locations help you organize your phone number inventory and configure your IP addresses for Voice. You can create Locations via either the Bandwidth App or the Bandwidth API. When a number is added to a Location, it inherits the settings and properties of that Location. You must have both a Sub-account and a Location to start ordering phone numbers.

To add and configure a Location:

  1. Log in to the Bandwidth App.
  2. In the side navigation bar, click Account and select Locations.
  3. Click Add Location.
  4. Complete the following fields:
    • Name: Enter the name of this Location. This field is required but can contain anything that makes sense to the Location provisioning.
    • Description: An optional field where you can add a description of this Location.
    • Sub-Account: Select a Sub-account that you want to associate with this Location.
    • Default location: Turn this switch on if you'd like this to be the primary Location. This means that when you order or port a number, this Location will show up first after you select your Sub-account.

create-location.png

  1. Click Voice. Under Voice IP address / DNS hosts, enter the Twilio SIP URI you created. In this example, it's bandwidth-interface.sip.twilio.com.

Bandwidth: Assigning numbers to Locations

The last step is to add numbers to the Location you just created. That’s it – any number within that Location will now have incoming calls routed to Twilio. For more information on assigning numbers to Locations, see this support article.

Testing inbound calls

TwiML demo app

Any calls placed to the numbers associated with your Twilio Location are now delivered by Bandwidth to the demo TwiML app https://demo.twilio.com/welcome/voice/, which will repeat a message that says “Thanks for the call. Configure your number's voice URL to change this message.”

Your application

Incoming calls can be delivered to your application on Twilio’s platform. This just requires you to change the Voice Request URL in your SIP domain to your hosted TwiML application. Please refer to our Twilio Programmable Voice guide for a demo application we have created. 

Setting up outbound call routing

For security reasons, it’s important to look at number permissions and SIP digest headers when setting up outbound calling. These will allow you to use a number for multiple applications.

Note: Please contact your account manager to request SIP Authentication to be activated on your account. If you'd like to configure via API, please refer to the first 2 steps in the SIP Registrar guide.

Bandwidth: Create a realm

To route calls through Bandwidth, you need to create a realm. Once created, it'll be used as part of the realm combined with <randomAccountHex>.auth.bandwidth.com:

  1. Log in to the Bandwidth App.
  2. In the side navigation bar, click Account and select SIP Credentials.
  3. In the lower section, click Add.
  4. Under Realm, enter a name for the realm.
  5. Under Description, add an optional description.
  6. Click Add.

add-realm.png

Bandwidth: Create new SIP credentials

To route outbound calls through Bandwidth, you also need to create a set of SIP credentials:

  1. Select SIP Credentials.
  2. In the upper section, click Add.
  3. Enter a Username and choose a Realm.
  4. Enter a Password, or click Supply Your Own Hashes to enter your hashes.
  5. Click Add SIP Credentials.

sip-credentials.png

Testing outbound calls

Programmable Voice API

To test an outbound call, it must be placed either via Programmable Voice or Flex. The following example shows how to place an outbound call using the Twilio Programmable Voice API. For more information, see Bring Your Own Carrier (BYOC) Trunking for Programmable Voice.

To create a call use the following format:

  • TO as sip:{desired_to_number}@realmname.<randomAccountHex>.auth.bandwidth.com:{port}
  • From as {Desired_E164}
  • SipAuthUsername as the username created above, like sipauthtest
  • SipAuthPassword as the password used to create the MD5 hash, like password
  • Url as {TwiML_app}
    • This is your TwiML application; for example, you can use http://demo.twilio.com/docs/voice.xml
  • AccountID as {AccountId}
    • This is your Twilio Account SID which you can retrieve from here.
  • AuthToken as {AuthToken}
    • This is your Twilio Authentication Token which you can retrieve from here.

For example:

curl 'https://api.twilio.com/2010-04-01/Accounts/{AccountId}/Calls.json' -X POST \--data-urlencode 'To=sip:+17778889999@realmname.<randomAccountHex>.auth.bandwidth.com:{port}' \--data-urlencode 'From=+15553334444' \--data-urlencode 'Url=http://requestb.in/zolm8azo' \--data-urlencode 'SipAuthUsername=sipauthtest' \--data-urlencode 'SipAuthPassword=password' \-u {AccountId}:{AuthToken}

Next steps

Now that you’ve established a SIP interface to connect your Bandwidth numbers to Twilio’s platform, you’re ready to implement BYOC to begin using Bandwidth numbers for Twilio Flex or Programmable Voice.

Article is closed for comments.