Inbound voice calls with PHP

Receive an Inbound Voice Call with PHP

Published June 28, 2018 by Michael Heap
Categories:

In our last PHP and voice blog post, we covered how to make an outbound voice call using Text-To-Speech. In this post, we’re going to change direction and write an application that handles inbound voice calls and returns a dynamic response.

The source code for this blog post is available on Github.

Prerequisites

To work through this post, you’ll need a Nexmo account. Sign up now if you don’t already have an account (it comes with €2 of free credit, which is enough to work along with this post).

You’ll need PHP installed before working through this post. I’m running PHP 7.2, but the code here should work on PHP 5.6 and above. You’ll also need Composer to download our dependencies.

Finally, you’ll need the Nexmo CLI installed. We’ll be using this to configure our Nexmo account and purchase a phone number.

Receiving a phone call with PHP

Before we get into the details about how it all works, we’ll start by creating a PHP application to handle incoming voice calls. When a voice call is received, Nexmo will make a request to your application to find out how to respond to that call.

We’re going to be using the Slim framework to handle the incoming request, so let’s install it now with composer:

Once that has completed, create a new file named index.php with the following contents. This will create a new Slim application and register a single endpoint (/webhook/answer) that accepts a GET request with a from query string parameter and returns the from value in the body.

Save this file and then open up a new terminal window. Let’s start the built in PHP server and serve our application on port 8000.

If you visit http://localhost:8000/webhook/answer?from=14155550100, you will see the from number returned in the response body.

This is a great start, but Nexmo won’t know what to do if we only respond with the caller’s phone number. To tell Nexmo how to handle the call, we have to return an NCCO.

To keep things simple, we’ll use Text-To-Speech to read the caller’s phone number back to them, digit by digit. First, we split their number in to an array of characters, then join them together using spaces:

Next, we define an NCCO that uses the talk action to read out these characters:

Then finally, we return this NCCO instead of $params['from']:

When we put it all together, index.php looks like the following:

Visit http://localhost:8000/webhook/answer?from=14155550100 again and you will see the following returned:

Congratulations! You just wrote an application that receives an inbound phone call and responds with some dynamic content. You can customise your response using any of the parameters that Nexmo provide, including to, from and conversation_uuid.

Exposing your application with ngrok

We’ve built an application that responds how we’d expect, but there’s one big problem at the moment. Nexmo are supposed to make a request to it when a call is received but it’s running on our local machine!

Don’t worry though, ngrok can save the day. If you’re unfamiliar with ngrok, there’s a fantastic introduction to ngrok available on the Nexmo blog.

Once you have ngrok installed, run ngrok http 8000 to expose your application to the internet. You’ll need to make a note of the ngrok URL generated as we’ll need to provide it to Nexmo (it’ll look something like http://abc123.ngrok.io).

Configure your Nexmo account

Once your application is exposed to the internet, the final thing to do is hook it up to a Nexmo phone number. Let’s start by purchasing a phone number using the Nexmo CLI:

Make a note of the number you just purchased, as we’ll need it in just a second!

The next step is to create a Nexmo application, which is a container for all the settings required for your application. In this case we need to tell Nemxo which URL to make a request to when a call is received (answer_url), and where to send any event information about the call (event_url).

We can use the Nexmo CLI to create an application, making sure to substitute http://abc123.ngrok.io for your own generated URL. We provide a name, then an answer_url and event_url for the application:

You can ignore the private key output as it is not required to receive inbound calls. Above the key is your new application’s ID. We do need that, so make a note (it’ll look similar to aaaaaaaa-bbbb-cccc-dddd-0123456789ab) then carry on reading.

The final thing to do is to link the number you purchased to the application you just created. This will tell Nexmo that when a call is received, they should make a GET request to the application’s answer_url to find out how to proceed with the call.

Once again, we can use the Nexmo CLI to do this, replacing the example phone number and application ID with your own:

That’s everything we needed to do for Nexmo to associate our PHP application to an incoming phone call. Give it a go now by calling the phone number you purchased.

Conclusion

Together, we just built an application that can receive an incoming phone call and dynamically generate a response in just 22 lines of code!

If you want to learn more about voice calls with PHP and Nexmo, you can find example building blocks in Nexmo Developer. Alternatively, if you want to make your inbound call response more complex (e.g. recording the audio from the caller) you can learn more about NCCOs in the NCCO reference

As always, if you have any questions about this post feel free to email [email protected] or join the Nexmo community Slack channel, where we’re waiting and ready to help.

Leave a Reply

Your email address will not be published.