Close mobile menu
HomeProgrammable SMSProgrammable VoiceText To SpeechVerifyConversationsBetaNumbersBetaLookupMMSHLRReportingBetaBalanceContactsGroups

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.

Cookie Settings