Programmatically Handle Inbound 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.

Next steps

You may now want to check out these resources:

Questions?

We’re always happy to help with code or other questions you might have! Check out our API Reference, Developer Tutorials, or contact our Support team.