Vonage SMS with Node.js: Delivery Status Webhooks & Callbacks Tutorial

Build a Node.js Express server that sends SMS messages, receives inbound SMS, and handles delivery status updates via webhooks using the Vonage Messages API. This guide covers project setup, implementation, security, and deployment.

What you'll build:

1. Send SMS messages programmatically via an API endpoint.
2. Receive incoming SMS messages sent to your Vonage virtual number via webhook.
3. Receive delivery status updates for sent messages via webhook.

Technologies you'll use:

• Node.js: JavaScript runtime for server-side development.
• Express: Minimal Node.js web framework.
• Vonage Messages API: Multi-channel API for sending and receiving messages (focus on SMS).
• @vonage/server-sdk: Official Vonage Node.js SDK.
• ngrok: Exposes local servers to the internet for webhook testing.
• dotenv: Loads environment variables from a .env file.

System Architecture:

+-----------------+      +---------------------+      +-----------------+
| Your Application|----->| Vonage Messages API |----->|   SMS Network   |
| (Node.js/Express)| SMS Send Request (POST) |      | (Mobile Carrier)|
+-----------------+      +---------------------+      +-----------------+
       ^  |                      |  ^
       |  | Webhook (POST)       |  | Webhook (POST)
       |  | /webhooks/inbound    |  | /webhooks/status
       |  +----------------------|--+
       |                         |
       +-------------------------+
         Receives Inbound SMS    Receives Delivery Status
         & Delivery Status

Prerequisites:

• Vonage API account (Sign up here)
• Node.js and npm (or yarn) installed locally
• Vonage virtual phone number capable of sending/receiving SMS
• ngrok installed (Download here). Authenticate ngrok with ngrok authtoken your-token for stable URLs and longer sessions.
• Basic familiarity with Node.js, Express, and terminal commands

1. Set Up the Project

Initialize your Node.js project and install dependencies.

1. Create project directory: Open your terminal and create a new directory for the project.

   bash

   mkdir vonage-sms-app
   cd vonage-sms-app
   

2. Initialize Node.js project: Create a package.json file.

   bash

   npm init -y
   

3. Install dependencies: Install Express, the Vonage SDK, and dotenv.

   bash

   npm install express @vonage/server-sdk dotenv
   

4. Create project structure: Create the main application file and environment variables file.

   bash

   touch server.js .env .gitignore
   

5. Configure .gitignore: Prevent committing sensitive information and dependencies.

   # .gitignore
   node_modules
   .env
   private.key
   

   Note: Add private.key preemptively to ensure this sensitive file is never accidentally committed to version control.

6. Set up environment variables (.env): Create a .env file in the project root. You'll populate this with credentials from Vonage later.

   bash

   # .env - Placeholder values, replace later
   
   # Vonage Credentials (Obtained from Vonage Application)
   VONAGE_APPLICATION_ID=
   VONAGE_PRIVATE_KEY_PATH=./private.key # Path relative to project root
   
   # Vonage Number (Your purchased virtual number)
   VONAGE_NUMBER=
   
   # Your Test Mobile Number (For sending test messages)
   MY_NUMBER= # Use E.164 format, e.g., 15551234567
   
   # Server Port
   PORT=3000
   
   • VONAGE_APPLICATION_ID: Identifies your specific Vonage application.
   • VONAGE_PRIVATE_KEY_PATH: Local path to the private key file for authenticating API requests.
   • VONAGE_NUMBER: Your Vonage virtual phone number for sending SMS.
   • MY_NUMBER: Your personal mobile number for testing (use E.164 format).
   • PORT: Port your local Express server listens on.

2. Integrate with Vonage

Configure Vonage by creating an Application and linking a number to get credentials and webhook URLs.

1. Log in to Vonage Dashboard: Access your Vonage API Dashboard.

2. Purchase a virtual number: Navigate to Numbers → Buy numbers. Find a number with SMS capabilities in your desired country and purchase it.

3. Create a Vonage Application:

   • Navigate to Applications → Create a new application.
   • Name your application (e.g., "NodeJS SMS App").
   • Click Generate public and private key. Save the private.key file immediately and place it in your project's root directory.
   • Enable the Messages capability.
   • Enter temporary placeholders for Inbound URL and Status URL (e.g., http://example.com/webhooks/inbound and http://example.com/webhooks/status). Set HTTP Method to POST for both. You'll update these later with your ngrok URL.
   • Create the application.

4. Get Application ID: Copy the Application ID displayed after creation.

5. Link your virtual number:

   • On the application's settings page, find Linked numbers.
   • Link your purchased virtual number.

6. Update .env file: Populate your .env file with the Application ID and Vonage virtual number.

   bash

   # .env - Example with values filled
   
   VONAGE_APPLICATION_ID=your-actual-application-id # Paste from Vonage Dashboard
   VONAGE_PRIVATE_KEY_PATH=./private.key
   
   VONAGE_NUMBER=your-vonage-virtual-number # E.g., 12015550123
   MY_NUMBER=your-personal-mobile-number # E.g., 15551234567
   
   PORT=3000
   

7. Start ngrok: Open a new terminal window and run ngrok, pointing it to port 3000.

   bash

   ngrok http 3000
   

   Copy the Forwarding HTTPS URL (e.g., https://randomstring.ngrok.io).

8. Configure webhook URLs in Vonage Application:

   • Return to your Vonage Application settings (Applications → Your App Name → Edit).
   • Update the Messages capability URLs:
     • Inbound URL: https://randomstring.ngrok.io/webhooks/inbound
     • Status URL: https://randomstring.ngrok.io/webhooks/status
   • Ensure HTTP method is POST for both.
   • Save changes.

   Webhook URL purposes:

   • Inbound URL: Vonage sends data about incoming SMS messages (sent to your Vonage number) here.
   • Status URL: Vonage sends delivery status updates (e.g., submitted, delivered, rejected) for messages you send here.

3. Implement Core Functionality (Express Server)

Write the Node.js code in server.js to handle sending, receiving, and status updates.

// server.js

require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const { Vonage } = require('@vonage/server-sdk');
const fs = require('fs'); // Needed to read the private key file

// --- Configuration ---
const app = express();
const port = process.env.PORT || 3000;

// Express middleware to parse JSON and URL-encoded request bodies
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// --- Vonage SDK Initialization ---
let vonage;
try {
    // Check if private key file exists before initializing
    if (!fs.existsSync(process.env.VONAGE_PRIVATE_KEY_PATH)) {
        throw new Error(`Private key file not found at path: ${process.env.VONAGE_PRIVATE_KEY_PATH}`);
    }

    vonage = new Vonage({
        applicationId: process.env.VONAGE_APPLICATION_ID,
        privateKey: process.env.VONAGE_PRIVATE_KEY_PATH
    });
    console.log("Vonage SDK initialized successfully.");
} catch (error) {
    console.error("Error initializing Vonage SDK:", error.message);
    console.error("Ensure VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY_PATH are set correctly in your .env file and the private key file exists.");
    process.exit(1); // Exit if SDK initialization fails
}

// --- API Endpoint for Sending SMS ---
app.post('/send-sms', async (req, res) => {
    console.log("Received request to /send-sms:", req.body);

    const { to, text } = req.body;

    // Basic input validation – presence check only
    // TODO: Implement more robust validation (e.g., phone number format using libphonenumber-js, text sanitization) for production. See Section 6.
    if (!to || !text) {
        console.error("Validation Error: 'to' and 'text' fields are required.");
        return res.status(400).json({ error: "'to' and 'text' fields are required." });
    }
    if (!process.env.VONAGE_NUMBER) {
         console.error("Configuration Error: VONAGE_NUMBER is not set in .env");
         return res.status(500).json({ error: "Server configuration error: Sender number not set." });
    }

    const from = process.env.VONAGE_NUMBER;

    try {
        const resp = await vonage.messages.send({
            message_type: "text",
            to: to,
            from: from,
            channel: "sms",
            text: text,
        });

        console.log("Message sent successfully. Message UUID:", resp.message_uuid);
        res.status(200).json({ message: "SMS sent successfully", message_uuid: resp.message_uuid });

    } catch (error) {
        console.error("Error sending SMS:", error.response ? error.response.data : error.message);
        // Provide more specific error feedback if available from Vonage response
        if (error.response && error.response.data) {
            res.status(error.response.status || 500).json({
                error: "Failed to send SMS",
                details: error.response.data
            });
        } else {
            res.status(500).json({ error: "Failed to send SMS", details: error.message });
        }
    }
});

// --- Webhook Endpoint for Inbound SMS ---
// Vonage sends incoming messages here (POST request)
app.post('/webhooks/inbound', (req, res) => {
    // TODO: Implement webhook signature verification for production. See Section 6.
    console.log("--- Inbound SMS Received ---");
    console.log("From:", req.body.from);
    console.log("To:", req.body.to);
    console.log("Text:", req.body.text);
    console.log("Full Body:", JSON.stringify(req.body, null, 2)); // Log the full payload

    // Vonage expects a 2xx response to acknowledge receipt of the webhook
    res.status(200).end();
});

// --- Webhook Endpoint for Delivery Status Updates ---
// Vonage sends status updates for sent messages here (POST request)
app.post('/webhooks/status', (req, res) => {
    // TODO: Implement webhook signature verification for production. See Section 6.
    console.log("--- Delivery Status Update Received ---");
    console.log("Message UUID:", req.body.message_uuid);
    console.log("Status:", req.body.status);
    console.log("Timestamp:", req.body.timestamp);
    if(req.body.error) {
        console.error("Error Code:", req.body.error.code);
        console.error("Error Reason:", req.body.error.reason);
    }
    console.log("Full Body:", JSON.stringify(req.body, null, 2)); // Log the full payload

    // Vonage expects a 2xx response (200 OK or 204 No Content)
    res.status(200).end(); // Can also use res.sendStatus(204);
});

// --- Simple Root Route ---
app.get('/', (req, res) => {
    res.send('SMS Application is running!');
});

// --- Start Server ---
app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
    console.log(`Configure your ngrok forwarding URL in Vonage Dashboard.`);
    // Remind user about ngrok and environment variables
    if (!process.env.VONAGE_APPLICATION_ID || !process.env.VONAGE_PRIVATE_KEY_PATH || !process.env.VONAGE_NUMBER) {
        console.warn("WARN: One or more Vonage environment variables (APPLICATION_ID, PRIVATE_KEY_PATH, VONAGE_NUMBER) seem missing in .env");
    }
});

// --- Basic Error Handling Middleware (Optional but Recommended) ---
app.use((err, req, res, next) => {
    console.error("Unhandled Error:", err.stack);
    res.status(500).send('Something broke!');
});

Code explanation:

1. Dependencies & setup: Loads dotenv, imports express and Vonage, initializes Express, and sets up middleware for parsing request bodies.
2. Vonage SDK initialization: Creates a Vonage instance using the applicationId and privateKey path from .env. Includes error handling if the key file is missing or credentials are not set.
3. /send-sms (POST):
   • Defines an endpoint to trigger sending SMS.
   • Expects to (recipient number) and text (message content) in the JSON request body.
   • Performs basic presence validation (!to || !text). Note: Production applications need more robust validation (see Section 6).
   • Uses vonage.messages.send() with appropriate parameters (message_type, to, from, channel, text).
   • Logs the message_uuid upon successful submission to Vonage.
   • Includes try...catch for robust error handling, logging errors, and returning appropriate HTTP status codes (400 for bad input, 500 or specific Vonage status for API errors).
4. /webhooks/inbound (POST):
   • This endpoint matches the Inbound URL configured in Vonage.
   • When an SMS is sent to your VONAGE_NUMBER, Vonage makes a POST request here.
   • Logs the sender (from), recipient (to), message content (text), and the full request body. Note: Production applications should verify the webhook signature (see Section 6).
   • Sends back a 200 OK status using res.status(200).end(). If Vonage doesn't receive a 2xx response, it assumes the webhook failed and retries, potentially leading to duplicate processing.
5. /webhooks/status (POST):
   • This endpoint matches the Status URL configured in Vonage.
   • When the delivery status of an SMS you sent changes (e.g., submitted, delivered, failed, rejected), Vonage makes a POST request here.
   • Logs the message_uuid (linking it back to the sent message), the status, timestamp, any potential error details, and the full request body. Note: Production applications should verify the webhook signature (see Section 6).
   • Sends back a 200 OK status to acknowledge receipt.
6. Server start & basic error handling: Starts the Express server on the configured port and includes a basic catch-all error handler.

4. Running and Testing the Application

1. Ensure ngrok is running: Keep the terminal window where you started ngrok http 3000 open. Confirm the HTTPS URL is correctly configured in your Vonage Application settings.

2. Start the Node.js server: In the terminal window for your project directory (where server.js is), run:

   bash

   node server.js
   

   You should see output indicating the server is listening and the Vonage SDK initialized.

3. Test sending SMS: Open a new terminal window or use a tool like Postman or Insomnia to send a POST request to your /send-sms endpoint. Replace YOUR_PERSONAL_MOBILE_NUMBER with the actual value from your .env file (MY_NUMBER).

   Using curl:

   bash

   curl -X POST http://localhost:3000/send-sms \
   -H "Content-Type: application/json" \
   -d '{
     "to": "YOUR_PERSONAL_MOBILE_NUMBER", # Replace with your actual number (e.g., 15551234567)
     "text": "Hello from Vonage via Node.js! Test time: '"$(date)"'"
   }'
   
   • Expected outcome:
     • Terminal running curl: You should get a JSON response like {"message":"SMS sent successfully","message_uuid":"some-uuid-string"}.
     • Terminal running server.js: You'll see logs for the /send-sms request and "Message sent successfully…".
     • Your mobile phone: You should receive the SMS message shortly.
     • Terminal running server.js: Soon after, you should see logs from /webhooks/status showing the status changing (e.g., submitted, then potentially delivered). Check the message_uuid to match the sent message.

4. Test receiving inbound SMS:

   • From your personal mobile phone, send an SMS message to your VONAGE_NUMBER (the one configured in .env).
   • Expected outcome:
     • Terminal running server.js: You should see logs from /webhooks/inbound showing the message details (From:, To:, Text:).
     • ngrok terminal: You might see activity indicating POST requests to /webhooks/inbound.

5. Test delivery failure (optional): Try sending an SMS to an invalid or non-existent number via the /send-sms endpoint. Observe the /webhooks/status logs in your server.js terminal – you should receive statuses like failed or rejected with corresponding error codes/reasons.

5. Error Handling and Logging

• API Errors: The /send-sms route includes try...catch to handle errors during the Vonage API call. It attempts to parse and return specific error details from the Vonage response.
• Webhook Errors: If your webhook endpoints (/inbound, /status) encounter an error processing the request before sending the 200 OK, Vonage will retry. Implement robust internal error handling within these routes if you perform complex logic (e.g., database lookups).
• Logging: We are currently using console.log and console.error. For production, this is insufficient. Implement a structured logging library like winston or pino. This allows for better log formatting (e.g., JSON), writing logs to files or external services, setting different log levels (debug, info, warn, error), and easier log analysis. This guide does not include the implementation of structured logging.
• Vonage Retries: Vonage requires a 2xx status code response from your webhook endpoints within a reasonable time (usually a few seconds) to consider the delivery successful. Design your webhook handlers to be fast and acknowledge receipt quickly, performing heavier processing asynchronously if needed (e.g., using a message queue).

6. Security Considerations

• Environment Variables: Never commit your .env file or your private.key file to source control. Use a .gitignore file as shown. In production, use your hosting provider's mechanism for managing environment variables securely.
• Private Key Security: Treat your private.key file like a password. Ensure its file permissions restrict access (e.g., chmod 400 private.key on Linux/macOS).
• Webhook Security (Crucial for Production): The current implementation does not verify if incoming webhooks genuinely originate from Vonage. This is a security risk in production. Attackers could send fake requests to your webhook endpoints. The Vonage Messages API supports signing webhooks with JWT (JSON Web Tokens). You must:
  1. Configure a signature secret in your Vonage Application settings.
  2. Use a library like jsonwebtoken in your Node.js app (npm install jsonwebtoken).
  3. Implement logic in your /webhooks/inbound and /webhooks/status routes to verify the Authorization: Bearer <token&gt; header of incoming requests against your configured secret before processing the payload. This guide does not include the JWT verification implementation. Refer to the official Vonage documentation on "Signed Webhooks" for implementation details.
• Input Validation (Important for Production): The /send-sms endpoint currently only checks if to and text exist. This is insufficient for production. Add more robust validation:
  • Phone Number Format: Validate the to number against the E.164 standard using a library like libphonenumber-js (npm install libphonenumber-js).
  • Text Sanitization: If the text content could potentially come from user input elsewhere in your system, sanitize it to prevent cross-site scripting (XSS) or other injection attacks, depending on how you use the text later. This guide does not include robust input validation implementation.
• Rate Limiting (Recommended for Production): To prevent abuse of your /send-sms endpoint (either accidental or malicious), implement rate limiting. Use middleware like express-rate-limit (npm install express-rate-limit) to restrict the number of requests a user can make in a given time window. Check Vonage's own API rate limits as well. This guide does not include rate limiting implementation.

7. Troubleshooting and Caveats

• ngrok Issues:
  • Ensure ngrok is running and hasn't timed out (free accounts have session limits). Authenticating ngrok might provide longer/more stable sessions.
  • Double-check the HTTPS URL from ngrok matches exactly what's configured in the Vonage Application Inbound URL and Status URL.
  • Firewalls might block ngrok; ensure your network allows outbound connections for ngrok.
• Credentials Errors:
  • Error initializing Vonage SDK: Private key file not found…: Verify VONAGE_PRIVATE_KEY_PATH in .env is correct relative to where you run node server.js, and the file exists.
  • API errors (401 Unauthorized): Double-check VONAGE_APPLICATION_ID is correct. Ensure the private.key file content hasn't been corrupted.
• Webhook Not Received:
  • Confirm ngrok is running and URLs match in Vonage.
  • Check the Vonage Dashboard under Logs → API Logs (or similar section) for errors related to webhook delivery failures from Vonage's side.
  • Ensure your server is running (node server.js) and didn't crash. Check server logs for errors.
  • Make sure your webhook endpoints (/webhooks/inbound, /webhooks/status) return a 200 OK or 204 No Content status quickly. Check server logs for errors within these handlers. Failure to respond quickly or with a 2xx status will cause Vonage to retry.
• Delivery Status (delivered) Not Received:
  • Delivery Receipts (DLRs) are carrier-dependent. Not all mobile networks or countries provide reliable delivered status updates back to Vonage. You will usually receive submitted, but delivered is not guaranteed.
  • Check if the Status URL is correctly configured and your /webhooks/status endpoint is working and returning 200 OK.
• Incorrect Phone Number Formatting: Always use the E.164 format (e.g., 15551234567 – the SDK often handles adding the + if needed, but being explicit is safer) for to and from numbers.
• Vonage Number Capabilities: Ensure the Vonage number you purchased is SMS-enabled for the direction you need (sending/receiving) in the relevant country.

8. Deployment Considerations

• Hosting: Deploy this application to a platform like Heroku, AWS (EC2, Lambda, Elastic Beanstalk), Google Cloud (App Engine, Cloud Run), DigitalOcean (App Platform), or similar PaaS/IaaS providers.
• Public URL: Replace the ngrok URL with your server's permanent public HTTPS URL in the Vonage Application webhook settings. Ensure your server is accessible from the internet and configured for HTTPS.
• Environment Variables: Configure environment variables (VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH, VONAGE_NUMBER, PORT, etc.) securely using your hosting provider's tools (e.g., Heroku Config Vars, AWS Secrets Manager, .env files managed securely on the server). Do not include the .env file in your deployment package/repository. Securely transfer or provide the private.key file to your production server and ensure the VONAGE_PRIVATE_KEY_PATH environment variable points to its location on the server.
• Process Management: Use a process manager like pm2 to keep your Node.js application running reliably in production. pm2 handles automatic restarts on crashes, manages logs, enables clustering for better performance, and more.
• CI/CD: Set up a Continuous Integration/Continuous Deployment pipeline (e.g., using GitHub Actions, GitLab CI, Jenkins, CircleCI) to automate testing and deployment processes, ensuring code quality and consistent releases.

9. Verification Checklist

Before considering this production-ready:

• Can successfully send an SMS via the /send-sms endpoint?
• Receive the SMS on the target mobile device?
• See logs for the /send-sms request in the server console?
• See logs for the /webhooks/status update (at least submitted) in the server console?
• Can successfully send an SMS to the Vonage number from a mobile device?
• See logs for the /webhooks/inbound message in the server console?
• Do both webhook endpoints consistently return 200 OK or 204 No Content quickly?
• Are all secrets (.env, private.key) excluded from Git?
• Is robust error handling implemented for API calls and webhook processing logic?
• Is structured logging configured (Strongly Recommended)?
• Is robust input validation implemented for the API endpoint (Strongly Recommended)?
• Is webhook signature verification (JWT) implemented (Crucial for Production)?
• Is rate limiting implemented on public-facing endpoints (Recommended)?
• Have deployment procedures been tested (environment variables, public URL update, process manager)?

This guide provides a solid foundation for sending, receiving, and tracking SMS messages using Node.js and Vonage. Enhance logging, error handling, and especially security (webhook verification, input validation, rate limiting) based on your specific production requirements. Refer to the official Vonage Messages API documentation for further details and advanced features.