Using Voxbone with Cataleya

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

What you’ll need to get started:

  1. A registered Voxbone account with assigned numbers. (Create your account here)
  2. A setup from the Cataleya Cloud

Note: For Voxbone, a free test account is enough for you to follow the steps in this guide and complete a technical validation of the integration of our voice services and Cataleya. In the below guide I’ve used Zoom Phone BYOC as the “end point” which is why you will see items named Zoom in the guide. We’ve done this as Cataleya provides more of a CPaaS layer that requires the configuration of endpoint devices – for the purposes of this demonstration, we’ve chosen to do this with Zoom Phone.

How it works

Cataleya + Voxbone

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 optimising for maximum call quality. To connect your Voxbone numbers to your Cataleya, we need to establish a SIP interface between the platforms.

This can be done in a single step as Cataleya has a wizard that allows Voxbone to be defined with different inbound and outbound end points.

1. Configuring Cataleya for use with Voxbone

Configuring a SIP Interface

The first thing that’s required is to make sure we’re creating an external interface for the SBC to talk with Voxbone. Go into the SIP Interface on the left-hand nav and create an interface that Voxbone can talk to (this may already be available to you).

Cataleya Platform - Modify SIP Interface

Choose whether you want to talk on UDP, TCP or TLS. We’ll need to know this later when we choose where to point the calls, so make a note of it.  Please keep this on port 5060 or 5061.

Configuring a Media Interface

Now it’s time to establish which ports the RTP will use. Voxbone supports the port range 10000 – 24000, so set your ports within this. If you want to control bandwidth use, you have some options to do so.

Configuring a Zone

The next step ensures that the system will be end-to-end capable. Cataleya refer to this as the Zone.  Simply click into the zone area on the left-hand navigation and then add a new zone and follow the Wizard.

  1. Step 1 is to label the Zone as Voxbone, and ensure that the Zone Type is
    interconnect. Cataleya - Step 1
  2. Step 2 is to setup the SIP Signalling profile.  Cataleya - Step 1Cataleya Platform - Step 1Cataleya Platform - Step 2We need to select the SIP interface we created earlier, then select a SIP profile to manage things within the signalling layer. To do this we need to do some more light configuration work. When you choose to Modify the SIP Param Profile, the default delected values will be generally okay to use. But make sure that Refer is enabled as one of the Methods Allowed, in case you need it in the future. Cataleya - Step 2 - Modify SIP Param ProfileThe only other setting that will definitely need your attention here is the re-route on 401/407 as No, as Voxbone uses SIP Digest Authentication and we need to ensure the system manages this.
  3. Step 3 is to configure the media. Cataleya - Step 3Here we need to link to the Media and then set up a Media Profile.  This is where you configure the codec you need. Cataleya - Step 3 - Modify Media Profile
  4. Step 4 is to configure the Call Admission Control settings (CAC). Cataleya - Step 4This is fairly straightforward and just needs you to set the maximum number of calls you wish to you wish to be able to handle concurrently. Please note that you can configure your capacity requirement directly in the Voxbone platform. We’d recommend setting it here to <20 Calls per second, unless you have engaged with us to increase this threshold.
  5. Step 5 is where we set up the security of the thresholds for calls into the system. Cataleya - Step 5Most of these settings can be kept as defaults.  However, as you can see the screen actually scrolls, and there are few more hidden features we need to adjust in the Allowed Sources. Cataleya - Step 5 - Allowed SourcesAs you can see we’ve added the Inbound IP addresses to the allowed list from all Voxbone Inbound SuperPops.You can find a list of signaling IPs here.
  6. Step 6 concerns setting up outbound routing. Cataleya - Step 6Here it’s simply a case of adding the Voxbone AnyCastIP address of, or
  7. Step 7 covers setting up the final routing. This will depend on your own settings, but the idea is to ensure the calls are routed out via the method of connectivity you have to Voxbone, (Internet or the Voxbone Connect product you use)
  8. Step 8 is the final stage and is where we set up transcoding. It’s just as simple yes/no as you require.

Now that Cataleya is configured, we need to go back into the Voxbone portal and point everything else as required.

Configuring a SIP URI To Point At Cataleya

Next, we will set up the SIP interface from Voxbone to Cataleya. In Voxbone’s platform, this is done via Voice URIs.

In order to differentiate between different Voice URIs that might be pointing at your Cataleya, 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.

This will be the Cataleya IP address listed in the SIP Profile, the first thing you setup.

  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 Voice URI for your Cataleya
  3. Specify the Voice URI as {E164}  or {E164}@YourCataleyaExternalIP

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 Cataleya 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 the codecs we set in the
    dial peer above to prevent any SDP or media-related errors under the “Codecs” menu. Make sure these are aligned to the Codecs you setup in the media profile earlier. Voxbone Platform - Select Voice URI
  4. Select the voice URI you created from the previous step, from the popup window.
  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 Cataleya

Testing Calls

Any calls placed to the numbers associated with your URI are now delivered by Voxbone to your Cataleya. If you used the {E164} keyword, your system should
see them as calls received to URI (called Voxbone DID)@YourCataleyaDomain. You should be able to do a packet capture within your CUBE to capture the traffic and see the incoming call.

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

Then check the following:

  • That your Account Manager or Customer Success 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 to be 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. Find ‘VoxOut National’ and click it to enable outbound calls. Be, and then be sure to hit ‘Apply’ to update the configuration.

Voxbone Platform - National Outbound Enabled

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.

Voxbone Platform - Outbound Voice Credentials

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

Note2: The Cataleya system does not directly add the Digest header. The way Cataleya is designed to work is to pass through this value from the source component that triggers the call. Therefore, just ensure that you add the SIP Digest header to the configuration. We’ll remind of this again as we get to the set up of this on the Voxbone side.

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


Our thanks to our friends at Cataleya for the access to their system and lab environment and the help getting this research lab set up and working.


For any questions, please contact us