Send SMS and Receive Delivery Status with Node.js, Express, and Vonage

This guide provides a complete walkthrough for building a Node.js application using the Express framework to send SMS messages via the Vonage Messages API and receive real-time delivery status updates through webhooks.

By the end of this tutorial, you will have a functional application capable of programmatically sending SMS and reliably tracking their delivery status – essential features for applications requiring notifications, alerts, or two-factor authentication.

Project Overview and Goals

What We're Building:

A Node.js backend application consisting of two main parts:

1. A script (index.js) to send an SMS message using the Vonage Messages API.
2. An Express server (server.js) to listen for incoming webhook requests from Vonage, specifically focusing on delivery status updates for the messages we send.

Problem Solved:

Many applications need to send SMS messages, but simply firing off an API request doesn't guarantee delivery. Mobile carriers might reject messages, or phones might be turned off. This guide addresses the need for reliable SMS delivery tracking by implementing status webhooks, providing confirmation (or failure reasons) for sent messages.

Technologies Used:

• Node.js: A popular JavaScript runtime for building scalable backend applications.
• Express: A minimal and flexible Node.js web application framework, ideal for creating API endpoints and webhook listeners.
• Vonage Messages API: A powerful API enabling communication across multiple channels (SMS, MMS, WhatsApp, etc.). We'll use it specifically for sending SMS and leveraging its webhook capabilities for status updates.
• @vonage/server-sdk: The official Vonage Node.js SDK simplifies interaction with the Vonage APIs.
• dotenv: A utility to load environment variables from a .env file, keeping sensitive credentials out of source code.
• ngrok: A tool to expose local development servers to the public internet, necessary for Vonage webhooks to reach our local machine during development.

System Architecture:

(This is a simplified text-based representation of the flow.)

+-------------------+      +-----------------+      +----------------+      +--------------+
| Your Node.js App  |----->|  Vonage API     |----->| Mobile Carrier |----->| User's Phone |
| (index.js)        |      | (Messages API)  |      +----------------+      +--------------+
+-------------------+      +-----------------+             |
                                   |                       | (Delivery Status)
                                   |                       V
+-------------------+      +-----------------+      +----------------+
| Your Express App  |<-----|  Vonage Webhook |<-----| Mobile Carrier |
| (server.js)       |      | (Status URL)    |      +----------------+
| Running on ngrok  |      +-----------------+
+-------------------+

Prerequisites:

1. Node.js and npm (or yarn): Installed on your system. (Download: https://nodejs.org/)
2. Vonage API Account: Sign up for free at https://dashboard.nexmo.com/sign-up. You'll receive free credits to start.
3. Vonage Phone Number: Purchase an SMS-capable virtual number from the Vonage Dashboard (Numbers > Buy numbers).
4. ngrok: Installed and authenticated. A free account is sufficient. (Download: https://ngrok.com/download)
5. Basic Terminal/Command Line Knowledge: Navigating directories, running commands.

Expected Outcome:

A local Node.js application that can:

• Send an SMS message to a specified phone number via a script.
• Receive and log delivery status updates (e.g., submitted, delivered, rejected) for sent messages in the server console.

1. Setting up the Project

Let's initialize our Node.js project and install the necessary dependencies.

1. Create Project Directory: Open your terminal or command prompt and create a new directory for the project, then navigate into it.

   bashCopy

   # Terminal
   mkdir vonage-sms-status-guide
   cd vonage-sms-status-guide

2. Initialize Node.js Project: This creates a package.json file to manage project dependencies and scripts.

   bashCopy

   # Terminal
   npm init -y

3. Install Dependencies: We need the Vonage SDK, the Express framework, and dotenv for environment variables.

   bashCopy

   # Terminal
   npm install @vonage/server-sdk express dotenv

4. Create Project Files: Create the main files for our sending script and our webhook server.

   bashCopy

   # Terminal (Linux/macOS)
   touch index.js server.js .env .env.example .gitignore
   
   # Terminal (Windows - PowerShell)
   New-Item index.js, server.js, .env, .env.example, .gitignore -ItemType File

5. Configure .gitignore: It's crucial to prevent committing sensitive information and unnecessary files to version control (like Git). Add the following to your .gitignore file:

   textCopy

   # .gitignore
   
   # Node dependencies
   node_modules/
   
   # Environment variables
   .env
   
   # OS generated files
   .DS_Store
   Thumbs.db

6. Set up Environment Variables (.env.example and .env): Environment variables allow us to configure the application without hardcoding sensitive values like API keys.

   • .env.example (Template for others): Add the following structure to .env.example. This file can be committed to Git as it shows what variables are needed, but contains no actual secrets.

     dotenvCopy

     # .env.example
     
     # Vonage API Credentials (Find on your Vonage Dashboard)
     # Note: While included, Messages API auth primarily uses Application ID/Private Key below.
     # Key/Secret might be used by other SDK functions or for legacy compatibility.
     VONAGE_API_KEY=YOUR_VONAGE_API_KEY
     VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
     
     # Vonage Application Credentials (Generated when creating a Vonage Application)
     # These are the primary credentials used for sending via Messages API in this guide.
     VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
     VONAGE_PRIVATE_KEY_PATH=./private.key # Or the actual path to your downloaded key
     
     # Vonage Number (Must be purchased from Vonage Dashboard and linked to the Application)
     VONAGE_NUMBER=YOUR_VONAGE_VIRTUAL_NUMBER
     
     # Recipient Number (The phone number to send the SMS to, include country code e.g., 15551234567)
     TO_NUMBER=RECIPIENT_PHONE_NUMBER
     
     # Port for the Express server
     PORT=3000

   • .env (Your actual secrets - DO NOT COMMIT TO GIT): Copy the contents of .env.example into .env and replace the placeholder values with your actual credentials and numbers. We'll get the VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY_PATH in the next section. Leave them blank for now or use temporary placeholders.

     dotenvCopy

     # .env (Replace with your actual values!)
     
     # Note: While included, Messages API auth primarily uses Application ID/Private Key below.
     VONAGE_API_KEY=abcdef1234567890
     VONAGE_API_SECRET=fedcba0987654321
     
     # These are the primary credentials used for sending via Messages API in this guide.
     VONAGE_APPLICATION_ID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
     VONAGE_PRIVATE_KEY_PATH=./private.key
     
     VONAGE_NUMBER=12015550100
     TO_NUMBER=15551234567
     
     PORT=3000

Project Structure:

Your project directory should now look like this (potentially with a private.key file after Section 2):

vonage-sms-status-guide/
├── node_modules/
├── .env
├── .env.example
├── .gitignore
├── index.js
├── package-lock.json
├── package.json
└── server.js

2. Integrating with Vonage (Configuration)

Before writing code, we need to configure our Vonage account and application correctly. The Messages API relies on a Vonage Application for authentication and webhook configuration when sending messages.

1. Log in to Vonage Dashboard: Access your dashboard at https://dashboard.nexmo.com/.

2. Find API Key and Secret: On the main dashboard page, you'll find your API key and API secret. Copy these into your .env file for VONAGE_API_KEY and VONAGE_API_SECRET. (As noted previously, the Messages API primarily uses Application ID/Private Key for sending in this guide, but including these is common practice for the SDK).

3. Ensure You Have a Vonage Number: Navigate to Numbers > Your numbers (UI paths may change; look for similar options if needed). If you don't have one, go to Buy numbers, select your country, ensure SMS capability is checked, search, and purchase a number. Copy this number (including country code, e.g., 12015550100) into your .env file for VONAGE_NUMBER.

4. Create a Vonage Application:

   • Navigate to Applications > + Create a new application (UI paths may change; look for similar options if needed).
   • Give your application a descriptive name (e.g., Node SMS Status Guide App).
   • Click Generate public and private key. This will automatically download a private.key file. Save this file directly into your vonage-sms-status-guide project directory (or note the path). Update VONAGE_PRIVATE_KEY_PATH in your .env file accordingly (e.g., ./private.key).
   • Under Capabilities, toggle Messages ON.
   • Two fields will appear: Inbound URL and Status URL.
     • For Status URL, enter a placeholder for now: http://example.com/webhooks/status. We'll update this later with our ngrok URL. Use POST as the HTTP Method.
     • For Inbound URL, enter http://example.com/webhooks/inbound. Use POST. (We aren't receiving SMS in this guide, but the field is often required).
   • Scroll down to Link virtual numbers and link the Vonage number you purchased earlier to this application.
   • Click Create application.
   • You'll be taken back to the Applications list. Find your new application and copy its Application ID. Paste this into your .env file for VONAGE_APPLICATION_ID.

5. Verify SMS API Settings (Optional but good practice):

   • Navigate to Settings.
   • Scroll down to API Settings.
   • Under Default SMS Setting, ensure Messages API is selected if you intend for all SMS interactions account-wide to default to it. However, our code specifically uses the Messages API via the Application ID/Private Key, so this setting is less critical for this specific guide but good to be aware of.
   • Important: Do not configure the Delivery receipts (DLR) webhooks field in the main account settings if you are using the Messages API Status URL within a Vonage Application. They serve similar purposes but are configured differently (Application Status URL vs. global SMS API DLR). Using the Application Status URL is the standard way for the Messages API.

You have now configured your Vonage account, created an application, linked your number, and obtained all necessary credentials for your .env file.

3. Implementing Core Functionality: Sending SMS

Let's write the code to send an SMS message using the Vonage SDK and the credentials we've set up.

1. Edit index.js: Open index.js and add the following code:

   javascriptCopy

   // index.js
   'use strict';
   
   // Load environment variables from .env file
   require('dotenv').config();
   
   // Import the Vonage SDK
   const { Vonage } = require('@vonage/server-sdk');
   const { SMS } = require('@vonage/messages');
   
   // --- Configuration ---
   // Retrieve credentials and numbers from environment variables
   const vonageApiKey = process.env.VONAGE_API_KEY; // Included for SDK convention
   const vonageApiSecret = process.env.VONAGE_API_SECRET; // Included for SDK convention
   const vonageApplicationId = process.env.VONAGE_APPLICATION_ID; // Primary auth for Messages API
   const vonagePrivateKeyPath = process.env.VONAGE_PRIVATE_KEY_PATH; // Primary auth for Messages API
   const vonageNumber = process.env.VONAGE_NUMBER;
   const recipientNumber = process.env.TO_NUMBER;
   
   // --- Input Validation (Basic) ---
   // Ensure all required environment variables are set
   if (!vonageApplicationId || !vonagePrivateKeyPath || !vonageNumber || !recipientNumber) {
       console.error(`Error: Missing required environment variables. Check your .env file.`);
       console.error(` VONAGE_APPLICATION_ID: ${vonageApplicationId ? 'Found' : 'Missing'}`);
       console.error(` VONAGE_PRIVATE_KEY_PATH: ${vonagePrivateKeyPath ? 'Found' : 'Missing'}`);
       console.error(` VONAGE_NUMBER: ${vonageNumber ? 'Found' : 'Missing'}`);
       console.error(` TO_NUMBER: ${recipientNumber ? 'Found' : 'Missing'}`);
       process.exit(1); // Exit if configuration is incomplete
   }
   
   // --- Initialize Vonage Client ---
   // Using Application ID and Private Key for authentication with Messages API
   const vonage = new Vonage({
       apiKey: vonageApiKey,       // Included per SDK convention
       apiSecret: vonageApiSecret, // Included per SDK convention
       applicationId: vonageApplicationId,
       privateKey: vonagePrivateKeyPath,
   });
   
   // --- Send SMS Function ---
   async function sendSms() {
       console.log(`Attempting to send SMS from ${vonageNumber} to ${recipientNumber}...`);
   
       // Define the message content
       const textContent = `Hello from Vonage! This is a test message sent on ${new Date().toLocaleTimeString()}. (Sent: ${Date.now()})`; // Add timestamp to make unique
   
       try {
           // Use the Messages API to send an SMS
           const resp = await vonage.messages.send(
               new SMS({
                   to: recipientNumber,
                   from: vonageNumber,
                   text: textContent,
               })
           );
   
           // Log the success response (contains message_uuid)
           console.log('SMS Submitted Successfully!');
           console.log('Message UUID:', resp.messageUuid); // Crucial for tracking status
   
       } catch (err) {
           // Log any errors that occur during sending
           console.error('Error sending SMS:');
           // Log specific Vonage API errors if available
           if (err.response && err.response.data) {
               console.error('API Response Error:', JSON.stringify(err.response.data, null, 2));
           } else {
               console.error(err); // Log the general error object
           }
           process.exitCode = 1; // Indicate failure
       }
   }
   
   // --- Execute Sending ---
   sendSms();

2. Code Explanation:

   • require('dotenv').config();: Loads variables from the .env file into process.env.
   • require('@vonage/server-sdk'): Imports the main Vonage SDK class.
   • require('@vonage/messages'): Imports the specific SMS class helper for constructing message objects, improving clarity.
   • Configuration Loading: Retrieves necessary credentials and numbers from process.env.
   • Input Validation: A basic check ensures critical environment variables are present before proceeding. Uses 'Found' : 'Missing' for clearer logging.
   • new Vonage(...): Initializes the Vonage client. For the Messages API, authentication primarily uses the applicationId and privateKey. The apiKey and apiSecret are included following SDK conventions but are not the primary auth method for this specific Messages API call.
   • sendSms() Function:
     • An async function to handle the asynchronous nature of the API call.
     • Constructs the SMS message using new SMS({...}). The to and from numbers are taken from environment variables, and a simple text message is defined. Adding a timestamp makes each message unique, which helps in testing.
     • vonage.messages.send(...): This is the core SDK method call to send the message via the Messages API.
     • Success Logging: If the await completes without throwing, the API has accepted the message for delivery. We log the messageUuid – this is the unique identifier Vonage assigns to the message, which will appear in the status webhook.
     • Error Handling: A try...catch block handles potential errors during the API call (e.g., network issues, invalid credentials, malformed requests). It logs detailed error information if available from the Vonage API response.

You can try running this now (node index.js), but the status updates won't work until we set up the webhook server and ngrok. You should see either a "SMS Submitted Successfully!" message with a UUID or an error in your console.

4. Implementing the Webhook Server for Status Updates

Now, we'll create the Express server that Vonage will send delivery status updates to.

1. Edit server.js: Open server.js and add the following code:

   javascriptCopy

   // server.js
   'use strict';
   
   // Load environment variables from .env file
   require('dotenv').config();
   
   // Import Express
   const express = require('express');
   const { json, urlencoded } = express; // Import body parsing middleware
   
   // --- Configuration ---
   const port = process.env.PORT || 3000; // Use port from .env or default to 3000
   const webhookPath = '/webhooks/status'; // The specific path for our status webhook
   
   // --- Initialize Express App ---
   const app = express();
   
   // --- Middleware ---
   // Enable parsing of JSON request bodies (Vonage sends JSON)
   app.use(json());
   // Enable parsing of URL-encoded request bodies (less common for Vonage webhooks, but good practice)
   app.use(urlencoded({ extended: true }));
   
   // --- Webhook Route Handler ---
   // Define a POST route handler for the status webhook path
   app.post(webhookPath, (req, res) => {
       console.log('--- Status Webhook Received ---');
       console.log('Timestamp:', new Date().toISOString());
   
       // Log the entire request body received from Vonage
       console.log('Request Body:', JSON.stringify(req.body, null, 2));
   
       // --- Extract Key Information (Example) ---
       // You would typically process this data, e.g., update a database
       const { message_uuid, status, timestamp, to, from, error, client_ref } = req.body;
   
       console.log(`\nExtracted Info:`);
       console.log(`  Message UUID: ${message_uuid}`);
       console.log(`  Status: ${status}`); // e.g., submitted, delivered, rejected, undeliverable
       console.log(`  Timestamp: ${timestamp}`);
       console.log(`  To: ${to}`);
       console.log(`  From: ${from}`);
       if (error) {
           console.log(`  Error Code: ${error.code}`);
           console.log(`  Error Reason: ${error.reason}`);
       }
       if (client_ref) {
           console.log(`  Client Reference: ${client_ref}`); // If you sent one
       }
       console.log('------------------------------\n');
   
       // --- Acknowledge Receipt ---
       // IMPORTANT: Respond with a 2xx status code (e.g., 200 OK or 204 No Content)
       // to let Vonage know the webhook was received successfully.
       // Failure to do so will cause Vonage to retry sending the webhook.
       res.status(204).send(); // 204 No Content is often suitable
   });
   
   // --- Default Route (Optional) ---
   // A simple root route to check if the server is running
   app.get('/', (req, res) => {
       res.send(`Webhook server running. Listening for POST requests on ${webhookPath}.`);
   });
   
   // --- Start Server ---
   app.listen(port, () => {
       console.log(`Webhook server listening on http://localhost:${port}`);
       console.log(`Expecting status webhooks at POST ${webhookPath}`);
   });

2. Code Explanation:

   • require('express'): Imports the Express framework.
   • express.json() & express.urlencoded(): Middleware essential for parsing the incoming request body. Vonage webhooks typically send data as JSON, so express.json() is crucial.
   • webhookPath: Defines the URL path (/webhooks/status) where the server will listen for incoming status updates. This must match the path configured in the Vonage Application's Status URL.
   • app.post(webhookPath, ...): Sets up a route handler specifically for POST requests to our defined path. This is where Vonage will send the data.
   • Logging: Inside the handler, we log the timestamp and the entire req.body (the data sent by Vonage) to the console. This is invaluable for debugging and understanding the data structure.
   • Data Extraction: We demonstrate how to pull out key fields like message_uuid, status, timestamp, and potential error details from the request body. In a real application, you'd use this data (especially message_uuid and status) to update your application's state (e.g., mark a message as delivered in a database).
   • res.status(204).send(): Critically important. This line sends an HTTP 204 No Content response back to Vonage. Any 2xx status code tells Vonage ""I received the webhook successfully."" If you don't send a 2xx response (or if your server errors out), Vonage will assume the webhook failed and will retry sending it multiple times, potentially leading to duplicate processing.
   • app.listen(...): Starts the Express server, making it listen for incoming requests on the specified port.

5. Running and Verifying with ngrok

Now we tie everything together using ngrok to expose our local webhook server to the internet so Vonage can reach it. This typically involves running processes in separate terminal windows: one for ngrok, one for the webhook server (server.js), and one to run the sending script (index.js).

(Note: For managing multiple processes during development, alternatives exist like running server/script in the background using & in Bash, or using terminal multiplexers like tmux or screen, though these are beyond the scope of this basic guide.)

1. Start ngrok: Open a new terminal window (keep the previous one for running the server/script). Run ngrok to forward traffic to the port your Express server will listen on (defined in .env, defaulting to 3000).

   bashCopy

   # Terminal 2: ngrok
   ngrok http 3000

   ngrok will display output similar to this:

   textCopy

   ngrok session starts             terminal_session
   Version          3.x.x
   Region           United States (us-cal-1)
   Latency          24ms
   Web Interface    http://127.0.0.1:4040
   Forwarding       https://<RANDOM_SUBDOMAIN>.ngrok-free.app -> http://localhost:3000
   
   Connections      ttl     opn     rt1     rt5     p50     p90
                    0       0       0.00    0.00    0.00    0.00

   Copy the https:// Forwarding URL (e.g., https://<RANDOM_SUBDOMAIN>.ngrok-free.app). This is your public URL.

2. Update Vonage Application Status URL:

   • Go back to your Vonage Dashboard > Applications.
   • Find the application you created earlier and click Edit.
   • In the Messages capability section, paste your full ngrok Forwarding URL into the Status URL field, making sure to append the correct path: YOUR_NGROK_URL/webhooks/status.
     • Example: https://<RANDOM_SUBDOMAIN>.ngrok-free.app/webhooks/status
   • Ensure the HTTP Method is POST.
   • Click Save changes.

3. Start the Webhook Server: Go back to your first terminal window (where your project code is). Start the Express server:

   bashCopy

   # Terminal 1: Project Directory
   node server.js

   You should see:

   textCopy

   Webhook server listening on http://localhost:3000
   Expecting status webhooks at POST /webhooks/status

4. Send a Test SMS: Open another new terminal window (or reuse Terminal 1 after stopping the server if needed, but it's easier to keep the server running). Navigate to your project directory and run the sending script:

   bashCopy

   # Terminal 3 (or reuse Terminal 1): Project Directory
   node index.js

   You should see the "SMS Submitted Successfully!" message and the messageUuid logged in this terminal.

5. Verify Delivery Status:

   • Check your recipient phone; you should receive the SMS within a few seconds to a minute.
   • Watch the terminal window where server.js is running (Terminal 1).
   • You should see log output starting with --- Status Webhook Received ---.
   • Initially, you might see a status like submitted.
   • Shortly after the message arrives on the phone, you should receive another webhook call with status: delivered.
   • Look for the message_uuid in the logged webhook body – it should match the UUID logged by index.js.

   Example server.js output for a delivered message (Timestamps updated):

   textCopy

   Webhook server listening on http://localhost:3000
   Expecting status webhooks at POST /webhooks/status
   --- Status Webhook Received ---
   Timestamp: 2023-10-27T10:30:15.123Z
   Request Body: {
     "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-111111111111",
     "to": "15551234567",
     "from": "12015550100",
     "timestamp": "2023-10-27T10:30:15.000Z",
     "status": "submitted",
     "channel": "sms",
     "usage": {
       "currency": "EUR",
       "price": "0.0050"
     }
   }
   ------------------------------
   
   --- Status Webhook Received ---
   Timestamp: 2023-10-27T10:30:18.456Z
   Request Body: {
     "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-111111111111",
     "to": "15551234567",
     "from": "12015550100",
     "timestamp": "2023-10-27T10:30:18.000Z",
     "status": "delivered",
     "channel": "sms",
     "usage": {
       "currency": "EUR",
       "price": "0.0050"
     }
   }
   
   Extracted Info:
     Message UUID: aaaaaaaa-bbbb-cccc-dddd-111111111111
     Status: delivered
     Timestamp: 2023-10-27T10:30:18.000Z
     To: 15551234567
     From: 12015550100
   ------------------------------

Congratulations! You've successfully sent an SMS and received its delivery status via a webhook.

6. Error Handling and Logging

• Sending Errors (index.js): The try...catch block in index.js catches errors during the initial API call (e.g., invalid credentials, insufficient funds, malformed request). Logging err.response.data provides specific Vonage error details.
• Webhook Errors (server.js):
  • Vonage Retries: If your server.js crashes or fails to return a 2xx status, Vonage will retry sending the webhook. Design your webhook handler to be idempotent (processing the same webhook multiple times should not cause adverse effects, e.g., check if you've already processed that message_uuid and status before updating a database).
  • Logging: The console.log statements are basic logging. For production, use a dedicated logging library (like winston or pino) to structure logs, write to files, and set log levels (info, warn, error).
• Delivery Status Errors: The status field in the webhook payload indicates delivery issues (e.g., rejected, undeliverable). The optional error object within the payload provides carrier-specific error codes and reasons, which can be logged for debugging delivery failures.

7. Security Considerations

• API Credentials: Never commit your .env file or hardcode credentials in your source code. Use environment variables and ensure .env is in your .gitignore.
• Webhook Security: CRITICAL FOR PRODUCTION: Publicly accessible webhooks can be called by anyone, not just Vonage. The code provided here does not verify incoming webhooks and is vulnerable if exposed publicly without additional security. For production environments, you must implement webhook signature verification. Vonage signs its webhook requests, allowing your server to cryptographically verify that the request genuinely came from Vonage and hasn't been tampered with. Failure to do this poses a significant security risk. Refer to the official Vonage documentation on Signed Webhooks for detailed instructions and implementation examples using libraries like jsonwebtoken or Node.js's built-in crypto module.
• Input Validation: Sanitize and validate any data extracted from webhooks after signature verification, before using it in database queries or other critical operations to prevent injection attacks or unexpected behavior.

8. Troubleshooting and Caveats

• ngrok Not Working: Ensure ngrok is running and you've correctly copied the https:// URL and appended /webhooks/status in the Vonage Application settings. Check firewalls if issues persist. Remember ngrok URLs change each time you restart it (unless you have a paid plan with static domains).
• No Webhooks Received:
  • Verify the Status URL in the Vonage Application is correct (HTTPS, correct path, POST method).
  • Ensure server.js is running and listening on the correct port (ngrok forwards to).
  • Check the ngrok web interface (http://127.0.0.1:4040 by default) for incoming requests and potential errors.
  • Confirm the Vonage number is linked to the correct Vonage Application.
• Incorrect Credentials Error: Double-check VONAGE_APPLICATION_ID and the path to VONAGE_PRIVATE_KEY_PATH in your .env file. Ensure the private.key file exists at that path and has the correct read permissions. Also verify VONAGE_API_KEY and VONAGE_API_SECRET if the SDK throws errors related to them.
• SMS Not Sent/Received:
  • Verify TO_NUMBER and VONAGE_NUMBER in .env are correct (include country code, no dashes/spaces).
  • Check your Vonage account balance.
  • Ensure the destination country/carrier is supported by Vonage and doesn't have restrictions on your Vonage number type.
  • Check index.js logs for specific API errors.
• Delivery Receipt (DLR) Delays/Missing: DLRs depend on downstream carriers reporting back to Vonage. Delays can occur. Not all carriers or number types reliably provide DLRs (especially for statuses beyond submitted). The delivered status is the most reliable confirmation.
• Multiple Webhook Calls for One Message: You will typically receive multiple status updates for a single message (e.g., submitted, then later delivered or failed). Your handler logic should account for this sequence.

9. Deployment and CI/CD (Conceptual)

• Hosting: Deploy server.js to a hosting provider (like Heroku, AWS EC2/Lambda, Google Cloud Run, DigitalOcean App Platform).
• Environment Variables: Configure your production environment variables securely through your hosting provider's interface (do not include the .env file in your deployment package). Remember to include private.key content securely (e.g., via environment variable or secure file storage).
• Webhook URL: Update the Vonage Application Status URL to point to your live production server's public URL (e.g., https://your-app-domain.com/webhooks/status). ngrok is only for local development.
• Webhook Security: Implement signature verification in your production deployment as discussed in Section 7.
• Process Management: Use a process manager like pm2 to keep your Node.js server running reliably in production.
• CI/CD: Set up a pipeline (using GitHub Actions, GitLab CI, Jenkins, etc.) to automatically test, build, and deploy your application upon code changes.

10. Verification and Testing

1. Environment Setup: Ensure .env is correctly populated with valid credentials and numbers.
2. ngrok Running: Confirm ngrok is active and forwarding to the correct local port (e.g., 3000).
3. Vonage Config: Double-check Application Status URL matches ngrok + /webhooks/status and uses POST.