Receiving SMS Delivery Receipts with PHP

Published June 25, 2018 by Michael Heap

We’ve previously covered sending and receiving SMS messages with PHP, but there’s one thing missing – delivery receipts.

Delivery receipts are sent when a message is received by a handset, by a network or not at all depending on the network that you’re sending a message to. You can find more information about this on the Nexmo knowledge base.

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


To work through this post, you’ll need a Nexmo account.

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 it to configure our delivery receipt URL on our Nexmo account.

Receiving an SMS delivery receipt with PHP

When a network informs Nexmo that an SMS message has been delivered, Nexmo can forward that information on to your application as a HTTP request.

When Nexmo receives an SMS for a phone number that you own, they make a HTTP request to a URL that you’ve configured containing all of the information about the SMS. (Don’t worry about configuring this URL yet, we’ll get to it a little later on)

To receive the delivery receipt, we’re going to be using the Slim framework Let’s install it now with composer:

Nexmo will make either a GET or a POST request to your application with the data, depending on how your account is configured (you can find your selected HTTP Method in the dashboard). In this post, we’ll write an application that can handle both HTTP methods.

To handle the incoming request, we’ll create a new Slim application and register a handler that responds to both GET and POST to /webhooks/delivery-receipt. To do this, create a file named index.php with the following contents:

This application will handle the incoming request and respond with a success code to Nexmo, but it doesn’t do anything yet. We want to take the incoming request values and log them out to the terminal. To do this we’ll check the POST body for values, falling back to GET parameters. Once we have an array of $params, we’ll log it out to the terminal using error_log. Update your $handler to look like the following:

That’s all we need to log incoming delivery receipts from Nexmo using PHP.

Exposing your application with ngrok

Whilst we have an application ready to handle delivery receipts, we need to expose it to the internet so that Nexmo can send requests to it.

We can use ngrok to expose our local application to the internet by running ngrok http 8000. Make a note of the ngrok URL generated (it’ll look something like as we need to provide this URL to Nexmo so that they know where to send the delivery receipt.

Configure your Nexmo account

The final thing to do is to configure the webhook URL for delivery receipts in the Nexmo dashboard. Visit your settings page, update Webhook URL for Delivery Receipt with your ngrok URL (e.g. and click Save Changes.

At this point, we can send an SMS and watch the delivery receipt arrive. You can either send an SMS using PHP or use the Nexmo CLI to send it. To keep things easy, let’s send an SMS using the CLI.

Not all countries support alpha senders. If this is the case, you may need to purchase a number by running nexmo number:buy --country_code US and use that as your from parameter

Open up a terminal and run the following to send an SMS:

It may take a few minutes due to network latency, but the SMS should be delivered soon and the delivery receipt should arrive soon after.


Receiving an SMS delivery receipt is very similar to receiving an inbound SMS message. When Nexmo receives data from the network, they transform it in to a HTTP request and send it to a URL that you have configured.

Nexmo Developer has more information on receiving SMS delivery receipts with PHP, including a flow diagram about how data is exchanged between you, Nexmo and the phone carrier.

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.

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 [email protected].