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

MessageBirdClient
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 MessageBirdClient('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 MessageBirdObjectsVoiceCall;
$call->source = '31970XXXXXXX';
$call->destination = '31970YYYYYYY';

What do these attributes mean? 🤔

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 MessageBirdObjectsVoiceCallFlow;
$flow->title = 'Test Flow';

The flow needs an attribute called

title
that describes it. This attribute can help you understand the flow but doesn’t affect its execution.

$step = new MessageBirdObjectsVoiceStep;
$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!

Cookie Settings