Build a Bulk SMS Broadcaster with Plivo, Fastify & Node.js: Complete Guide (2025)

Build a scalable bulk SMS broadcasting service using Fastify's performance and Plivo's efficient bulk messaging API. Send a single SMS message to thousands of recipients with a single API request. This guide walks you through project setup, implementation, error handling, retry logic, and deployment best practices.

You'll build a robust API endpoint that accepts phone numbers and messages, then uses Plivo to broadcast SMS efficiently. This approach dramatically outperforms sending individual messages in a loop – reducing latency and API call overhead.

Project Overview and Goals

• Problem: Sending the same SMS message to numerous recipients individually is slow, inefficient, and easily hits API rate limits.

• Solution: Build a Fastify API endpoint (POST /broadcast) that accepts destination phone numbers and a message body. Your endpoint will use the Plivo Node.js SDK to send messages to all recipients via Plivo's bulk messaging feature (single API call).

• Technologies:

  • Node.js: Your runtime environment.
  • Fastify: A high-performance, low-overhead Node.js web framework. Choose it for speed, extensibility, and built-in validation. Note: Fastify v5 is the current version requiring Node.js v20+. Fastify v4 support ends June 30, 2025.
  • Plivo Node.js SDK: Simplifies interaction with the Plivo REST API. Current version: v4.74.0 as of early 2025.
  • dotenv & fastify-env: Manage environment variables securely and reliably.

• Architecture:

  textCopy

   +-----------------+      +---------------------+      +-------------+      +-----------------+
   | Client (e.g. UI,| ---> | Fastify API Server  | ---> | Plivo API   | ---> | SMS Recipients  |
   | Curl, Postman)  |      | (POST /broadcast)   |      | (Bulk Send) |      | (Mobile Phones) |
   +-----------------+      +---------------------+      +-------------+      +-----------------+
                                    |
                                    | Uses Plivo SDK
                                    | Reads Env Vars (.env)
                                    | Logs Events/Errors

• Outcome: A functional Fastify application with a single endpoint (/broadcast) that accepts bulk SMS requests and dispatches them via Plivo.

• Prerequisites:

  • Install Node.js v22 LTS or later (v20 LTS minimum). Note: Node.js v18 reaches end-of-life on April 30, 2025 and requires upgrading.
  • Install npm or yarn package manager.
  • Create a Plivo account (sign up at Plivo).
  • Purchase a Plivo phone number capable of sending SMS (available in your Plivo console).
  • Locate your Plivo Auth ID and Auth Token (found in the Plivo console).

1. Setting Up the Project

Initialize your Node.js project and install dependencies. These instructions work across all operating systems.

1. Create Project Directory:

   bashCopy

   mkdir fastify-plivo-broadcaster
   cd fastify-plivo-broadcaster

2. Initialize npm Project:

   bashCopy

   npm init -y

   This creates a package.json file.

3. Install Dependencies:

   • fastify: The core web framework.
   • plivo: The official Plivo Node.js SDK.
   • dotenv: Loads environment variables from a .env file.
   • fastify-env: Schema-based environment variable validation for Fastify.
   bashCopy

   npm install fastify plivo dotenv fastify-env

4. Install Development Dependencies (Optional but Recommended):

   • nodemon: Automatically restarts the server on file changes during development.
   • pino-pretty: Formats Pino logs for readability during development.
   bashCopy

   npm install --save-dev nodemon pino-pretty

5. Configure package.json Scripts:

   Open package.json and add/modify the scripts section:

   jsonCopy

   {
     ""name"": ""fastify-plivo-broadcaster"",
     ""version"": ""1.0.0"",
     ""description"": """",
     ""main"": ""src/server.js"",
     ""scripts"": {
       ""start"": ""node src/server.js"",
       ""dev"": ""nodemon src/server.js | pino-pretty"",
       ""test"": ""echo \""Error: no test specified\"" && exit 1""
     },
     ""keywords"": [],
     ""author"": """",
     ""license"": ""ISC"",
     ""dependencies"": {
       ""dotenv"": ""^..."",
       ""fastify"": ""^..."",
       ""fastify-env"": ""^..."",
       ""plivo"": ""^...""
     },
     ""devDependencies"": {
       ""nodemon"": ""^..."",
       ""pino-pretty"": ""^...""
     }
   }

   (Note: The dev script pipes output to pino-pretty for readable logs during development).

6. Create Project Structure:

   Organize your code for clarity and maintainability.

   bashCopy

   mkdir src
   mkdir src/routes
   mkdir src/services
   touch src/server.js
   touch src/routes/broadcast.js
   touch src/services/plivoService.js
   touch .env
   touch .gitignore

   • src/: Contains all source code.
   • src/routes/: Holds route definitions.
   • src/services/: Contains business logic interacting with external services (like Plivo).
   • src/server.js: The main application entry point.
   • .env: Stores sensitive credentials and configuration (DO NOT commit this file).
   • .gitignore: Specifies files/directories to be ignored by Git.

7. Configure .gitignore:

   Add the following lines to your .gitignore file to prevent committing sensitive information and unnecessary files:

   textCopy

   # .gitignore
   node_modules
   .env
   npm-debug.log
   *.log

8. Set Up Environment Variables (.env):

   Open the .env file and add your Plivo credentials and server configuration.

   • PLIVO_AUTH_ID: Your Plivo Account Auth ID. Find this on the overview page of your Plivo Console.
   • PLIVO_AUTH_TOKEN: Your Plivo Account Auth Token. Also on the overview page.
   • PLIVO_SOURCE_NUMBER: A Plivo phone number you own (in E.164 format, e.g., +14155552671) enabled for SMS. Find this under Phone Numbers -> Your Numbers in the console.
   • HOST: The host address the server should listen on (e.g., 0.0.0.0 to listen on all available network interfaces, or 127.0.0.1 for localhost only).
   • PORT: The port number for the server (e.g., 3000).
   • LOG_LEVEL: Controls logging verbosity (e.g., info, debug, warn, error). Fastify uses Pino logger.
   dotenvCopy

   # .env
   PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
   PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
   PLIVO_SOURCE_NUMBER=+1XXXXXXXXXX
   HOST=0.0.0.0
   PORT=3000
   LOG_LEVEL=info

   Replace the placeholder values with your actual Plivo credentials and desired settings.

9. Initialize Basic Fastify Server (src/server.js):

   Set up the basic server structure and configure fastify-env to load and validate our environment variables.

   javascriptCopy

   // src/server.js
   'use strict';
   
   // Load environment variables from .env file first
   require('dotenv').config();
   
   const Fastify = require('fastify');
   const fastifyEnv = require('fastify-env');
   const broadcastRoutes = require('./routes/broadcast');
   
   // Define schema for environment variables
   const envSchema = {
     type: 'object',
     required: [
       'PORT',
       'HOST',
       'PLIVO_AUTH_ID',
       'PLIVO_AUTH_TOKEN',
       'PLIVO_SOURCE_NUMBER',
     ],
     properties: {
       PORT: { type: 'string', default: 3000 },
       HOST: { type: 'string', default: '0.0.0.0' },
       PLIVO_AUTH_ID: { type: 'string' },
       PLIVO_AUTH_TOKEN: { type: 'string' },
       PLIVO_SOURCE_NUMBER: {
           type: 'string',
           pattern: '^\\+[1-9]\\d{1,14}$' // E.164 format regex
       },
       LOG_LEVEL: { type: 'string', default: 'info' },
       // Add other env vars here if needed
     },
   };
   
   // Determine logger options based on NODE_ENV
   // Use pino-pretty only in development
   const loggerConfig = process.env.NODE_ENV === 'production'
     ? { level: process.env.LOG_LEVEL || 'info' } // Production: JSON logs
     : { // Development: Pretty logs
         level: process.env.LOG_LEVEL || 'info',
         transport: {
           target: 'pino-pretty',
           options: {
             translateTime: 'HH:MM:ss Z',
             ignore: 'pid,hostname',
           },
         },
       };
   
   // Initialize Fastify with logging options
   const fastify = Fastify({ logger: loggerConfig });
   
   const startServer = async () => {
     try {
       // Register fastify-env plugin
       await fastify.register(fastifyEnv, {
         schema: envSchema,
         dotenv: true, // Load .env file using dotenv
       });
   
       // Make Plivo credentials available across the app via decoration
       // This prevents needing to pass `fastify.config` everywhere
       fastify.decorate('plivoConfig', {
         authId: fastify.config.PLIVO_AUTH_ID,
         authToken: fastify.config.PLIVO_AUTH_TOKEN,
         sourceNumber: fastify.config.PLIVO_SOURCE_NUMBER,
       });
   
       // Register application routes
       fastify.register(broadcastRoutes, { prefix: '/api/v1' }); // Add a version prefix
   
       // Basic health check route
       fastify.get('/health', async (request, reply) => {
         return { status: 'ok', timestamp: new Date().toISOString() };
       });
   
       // Start the server
       await fastify.listen({
         port: parseInt(fastify.config.PORT, 10),
         host: fastify.config.HOST,
       });
   
       fastify.log.info(`Server dependencies loaded successfully.`);
   
     } catch (err) {
       fastify.log.error(err);
       process.exit(1);
     }
   };
   
   startServer();

   • We use dotenv to load the .env file before Fastify initializes fully.
   • fastify-env validates the loaded environment variables against envSchema. This ensures critical configuration is present and correctly formatted (like the E.164 pattern for the phone number).
   • We decorate the fastify instance with plivoConfig to make credentials easily accessible in services/routes without explicit passing.
   • A simple /health endpoint is added for monitoring.
   • Routes are registered with a /api/v1 prefix for better API versioning.
   • Logging is configured using Pino. Crucially, pino-pretty is conditionally used only when NODE_ENV is not production, ensuring readable logs in development and efficient JSON logs in production.

10. Run the Server (Development):

    bashCopy

    npm run dev

    You should see pretty-printed output indicating the server is listening on the configured host and port (e.g., http://0.0.0.0:3000). If fastify-env encounters missing or invalid variables, it will throw an error. To run in production mode (for JSON logs): NODE_ENV=production npm start.

2. Implementing Core Functionality (Plivo Service)

Now, let's create the service responsible for interacting with the Plivo API.

1. Create Plivo Service (src/services/plivoService.js):

   This service initializes the Plivo client and exposes a function to send bulk messages.

   javascriptCopy

   // src/services/plivoService.js
   'use strict';
   
   const plivo = require('plivo');
   
   let plivoClient; // Singleton client instance
   
   /**
    * Initializes the Plivo client using configuration from the Fastify instance.
    * Should be called once during application startup or on first use.
    * @param {object} config - Plivo configuration object { authId, authToken, sourceNumber }
    * @param {object} logger - Fastify logger instance
    */
   function initializePlivoClient(config, logger) {
     if (!plivoClient) {
       if (!config || !config.authId || !config.authToken) {
         logger.error('Plivo Auth ID or Auth Token is missing in config.');
         throw new Error('Plivo credentials are required for initialization.');
       }
       try {
          plivoClient = new plivo.Client(config.authId, config.authToken);
          logger.info('Plivo client initialized successfully.');
       } catch (error) {
          logger.error({ err: error }, 'Failed to initialize Plivo client');
          throw error; // Re-throw to prevent application start if client fails
       }
     }
     return plivoClient;
   }
   
   
   /**
    * Sends a single SMS message to multiple recipients using Plivo's bulk messaging.
    * @param {string[]} destinations - An array of destination phone numbers in E.164 format.
    * @param {string} message - The text message content.
    * @param {object} config - Plivo configuration object { authId, authToken, sourceNumber }
    * @param {object} logger - Fastify logger instance
    * @returns {Promise<object>} - The Plivo API response object.
    * @throws {Error} - If Plivo API call fails or input is invalid.
    */
   async function sendBulkSms(destinations, message, config, logger) {
     // Ensure client is initialized (idempotent)
     initializePlivoClient(config, logger);
   
     if (!Array.isArray(destinations) || destinations.length === 0) {
       logger.warn('sendBulkSms called with invalid or empty destinations array.');
       throw new Error('Destinations array cannot be empty.');
     }
     if (!message || typeof message !== 'string' || message.trim() === '') {
       logger.warn('sendBulkSms called with invalid or empty message.');
       throw new Error('Message content cannot be empty.');
     }
     if (!config.sourceNumber) {
          logger.error('Plivo source number is missing from configuration.');
          throw new Error('Plivo source number is required.');
     }
   
     // Plivo expects destination numbers separated by '<'
     // Filter out potential duplicates before joining
     const uniqueDestinations = [...new Set(destinations)];
     const plivoDestinationString = uniqueDestinations.join('<');
   
     // Plivo's current limit is 1,000 unique destination numbers per API call
     const MAX_RECIPIENTS_PER_REQUEST = 1000; // Source: https://www.plivo.com/docs/messaging/api/message/bulk-messaging
     if (uniqueDestinations.length > MAX_RECIPIENTS_PER_REQUEST) {
         logger.warn(`Attempted to send to ${uniqueDestinations.length} recipients, exceeding Plivo's limit of ${MAX_RECIPIENTS_PER_REQUEST}. The current implementation does NOT automatically batch requests. Request may fail.`);
         // Depending on requirements, you might throw an error or implement batching logic here.
         // throw new Error(`Cannot send to more than ${MAX_RECIPIENTS_PER_REQUEST} recipients in a single request without batching.`);
     }
   
   
     logger.info(
       `Attempting to send bulk SMS via Plivo to ${uniqueDestinations.length} unique recipients.`,
       );
   
     try {
       const response = await plivoClient.messages.create(
         config.sourceNumber,    // src: Your Plivo number
         plivoDestinationString, // dst: Recipients separated by '<'
         message,                // text: The message content
         // Optional parameters (e.g., method, url for status callbacks)
         // {
         //   method: 'POST', // Method for status callbacks
         //   url: 'https://your-app.com/plivo/status-callback' // Your callback URL
         // }
       );
   
       logger.info(
         {
           message_uuid: response.messageUuid,
           api_id: response.apiId,
           recipient_count: uniqueDestinations.length,
         },
         'Plivo bulk message request successful.',
       );
   
       // The response contains message UUIDs for tracking, but not individual delivery status here.
       // Use Webhooks for detailed status updates.
       return response;
   
     } catch (error) {
       logger.error(
         {
           err: error,
           plivoError: error.message, // Plivo SDK often puts useful info here
           statusCode: error.statusCode, // Plivo SDK might add statusCode
         },
         'Plivo API error during bulk message send.',
       );
       // Re-throw a generic error or a custom application error
       throw new Error(`Failed to send bulk SMS via Plivo: ${error.message}`);
     }
   }
   
   module.exports = {
     initializePlivoClient, // Export initializer if needed elsewhere, though route will handle it
     sendBulkSms,
   };

   • We use a module-level variable plivoClient to act as a singleton – the client is initialized only once.
   • The initializePlivoClient function handles the creation, taking config and logger from Fastify.
   • sendBulkSms performs input validation (non-empty destinations array, non-empty message).
   • It filters duplicate numbers using new Set(). Crucially, it joins the unique destination numbers with the < delimiter as required by Plivo's bulk API. Plivo automatically verifies that each destination number is in the correct format and removes duplicates, but pre-filtering improves efficiency.
   • It includes a check against Plivo's documented recipient limit of 1,000 per request. Note: The warning message explicitly states that automatic batching is not implemented in this code.
   • It calls plivoClient.messages.create with the source number, the <-separated destination string, and the message text.
   • Successful responses and errors from the Plivo API are logged appropriately.
   • Errors are caught and re-thrown to be handled by the route.
   • We comment out the optional url parameter for status callbacks – implementing webhooks is a vital next step for production monitoring but beyond this initial setup scope.

3. Building the API Layer (Broadcast Route)

Let's create the Fastify route that exposes our bulk sending functionality.

1. Define Route and Schema (src/routes/broadcast.js):

   This file defines the POST /broadcast endpoint, validates the incoming request body, and calls the Plivo service.

   javascriptCopy

   // src/routes/broadcast.js
   'use strict';
   
   const { sendBulkSms, initializePlivoClient } = require('../services/plivoService');
   
   // Define the schema for the request body and response
   const broadcastSchema = {
     body: {
       type: 'object',
       required: ['destinations', 'message'],
       properties: {
         destinations: {
           type: 'array',
           minItems: 1,
           items: {
             type: 'string',
             // Basic E.164 format validation
             pattern: '^\\+[1-9]\\d{1,14}$',
           },
           description: 'Array of recipient phone numbers in E.164 format (e.g., +14155552671)',
         },
         message: {
           type: 'string',
           minLength: 1,
           maxLength: 1600, // Standard SMS limit consideration (Plivo handles segmentation)
           description: 'The text message content to send.',
         },
       },
     },
     response: {
       200: { // Successful response
         type: 'object',
         properties: {
           message: { type: 'string' },
           message_uuid: { type: 'array', items: { type: 'string' } }, // Plivo returns UUIDs array
           api_id: { type: 'string' },
           recipient_count: { type: 'integer' },
         },
       },
       400: { // Bad request (validation failed)
          type: 'object',
          properties: {
            statusCode: { type: 'integer' },
            error: { type: 'string' },
            message: { type: 'string' },
          },
       },
        500: { // Server error (e.g., Plivo API failed)
          type: 'object',
          properties: {
            statusCode: { type: 'integer' },
            error: { type: 'string' },
            message: { type: 'string' },
          },
        },
        // Add other status codes like 429 for Rate Limiting if implemented
     },
   };
   
   
   async function broadcastRoutes(fastify, options) {
     // Ensure Plivo client is initialized when this route plugin is loaded
     // Access config decorated onto fastify instance in server.js
      initializePlivoClient(fastify.plivoConfig, fastify.log);
   
     fastify.post('/broadcast', { schema: broadcastSchema }, async (request, reply) => {
       const { destinations, message } = request.body;
       const requestId = request.id; // Fastify generates a unique ID for each request
   
       fastify.log.info(
           `[${requestId}] Received broadcast request for ${destinations.length} destinations.`,
           );
   
       try {
         // Call the Plivo service function
         const plivoResponse = await sendBulkSms(
            destinations,
            message,
            fastify.plivoConfig, // Pass Plivo config from fastify instance
            request.log // Pass request-specific logger for better context
         );
   
         // Send success response back to the client
         reply.code(200).send({
           message: plivoResponse.message, // e.g., ""message(s) queued""
           message_uuid: plivoResponse.messageUuid,
           api_id: plivoResponse.apiId,
           recipient_count: destinations.length, // Or use unique count if preferred
         });
   
          fastify.log.info(
            `[${requestId}] Broadcast request processed successfully. Plivo API ID: ${plivoResponse.apiId}`,
          );
   
       } catch (error) {
          fastify.log.error(
              `[${requestId}] Error processing broadcast request: ${error.message}`,
              { err: error } // Log the full error object
            );
   
         // Determine appropriate status code (could refine based on error type)
         // If it's a known Plivo client-side error (e.g., validation) maybe 400?
         // Otherwise, assume 500 for server/Plivo issues.
         // For now, defaulting to 500 for simplicity.
          reply.code(500).send({
            statusCode: 500,
            error: 'Internal Server Error',
            message: `Failed to send broadcast: ${error.message}`, // Provide some context
          });
       }
     });
   
      // You can add more routes here if needed
   }
   
   module.exports = broadcastRoutes;

   • We define a broadcastSchema using Fastify's schema validation capabilities. This automatically validates the request.body against the defined structure, types, and constraints (like minItems, minLength, and the E.164 pattern). If validation fails, Fastify automatically sends a 400 Bad Request response.
   • The schema also defines expected response formats for different status codes (200, 400, 500).
   • The route handler extracts destinations and message from the validated request.body.
   • It calls the sendBulkSms service function, passing the necessary data, the Plivo configuration (fastify.plivoConfig), and the request-specific logger (request.log) for contextual logging.
   • It handles success by sending a 200 response with relevant details from the Plivo API response.
   • It handles errors caught from the service layer by logging them and sending a 500 Internal Server Error response.

2. Register Route in Server:

   Ensure the route is registered in src/server.js (already done in Step 1.9). The line fastify.register(broadcastRoutes, { prefix: '/api/v1' }); handles this.

3. Test the Endpoint:

   Restart your server (npm run dev). You can now test the endpoint using curl or a tool like Postman.

   Using curl:

   Replace placeholders with your actual server address, valid E.164 numbers (use your own test numbers!), and a message.

   bashCopy

   curl -X POST http://localhost:3000/api/v1/broadcast \
   -H ""Content-Type: application/json"" \
   -d '{
     ""destinations"": [""+14155551234"", ""+14155555678"", ""+14155551234""],
     ""message"": ""Hello from the Fastify Bulk Broadcaster! Test message.""
   }'

   Expected Success Response (Example):

   jsonCopy

   {
     ""message"": ""message(s) queued"",
     ""message_uuid"": [
       ""e8f3a0ee-a1d7-11eb-8f9c-0242ac110002"",
       ""e8f3a3a8-a1d7-11eb-8f9c-0242ac110002""
     ],
     ""api_id"": ""f9b3aabc-a1d7-11eb-b3e0-0242ac110003"",
     ""recipient_count"": 3
   }

   (Note: Plivo's actual response structure for message_uuid might vary slightly; consult their documentation. The service filters duplicates before sending, so only 2 unique numbers are sent here).

   Example Error Response (Validation Failure):

   If you send invalid data (e.g., missing message or invalid phone number format):

   jsonCopy

   {
     ""statusCode"": 400,
     ""error"": ""Bad Request"",
     ""message"": ""body/destinations/0 must match pattern \""^\\\\+[1-9]\\\\d{1,14}$\""""
   }

   Example Error Response (Server/Plivo Error):

   If Plivo credentials are wrong or the API call fails:

   jsonCopy

   {
     ""statusCode"": 500,
     ""error"": ""Internal Server Error"",
     ""message"": ""Failed to send broadcast: Error: Authentication credentials invalid. Please check your auth_id and auth_token.""
   }

4. Integrating with Plivo (Credentials & Setup)

We've already integrated the SDK, but let's explicitly cover obtaining and securing credentials.

1. Obtain Plivo Auth ID and Auth Token:

   • Log in to your Plivo Console (https://console.plivo.com/).
   • On the main Dashboard/Overview page, you will find your Auth ID and Auth Token.
   • Copy these values carefully.

2. Obtain Plivo Source Number:

   • Navigate to Messaging -> Phone Numbers in the Plivo Console sidebar.
   • If you don't have a number, you'll need to buy one capable of sending SMS messages to your target regions.
   • Copy the Number in E.164 format (e.g., +14155552671).

3. Secure Storage:

   • As done in Step 1.8, place these credentials only in your .env file:

     dotenvCopy

     # .env
     PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
     PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
     PLIVO_SOURCE_NUMBER=+1XXXXXXXXXX
     # ... other vars

   • Crucially: Ensure .env is listed in your .gitignore file to prevent accidentally committing secrets to version control.

   • In production environments, use your hosting provider's mechanism for managing secrets (e.g., AWS Secrets Manager, Kubernetes Secrets, environment variables injected by the platform).

4. Fallback Mechanisms:

   • The current implementation relies directly on Plivo. For high availability, consider:
     • Retry Logic: Implement application-level retries with exponential backoff (see Section 5) for transient network errors before calling Plivo.
     • Secondary Provider: Abstract the SMS sending logic further. If Plivo fails consistently (e.g., platform outage), you could potentially switch to a different SMS provider API. This adds significant complexity. For this guide, we focus on robust error handling with Plivo.

5. Error Handling, Logging, and Retry Mechanisms

We've built basic error handling and logging. Let's enhance it.

1. Consistent Error Handling:

   • Service Layer (plivoService.js): Catches specific Plivo API errors, logs detailed information (including Plivo error messages/codes if available), and throws a standardized Error object.
   • Route Layer (broadcast.js): Catches errors propagated from the service layer. Logs the error with request context (request.id, request.log). Sends an appropriate HTTP status code (4xx for client errors it can detect, 5xx for server/dependency errors) and a generic error message to the client, avoiding leaking internal details. Fastify's schema validation automatically handles 400 errors for invalid input.
   • Global Error Handler (Optional): For unhandled exceptions, Fastify allows setting a global error handler using fastify.setErrorHandler((error, request, reply) => { ... }). This can catch unexpected errors and ensure a consistent error response format.

2. Logging:

   • Levels: Use LOG_LEVEL env var (info, debug, warn, error, fatal) to control verbosity. info is good for production, debug for development.
   • Context: Fastify automatically injects reqId into logs. We pass request.log to the service layer (sendBulkSms) so service-level logs also contain the request ID, making it easy to trace a single request's lifecycle through logs.
   • Format: As configured in Section 1, pino-pretty is used for development readability. In production (NODE_ENV=production), output defaults to JSON logs for easier parsing by log aggregation systems (e.g., ELK stack, Datadog, Loki).
   • What to Log:
     • Request received (info)
     • Validation errors (warn or info, Fastify handles response)
     • Calls to external services (Plivo) (info/debug)
     • Successful external service responses (info)
     • Errors from external services (error)
     • Application logic errors (error)
     • Key decision points or state changes (debug)

3. Retry Mechanisms:

   • Plivo Internal Retries: Plivo may have internal retries for certain transient issues, but don't rely solely on this.
   • Application-Level Retries: For network errors or specific Plivo error codes indicating a temporary issue (e.g., rate limit exceeded, temporary gateway error), you can implement retries before calling plivoClient.messages.create. Libraries like async-retry or p-retry are excellent for this.

   Example using async-retry (Conceptual):

   First, install the library:

   bashCopy

   npm install async-retry

   Then, modify the service conceptually:

   javascriptCopy

   // src/services/plivoService.js (Conceptual modification with async-retry)
   const retry = require('async-retry');
   const plivo = require('plivo'); // Assuming plivo is already required
   
   let plivoClient;
   function initializePlivoClient(config, logger) { /* ... as before ... */ }
   
   async function sendBulkSms(destinations, message, config, logger) {
     initializePlivoClient(config, logger);
     // ... existing validation ...
     const uniqueDestinations = [...new Set(destinations)];
     const plivoDestinationString = uniqueDestinations.join('<');
     // ... MAX_RECIPIENTS_PER_REQUEST check ...
   
     logger.info(
       `Attempting to send bulk SMS via Plivo to ${uniqueDestinations.length} unique recipients (with retry logic).`
     );
   
     try {
       // Wrap the Plivo call in retry logic
       const response = await retry(
         async (bail, attemptNumber) => {
           // bail is a function to stop retrying (e.g., for auth errors)
           // attemptNumber is the current retry attempt
           logger.debug(`Plivo API call attempt #${attemptNumber}`);
           try {
             const result = await plivoClient.messages.create(
                config.sourceNumber,
                plivoDestinationString,
                message
                // Optional params...
             );
             logger.info(`Plivo API attempt #${attemptNumber} successful.`);
             return result; // Success, return result
           } catch (error) {
             logger.warn(`Plivo API attempt #${attemptNumber} failed: ${error.message}`);
             // Decide if the error is retryable
             // Example: Don't retry authentication errors (401)
             if (error.statusCode === 401 || (error.message && error.message.includes('Authentication credentials invalid'))) {
                logger.error('Authentication error. Not retrying.');
                bail(new Error(`Plivo authentication failed: ${error.message}`)); // Stop retrying
                return; // Necessary after bail
             }
             // Example: Retry potentially transient errors (rate limit 429, server errors 5xx)
             if (error.statusCode === 429 || error.statusCode >= 500) {
                logger.warn(`Retryable error detected (status: ${error.statusCode}). Throwing to trigger retry.`);
                throw error; // Throw error to trigger retry by async-retry
             }
             // For other client-side errors (e.g., invalid number 400), don't retry
             logger.error(`Non-retryable Plivo error (status: ${error.statusCode || 'N/A'}). Not retrying.`);
             bail(new Error(`Non-retryable Plivo error: ${error.message}`));
             return; // Necessary after bail
           }
         },
         {
           retries: 3, // Number of retries (total attempts = retries + 1)
           factor: 2, // Exponential backoff factor
           minTimeout: 1000, // Initial delay ms
           maxTimeout: 5000, // Max delay ms
           onRetry: (error, attempt) => {
             logger.warn(`Retrying Plivo API call (attempt ${attempt}) due to: ${error.message}`);
           },
         }
       );
   
       logger.info(
         {
           message_uuid: response.messageUuid,
           api_id: response.apiId,
           recipient_count: uniqueDestinations.length,
         },
         'Plivo bulk message request successful after potential retries.',
       );
       return response;
   
     } catch (error) {
       // This catches errors after all retries fail or if bail was called
       logger.error(
         {
           err: error,
           plivoError: error.message,
           statusCode: error.statusCode,
         },
         'Plivo API error during bulk message send after all retries.',
       );
       throw new Error(`Failed to send bulk SMS via Plivo after retries: ${error.message}`);
     }
   }
   
   module.exports = { initializePlivoClient, sendBulkSms };

   • This adds complexity but improves resilience against temporary Plivo issues or network glitches. Carefully define which errors are retryable.
   • Avoid retrying user errors (e.g., invalid phone numbers, authentication failures) – these won't succeed on retry and waste resources.
   • For rate limiting (429), consider adding a longer delay or implementing a queue-based approach.

6. Deployment and Production Considerations

Before deploying your Fastify bulk SMS broadcaster to production, consider these important factors:

1. Environment Variables:

   • Never hardcode credentials. Always use environment variables.
   • Use your cloud provider's secret management service (AWS Secrets Manager, Azure Key Vault, Google Secret Manager, etc.).
   • Set NODE_ENV=production to enable production logging (JSON format, no pino-pretty).

2. Security:

   • Rate Limiting: Implement rate limiting on the /broadcast endpoint to prevent abuse. Use plugins like @fastify/rate-limit.
   • Authentication: Add API key authentication or OAuth to protect your endpoint from unauthorized access.
   • Input Sanitization: While schema validation helps, ensure message content is sanitized if storing or displaying it.
   • HTTPS: Always use HTTPS in production to encrypt data in transit.

3. Monitoring and Observability:

   • Health Checks: The /health endpoint should be monitored by your orchestration platform (Kubernetes, AWS ECS, etc.).
   • Metrics: Track API response times, error rates, and Plivo API success/failure rates.
   • Alerting: Set up alerts for increased error rates or slow response times.
   • Distributed Tracing: For complex systems, consider adding OpenTelemetry or similar tracing.

4. Webhooks for Delivery Status:

   • Implement a webhook endpoint to receive delivery status updates from Plivo.
   • Store delivery status in a database for auditing and analytics.
   • This requires exposing a publicly accessible endpoint (e.g., POST /api/v1/plivo/callback).

5. Scaling Considerations:

   • Fastify is designed for high performance, but for very high volumes:
     • Use a load balancer to distribute traffic across multiple instances.
     • Consider using a message queue (RabbitMQ, AWS SQS, Redis) to decouple request handling from SMS sending.
     • Implement database persistence for tracking message status and history.

6. Error Recovery:

   • Consider implementing a dead-letter queue for failed messages.
   • Implement automatic retry with exponential backoff for transient failures.
   • Log all failures with sufficient context for debugging.

7. Testing:

   • Write unit tests for your service layer (plivoService.js).
   • Write integration tests for your routes.
   • Use Plivo's test credentials or sandbox environment for testing.

8. Documentation:

   • Document your API endpoints with examples.
   • Provide clear error messages and status codes.
   • Document rate limits and usage quotas.

9. Compliance:

   • TCPA Compliance: Ensure you have proper consent before sending SMS messages to US numbers.
   • 10DLC Registration: Register your use case with The Campaign Registry for A2P messaging in the US.
   • Opt-out Handling: Implement automatic opt-out handling (STOP, UNSUBSCRIBE).
   • GDPR/Privacy: Handle personal data (phone numbers) in compliance with applicable privacy laws.

Conclusion

You've successfully built a production-ready bulk SMS broadcasting service using Plivo, Fastify, and Node.js. This implementation provides:

• Efficient bulk messaging using Plivo's API (up to 1,000 recipients per request)
• Robust error handling with detailed logging
• Input validation using Fastify schemas
• Security best practices for credential management
• Production-ready logging with Pino
• Optional retry mechanisms for resilience

Next Steps

• Implement webhook handlers for delivery status tracking
• Add authentication and rate limiting
• Set up monitoring and alerting
• Implement batching logic for >1,000 recipients
• Add database persistence for message history
• Register for 10DLC if sending to US numbers
• Consider adding a message queue for high-volume scenarios

Additional Resources

• Plivo API Documentation
• Fastify Documentation
• Node.js Best Practices
• 10DLC Registration Guide