How to Send Bulk SMS with Node.js, Express, and Plivo API (2025 Guide)

+-------------+       +---------------------+       +---------------+       +-------------+
|   Client    | ----> | Node.js/Express API | ----> | Plivo API     | ----> |  Recipients |
| (e.g., App, |       | (Bulk SMS Service)  |       | (SMS Gateway) |       | (Mobile Phones)|
|  Script)    |       +----------^----------+       +-------^-------+       +-------------+
+-------------+                  |                          |
                                 | Webhook (Delivery Reports)|
                                 +---------------------------+

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

npm init -y

npm install express plivo dotenv body-parser express-rate-limit winston

node-plivo-bulk-sms/
├── src/
│   ├── services/
│   │   └── plivoService.js      # Logic for interacting with Plivo
│   ├── routes/
│   │   └── api.js               # API route definitions
│   ├── middleware/
│   │   ├── auth.js              # API key authentication
│   │   └── validateWebhook.js   # Plivo webhook validation
│   ├── config/
│   │   └── logger.js            # Winston logger configuration
│   └── app.js                   # Express application setup
├── .env                         # Environment variables (DO NOT COMMIT)
├── .gitignore                   # Files/folders to ignore in Git
└── package.json

# .env

# Plivo Credentials
PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
PLIVO_SENDER_ID=YOUR_PLIVO_PHONE_NUMBER_OR_SENDER_ID # e.g., +14155551212 (E.164 format)

# Application Settings
PORT=3000
API_BASE_URL=http://localhost:3000 # Change for production/ngrok
API_KEY=YOUR_SECRET_API_KEY # Generate a strong random key - REQUIRED for API access

# Webhook Validation Secret (Optional - Defaults to PLIVO_AUTH_TOKEN if not set)
# Plivo signs webhooks with your Auth Token by default using V3 signature validation.
# Set this only if you configure a *different* specific webhook secret
# in your Plivo Application settings.
# Leave this commented out or explicitly set it to your Auth Token.
# PLIVO_WEBHOOK_SECRET=YOUR_SEPARATE_WEBHOOK_SECRET_IF_ANY

# .gitignore

# Dependencies
node_modules/

# Environment Variables
.env

# Logs
logs/
*.log

# OS generated files
.DS_Store
Thumbs.db

// src/config/logger.js
const winston = require('winston');
const fs = require('fs');
const path = require('path');

const logDir = 'logs';

// Create the log directory if it does not exist
if (!fs.existsSync(logDir)) {
  fs.mkdirSync(logDir);
}

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
    winston.format.errors({ stack: true }), // Log stack traces
    winston.format.splat(),
    winston.format.json() // Log in JSON format
  ),
  defaultMeta: { service: 'bulk-sms-service' },
  transports: [
    // Write all logs with level `error` and below to `error.log`
    // Write all logs with level `info` and below to `combined.log`
    new winston.transports.File({ filename: path.join(logDir, 'error.log'), level: 'error' }),
    new winston.transports.File({ filename: path.join(logDir, 'combined.log') }),
  ],
});

// If not in production, log to the console with simplified formatting
if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.combine(
      winston.format.colorize(),
      winston.format.simple()
    ),
  }));
}

module.exports = logger;

// src/services/plivoService.js
const plivo = require('plivo');
const logger = require('../config/logger');

const PLIVO_AUTH_ID = process.env.PLIVO_AUTH_ID;
const PLIVO_AUTH_TOKEN = process.env.PLIVO_AUTH_TOKEN;
const PLIVO_SENDER_ID = process.env.PLIVO_SENDER_ID;
const API_BASE_URL = process.env.API_BASE_URL;

if (!PLIVO_AUTH_ID || !PLIVO_AUTH_TOKEN || !PLIVO_SENDER_ID) {
  logger.error('CRITICAL: Plivo credentials (Auth ID, Auth Token) or Sender ID missing in environment variables. Application cannot send SMS.');
  // In a real application, throw an error here to prevent startup
  // throw new Error('Missing Plivo configuration.');
}
if (!API_BASE_URL) {
    logger.warn('API_BASE_URL environment variable is not set. Webhook URLs may not be generated correctly.');
}


const client = new plivo.Client(PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN);

// Plivo's documented limit for destination numbers per API call (as of October 2025)
// Source: Plivo Messaging API Documentation
const PLIVO_DST_LIMIT = 1000;

/**
 * Sends a single batch of SMS messages using Plivo's bulk feature.
 * @param {string[]} recipientsBatch - Array of recipient phone numbers in E.164 format (max 1,000).
 * @param {string} message - The text message content.
 * @returns {Promise<object>} - Plivo API response for the message creation.
 * @throws {Error} - If the Plivo API call fails.
 */
async function sendBulkSmsBatch(recipientsBatch, message) {
  if (recipientsBatch.length === 0) {
    logger.warn('Attempted to send an empty batch.');
    return { message: 'Empty batch, no messages sent.', uuids: [] };
  }
  if (recipientsBatch.length > PLIVO_DST_LIMIT) {
    logger.error(`Batch size exceeds Plivo limit of ${PLIVO_DST_LIMIT}. Size: ${recipientsBatch.length}`);
    // This condition indicates a programming error in the calling function (sendBulkSms)
    throw new Error(`Programming Error: Batch size ${recipientsBatch.length} exceeds limit of ${PLIVO_DST_LIMIT}`);
  }

  // Plivo's delimiter for bulk SMS: join phone numbers with '<' character
  const destinationNumbers = recipientsBatch.join('<');
  const deliveryReportUrl = `${API_BASE_URL}/api/webhooks/plivo/delivery-report`; // Your webhook URL

  logger.info(`Sending batch of ${recipientsBatch.length} messages. First few recipients: ${recipientsBatch.slice(0, 3).join(', ')}…`);

  try {
    const response = await client.messages.create(
      PLIVO_SENDER_ID, // src (must be E.164 format or approved alphanumeric sender ID)
      destinationNumbers, // dst (E.164 format numbers joined with '<')
      message, // text
      {
        url: deliveryReportUrl, // URL for delivery reports (webhook endpoint)
        method: 'POST',        // HTTP method for delivery reports
      }
    );

    logger.info(`Plivo batch sent successfully. API Response Message: "${response.message}". Message UUID(s): ${response.messageUuid ? response.messageUuid.join(', ') : 'N/A'}`);
    // Note on Message UUIDs: Plivo's API response structure might contain one or more UUIDs.
    // Track the status of *each individual recipient* in the bulk send via the Delivery
    // Report webhooks, which contain a MessageUUID specific to that recipient's message
    // attempt. Ensure your webhook handler uses the DLR's UUID.
    return response;

  } catch (error) {
    logger.error('Plivo API Error sending batch:', {
      errorMessage: error.message,
      errorStack: error.stack,
      recipientsCount: recipientsBatch.length,
      // Consider logging error details from Plivo if available (e.g., error.statusCode)
    });
    // Rethrow to allow the caller (sendBulkSms) to handle batch failures
    throw error;
  }
}

/**
 * Sends bulk SMS messages, handling batching based on Plivo's limits.
 * @param {string[]} allRecipients - Array of all recipient phone numbers.
 * @param {string} message - The text message content.
 * @returns {Promise<object[]>} - Array of PromiseSettledResult objects for each batch.
 */
async function sendBulkSms(allRecipients, message) {
  if (!allRecipients || allRecipients.length === 0) {
    logger.warn('No recipients provided for bulk SMS.');
    return [];
  }

  logger.info(`Initiating bulk send request for ${allRecipients.length} recipients.`);

  const batchPromises = [];
  for (let i = 0; i < allRecipients.length; i += PLIVO_DST_LIMIT) {
    const batch = allRecipients.slice(i, i + PLIVO_DST_LIMIT);
    // Don't await here; start all batch sends concurrently.
    batchPromises.push(sendBulkSmsBatch(batch, message));
  }

  // Wait for all batch sending promises to resolve or reject.
  // Promise.allSettled is ideal here as it waits for all promises, regardless of success/failure.
  const results = await Promise.allSettled(batchPromises);

  const successfulBatches = [];
  const failedBatches = [];

  results.forEach((result, index) => {
    const batchNumber = index + 1;
    const batchRecipientCount = (index === Math.floor(allRecipients.length / PLIVO_DST_LIMIT))
      ? allRecipients.length % PLIVO_DST_LIMIT || PLIVO_DST_LIMIT // Last batch size
      : PLIVO_DST_LIMIT; // Full batch size

    if (result.status === 'fulfilled') {
      logger.info(`Batch ${batchNumber} (${batchRecipientCount} recipients) sent successfully. Response:`, result.value);
      successfulBatches.push(result.value);
    } else {
      // result.reason contains the error thrown by sendBulkSmsBatch
      logger.error(`Batch ${batchNumber} (${batchRecipientCount} recipients) failed to send. Reason:`, result.reason?.message || result.reason);
      failedBatches.push({ batchNumber, reason: result.reason?.message || result.reason });
    }
  });

  if (failedBatches.length > 0) {
    // In a production system, trigger alerts or specific retry logic for failed batches.
    logger.warn(`Bulk send request processed with ${failedBatches.length} out of ${results.length} batches failing submission to Plivo.`);
  } else {
    logger.info(`All ${results.length} bulk send batches were submitted to Plivo successfully.`);
  }

  // Return the detailed results array containing status and value/reason for each batch promise.
  return results;
}

/**
 * Validates Plivo webhook signatures (V3).
 * Uses Plivo's V3 signature validation method with HMAC-SHA256.
 * @param {string} signature - The X-Plivo-Signature-V3 header value.
 * @param {string} nonce - The X-Plivo-Signature-V3-Nonce header value.
 * @param {string} url - The full URL Plivo posted to (as received by your server).
 * @param {string} body - The raw request body string.
 * @returns {boolean} - True if the signature is valid, false otherwise.
 *
 * Source: Plivo Node.js SDK validateV3Signature method
 * (npmjs.com/package/plivo, October 2025)
 */
function validateWebhookSignature(signature, nonce, url, body) {
    // Use the specific webhook secret if provided, otherwise default to the Plivo Auth Token.
    // Plivo's default behavior is to sign webhooks with the Auth Token using V3 signature.
    const webhookSecret = process.env.PLIVO_WEBHOOK_SECRET || PLIVO_AUTH_TOKEN;

    if (!webhookSecret) {
        // This should not happen if PLIVO_AUTH_TOKEN is set as checked earlier.
        logger.error('CRITICAL: Cannot validate webhook: Neither PLIVO_WEBHOOK_SECRET nor PLIVO_AUTH_TOKEN is set.');
        return false;
    }
    if (!signature || !nonce || !url || body === undefined || body === null) {
        logger.warn('Webhook validation failed: Missing signature, nonce, URL, or body for validation.');
        return false;
    }

    try {
        // Use the Plivo SDK's built-in utility for V3 signature validation.
        // This method uses HMAC-SHA256 to validate the webhook authenticity.
        const isValid = plivo.validateV3Signature(url, nonce, signature, webhookSecret);
        if (!isValid) {
            logger.warn('Webhook validation failed: Invalid signature computed.');
        }
        return isValid;

    } catch (error) {
        logger.error('Error during webhook signature validation process:', error);
        return false;
    }
}


module.exports = {
  sendBulkSms,
  validateWebhookSignature,
};

// src/middleware/auth.js
const logger = require('../config/logger');
const API_KEY = process.env.API_KEY;

// CRITICAL SECURITY CHECK: API Key MUST be configured for production environments.
if (!API_KEY) {
  logger.error('CRITICAL SECURITY RISK: API_KEY environment variable is not set. API endpoint is unprotected!');
  // In production, throw an error here to prevent the app from starting insecurely.
  // throw new Error('API_KEY environment variable is required.');
}

const apiKeyAuth = (req, res, next) => {
  // If no API key is configured (despite the warning), log and deny access.
  // This enforces that the key MUST be set. Remove this block ONLY if you
  // intentionally want the API open without a key (highly discouraged).
  if (!API_KEY) {
    logger.error('API access denied: API_KEY is not configured on the server.');
    return res.status(500).json({ error: 'Server configuration error: API key not set.' });
  }

  const providedApiKey = req.headers['x-api-key'];

  if (!providedApiKey) {
    logger.warn('API access attempt DENIED: Missing x-api-key header.');
    return res.status(401).json({ error: 'Your API key is missing in the x-api-key header. Include a valid API key to authenticate.' });
  }

  if (providedApiKey !== API_KEY) {
    logger.warn('API access attempt DENIED: Invalid API key provided.');
    return res.status(403).json({ error: 'Your API key is invalid. Verify the key in your account settings.' });
  }

  // API key is valid
  logger.debug('API key validated successfully.'); // Use debug level for successful auth
  next();
};

module.exports = apiKeyAuth;

// src/middleware/validateWebhook.js
const express = require('express');
const logger = require('../config/logger');
const { validateWebhookSignature } = require('../services/plivoService');

// Middleware to capture the raw body for signature verification
// Use this BEFORE any JSON parsing middleware for the webhook route.
const captureRawBody = express.raw({
    type: '*/*', // Capture raw body for any content type Plivo might send
    verify: (req, res, buf, encoding) => {
        try {
            if (buf && buf.length) {
                req.rawBody = buf.toString(encoding || 'utf8');
                logger.debug('Raw body captured for webhook validation.');
            } else {
                req.rawBody = ''; // Ensure rawBody exists even if empty
                logger.debug('Empty raw body captured for webhook validation.');
            }
        } catch (e) {
            logger.error('Error capturing raw body:', e);
            req.rawBody = null; // Indicate failure to capture
        }
    },
});


const validatePlivoWebhook = (req, res, next) => {
  const signature = req.headers['x-plivo-signature-v3'];
  const nonce = req.headers['x-plivo-signature-v3-nonce'];
  // Construct the full URL Plivo used to POST. Ensure base URL matches reality.
  // Using req.protocol, req.get('host'), and req.originalUrl is generally reliable.
  const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`;

  // Use the raw body saved by the captureRawBody middleware
  const rawBody = req.rawBody;

  if (rawBody === null) {
      // Error occurred during raw body capture
      return res.status(500).send('Internal Server Error: Failed to process request body.');
  }

  if (!signature || !nonce) {
    logger.warn('Webhook validation failed: Missing X-Plivo-Signature-V3 or X-Plivo-Signature-V3-Nonce header.');
    // Don't reveal *why* validation failed in the response for security.
    return res.status(400).send('Webhook validation failed.');
  }

  logger.debug(`Attempting webhook validation. URL: ${url}, Nonce: ${nonce}, Signature: ${signature ? 'Present' : 'Missing'}, RawBody Length: ${rawBody?.length}`);

  if (validateWebhookSignature(signature, nonce, url, rawBody)) {
    logger.info('Webhook signature validated successfully.');
    next(); // Signature is valid, proceed to the handler
  } else {
    logger.error('Webhook validation failed: Invalid signature detected.');
    // Return 403 Forbidden for invalid signatures
    res.status(403).send('Forbidden: Invalid webhook signature.');
  }
};


module.exports = { validatePlivoWebhook, captureRawBody };

// src/routes/api.js
const express = require('express');
const { sendBulkSms } = require('../services/plivoService');
const logger = require('../config/logger');
const apiKeyAuth = require('../middleware/auth');
const { validatePlivoWebhook } = require('../middleware/validateWebhook');

const router = express.Router();

// === Bulk SMS Sending Endpoint ===
router.post('/bulk-sms', apiKeyAuth, async (req, res) => {
  const { recipients, message } = req.body;

  // --- Input Validation ---
  // Basic checks
  if (!recipients || !Array.isArray(recipients) || recipients.length === 0) {
    logger.warn('Bad Request (400): Invalid or missing recipients array.');
    return res.status(400).json({ error: '"recipients" must be a non-empty array.' });
  }
  if (!message || typeof message !== 'string' || message.trim() === '') {
    logger.warn('Bad Request (400): Invalid or missing message string.');
    return res.status(400).json({ error: '"message" must be a non-empty string.' });
  }

  // **PRODUCTION TODO: Implement Robust Validation Here**
  // - Iterate through `recipients`:
  //   - Verify each recipient string matches E.164 format (e.g., using a library like `libphonenumber-js`).
  //   - Reject the entire request or filter out invalid numbers based on requirements.
  // - Check `message` length against SMS segment limits (160 GSM-7 characters, less for UCS-2).
  // - Sanitize message content if necessary (less critical if backend-generated).
  const validatedRecipients = recipients; // Replace with validated/filtered list
  const recipientCount = validatedRecipients.length;

  if (recipientCount === 0) {
      logger.warn('Bad Request (400): No valid recipients after validation.');
      return res.status(400).json({ error: 'No valid recipient phone numbers provided.' });
  }
  // --- End Input Validation ---

  logger.info(`Received valid bulk SMS request for ${recipientCount} recipients via API Key.`);

  try {
    // **PERFORMANCE NOTE:** For very large lists (e.g., 10,000+), processing `sendBulkSms`
    // directly in the request handler can cause timeouts.
    // Implement a background job queue (e.g., BullMQ, RabbitMQ):
    // 1. API receives request, validates input.
    // 2. API adds a job to the queue with recipients and message.
    // 3. API immediately returns 202 Accepted with a job ID.
    // 4. A separate worker process picks up the job and calls `sendBulkSms`.
    // This guide implements the direct synchronous approach for simplicity.
    logger.info(`Calling sendBulkSms for ${recipientCount} recipients…`);
    const results = await sendBulkSms(validatedRecipients, message);

    // Analyze results from Promise.allSettled
    const failedCount = results.filter(r => r.status === 'rejected').length;
    const totalBatches = results.length;

    if (failedCount > 0) {
       logger.warn(`Bulk SMS request processed: ${failedCount} out of ${totalBatches} batch(es) failed during submission to Plivo.`);
       // 207 Multi-Status indicates partial success/failure during submission phase.
       res.status(207).json({
         status: 'ProcessedWithFailures',
         message: `${failedCount} out of ${totalBatches} batch(es) failed submission. Check server logs for details on failed batches.`,
         totalRecipients: recipientCount,
         totalBatches: totalBatches,
         failedBatches: failedCount,
         // Optionally include more detailed results if needed, but be mindful of response size
         // results: results
       });
    } else {
       logger.info(`Bulk SMS request processed successfully: All ${totalBatches} batches submitted to Plivo.`);
       // 202 Accepted is appropriate as final delivery is asynchronous via webhooks.
       res.status(202).json({
         status: 'Accepted',
         message: 'Bulk SMS request accepted and all batches submitted for processing by Plivo.',
         totalRecipients: recipientCount,
         totalBatches: totalBatches,
         // Optionally return initial batch UUIDs if useful, though DLRs are more reliable per recipient.
         // initialApiResponses: results.map(r => r.value) // Only includes responses from fulfilled promises
       });
    }

  } catch (error) {
    // Catch unexpected errors not handled within sendBulkSms (should be rare if service handles its errors)
    logger.error('Unhandled error processing /bulk-sms request:', error);
    res.status(500).json({ error: 'Internal server error processing bulk SMS request.' });
  }
});


// === Plivo Delivery Report Webhook ===
// The `captureRawBody` middleware must run BEFORE `validatePlivoWebhook` and `express.json`
// (See `app.js` for middleware order). `validatePlivoWebhook` runs next.
router.post('/webhooks/plivo/delivery-report', validatePlivoWebhook, express.json(), (req, res) => {
  // Signature is already validated by the middleware.
  // The body is now parsed as JSON by `express.json()`.
  const deliveryReport = req.body;

  // Check if body parsing worked and is an object
  if (!deliveryReport || typeof deliveryReport !== 'object') {
      logger.warn('Webhook received valid signature but invalid/empty JSON body.');
      return res.status(400).json({ error: 'Invalid request body.' });
  }

  logger.info('Received validated Plivo Delivery Report (DLR). Processing…', { report: deliveryReport });

  // --- Process the Delivery Report ---
  // Extract key information:
  const messageUuid = deliveryReport.MessageUUID;
  const status = deliveryReport.Status; // e.g., "delivered", "failed", "undelivered", "sent", "queued"
  const recipient = deliveryReport.To;
  const errorCode = deliveryReport.ErrorCode; // Present on failure/undelivered (e.g., "400", "500")
  const timestamp = deliveryReport.Time; // Timestamp of the status event
  const units = deliveryReport.Units; // Number of SMS segments used
  const totalAmount = deliveryReport.TotalAmount; // Cost

  // **PRODUCTION TODO: Implement Database/Storage Update Logic Here**
  // This is the critical part for tracking message status.
  // 1. **Find:** Look up the message attempt in your database/storage using `messageUuid`
  //    (ensure `messageUuid` from the DLR is stored when the message is initially tracked).
  //    You might also use `recipient` as a secondary lookup key if needed.
  // 2. **Update:** Update the status of the corresponding record based on `status`.
  //    Store `errorCode`, `timestamp`, `units`, `totalAmount`.
  // 3. **Idempotency:** Ensure this update is idempotent. If Plivo retries the webhook,
  //    processing the same DLR again should not cause issues (e.g., check current status
  //    before updating, or use database constraints).
  // 4. **Logging/Alerting:** Log failures with error codes for analysis. Trigger alerts
  //    for specific critical error codes or high failure rates.
  // 5. **Retry Logic (Advanced):** Based on `status` and `errorCode`, decide if a retry
  //    for *this specific recipient* is warranted (e.g., for transient errors). This
  //    requires more complex state management.

  logger.info(`DLR Processed: UUID=${messageUuid}, To=${recipient}, Status=${status}, ErrorCode=${errorCode || 'N/A'}, Units=${units}, Cost=${totalAmount}`);

  // --- Acknowledge Receipt to Plivo ---
  // Plivo expects a 2xx response to stop retrying the webhook.
  // Send 200 OK immediately after logging/basic processing.
  // Database updates can happen asynchronously if needed for performance,
  // but ensure the acknowledgment is sent promptly.
  res.status(200).json({ message: 'Delivery report received and acknowledged.' });
});


module.exports = router;