Receive voice calls

In this Programmable Voice Calling API Quickstart, you'll learn how to handle inbound voice calls using webhooks, Flow Builder, and MessageBird’s Programmable Voice Calling API.

We’ll walk you through the following steps:

1. Purchase a Virtual Mobile Number from MessageBird
2. Set up a Webhook Handler
3. Set up a flow in Flow Builder

Step 1: Purchase your Voice-enabled Virtual Mobile Number

1. Go to Numbers in the MessageBird Dashboard and click on Buy a number
2. Pick the country in which you and your customers are located, and make sure the Voice capability is selected.
3. Choose one number from the selection

Step 2: Set up your Webhook Handler

To retrieve a Call Flow from a URL (i.e. set up a call webhook), you must use the HTTP GET method in your application.

When a person calls a virtual number assigned to such a URL via Flow Builder, you'll need to make an HTTP request to your application and retrieve the call flow - this will be what the caller hears on the other end of the call.

Since it's a GET, you'll need to send parameters in the query string.

For most applications, you should only need the source field - which indicates the phone number that's calling.

Your application should return a call flow encoded as JSON or XML with the appropriate content type, for example, application/json for a JSON-encoded call flow or application/xml for an XML-encoded call flow.

Here’s an example of an XML-encoded call flow with a single step:

<?xml version="1.0" encoding="UTF-8"?>
<Say language="en-GB" voice="female">Hello, thanks for calling!</Say>

We recommend that you check the Voice Calling API documentation for a list of available step actions and options.

Step 3: Set up Flow Builder for inbound calls

Now, configure a simple flow using Flow Builder to handle inbound voice calls on a virtual number:

1. Go to Flow Builder, hit the button Create new flow and then Create Custom Flow.
2. Select Phone Call then select the your number or numbers.
3. Add a new step, choose Fetch call flow from URL, and paste the same local-tunnel base URL into the form, but this time append /webhook-voice to it.
4. Hit Publish to activate the flow.

Congrats! You can now programmatically handle inbound voice calls using Webhooks, Flow Builder, and the Programmable Voice Calling API.