Introduction

When you send a text message using the Vonage APIs, the HTTP response tells you whether the message was accepted for sending. It doesn’t tell you whether it actually reached the recipient’s handset.

To find that out, you need a delivery receipt. In this tutorial, you’ll learn how to receive SMS delivery receipts using the Vonage Messages API and Node.js.

Prerequisites

Before you begin, make sure you have the following:

Node.js installed. This tutorial uses Node.js 18 or later.

installed. This tutorial uses Node.js 18 or later.

ngrok installed and a free account set up. You’ll use it to expose your local server to the internet so Vonage can reach your webhook.

installed and a free account set up. You’ll use it to expose your local server to the internet so Vonage can reach your webhook.

The Vonage CLI installed. Run npm install -g @vonage/cli to install it globally.

The Vonage CLI installed. Run npm install -g @vonage/cli to install it globally.

A Vonage API account.

A Vonage API account.

How Delivery Receipts Work With the Messages API

When a message is delivered, the mobile carrier returns a delivery receipt to Vonage. If you’ve configured a webhook, Vonage forwards that receipt to your endpoint as a POST request.

The Messages API uses a Message Status webhook for this purpose. This is the Messages API equivalent of the Delivery Receipt (DLR) used by the SMS API. Rather than a single callback, you’ll typically receive two: one with a status of submitted when the message is accepted by the carrier, and a second with a status of delivered once it reaches the handset.

The Messages API status webhook supports the following status values:

submitted: the message has been accepted for delivery

submitted: the message has been accepted for delivery

delivered: the message has been delivered to the handset

delivered: the message has been delivered to the handset

rejected: the carrier refused to deliver the message

rejected: the carrier refused to deliver the message

undeliverable: Messages API was unable to connect to the messaging provider, may be due to a messaging provider outage or other incident

undeliverable: Messages API was unable to connect to the messaging provider, may be due to a messaging provider outage or other incident

See the Messages API Status Callbacks documentation for more details.

Set Up ngrok

is a cross-platform tool that creates a public URL pointing to a server running on your local machine. You’ll use it to expose your webhook so Vonage can send POST requests to it during development.

Once ngrok is installed and you’re logged in, run the following command:

After it starts, ngrok will display a Forwarding URL that looks something like this:

Note that URL; you’ll need it in the next step.

Note: On the free plan, the ngrok URL changes every time you restart the server. You’ll need to update your webhook URLs in the Vonage Dashboard whenever that happens.

Note: On the free plan, the ngrok URL changes every time you restart the server. You’ll need to update your webhook URLs in the Vonage Dashboard whenever that happens.

Configure Your Vonage Account

Switch to the Messages API

Sign in to your Vonage API Dashboard and go to API Settings. In the Messaging API type section, select Messages API and save your changes.

This tells Vonage to use the Messages API format for all SMS webhooks on your account.

Create a Vonage Application

The Messages API uses application-level configuration, meaning your webhook URLs and authentication credentials are tied to a specific Vonage Application and override the account-level settings.

In the Dashboard, go to Applications and click Create a new application. Give it a name, something like SMS Delivery Receipts works well.

Click Generate public and private key. Your browser will download a private.key file. You’ll need to move it into your project directory once created, then add it to your .gitignore so it doesn’t end up in version control.

Under Capabilities, enable Messages and fill in both webhook URLs using your ngrok Forwarding URL:

Click Generate new application to save. On the application page, scroll to Link virtual numbers and link the Vonage number you’ll use to send SMS messages.

Set Up the Node.js Project

Open a terminal, create a new directory for your project, and initialise it:

Install Express and body-parser:

You’ll use Express to handle incoming webhook requests and body-parser to parse the JSON payloads.

Write the Webhook Handler

Create a file called index.js and add the following code:

The /webhooks/message-status endpoint is where Vonage will send delivery status updates. The handler logs the request body to the console and returns a 200 response.

The /webhooks/inbound-message endpoint handles incoming SMS messages. You don’t need to do anything with inbound messages for this tutorial, but the endpoint must exist and return 200. Without it, Vonage will keep retrying inbound message callbacks and may queue up a backlog.

Run the Application

Start the server with the following command:

You should see the server listening on port 3000 in your terminal.

Now send a text message from your Vonage virtual number to your mobile phone. You can do this using the Vonage CLI or a curl request:

Replace YOUR_PHONE_NUMBER with your personal number (including country code, no leading +), YOUR_VONAGE_NUMBER with your Vonage virtual number, and $JWT with a JWT generated for your application.

What to Expect

If the message is delivered successfully, you’ll see two callbacks in your terminal. The first arrives shortly after sending:

A few seconds later, you’ll receive the delivery confirmation:

The message_uuid field links both callbacks to the same message. You can use it to track delivery status in your application. For example, you can store it in a database when you send the message and update the record when the status callback arrives.

Conclusion

You’ve set up a Node.js application that receives SMS delivery receipts using the Vonage Messages API. Along the way, you configured a Vonage Application with a Message Status webhook, wrote handlers for both the status and inbound message endpoints, and tested the full delivery flow.

From here, you could extend this project to: