Send, Receive, and Track SMS with Node.js, Express, and Vonage - code-examples -

This guide provides a step-by-step walkthrough for building a robust Node.js application using the Express framework to send SMS messages, receive inbound SMS, and handle delivery status updates via webhooks using the Vonage Messages API.

We will cover everything from project setup and core implementation to security considerations and deployment advice, aiming to provide a solid foundation for a production-ready solution.

Goal: Build a Node.js Express server that can:

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

Technologies Used:

  • Node.js: A JavaScript runtime environment for server-side development.
  • Express: A minimal and flexible Node.js web application framework.
  • Vonage Messages API: A multi-channel API for sending and receiving messages (we'll focus on SMS).
  • @vonage/server-sdk: The official Vonage Node.js SDK for interacting with the API.
  • ngrok: A tool to expose local servers to the internet for webhook testing during development.
  • dotenv: A module to load 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:

  • A Vonage API account (Sign up via the Vonage Communications APIs page - find the Sign Up option).
  • Node.js and npm (or yarn) installed locally.
  • A Vonage virtual phone number capable of sending/receiving SMS.
  • ngrok installed (Download here). Note: Depending on your usage or need for stable URLs/longer sessions, you might need to authenticate ngrok using ngrok authtoken your-token after signing up for an ngrok account.
  • Basic familiarity with Node.js, Express, and terminal commands.

1. Setting up the Project

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

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

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

  2. Initialize Node.js Project: Initialize the project using npm (or yarn). This creates a package.json file.

    npm init -y

  3. Install Dependencies: Install Express for the web server, the Vonage SDK, and dotenv for managing environment variables.

    npm install express @vonage/server-sdk dotenv

  4. Create Project Structure: Create the main application file and a file for environment variables.

    touch server.js .env .gitignore

  5. Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent committing sensitive information and dependencies.

    # .gitignore
node_modules
.env
private.key

    Note: We also add private.key preemptively. It's good practice to ensure this sensitive file, which you might download directly into the project folder later, is never accidentally committed to version control.

  6. Set Up Environment Variables (.env): Create a .env file in the project root. We will populate this with credentials obtained from Vonage in a later step. Use clear variable names and avoid quotes unless the value contains spaces or special characters.

    # .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: The local path to the private key file associated with your Vonage application, used for authenticating API requests.
    • VONAGE_NUMBER: Your Vonage virtual phone number used for sending SMS.
    • MY_NUMBER: Your personal mobile number for testing purposes (ensure it's in E.164 format).
    • PORT: The port your local Express server will listen on.

2. Integrating with Vonage

Before writing code, we need to configure Vonage by creating an Application and linking a number. This provides the necessary credentials and sets up webhook URLs.

  1. Log in to Vonage Dashboard: Access your Vonage API Dashboard. (Note: Dashboard layout may change over time).

  2. Purchase a Virtual Number: If you don't have one, navigate to the section for managing numbers (e.g., Numbers -> Buy numbers). Find a number with SMS capabilities in your desired country and purchase it. Note this number down. Consult the Vonage documentation if you cannot easily locate this section.

  3. Create a Vonage Application:

    • Navigate to the section for managing applications (e.g., Applications -> Create a new application).
    • Give your application a name (e.g., 'NodeJS SMS App').
    • Look for an option to Generate public and private key. Immediately save the private.key file that downloads. Place this file in your project's root directory (or update VONAGE_PRIVATE_KEY_PATH in .env if you save it elsewhere). The public key is stored by Vonage.
    • Enable the Messages capability.
    • You will see fields for Inbound URL and Status URL. We will fill these shortly using ngrok. For now, you can enter temporary placeholders like http://example.com/webhooks/inbound and http://example.com/webhooks/status. We must update these later. Ensure the HTTP Method is set to POST for both.
    • Click the button to create/generate the new application.

  4. Get Application ID: After creation, you'll be taken to the application's page or overview. Copy the Application ID displayed.

  5. Link Your Virtual Number:

    • On the application's settings page, find the area for Linked numbers.
    • Click the option to Link your virtual number and select the number you purchased earlier.

  6. Update .env File: Now, populate your .env file with the Application ID and your Vonage Virtual Number. Ensure VONAGE_PRIVATE_KEY_PATH points correctly to where you saved the private.key file. Add your personal number to MY_NUMBER.

    # .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: We need a publicly accessible URL to receive webhooks from Vonage on our local machine. Open a new terminal window in your project directory and run ngrok, pointing it to the port your Express server will use (defined in .env as 3000).

    ngrok http 3000

    ngrok will display a Forwarding URL (e.g., https://randomstring.ngrok.io). Copy this HTTPS URL.

  8. Configure Webhook URLs in Vonage Application:

    • Go back to your Vonage Application settings in the dashboard (Applications -> Your App Name -> Edit or similar).
    • Update the Messages capability URLs:
      • Inbound URL: Paste your ngrok HTTPS URL and append /webhooks/inbound. Example: https://randomstring.ngrok.io/webhooks/inbound
      • Status URL: Paste your ngrok HTTPS URL and append /webhooks/status. Example: https://randomstring.ngrok.io/webhooks/status
    • Ensure the HTTP method for both is set to POST.
    • Click Save changes.

    Why these specific URLs?

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

3. Implementing Core Functionality (Express Server)

Now let's 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("Please 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(`ngrok forwarding URL should be configured 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, sets up middleware for parsing request bodies.
  2. Vonage SDK Init: 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.
    • The code 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).
    • Crucially, it sends back a 200 OK status using res.status(200).end(). If Vonage doesn't receive a 2xx response, it will assume the webhook failed and retry, 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.
    • The code 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).
    • It also 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:

    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:

    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. You should 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: Remember 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. You should 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. You will need to 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. Remember to 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.