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?
First, let's create a new file in the directory of your
composer.jsonfile and call it
Now we can include the Composer autoloader in this file so you can access the SDK (and other packages):
Then, initialize the SDK by creating a new instance of the
MessageBird\Clientclass. The constructor takes a single argument, your API key. For testing the SDK, you can simply replace the string
YOUR-API-KEYin 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
$call = new MessageBird\Objects\Voice\Call;$call->source = '31970XXXXXXX';$call->destination = '31970YYYYYYY';
What do these attributes mean? 🤔
sourceis the caller ID that appears on the receiving phone. Don’t forget to specify this telephone number in the international format with country code.
destinationis 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
callFlowis 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;$flow->title = 'Test Flow';
The flow needs an attribute called
titlethat describes it. This attribute can help you understand the flow but doesn’t affect its execution.
$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:
actionclassifies what the step does. For instance, the action type
sayindicates that this step is responsible for reading a written block of text.
optionscontain the configuration of the step. The attributes that you can or must specify here depend on the action type. For
payloadto define the text to speak,
languageto indicate the language of the text as an ISO language code, and
voiceto determine the speaker,
You need to add the steps as an array on the
stepsattribute 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
catchand provide user-friendly error handling inside the catch block.
Enough said, let's try running it from the command line:
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 email@example.com; we’ll help you out.
Nice work! 🎉
You just initiated your first voice call with the MessageBird API!
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 firstname.lastname@example.org; we'd love to help!