Send SMS with Node.js, Express, and Plivo: A Developer Guide - code-examples -

This guide provides a step-by-step walkthrough for building a simple yet robust Node.js application using the Express framework to send SMS messages via the Plivo API. We'll cover everything from project setup and configuration to implementing the core sending logic, handling errors, and testing the endpoint.

By the end of this tutorial, you will have a functional Express API endpoint capable of accepting requests to send SMS messages. This forms a foundational building block for integrating SMS notifications, alerts, or communication features into larger applications.

Technologies Used:

  • Node.js: A JavaScript runtime environment for building server-side applications.
  • Express.js: A minimal and flexible Node.js web application framework.
  • Plivo: A cloud communications platform providing APIs for SMS, voice, and more.
  • dotenv: A module to load environment variables from a .env file into process.env.

Prerequisites:

  • Node.js and npm (or yarn): Installed on your development machine. You can download them from nodejs.org.
  • Plivo Account: Sign up for a free Plivo account at plivo.com.
  • Plivo Auth ID and Auth Token: Found on your Plivo console dashboard upon logging in.
  • A Plivo Phone Number: You need an SMS-enabled Plivo phone number to act as the sender (src). You can purchase one from the `Phone Numbers` -> `Buy Numbers` section of the Plivo console.
    • Important: Sending SMS to the US and Canada requires using a Plivo phone number as the sender ID. Other countries may support alphanumeric sender IDs (check Plivo documentation and local regulations).
    • Trial Account Limitation: If using a Plivo trial account, you can only send SMS messages to phone numbers verified in your Plivo console under `Phone Numbers` -> `Sandbox Numbers`.

Setting up the Project

Let's start by creating our project directory and initializing it with npm.

  1. Create Project Directory: Open your terminal or command prompt and run:

    mkdir node-plivo-sms
cd node-plivo-sms

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

    npm init -y

  3. Install Dependencies: We need Express for the web server, the Plivo Node.js SDK to interact with the API, and dotenv to manage environment variables securely.

    npm install express plivo dotenv

  4. Project Structure: Create the basic files and directories. Your structure should look like this:

    node-plivo-sms/
├── node_modules/
├── .env
├── .gitignore
├── package.json
├── package-lock.json
└── server.js

  5. Configure .gitignore: Create a file named .gitignore in the project root and add the following lines to prevent committing sensitive information and unnecessary files:

    # .gitignore

# Node dependencies
node_modules/

# Environment variables
.env

# Logs (Optional but good practice)
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Optional editor directories
.idea/
.vscode/
*.swp
    • Why? The .env file will contain your secret API credentials, which should never be committed to version control. node_modules contains installed dependencies, which can be reinstalled using npm install.

Plivo Configuration and Environment Variables

Securely storing your Plivo credentials is crucial. We'll use environment variables managed by the dotenv package.

  1. Create .env file: In the root of your project, create a file named .env.

  2. Add Plivo Credentials: Open the .env file and add your Plivo Auth ID, Auth Token, and your Plivo phone number. Obtain these from your Plivo Console:

    # Plivo Credentials - Get from https://console.plivo.com/dashboard/
PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN

# Your Plivo phone number (must be SMS enabled)
# Use E.164 format (e.g., +14155551234)
PLIVO_SENDER_NUMBER=YOUR_PLIVO_PHONE_NUMBER
    • Replace YOUR_PLIVO_AUTH_ID, YOUR_PLIVO_AUTH_TOKEN, and YOUR_PLIVO_PHONE_NUMBER with your actual credentials and number.
    • Important: Ensure the phone number is in E.164 format (includes the + and country code).

Implementing the Core SMS Sending Logic

Now, let's write the code in server.js to set up the Express server and integrate the Plivo client.

// server.js
'use strict'; // Enforce stricter parsing and error handling

// 1. Load Environment Variables
require('dotenv').config(); // Load variables from .env file into process.env

// 2. Import Dependencies
const express = require('express');
const plivo = require('plivo');

// 3. Initialize Express App
const app = express();
app.use(express.json()); // Middleware to parse JSON request bodies

// 4. Validate Essential Environment Variables
const { PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, PLIVO_SENDER_NUMBER } = process.env;

if (!PLIVO_AUTH_ID || !PLIVO_AUTH_TOKEN || !PLIVO_SENDER_NUMBER) {
    console.error(
        'Error: Plivo environment variables (PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, PLIVO_SENDER_NUMBER) are missing or empty in .env file.'
    );
    process.exit(1); // Exit if essential config is missing
}

// 5. Initialize Plivo Client
// Ensure you handle potential errors during client initialization if necessary,
// though the SDK typically doesn't throw errors here unless inputs are malformed.
const plivoClient = new plivo.Client(PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN);

// 6. Define the SMS Sending Route
app.post('/send-sms', async (req, res) => {
    // --- Basic Input Validation ---
    const { to, text } = req.body; // Get destination number and message text from request body

    if (!to || !text) {
        // Use 400 Bad Request for missing client input
        return res.status(400).json({
            success: false,
            error: 'Missing required fields: `to` and `text` in request body.',
        });
    }

    // Basic validation for 'to' number format (E.164)
    // Note: This regex is a basic check. Full E.164 validation is more complex
    // and might involve library lookups or more sophisticated patterns.
    if (!/^\+[1-9]\d{1,14}$/.test(to)) {
         return res.status(400).json({
            success: false,
            error: 'Invalid `to` phone number format. Use E.164 format (e.g., +14155551234).',
        });
    }

    // --- Send SMS using Plivo ---
    console.log(`Attempting to send SMS to: ${to}, Text: ""${text}""`);

    try {
        const response = await plivoClient.messages.create({
            src: PLIVO_SENDER_NUMBER, // Sender ID (Your Plivo Number)
            dst: to,                  // Destination Number (From request)
            text: text,               // Message Text (From request)
        });

        console.log('Plivo API Response:', response);

        // Check if message was successfully queued (basic check based on presence of message_uuid)
        // The exact structure might vary slightly based on SDK version or specific scenarios.
        // Refer to Plivo Node SDK documentation for definitive response structure.
        if (response && response.message_uuid) {
             res.status(200).json({
                success: true,
                message: 'SMS sent successfully queued.',
                message_uuid: response.message_uuid, // Return the message UUID (string expected)
                api_id: response.api_id,           // Return the API ID
            });
        } else {
             // This case might indicate an issue not caught by an exception (unlikely but possible)
             console.error('Plivo response indicates message queuing failed or missing expected fields:', response);
             res.status(500).json({
                success: false,
                error: 'Failed to queue SMS via Plivo (unexpected response structure).',
                details: response, // Include Plivo response for debugging
            });
        }

    } catch (error) {
        console.error('Error sending SMS via Plivo:', error);

        // Provide more specific feedback based on Plivo error if possible
        // Plivo errors often have status codes and detailed messages
        const statusCode = error.statusCode || 500; // Default to 500 Internal Server Error
        const errorMessage = error.message || 'An unexpected error occurred.';
        // Plivo error details might be in error.error or nested differently.
        // Check Plivo Node SDK documentation for the specific error object structure.
        const errorDetails = error.error || {};

        res.status(statusCode).json({
            success: false,
            error: `Plivo API Error: ${errorMessage}`,
            details: errorDetails,
        });
    }
});

// 7. Start the Server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
    console.log(`Plivo Sender Number: ${PLIVO_SENDER_NUMBER}`);
    console.log('API Endpoint: POST /send-sms');
    console.log('Required Body: { ""to"": ""+1XXXXXXXXXX"", ""text"": ""Your message"" }');
});

Code Explanation:

  1. Load Environment Variables: require('dotenv').config() loads the variables defined in your .env file into process.env. This must happen before you access these variables.
  2. Import Dependencies: Imports the express framework and the plivo SDK.
  3. Initialize Express App: Creates an instance of the Express application and uses express.json() middleware to automatically parse incoming requests with JSON payloads (like the one we'll send).
  4. Validate Environment Variables: Checks if the essential Plivo credentials are loaded. If not, it logs an error and exits, preventing the server from starting without proper configuration.
  5. Initialize Plivo Client: Creates an instance of the Plivo client using your Auth ID and Auth Token from the environment variables.
  6. Define /send-sms Route:
    • Sets up a POST endpoint at /send-sms.
    • Uses async/await for handling the asynchronous Plivo API call cleanly.
    • Input Validation: Extracts to (destination number) and text (message content) from the request body (req.body). It performs basic checks to ensure both fields are present and the to number roughly matches the E.164 format. Note: The E.164 regex used (/^\+[1-9]\d{1,14}$/) is a basic structural check; comprehensive E.164 validation is more involved.
    • Plivo API Call: Uses plivoClient.messages.create() to send the SMS.
      • src: The sender number (your Plivo number from .env).
      • dst: The destination number (from the request).
      • text: The message content (from the request).
    • Success Response: If the API call is successful (doesn't throw an error and returns expected fields like message_uuid), it logs the Plivo response and sends a 200 OK response back to the client with the message_uuid and api_id.
    • Error Handling: If the Plivo API call fails (e.g., invalid credentials, insufficient funds, invalid number), the catch block executes. It logs the detailed error and sends an appropriate HTTP status code (using error.statusCode if available, otherwise 500) and an error message back to the client, potentially including details from error.error.
  7. Start Server: Starts the Express server, listening for incoming requests on the port specified by the PORT environment variable, or defaulting to 3000.

Running Locally and Verification

Now, let's run the server and test the endpoint.

  1. Start the Server: Open your terminal in the project directory (node-plivo-sms) and run:

    node server.js

    You should see output like:

    Server running on port 3000
Plivo Sender Number: +1XXXXXXXXXX
API Endpoint: POST /send-sms
Required Body: { ""to"": ""+1YYYYYYYYYY"", ""text"": ""Your message"" }

  2. Test with curl: Open a new terminal window (leaving the server running) and use curl (or a tool like Postman) to send a POST request to your endpoint.

    • Replace +1YYYYYYYYYY with a valid destination phone number (remember the trial account restrictions: use a verified sandbox number if applicable).
    • Replace ""Hello from Node and Plivo!"" with your desired message text.
    curl -X POST http://localhost:3000/send-sms \
-H ""Content-Type: application/json"" \
-d '{
  ""to"": ""+1YYYYYYYYYY"",
  ""text"": ""Hello from Node and Plivo!""
}'

  3. Check Response:

    • Successful Request: If everything works, curl should output something like (UUIDs and IDs will vary): 
      {
  ""success"": true,
  ""message"": ""SMS sent successfully queued."",
  ""message_uuid"": ""some-unique-message-uuid-string"",
  ""api_id"": ""some-unique-api-id-string""
}
      You should also receive the SMS on the destination phone shortly after. Check the server logs for the Plivo API Response.
    • Failed Request (e.g., Validation Error): If you send an invalid request (e.g., missing to field): 
      {
  ""success"": false,
  ""error"": ""Missing required fields: `to` and `text` in request body.""
}
    • Failed Request (e.g., Plivo API Error): If Plivo rejects the request (e.g., invalid Auth ID): 
      {
  ""success"": false,
  ""error"": ""Plivo API Error: Authentication credentials invalid. Check your Auth ID and Auth Token."",
  ""details"": {} // Plivo might provide more details here depending on the error
}
      Check the server logs for the detailed Error sending SMS via Plivo.

  4. Verify SMS Delivery: Check the destination phone for the incoming SMS message.

Troubleshooting and Caveats

  • Authentication Errors (401 Unauthorized): Double-check your PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN in the .env file. Ensure they are copied correctly from the Plivo console and that the .env file is being loaded (no typos in require('dotenv').config()).
  • Invalid Sender ID: Ensure PLIVO_SENDER_NUMBER is a valid, SMS-enabled Plivo number you own, formatted in E.164. If sending outside the US/Canada, you might need to register an Alphanumeric Sender ID with Plivo support depending on the destination country's regulations. Check Plivo's SMS API coverage page for country-specific rules.
  • Invalid Destination Number (to): Ensure the to number in your request body is in E.164 format (+ followed by country code and number).
  • Trial Account Restrictions: Remember you can only send to verified sandbox numbers on a trial account. Add numbers under `Phone Numbers` -> `Sandbox Numbers` in the Plivo console.
  • Insufficient Funds: If you're using a paid account, ensure you have enough credits.
  • Rate Limiting: Plivo enforces rate limits on API requests. For high-volume sending, implement proper queuing and potentially exponential backoff in your application logic (beyond the scope of this basic guide).
  • Encoding: Plivo handles GSM and Unicode characters (including emojis). Be aware that messages with Unicode characters have a lower character limit per SMS segment (70 vs. 160 for GSM). Long messages are automatically concatenated. See Plivo's Encoding and Concatenation guide.
  • Network Issues: Ensure your server can reach Plivo's API endpoints (api.plivo.com). Firewalls or network configurations could block outgoing connections.
  • SDK Response/Error Structure: The exact fields returned by the Plivo SDK upon success (response.message_uuid, response.api_id) or the structure of the error object in the catch block might change between SDK versions. Always refer to the official Plivo Node SDK documentation for the version you are using.

Deployment Considerations

While this guide focuses on local development, here are key points for deploying this application:

  • Environment Variables: Never commit your .env file. Production environments (like Heroku, AWS, Google Cloud, DigitalOcean) provide mechanisms to securely set environment variables directly on the platform. Configure PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, and PLIVO_SENDER_NUMBER in your hosting provider's settings.
  • PORT Variable: Most hosting platforms automatically assign a PORT environment variable. The code const PORT = process.env.PORT || 3000; correctly uses the assigned port or falls back to 3000.
  • Process Management: Use a process manager like pm2 or rely on your platform's tools (e.g., Heroku Dynos, Docker containers) to keep your Node.js application running reliably and restart it if it crashes.
  • Logging: Implement more robust logging (e.g., using Winston or Pino) to capture detailed information in production, especially errors, and potentially send logs to a centralized logging service.
  • Security: Add rate limiting (e.g., using express-rate-limit) to your API endpoint to prevent abuse. Consider adding API key authentication if this endpoint will be exposed publicly or used by multiple clients.

Conclusion and Next Steps

You have successfully built a basic Node.js Express application capable of sending SMS messages using the Plivo API. You learned how to set up the project, manage credentials securely, implement the sending logic with error handling, and test the API endpoint.

Further Enhancements:

  • Receiving SMS: Implement a webhook endpoint using Express to receive incoming SMS messages sent to your Plivo number.
  • Status Callbacks: Configure a url or log parameter in the messages.create call or Plivo Application settings to receive status updates (e.g., delivered, failed) for sent messages.
  • More Robust Validation: Implement more comprehensive validation for phone numbers (potentially using a dedicated library) and message content.
  • Web Interface: Build a simple frontend (using HTML, CSS, and JavaScript or a framework like React/Vue/Angular) to interact with your API.
  • Database Integration: Store message logs, user data, or application state in a database.
  • Bulk Sending: Adapt the logic to handle sending messages to multiple recipients efficiently, potentially using Promise.all for better concurrency while respecting Plivo rate limits.

This foundation enables you to integrate powerful SMS communication features into your Node.js applications effectively and securely.