Using Voxbone with FreeSWITCH

With FreeSWITCH, it’s easy to Bring Your Own Carrier (BYOC) and unlock more value from the platform by using a dedicated telephony provider. The following guide shows you how to bring your Voxbone phone numbers to FreeSWITCH.

A little disclaimer: This is a guide developed by Voxbone’s Product team to help you get the most out of our platform. It isn’t necessarily supported or endorsed by the other platform, but we’re confident in its technical accuracy.

Bringing your own carrier service (Voxbone!) to FreeSWITCH is an easy way to save time and hassle, while supercharging your business comms with access to global dialing, thousands of virtual numbers, and HD voice quality all over the world. Voxbone offers instant access to 93% of global GDP, and it couldn’t be easier to integrate our platform with FreeSWITCH’s software.

Take back control of your voice with minimal latency, 500+ global points of interconnection, and long-term stability across every market we serve.

Learn more about the benefits of using Voxbone as your preferred carrier.

It’s easy to connect numbers from your Voxbone account to the FreeSWITCH platform, and enjoy both inbound and outbound calling services with the following simple configuration.

What you’ll need to get started

  1. A registered Voxbone account complete with phone numbers. (Create your account here)
  2. A running instance of FreeSWITCH.

How it works

FreeSwitch + Voxbone

When a call is received by Voxbone, we deliver it to your FreeSWITCH instance through something called voice URIs – a kind of address for your voice services. 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 and make/receive calls on FreeSWITCH, we need to establish a SIP interface between the Voxbone platform and FreeSWITCH.

This can be done in four steps:

  1. Inbound configuration: allows signalling/media traffic from Voxbone via Access Control Lists (ACLs)
  2. Outbound configuration: creates a gateway for Voxbone
  3. Configuring dial plans
  4. Reloading your configurations to apply the changes

Allowing inbound traffic from Voxbone to FreeSWTICH

First, we need to whitelist Voxbone’s signalling and media IPs on the FreeSWITCH instance.

Tip: You can find a list of our signalling IPs for all our Points of Presence (PoPs) here.

This is done in two steps.

  1. Modify the autoload_configs/acl.conf.xml file and allow traffic from Voxbone’s IP addresses.
    You can choose to only allow IPs/ranges for the PoPs that you’re using, but we recommend that you list our global network for a future-proof and failsafe configuration.
<list name="voxbone" default="deny">
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>
<node type="allow" cidr=""/>

  1. Apply the newly-created Voxbone ACL to inbound calls by modifying the file sip_profiles/internal.xml as follows:
<param name="apply-inbound-acl" value="voxbone"/>

Configure inbound call routing

Inbound call routing on FreeSWITCH is managed under dial plans with public context. We recommend that you create a new dial plan XML file for managing routing on Voxbone traffic, but you can also modify the dialplan/public.xml file directly.

To route inbound calls from Voxbone to a user registered on your FreeSWITCH, create an extension for Voxbone by creating a new file dialplan/public/voxbone_sip.xml:

<extension name="voxbone_sip">
<condition field="destination_number" expression="^(\d+)$">
<action application="set" data="domain_name=$${domain}"/>
<action application="playback" data="phrase:greeting"/>
<action application="transfer" data="1000 XML default"/>

This condition will route all inbound calls to the registered extension “1000”. If you want to match a specific phone number, you can simply modify the “expression” attribute of the condition as follows, and continue adding more conditions for different users. It’s completely up to you! To learn more about dial plans, refer to the FreeSWITCH Wiki.

<extension name="voxbone_sip">
<condition field="destination_number" expression="^\+32466900884$">
<action application="set" data="domain_name=$${domain}"/>
<action application="playback" data="phrase:greeting"/>
<action application="transfer" data="1000 XML default"/>

The above example shows routing a specific phone number to an extension.

Create a Voxbone gateway

Similar to with routing inbound calls, outbound calls from FreeSWITCH also use dial plans, in which you’ll define the conditions for using certain outbound paths (called “Gateways”). To configure outbound calls using Voxbone, create an external SIP profile under the sip_profiles/external/ folder or modify the XML file sip_profiles/external.xml directly.

To manage your configurations more easily, we recommend either using a dedicated configuration file for all your external connections, or different files per connection. For this tutorial, we’ve created a new file : sip_profiles/external/voxbone.xml

<gateway name="voxbone_outbound">
<!-- This is the anycast outbound signalling IP for Voxbone, alternatively, you can use the FQDN, or regional FQDNs such as -->
<param name="proxy" value=""/>
<!-- Voxbone authenticates outbound calls by SIP DIGEST. Your username is defaulted to your account username, but can be managed on our portal along with your password, under Configuration > Configure Outbound Settings. -->
<param name="auth-username" value="YourVoxboneUsername"/>
<param name="password" value="YourVoxoutPassword"/>
<param name="realm" value=""/>
<!-- Authentication is SIP Digest, not register-based -->
<param name="register" value="false"/>
<!-- Optionally, you can enforce UDP instead of TCP. Both are supported. -->
<param name="register-transport" value="udp"/>
<!-- Optionally, you can enforce RFC2833 as DTMF type. Make sure this matches the configuration options you have on Voxbone platform -->
<param name="dtmf-type" value="rfc2833"/>
<!-- Depending on how you want to present the outbound caller ID, you can leverage the sip_cid_type parameter. In order to do so, we must set caller-id-in-from parameter to true -->
<param name="caller-id-in-from" value="true"/>
<variable name="sip_cid_type" value="rpid"/>

You can copy the example configuration above and modify the username and password. Once you’re done, just save the file.

To learn more about how to manage caller ID configurations on FreeSWITCH and understand how to use sip_cid_type, here’s a guide.

Configure outbound call routing

To use Voxbone for outbound calls via the gateway we just configured, we need to create extensions and conditions defining the routes for which FreeSWITCH will use Voxbone. Like with inbound call routing, we recommend that you create a new dial plan XML file for managing routing on Voxbone traffic. But you can also directly modify the dialplan/default.xml file.

To bridge outbound calls to Voxbone based on conditions, create an extension for Voxbone by creating a new file dialplan/default/voxbone_outbound.xml:

<extension name="voxbone_outbound">
<!-- This matches all dialled numbers within the US -->
<condition field="destination_number" expression="^(1{0,1}\d{10})$">
<!-- You can use a default outbound caller ID on all calls routed through Voxbone by setting the effective_caller_id_number parameter -->
<action application="set" data="effective_caller_id_number=+15550000000"/>
<!-- If you’re using CNAM, you can set the caller name by setting the effective_caller_id_name parameter -->
<action application="set" data="effective_caller_id_name=${outbound_caller_id_name}"/>
<!-- Once you’re done with setting parameters or any other actions, finally bridge the call to Voxbone gateway. If you’ve used a different name for your gateway than the one used in this tutorial, change the voxbone_outbound string to match the name attribute specified for your gateway. Voxbone expects a standard E.164 representation for the destination. Make sure the resulting path has a standard E.164 representation with the + sign at the end. -->
<action application="bridge" data="sofia/gateway/voxbone_outbound/+1$1"/>

To learn more about how to specify and user regular expressions in FreeSWITCH dial plans, here’s a guide.

Creating a voice URI between Voxbone and FreeSWITCH

This is where we set up the SIP interface from Voxbone to your FreeSWITCH instance. On Voxbone platform, this is done via voice URIs. This tutorial explains how to setup configuration manually for testing purposes. You can also automate the provisioning by using our APIs.

Here, you’ll use the IP address or domain/FQDN for the FreeSWITCH instance that you’ve set up to use with Voxbone.

Note: To be able to differentiate call routing, on Voxbone you can use the reserved keyword “{E164}”, which lets us use the same voice URI for many different numbers – plus detect what number is called/who’s calling on your dial plan.

  1. Log in to your Voxbone account.
  2. Go to Configure > Configure Voice URIs (or, if you’re logged in, click here).
  3. Click ‘New’ to create a Voice URI routed to your FreeSWITCH instance.
  4. Specify the Voice URI as {E164}@(IP address or domain for your FreeSWITCH instance). For example: {E164} or {E164}@

When you’re done, your Voice URI should look something like this:

Route your Voxbone numbers to FreeSWITCH

Now, we need to link one of our numbers to the FreeSWITCH Voice 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’. Make sure to match the codecs to the ones you configured on FreeSWITCH.
  4. In the window, select the voice URI you just created.
  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 FreeSWITCH instance, at the user’s phone who was assigned this number, based on your dial plan.

Testing inbound calls

Any calls placed to the numbers associated with your FreeSWITCH URI are now delivered by Voxbone to your instance. If you used the {E164} keyword, your external dial plan should see them as calls received to URI (called Voxbone DID)@(IP address or domain for your FreeSWITCH instance).

In this tutorial, for example, if the Voxbone number “3228080000” is linked to +{E164}@, when a call is placed, your FreeSWITCH instance will see an incoming call to [email protected]

Now you can use the dial plans as usual to handle the incoming call.

Testing Outbound Calls

To test outbound calls via Voxbone through FreeSWITCH, make sure you have outbound dialing enabled with Voxbone (either national or international) on the phone number assigned to the user, or set as the default caller id on your gateway or dial plan.

Testing International/National Calls

After configuring the Voxbone gateway and making sure to present a valid caller id either used by your dial plan or user’s caller id, just place a call from a client that’s registered to FreeSWITCH.

Testing Emergency Calls

As testing actual calls to emergency services is impractical, we have a dedicated 3-digit number you can dial to ensure your setup works fine for real emergency calls.

To test it, make sure your dial plan allows 3-digit dials and such calls use the Voxbone gateway you created. Then, dial “777” from a SIP endpoint that’s registered to FreeSWITCH, which will connect you to an echo service.

Once you validate two-way media, all emergency calls will work fine, as long as your phone numbers are enabled for the service on the Voxbone platform.


Support & troubleshooting

Once you’re done with the setup, it’s recommended to confirm the newly created gateway is active and being used as sometimes reloadacl and reloadxml commands might not do all. Read more about reloading here. Run the following command on FreeSWITCH CLI to make sure the new gateway setup is applied :

sofia profile external rescan reloadxml

Alternatively, check the gateways and their status by running the following command :

sofia profile external gwlist

Once you’re set up to perform tests, the “Basic Calls” and “Other Tests” section on the FreeSWITCH guide on configurations is a good resource to follow through.

If the FreeSWITCH instance is deployed on Google Cloud, you might need to check the firewall configs on the machine to allow signalling and media ranges. A practical way for doing this on GCP is via firewall rules. These allow you to create rules with tags that can be easily reused on any new machines you create. For our lab environment, we created 2 rules for FreeSWITCH and 1 for allowing SIP and assigned those under “Network Tags” on the VM instance.

If you’re still having trouble connecting Voxbone to FreeSWITCH, here are a few last tips:

  1. You can check whether your calls are reaching Voxbone by looking at your Call History (Login to Voxbone > Account > Call History)
  2. If you see a call record on Voxbone with an error message, contact our care team by creating a ticket. Getting a SIP trace from your FreeSWITCH will be very helpful for us in investigating issues.
  3. If you don’t see a call record showing up in Voxbone, this means the call was declined or rejected by your FreeSWITCH dial plan or configurations.

For any questions, please contact us