Record a Phone Message with PHP

Record a Phone Message with PHP

Published August 14, 2018 by Martyn Davies

Recording a phone message is the key first step in building a fully fledged voice mail system. In this tutorial, we’ll go through the steps required to set up a phone number with the ability to record an incoming call using PHP and the Nexmo command line interface.

The code for this tutorial can be found in our PHP Building Blocks section.


You’ll need the following things:

The code you will create is expected to work with any version of PHP 5.6 or above.

Our recommended way of working with Nexmo, from an administration point of view, is to use our command line tool, Nexmo-CLI.

In order to make the code on our local machine accessible to the outside world, we’re going to use ngrok, so ensure you have that installed as well.

Receiving and recording a phone message

Start by installing Slim into your working folder if you haven’t already done so.

You’ll need just one PHP file for this example, so create one called index.php in your working folder and open it in your editor of choice.

Add the following code to your index.php:

Let’s walk through what is happening here:

  1. The incoming call will be routed through to /webhooks/answer, then the NCCO will take over.
  2. The NCCO reads a message to the caller.
  3. Then the callers message is recorded.
  4. The recording data is passed to a new eventUrl, in this case /webhooks/recording.
  5. A message is spoken, letting the user know their message was received, and then the NCCO hangs up.

You’ll notice that it is the $ncco array that handles most of the work in this function.

NCCO stands for Nexmo Call Control Object and is a JSON array that you use to control the flow of a Voice API call.

You can dig deeper into the functionality of the NCCO, and learn more about how to extend the capabilities of your app by reading the reference documentation.

Handle the recorded message

In the code above, the NCCO has a record action with an eventUrl in it, which has been set to /webhooks/recording. This is where all the data about the recording, including the location of the recorded file, will be sent.

However, right now it doesn’t exist, so below the /webhooks/answer route, and before $app->run();, add this new code:

Let’s walk through this route and its function:

  1. It receives a POST request with a JSON object containing all kinds of info about our recording.
  2. It logs the URL of the recording that was made.
  3. Responds with the status 204, so the NCCO doesn’t keep trying to send this over and over again.

Running the code

Now, you’re set up and ready to run the code. You can do that by entering the following command in your terminal:

This will start a server and route any traffic to http://localhost:3000 through to your index.php file.

Expose your app with ngrok

In order to properly test this code, and allow Nexmo to make requests to your app, you need to expose the code running on your local machine to the world.

ngrok is our tool of choice for this, and we’ve provided a great introduction to the tool that you can read to get up to speed if you haven’t used it before.

Once you have ngrok installed, run ngrok http 3000 to expose your application to the internet. Make a note of the ngrok URL generated as you’ll need to provide it to Nexmo in the next step (it’ll look something like

Buy a number & connect your app

With the code completed, and your app available to the world, you now need to get yourself a phone number and link your app to it.

Start by purchasing a number via the Nexmo CLI:

You can use a different country code if you want to. Make a note of the number you purchase, as you’ll need it for the next step.

Next, use the Nexmo CLI to create your application making sure you substitute <your_ngrok_url> with the newly generated URL that ngrok gave you earlier:

The response you’ll get back will contain a huge private key output and, above that, an application ID.

Make a note of the application ID (which looks like this: e7b25242-77a1-42cd-a32e-09fbbcb375f4) and then link it to your new number using this command:

Now you code is connected to the number! You can test it out by dialling the number you purchased and following the steps that are magically spoken to you on the other end of the line!

Check your console output after you finish recording your message. There you’ll see the recording_url. If you want to then download this, take a look a the Download a recording building block and add that additional code to your app.


Once you know how to record messages, you can quickly extend this code into a more fully fledged voicemail system by writing the recording_url to a database and adding a simple front end to allow users to listen to messages.

You could also extend the app to send an SMS message notification to someone when a new message is recorded, or even email the recordings to a predetermined email address.

As ever, this is just the start. Feel free to ask questions, or share what you’ve been building in the Nexmo Community Slack channel, or directly with us on

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at