Using Voxbone with Twilio

Quick Links

  1. Setting Up Inbound Call Routing
  2. Setting Up Outbound Call Routing
  3. Setting Up Secure Comms


Introduction

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. In effect, this enables you to Bring Your Own Carrier (us!) to your communications provider. Why is this better than paying for a bundled service from one provider? Because it allows you to benefit from Voxbone’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’ll need to get started:

  1. A registered Voxbone account with assigned numbers. (Create your account here)
  2. A registered account with Twilio (Create it here)

Note: On both platforms, a free-trial account is also enough to get started!

How it works

When a call is received on our platform, we deliver this call to your designated SIP interface through voice URIs. Behind the scenes, we take care of complex things like least-cost routing, finding the best provider and optimizing for maximum call quality. To connect your Voxbone numbers to Twilio’s platform, we need to establish a SIP interface between our platform and theirs.

This can be done in 3 steps:

  1. Setting Up Inbound Call Routing
  2. Setting Up Outbound Call Routing
  3. Setting Up Secure Comms


1. Setting Up Inbound Call Routing

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

Setting Up IP Whitelisting

First, we need to whitelist Voxbone’s signaling IPs from the Twilio side for your apps. You can find a list of our signaling IPs for all our points of presence (PoPs) here.

Here’s what to do.

  1. Log in to your Twilio account
  2. In the dashboard, go to Programmable Voice > SIP Domains > IP Address 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 “Voxbone” as the friendly name for this ACL. As the pop-up only allows you to enter one IP, you can start by using your favorite Voxbone PoP. For example, Belgium:Twilio new access control list
  4. You will be taken to the newly created ACL page. Keep adding other Voxbone PoPs by clicking the “+” sign under “IP Address Ranges”. Note that we’re not actually using ranges but single IPs with “32” as subset.
  5. When you’re done adding all the signaling PoP addresses, your ACL should look something like this:Twilio access list complete
  6. All done! Now we can create a SIP interface and link this ACL to it!

Note: Make sure your numbers are in E164 format.

Setting up a SIP URI

Next, we’ll define the path/domain by which we can access Twilio apps from Voxbone.

  1. In the Twilio dashboard, go to Programmable Voice > SIP Domains > Domains, or click here and then click “+” to create a new SIP Domain.
  2. Specify your new SIP domain. Note what you created, as this will be needed in the next step. This is the domain of your SIP URI. I’m using “voxbone-interface.sip.twilio.com” for this tutorial. That makes my Voice URI for Voxbone: anything@voxbone-interface.sip.twilio.com
  3. Specify a TwiML app connected via this interface. For testing purposes, you can use “https://demo.twilio.com/welcome/voice/”
  4. Finally, add your ACL under the “Voice Authentication” section in the drop-down list. When you’re done, your SIP interface should look something like this: Twilio New SIP Domain

Setting Up a SIP URI To Point At Twilio

This is where we set up the SIP interface from Voxbone to Twilio. On our platform, this is done via Voice URIs. As noted from the previous step, our SIP domain is “voxbone-interface.sip.twilio.com” and a standard SIP URI is in the format of user@sip-domain.com. For example: me@voxbone-interface.sip.twilio.com.

To be able to differentiate on your Twilio app, we’ll use a reserved keyword on our platform, “{E164}”, so that we can use the same voice URI for many different numbers and detect what number is called/who’s calling from our Twilio app.

  1. Log in to your Voxbone account.
  2. Go to Configure > Configure Voice URIs or, if you’re logged in, click here. Then click “New” to create a Twilio Voice URI.
  3. Specify the Voice URI as {E164}@(whatever you set as the SIP domain on Twilio). For example: {E164}@voxbone-interface.sip.twilio.com. When you’re done, your Voice URI should look something like this: Voxbone Create Voice URI

Adding a Number to the URI So You Can Call it, and Adding an Audio Codec

Now, we need to link one of our phone numbers to the Twilio URI we just created.

  1. Go to Configure > Configure DIDs or, if you’re logged in, click here.
  2. Use filters to pick a number of your choice to assign for testing and hit “Search”.
  3. Once you’ve picked your number, under the Configuration menu, go to the “Voice” tab and click “Voice URI”. Also, make sure to pick at least g.729 and g.711 codecs to prevent any SDP or media-related errors under the “Codecs” menu. Voxbone configure DID
  4. Select the voice URI you created from the previous step, from the popup window. Voxbone Select a Voice URI
  5. Hit “Apply” and “Continue”, then finally, “Confirm.”
  6. All set! Now place a call to the number you are using for testing. It should reach your designated Twilio App on your Twilio SIP Interface.

Testing Calls

Any calls placed to the numbers associated with your Twilio URI are now delivered by Voxbone to Twilio. If you used the {E164} keyword, your Twilio app should see them as calls received to URI (called Voxbone DID)@(Twilio SIP Interface Domain). For example in this tutorial, if the Voxbone number “3228080000” is linked to {E164}@voxbone-interface.sip.twilio.com, when a call is placed, your Twilio app would see an incoming call to 3228080000@voxbone-interface.sip.twilio.com on the app you linked to the interface.

Now, based on the SIP headers, you can keep using your existing app/business logic without changing anything, but with the added benefits that come from using Voxbone as the delivery platform for your calls.

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

But there are a few steps to take before we get there.

Enabling Outbound

Before you start, make sure you have an online account with Voxbone and that Voxbone’s service interoperates with your network by following the inbound guide above.

Then check the following:

  • That your Account Manager has activated Voxbone’s outbound service for your account, and for your country of choice
  • That you’ve got 2 test numbers for outbound calling
    These are test numbers in countries that have our outbound service available. Our team will confirm that access has been granted for these numbers.
  • If the country you are using requires Emergency Services enabled, please ensure you speak to our team about getting this set up at the same time, as otherwise it might delay this process.

Go to ‘Configure DIDs’ in the Voxbone platform, and select the numbers you wish to set up for outbound service. Click on ‘VoxOut National’ and click to enable, and then be sure to hit ‘Apply’ to update the configuration.

This allows you to use this number as an outbound presentation number across any number of integrations.

Enabling SIP Digest Security

The next thing that needs to be set up is the security configuration that Voxbone requires for outbound calling. Voxbone uses SIP Digest headers. To set up the credentials, please go to ‘Configure Outbound Voice’.

Here you can add the username and password used on the system.

Note: We strongly recommend you use the generation tool to generate a large, complex key for use within the system. This is a central configuration and only needs setting up once.

Setting Up Call Diversion

To allow call forwarding or call diversion to support passing or presenting third-party call IDs, the system needs to have the following setup.

  • The number listed in the ‘FROM’ field can be either a Voxbone or third-party number
  • The number in the ‘TO’ field can be a number listed in our routing prefix table
  • The number in the ‘DIVERSION’ field must be a Voxbone number activated for outbound voice

Twilio Programmable Voice

With the Twilio platform, it’s possible to set up outbound calling in a variety of ways.

We’ve tested it in two:

  • Linking an inbound call, to then call a TwiML Bin containing the following code, to allow the call to be linked end to end.
  • Calling the Twilio CLI (or API), with an equivalent call, from an internal endpoint as the source.

Now we’ll focus on the TwiML used in more detail. (Notes are with “//” and in italics to highlight)

<?xml version="1.0" encoding="UTF-8"?> //Important to flag the encoding.
<Response>
<Say>Please hold while we connect the call.</Say>
<Dial callerId="{Voxbone_Enabled_Outbound_DDI"> //Passing in the CallerID from the list of outbound enabled Voxbone numbers is key here, this should be in E164 format. E.G +441234XXXXXX
<Sip username="{Username_set up_on_OutboundVoice_on_Voxbone_earlier}" password="{Securepassword_set up_on_OutboundVoice_on_Voxbone_earlier}">
// This is the SIP Digest being passed, it is not your Voxbone account details, but the additional information set up in Enabling Digest Security.
+44{DialledNumber}@81.201.89.110
// Note that the number is sent in E164 number format
//Again, here is the dialled number, and at this point we’re passing in the “anycast IP Address”, which will automatically route to the closest Voxbone PoP. if you want control of this, please choose from the list here
</Sip>
</Dial>
</Response>
Note: on call diversion/impersonation: Twilio currently cannot pass full SIP Headers such as diversion headers, so it’s currently not possible to perform call diversion with the integration as it stands.

3. Setting Up Secure Comms

Currently Twilio only supports SRTP with the Elastic SIP offering, and not through the programmable voice offering. This means that SRTP is still currently unavailable through this integration.

For any questions, please contact us