Making outbound voice calls with MessageBird

⏱ 10 min build time

In this MessageBird Developer Tutorial you’ll learn how to make calls with the MessageBird Voice API.

Before we get started, have you set up your PHP development environment and project directory with the MessageBird SDK?

No! Make sure you to set this up before continuing; you can read this MessageBird Developer Tutorial to learn how to do so.
Yes! Great! We’ll show you how to make your first API request and begin establishing Voice Calls with MessageBird using PHP.

Getting Started

First, let's create a new file in the directory of your composer.json file and call it make_call.php.

Now we can include the Composer autoloader in this file so you can access the SDK (and other packages):

<?php
require_once __DIR__.'/vendor/autoload.php';

Then, initialize the SDK by creating a new instance of the MessageBird\Client class. The constructor takes a single argument, your API key. For testing the SDK, you can simply replace the string YOUR-API-KEY in the following PHP code and thus hardcode your API key.

Pro-tip: For production applications, we recommended storing the key in a configuration file or environment variable instead, and pass this variable with the key to the constructor.

$messagebird = new MessageBird\Client('YOUR-API-KEY');

The SDK defines a PHP class for voice calls. Let’s create an instance of this class and then assign values for the required attributes source and destination:

$call = new MessageBird\Objects\Voice\Call;
$call->source = '31970XXXXXXX';
$call->destination = '31970YYYYYYY';

What do these attributes mean? 🤔

The source is the caller ID that appears on the receiving phone. Don’t forget to specify this telephone number in the international format with country code. The number must be owned or verified in your account.
The destination is the phone number that MessageBird should call. Likewise, you must specify this telephone number in the international format with country code.

Make sure to replace the values in the sample code with adequate data for testing.

A third attribute named callFlow is required, but before we can assign it to the call, we need to create it as an object as well. The call flow specifies one or more steps that will execute once the receiver picks up the call. They can be different actions, which include playing audio files, reading a block of text with a synthesized voice (TTS) or forwarding the call to another phone.

$flow = new MessageBird\Objects\Voice\CallFlow;

$step = new MessageBird\Objects\Voice\Step;
$step->action = 'say';
$step->options = [
    'payload' => 'Hey you, a little bird told me you wanted a call!',
    'language' => 'en-GB',
    'voice' => 'female'
];

Every step has two attributes:

The action classifies what the step does. For instance, the action type say indicates that this step is responsible for reading a written block of text.
The array options contain the configuration of the step. The attributes that you can or must specify here depend on the action type. For say you need payload to define the text to speak, language to indicate the language of the text as an ISO language code, and voice to determine the speaker, male or female.

You need to add the steps as an array on the steps attribute of the flow. Our example flow has only one:

$flow->steps = [ $step ];

To learn more about call flows and steps, especially the types of actions that are available and which options are required or optionally available for them, you can read the ‘Call flows’ section in our Voice Calling API documentation.

Once the flow is ready, we can assign it to the call:

$call->callFlow = $flow;

There are additional optional attributes for the call objects as well; you can find them in the ‘Calls’ section of our Voice Calling API documentation.

Once the call object is fully configured, you can send it through the API. Call voiceCalls->create() on the SDK instance and pass your previously created call object as the first argument:

$response = $messagebird->voiceCalls->create($call);
var_dump($response);

Your first PHP script is ready, save it! Keep in mind that the MessageBird SDK throws an exception when something goes wrong with your API request. It's okay for now, but in production applications you should place any API call between try and catch and provide user-friendly error handling inside the catch block.

Enough said, let's try running it from the command line:

php make_call.php

You should see the API response as output from the script due to the var_dump() function. If you used a live API key and had verified your number or added credits to your account, your phone will ring shortly and, once you pick up, deliver a message.

If you see an error from the script try to read and understand the message so the problem can be fixed. If you have trouble still, don’t hesitate to contact us at support@messagebird.com; we’ll help you out.

Nice work! 🎉

You just initiated your first voice call with the MessageBird API!

Start building!

Let's head over to the next MessageBird Developer Tutorial and learn how to set up and handle incoming voice calls.

Want to start building your solution but not quite sure how to get started? Feel free to let us know at support@messagebird.com; we'd love to help!

Is this page useful?

Questions?

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

Cookie Settings