Plivo WhatsApp Integration with Node.js and Fastify: Complete Guide 2025

# Create project directory and navigate into it
mkdir fastify-plivo-whatsapp
cd fastify-plivo-whatsapp

# Initialize npm project
npm init -y

# Install core dependencies
# Note: Use 'plivo' (not 'plivo-node' which is deprecated)
npm install fastify @fastify/env @fastify/sensible @fastify/type-provider-typebox plivo

# Install development dependencies
npm install typescript @types/node ts-node nodemon pino-pretty --save-dev

# Initialize TypeScript configuration
npx tsc --init --rootDir src --outDir dist --esModuleInterop --resolveJsonModule --lib esnext --module commonjs --allowJs true --noImplicitAny true

fastify-plivo-whatsapp/
├── dist/             # Compiled JavaScript output (from tsc)
├── src/              # TypeScript source code
│   ├── routes/       # API route definitions
│   ├── services/     # Business logic (Plivo interaction)
│   ├── schemas/      # Request/response validation schemas
│   ├── utils/        # Utility functions
│   └── server.ts     # Fastify server setup and entry point
├── .env              # Environment variables (DO NOT COMMIT)
├── .env.example      # Example environment variables (commit this)
├── .gitignore
├── package.json
└── tsconfig.json

{
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "nodemon --watch src --ext ts --exec ts-node src/server.ts",
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

// src/server.ts
import Fastify, { FastifyInstance, FastifyServerOptions } from 'fastify';
import sensible from '@fastify/sensible';
import envPlugin from '@fastify/env';
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
import { S } from '@fastify/type-provider-typebox';

// Import routes
import whatsappRoutes from './routes/whatsappRoutes';
// Import Plivo initializer
import { initializePlivoClient } from './services/plivoService';

// Define environment variable schema
const envSchema = S.Object({
  PORT: S.Number({ default: 3000 }),
  HOST: S.String({ default: '0.0.0.0' }),
  LOG_LEVEL: S.String({ default: 'info' }),
  PLIVO_AUTH_ID: S.String(),
  PLIVO_AUTH_TOKEN: S.String(),
  PLIVO_WHATSAPP_NUMBER: S.String(),
  PLIVO_WEBHOOK_SECRET: S.String({ default: '' }),
  API_KEY: S.String(),
});

// Declare module augmentation for FastifyInstance
declare module 'fastify' {
  interface FastifyInstance {
    config: {
      PORT: number;
      HOST: string;
      LOG_LEVEL: string;
      PLIVO_AUTH_ID: string;
      PLIVO_AUTH_TOKEN: string;
      PLIVO_WHATSAPP_NUMBER: string;
      PLIVO_WEBHOOK_SECRET: string;
      API_KEY: string;
    };
  }
}


async function buildServer(): Promise<FastifyInstance> {
  const isProduction = process.env.NODE_ENV === 'production';

  const serverOptions: FastifyServerOptions = {
    logger: {
      level: process.env.LOG_LEVEL || 'info',
      // Use pino-pretty only in development for better readability
      transport: isProduction
        ? undefined
        : { target: 'pino-pretty', options: { translateTime: 'SYS:standard', ignore: 'pid,hostname' } },
    },
    ajv: {
      customOptions: {
        removeAdditional: 'all',
        useDefaults: true,
        coerceTypes: true,
        allErrors: true,
      }
    }
  };

  const server = Fastify(serverOptions).withTypeProvider<TypeBoxTypeProvider>();

  try {
    // Register environment variables plugin
    await server.register(envPlugin, {
      dotenv: true,
      schema: envSchema,
    });

    // Initialize Plivo Client *after* config is loaded
    initializePlivoClient(server);

    // Register sensible plugin (adds useful decorators like httpErrors)
    await server.register(sensible);

    // Register Routes
    await server.register(whatsappRoutes, { prefix: '/api/whatsapp' });

    // Default Root Route
    server.get('/', async (request, reply) => {
      return { message: 'Fastify Plivo WhatsApp Service Running', timestamp: new Date().toISOString() };
    });

    // Health Check Route
    server.get('/health', async (request, reply) => {
      return { status: 'ok', timestamp: new Date().toISOString() };
    });

    server.log.info('Server plugins and routes registered successfully.');

  } catch (err) {
    server.log.error(err, 'Error during server setup');
    process.exit(1);
  }

  return server;
}


async function start() {
  let server: FastifyInstance | null = null;
  try {
      server = await buildServer();

      await server.listen({ port: server.config.PORT, host: server.config.HOST });
      server.log.info(`Server listening at http://${server.config.HOST}:${server.config.PORT}`);
      server.log.info(`Plivo WhatsApp Number configured: ${server.config.PLIVO_WHATSAPP_NUMBER}`);

      setupGracefulShutdown(server);

  } catch (err) {
      if (server) {
          server.log.error(err, 'Error starting server');
      } else {
          console.error('Error during server build/start:', err);
      }
      process.exit(1);
  }
}

// Graceful shutdown handler
const setupGracefulShutdown = (server: FastifyInstance) => {
    const shutdown = async (signal: string) => {
        server.log.warn(`Received ${signal}. Shutting down gracefully…`);
        try {
            await server.close();
            server.log.info('Server closed successfully.');
            process.exit(0);
        } catch (err) {
            server.log.error(err, 'Error during graceful shutdown');
            process.exit(1);
        }
    };

    process.on('SIGINT', () => shutdown('SIGINT'));
    process.on('SIGTERM', () => shutdown('SIGTERM'));
};


// Start the server
start().catch(err => {
  console.error('Unhandled error during startup process:', err);
  process.exit(1);
});

// src/services/plivoService.ts
import { Client, MessageCreateParams, Template } from 'plivo-node';
import { FastifyInstance } from 'fastify';

let plivoClient: Client;

// Initialize the Plivo client using config from Fastify instance
export function initializePlivoClient(server: FastifyInstance): void {
  if (!plivoClient) {
    if (!server.config.PLIVO_AUTH_ID || !server.config.PLIVO_AUTH_TOKEN) {
        server.log.error('Plivo Auth ID or Auth Token missing in configuration. Cannot initialize Plivo client.');
        throw new Error('Plivo credentials missing.');
    }
    plivoClient = new Client(
      server.config.PLIVO_AUTH_ID,
      server.config.PLIVO_AUTH_TOKEN
    );
    server.log.info('Plivo client initialized successfully.');
  }
}

// Send a standard WhatsApp text message
export async function sendWhatsAppTextMessage(
  server: FastifyInstance,
  to: string,
  text: string
): Promise<any> {
  if (!plivoClient) {
    server.log.error('Plivo client accessed before initialization.');
    throw new Error('Plivo client not initialized. Call initializePlivoClient first.');
  }

  const params: MessageCreateParams = {
    src: server.config.PLIVO_WHATSAPP_NUMBER,
    dst: to,
    text: text,
    type: 'whatsapp',
  };

  server.log.info({ dst: to, type: 'text' }, 'Sending WhatsApp text message via Plivo');

  try {
    const response = await plivoClient.messages.create(params);
    server.log.info({ message_uuid: response.messageUuid, api_id: response.apiId }, 'WhatsApp text message sent successfully via Plivo');
    return response;
  } catch (error: any) {
    server.log.error({ error: error.message, stack: error.stack, params }, 'Error sending WhatsApp text message via Plivo');
    throw new Error(`Plivo API Error: ${error.message || 'Unknown error'}`);
  }
}

// Send a WhatsApp template message
export async function sendWhatsAppTemplateMessage(
  server: FastifyInstance,
  to: string,
  template: Template
): Promise<any> {
  if (!plivoClient) {
     server.log.error('Plivo client accessed before initialization.');
    throw new Error('Plivo client not initialized. Call initializePlivoClient first.');
  }

  if (!template || !template.name || !template.language) {
     server.log.warn({ templateReceived: template }, 'Invalid template object provided to sendWhatsAppTemplateMessage');
     throw new Error('Invalid template object: name and language are required.');
  }

  const params: MessageCreateParams = {
    src: server.config.PLIVO_WHATSAPP_NUMBER,
    dst: to,
    template: template,
    type: 'whatsapp',
  };

  server.log.info({ dst: to, templateName: template.name }, 'Sending WhatsApp template message via Plivo');

  try {
    const response = await plivoClient.messages.create(params);
    server.log.info({ message_uuid: response.messageUuid, api_id: response.apiId }, 'WhatsApp template message sent successfully via Plivo');
    return response;
  } catch (error: any) {
    server.log.error({ error: error.message, stack: error.stack, params }, 'Error sending WhatsApp template message via Plivo');
    throw new Error(`Plivo API Error: ${error.message || 'Unknown error'}`);
  }
}

// src/schemas/whatsappSchemas.ts
import { Type, Static } from '@fastify/type-provider-typebox';

// Schema for sending a plain text message
export const SendTextBodySchema = Type.Object({
  to: Type.String({
    description: 'Recipient WhatsApp number in E.164 format (e.g., +14155551234)',
    pattern: '^\\+[1-9]\\d{1,14}$'
  }),
  text: Type.String({ description: 'The text content of the message', minLength: 1, maxLength: 4096 })
});
export type SendTextBody = Static<typeof SendTextBodySchema>;

// Schema for Plivo Template Parameter component
const TemplateParameterSchema = Type.Object({
  type: Type.Union([Type.Literal('text'), Type.Literal('media'), Type.Literal('payload')]),
  text: Type.Optional(Type.String()),
  media: Type.Optional(Type.String({ format: 'uri', description: 'URL of the media file' })),
  payload: Type.Optional(Type.String())
});

// Schema for Plivo Template Component
const TemplateComponentSchema = Type.Object({
  type: Type.Union([Type.Literal('header'), Type.Literal('body'), Type.Literal('footer'), Type.Literal('button')]),
  sub_type: Type.Optional(Type.String()),
  index: Type.Optional(Type.Number()),
  parameters: Type.Optional(Type.Array(TemplateParameterSchema))
});

// Schema for Plivo Template object
export const PlivoTemplateSchema = Type.Object({
    name: Type.String({ description: 'The registered name of the template' }),
    language: Type.String({ description: 'The language code of the template (e.g., en_US)' }),
    components: Type.Optional(Type.Array(TemplateComponentSchema))
});
export type PlivoTemplate = Static<typeof PlivoTemplateSchema>;


// Schema for sending a template message
export const SendTemplateBodySchema = Type.Object({
  to: Type.String({
      description: 'Recipient WhatsApp number in E.164 format',
      pattern: '^\\+[1-9]\\d{1,14}$'
  }),
  template: PlivoTemplateSchema
});
export type SendTemplateBody = Static<typeof SendTemplateBodySchema>;

// Generic Success Response Schema
export const SuccessResponseSchema = Type.Object({
  message: Type.String(),
  message_uuid: Type.Optional(Type.String()),
  api_id: Type.Optional(Type.String())
});
export type SuccessResponse = Static<typeof SuccessResponseSchema>;


// Schema for incoming Plivo WhatsApp message webhook
export const PlivoIncomingWebhookSchema = Type.Object({
    From: Type.String(),
    To: Type.String(),
    Type: Type.String(),
    Text: Type.Optional(Type.String()),
    MediaUrl0: Type.Optional(Type.String()),
    MediaContentType0: Type.Optional(Type.String()),
    NumMedia: Type.Optional(Type.String()),
    Latitude: Type.Optional(Type.String()),
    Longitude: Type.Optional(Type.String()),
    LocationAddress: Type.Optional(Type.String()),
    ContactName: Type.Optional(Type.String()),
    ContactNumber: Type.Optional(Type.String()),
    ButtonPayload: Type.Optional(Type.String()),
    ListResponseTitle: Type.Optional(Type.String()),
    InteractiveType: Type.Optional(Type.String()),
    MessageUUID: Type.String()
});
export type PlivoIncomingWebhook = Static<typeof PlivoIncomingWebhookSchema>;

// Schema for incoming Plivo WhatsApp status webhook
export const PlivoStatusWebhookSchema = Type.Object({
    MessageUUID: Type.String(),
    Status: Type.String(),
    To: Type.String(),
    From: Type.String(),
    ErrorCode: Type.Optional(Type.String()),
    ErrorMessage: Type.Optional(Type.String()),
});
export type PlivoStatusWebhook = Static<typeof PlivoStatusWebhookSchema>;

// src/routes/whatsappRoutes.ts
import { FastifyInstance, FastifyPluginOptions, FastifyRequest, FastifyReply } from 'fastify';
import { Type } from '@fastify/type-provider-typebox';
import { PlivoIncomingWebhook, PlivoStatusWebhook, PlivoTemplate, SendTemplateBody, SendTextBody, SendTemplateBodySchema, SendTextBodySchema, SuccessResponse, SuccessResponseSchema, PlivoIncomingWebhookSchema, PlivoStatusWebhookSchema } from '../schemas/whatsappSchemas';
import { sendWhatsAppTemplateMessage, sendWhatsAppTextMessage } from '../services/plivoService';

// Simple Authentication Hook (API Key)
async function authenticate(request: FastifyRequest, reply: FastifyReply) {
  const apiKey = request.headers['x-api-key'];
  if (!apiKey || apiKey !== request.server.config.API_KEY) {
      request.log.warn('Authentication failed: Invalid or missing API Key');
      reply.unauthorized('Invalid or missing API Key');
      return reply;
  }
}

// Plivo Webhook Validation Hook (Partial Implementation)
async function validatePlivoWebhook(request: FastifyRequest, reply: FastifyReply) {
    const secret = request.server.config.PLIVO_WEBHOOK_SECRET;
    // Skip validation if no secret is configured
    if (!secret) {
        request.log.warn('Skipping Plivo webhook validation: PLIVO_WEBHOOK_SECRET not configured.');
        return;
    }

    const signature = request.headers['x-plivo-signature-v3'] as string;
    const nonce = request.headers['x-plivo-signature-v3-nonce'] as string;

    if (!signature || !nonce) {
        request.log.warn('Plivo webhook validation failed: Missing X-Plivo-Signature-V3 or X-Plivo-Signature-V3-Nonce headers.');
        reply.badRequest('Missing Plivo signature headers');
        return reply;
    }

    // TODO: Implement signature verification using crypto.
    // The signature is calculated using HMAC-SHA256(URL + Nonce + RawBody, WebhookSecret).
    // Use libraries like `fastify-raw-body` to access the raw payload.
    // See Plivo documentation: https://www.plivo.com/docs/getting-started/concepts/webhooks#validate-requests-from-plivo

    request.log.info('Plivo webhook headers present. TODO: Implement full signature validation.');
}


// Define the routes
export default async function whatsappRoutes(server: FastifyInstance, options: FastifyPluginOptions) {

  // Send Text Message Endpoint
  server.post<{ Body: SendTextBody; Reply: SuccessResponse | { error: string } }>(
    '/send/text',
    {
      schema: {
        description: 'Sends a plain text WhatsApp message via Plivo.',
        tags: ['WhatsApp'],
        summary: 'Send Text Message',
        headers: {
            type: 'object',
            properties: { 'x-api-key': { type: 'string' } },
            required: ['x-api-key']
        },
        body: SendTextBodySchema,
        response: {
          200: SuccessResponseSchema,
        },
      },
      preHandler: [authenticate]
    },
    async (request, reply) => {
      try {
        const { to, text } = request.body;
        const plivoResponse = await sendWhatsAppTextMessage(server, to, text);
        reply.send({
          message: 'WhatsApp text message sent successfully.',
          message_uuid: plivoResponse.messageUuid?.[0],
          api_id: plivoResponse.apiId
        });
      } catch (error: any) {
        request.log.error(error, 'Error in /send/text handler');
        reply.internalServerError(error.message || 'Failed to send WhatsApp text message.');
      }
    }
  );

  // Send Template Message Endpoint
  server.post<{ Body: SendTemplateBody; Reply: SuccessResponse | { error: string } }>(
    '/send/template',
    {
      schema: {
        description: 'Sends a WhatsApp template message via Plivo.',
        tags: ['WhatsApp'],
        summary: 'Send Template Message',
        headers: {
            type: 'object',
            properties: { 'x-api-key': { type: 'string' } },
            required: ['x-api-key']
        },
        body: SendTemplateBodySchema,
        response: {
          200: SuccessResponseSchema,
        },
      },
      preHandler: [authenticate]
    },
    async (request, reply) => {
      try {
        const { to, template } = request.body;
        const plivoResponse = await sendWhatsAppTemplateMessage(server, to, template as PlivoTemplate);
        reply.send({
          message: 'WhatsApp template message sent successfully.',
          message_uuid: plivoResponse.messageUuid?.[0],
          api_id: plivoResponse.apiId
        });
      } catch (error: any) {
        request.log.error(error, 'Error in /send/template handler');
        reply.internalServerError(error.message || 'Failed to send WhatsApp template message.');
      }
    }
  );

  // Plivo Webhook Endpoint (Incoming Messages & Status Updates)
  server.post<{ Body: PlivoIncomingWebhook | PlivoStatusWebhook }>(
    '/webhooks/plivo',
    {
      schema: {
        description: 'Receives incoming WhatsApp messages and status updates from Plivo.',
        tags: ['Webhooks', 'WhatsApp'],
        summary: 'Plivo Webhook Handler',
        response: {
          200: Type.Object({ status: Type.String() }),
        },
      },
      preHandler: [validatePlivoWebhook]
    },
    async (request, reply) => {
      const payload = request.body;
      request.log.info({ payload }, 'Received Plivo webhook');

      try {
        // Differentiate between Message Status and Incoming Message
        if ('Status' in payload && 'MessageUUID' in payload && !('Type' in payload)) {
          const statusPayload = payload as PlivoStatusWebhook;
          request.log.info({ uuid: statusPayload.MessageUUID, status: statusPayload.Status }, 'Processing Plivo status update webhook');
          // TODO: Handle status update (e.g., update message status in DB)

        } else if ('Type' in payload && 'From' in payload && 'To' in payload && 'MessageUUID' in payload) {
          const incomingPayload = payload as PlivoIncomingWebhook;
          request.log.info({ uuid: incomingPayload.MessageUUID, from: incomingPayload.From, type: incomingPayload.Type }, 'Processing Plivo incoming message webhook');
          // TODO: Handle incoming message (e.g., log message, trigger auto-reply)

        } else {
          request.log.warn({ payload }, 'Received unknown Plivo webhook payload structure.');
        }

        reply.code(200).send({ status: 'received' });

      } catch (error: any) {
        request.log.error(error, 'Error processing Plivo webhook');
        reply.code(200).send({ status: 'error processing' });
      }
    }
  );
}

npm run dev

curl -X POST http://localhost:3000/api/whatsapp/send/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secure-api-key" \
  -d '{
    "to": "+14155552345",
    "text": "Hello from Fastify and Plivo!"
  }'

curl -X POST http://localhost:3000/api/whatsapp/send/template \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secure-api-key" \
  -d '{
    "to": "+14155552345",
    "template": {
      "name": "welcome_template",
      "language": "en_US",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "John Doe"
            }
          ]
        }
      ]
    }
  }'

ngrok http 3000

# Use official Node.js LTS image
FROM node:22-alpine

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source code
COPY . .

# Build TypeScript
RUN npm run build

# Expose port
EXPOSE 3000

# Start the application
CMD ["node", "dist/server.js"]

node_modules
dist
.env
.git
.gitignore
*.md

# Build the image
docker build -t fastify-plivo-whatsapp .

# Run the container
docker run -p 3000:3000 --env-file .env fastify-plivo-whatsapp

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: whatsapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

docker-compose up -d