Build WhatsApp Integration with Vonage and NestJS: Complete Guide

sequenceDiagram
    participant User as WhatsApp User
    participant WhatsApp
    participant Vonage as Vonage Messages API
    participant Ngrok as ngrok (Dev Only)
    participant NestJS as NestJS Application

    User->>+WhatsApp: Sends message
    WhatsApp->>+Vonage: Delivers inbound message
    Vonage->>+Ngrok: Forwards message to webhook URL
    Ngrok->>+NestJS: Delivers message payload to /webhooks/inbound
    NestJS-->>-Ngrok: Responds 200 OK
    Ngrok-->>-Vonage: Forwards 200 OK
    Note right of NestJS: Process inbound message (e.g., log, reply)
    NestJS->>+Vonage: Sends reply message via API
    Vonage->>+WhatsApp: Delivers reply message
    WhatsApp->>-User: Shows reply message

    Note over Vonage, NestJS: Status Updates
    Vonage->>+Ngrok: Forwards status update to webhook URL
    Ngrok->>+NestJS: Delivers status payload to /webhooks/status
    NestJS-->>-Ngrok: Responds 200 OK
    Ngrok-->>-Vonage: Forwards 200 OK
    Note right of NestJS: Process status update (e.g., log)

npm install -g @nestjs/cli

nest new vonage-whatsapp-nestjs
cd vonage-whatsapp-nestjs

npm install @vonage/server-sdk @vonage/messages @vonage/jwt @nestjs/config dotenv
# Or using yarn:
# yarn add @vonage/server-sdk @vonage/messages @vonage/jwt @nestjs/config dotenv

# .env

# Vonage API Credentials & Application Details
VONAGE_API_KEY=YOUR_VONAGE_API_KEY
VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
VONAGE_PRIVATE_KEY_PATH=./private.key # Path relative to project root
VONAGE_API_SIGNATURE_SECRET=YOUR_VONAGE_SIGNATURE_SECRET # For webhook verification

# Vonage WhatsApp Number (Sandbox or Purchased)
VONAGE_WHATSAPP_NUMBER=VONAGE_PROVIDED_WHATSAPP_NUMBER

# Application Port
PORT=3000 # Default NestJS port

# Vonage API Host (Optional: Use sandbox for testing initially)
VONAGE_API_HOST=https://messages-sandbox.nexmo.com # For production, remove this line to default to the production URL (api.nexmo.com)

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { VonageModule } from './vonage/vonage.module'; // We will create this
import { WebhooksModule } from './webhooks/webhooks.module'; // We will create this

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigModule available globally
      envFilePath: '.env', // Load variables from .env file
    }),
    VonageModule, // Add Vonage module
    WebhooksModule, // Add Webhooks module
  ],
  controllers: [AppController], // Default controller
  providers: [AppService], // Default service
})
export class AppModule {}

ngrok http 3000

nest g module vonage
nest g service vonage --no-spec # --no-spec skips generating a test file for now

// src/vonage/vonage.module.ts
import { Module } from '@nestjs/common';
import { VonageService } from './vonage.service';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule if needed directly

@Module({
  imports: [ConfigModule], // Ensure ConfigService is available if needed directly
  providers: [VonageService],
  exports: [VonageService], // Export the service so other modules can use it
})
export class VonageModule {}

// src/vonage/vonage.service.ts
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Vonage } from '@vonage/server-sdk';
import { WhatsAppText } from '@vonage/messages';
import * as fs from 'fs';

@Injectable()
export class VonageService implements OnModuleInit {
  private readonly logger = new Logger(VonageService.name);
  private vonageClient: Vonage;
  private vonageWhatsAppNumber: string;

  constructor(private configService: ConfigService) {}

  // Initialize the client when the module loads
  onModuleInit() {
    try {
      const apiKey = this.configService.get<string&gt;('VONAGE_API_KEY');
      const apiSecret = this.configService.get<string&gt;('VONAGE_API_SECRET');
      const applicationId = this.configService.get<string&gt;(
        'VONAGE_APPLICATION_ID',
      );
      const privateKeyPath = this.configService.get<string&gt;(
        'VONAGE_PRIVATE_KEY_PATH',
      );
      // Check for optional sandbox host, default to production if not set
      const apiHost = this.configService.get<string&gt;('VONAGE_API_HOST');
      this.vonageWhatsAppNumber = this.configService.get<string&gt;(
        'VONAGE_WHATSAPP_NUMBER',
      );

      // Validate required config
      if (
        !apiKey ||
        !apiSecret ||
        !applicationId ||
        !privateKeyPath ||
        !this.vonageWhatsAppNumber
      ) {
        throw new Error('Missing required Vonage configuration in .env file');
      }

      // Ensure private key file exists
      if (!fs.existsSync(privateKeyPath)) {
        throw new Error(`Private key file not found at: ${privateKeyPath}`);
      }

      const privateKey = fs.readFileSync(privateKeyPath);

      this.vonageClient = new Vonage(
        {
          apiKey: apiKey,
          apiSecret: apiSecret,
          applicationId: applicationId,
          privateKey: privateKey,
        },
        // Optional: Specify API host for sandbox or specific region
        // If VONAGE_API_HOST is not set in .env, it defaults to production
        apiHost ? { apiHost: apiHost } : {},
      );

      this.logger.log('Vonage client initialized successfully.');
      if (apiHost) {
        this.logger.warn(`Vonage client using API host: ${apiHost}`);
      } else {
        this.logger.log('Vonage client using default production API host.');
      }
    } catch (error) {
      this.logger.error('Failed to initialize Vonage client:', error.message);
      // Depending on your app's needs, you might want to throw the error
      // or handle it differently to prevent the app from starting incorrectly.
      throw new Error(`Vonage initialization failed: ${error.message}`);
    }
  }

  /**
   * Sends a WhatsApp text message.
   * @param to The recipient's phone number (E.164 format, without leading '+').
   * @param text The message content.
   * @returns The message UUID on success.
   * @throws Error if sending fails.
   */
  async sendWhatsAppTextMessage(to: string, text: string): Promise<string&gt; {
    if (!this.vonageClient) {
      this.logger.error(
        'Vonage client not initialized. Cannot send message.',
      );
      throw new Error('Vonage client not available.');
    }

    this.logger.log(`Attempting to send WhatsApp message to ${to}`);

    try {
      const response = await this.vonageClient.messages.send(
        new WhatsAppText({
          from: this.vonageWhatsAppNumber,
          to: to, // E.164 format without '+'
          text: text,
        }),
      );

      this.logger.log(
        `Message sent successfully to ${to}. Message UUID: ${response.messageUuid}`,
      );
      return response.messageUuid;
    } catch (error) {
      this.logger.error(`Error sending WhatsApp message to ${to}:`, error);

      // Log more detailed error info if available
      if (error.response?.data) {
        this.logger.error('Vonage API Error details:', error.response.data);
      }

      // Re-throw a more specific error or a generic one
      throw new Error(
        `Failed to send WhatsApp message: ${
          error.response?.data?.title || error.message
        }`,
      );
    }
  }

  // Add methods for other message types (images, templates, etc.) as needed
}

nest g module webhooks
nest g controller webhooks --no-spec
# Optional: nest g service webhooks --no-spec (if logic becomes complex)

// src/webhooks/webhooks.module.ts
import { Module } from '@nestjs/common';
import { WebhooksController } from './webhooks.controller';
import { ConfigModule } from '@nestjs/config';
import { VonageModule } from '../vonage/vonage.module'; // Import VonageModule

@Module({
  imports: [
    ConfigModule, // For accessing signature secret if needed here
    VonageModule, // Make VonageService available
  ],
  controllers: [WebhooksController],
  // providers: [WebhooksService], // Add if you create a service
})
export class WebhooksModule {}

// src/webhooks/webhooks.controller.ts
import {
  Controller,
  Post,
  Body,
  Headers,
  Req,
  Res,
  HttpStatus,
  Logger,
  BadRequestException,
  InternalServerErrorException,
  UnauthorizedException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Request, Response } from 'express';
import { verifySignature } from '@vonage/jwt';
import { VonageService } from '../vonage/vonage.service';
import { InboundMessageDto } from './dto/inbound-message.dto'; // Import DTO
import { StatusUpdateDto } from './dto/status-update.dto'; // Import DTO

@Controller('webhooks') // Base path for all routes in this controller
export class WebhooksController {
  private readonly logger = new Logger(WebhooksController.name);
  private readonly signatureSecret: string;

  constructor(
    private configService: ConfigService,
    private vonageService: VonageService, // Inject VonageService
  ) {
    this.signatureSecret = this.configService.get<string&gt;(
      'VONAGE_API_SIGNATURE_SECRET',
    );
    if (!this.signatureSecret) {
      this.logger.error('VONAGE_API_SIGNATURE_SECRET is not set in .env');
      // Handle this critical configuration error appropriately
      throw new InternalServerErrorException(
        'Server configuration error: Missing signature secret.',
      );
    }
  }

  // --- Helper Method for Signature Verification ---
  private verifyVonageSignature(req: Request): boolean {
    try {
      // NestJS might lowercase headers, be cautious
      const authorizationHeader =
        req.headers['authorization'] || req.headers['Authorization'];
      if (!authorizationHeader || !authorizationHeader.startsWith('Bearer ')) {
        this.logger.warn('Missing or invalid Authorization header');
        return false;
      }

      const token = authorizationHeader.split(' ')[1];
      if (!token) {
        this.logger.warn('Bearer token missing in Authorization header');
        return false;
      }

      // --- PRODUCTION SECURITY REQUIREMENT ---
      // The following logic relies on accessing the RAW request body *before*
      // it's parsed by NestJS's bodyParser. This is configured in `main.ts`
      // using `{ rawBody: true }` and detailed in Section 5.2.
      // The `verifySignature` function MUST use this raw body buffer.

      const rawBody = (req as any).rawBody; // Cast to access rawBody (requires setup in main.ts)
      if (!rawBody) {
          this.logger.error(
              'Raw request body not available for signature verification. ' +
              'Ensure rawBody is enabled in main.ts (Section 5.2) and this check runs before body parsing if custom middleware is used.'
          );
          // Fail verification if raw body is missing
          return false;
      }

      // Verify the JWT signature against the raw request body buffer
      const isSignatureValid = verifySignature(token, this.signatureSecret, rawBody);

      if (!isSignatureValid) {
        this.logger.warn('Invalid JWT signature received');
        return false;
      }

      this.logger.log('Valid JWT signature verified using raw body');
      return true;
    } catch (error) {
      this.logger.error('Error during signature verification:', error);
      return false;
    }
  }


  // --- Inbound Message Webhook ---
  @Post('inbound')
  handleInboundMessage(
    @Body() body: InboundMessageDto, // Use DTO for validation
    @Req() req: Request,
    @Res() res: Response,
  ) {
    this.logger.log('Received inbound message webhook');
    // Body is already validated by ValidationPipe (setup in main.ts)
    // Log the validated body for debugging if needed (be mindful of sensitive data)
    // this.logger.debug('Validated Inbound Payload:', JSON.stringify(body, null, 2));

    // 1. Verify Signature (CRITICAL FOR SECURITY)
    // IMPORTANT: This requires enabling raw body parsing (Section 5.2)
    // and ensuring the verifyVonageSignature helper uses the raw body.
    if (!this.verifyVonageSignature(req)) {
      this.logger.error('Unauthorized inbound request: Invalid signature');
      return res.status(HttpStatus.UNAUTHORIZED).send('Invalid signature');
    }

    // 2. Process the message (using validated DTO properties)
    const messageType = body.message_type;
    const fromNumber = body.from.number;
    const messageContent = body.message?.content?.text; // Text is optional based on message type

    if (messageType === 'text' && fromNumber && messageContent) {
      this.logger.log(
        `Received text message ""${messageContent}"" from ${fromNumber}`,
      );

      // Example: Simple echo reply
      const replyText = `You sent: ""${messageContent}""`;
      this.vonageService
        .sendWhatsAppTextMessage(fromNumber, replyText)
        .then((messageUuid) =&gt; {
          this.logger.log(
            `Reply sent to ${fromNumber}. Message UUID: ${messageUuid}`,
          );
        })
        .catch((error) =&gt; {
          this.logger.error(`Failed to send reply to ${fromNumber}:`, error);
          // Decide if you still want to send 200 OK to Vonage
        });
    } else {
      this.logger.warn(
        `Received non-text message or unexpected structure: Type=${messageType}, From=${fromNumber}`,
      );
      // Handle other message types (image, audio, location, etc.) or errors
    }

    // 3. Respond to Vonage (CRITICAL)
    // Always send a 200 OK quickly to acknowledge receipt,
    // otherwise Vonage will retry the webhook.
    res.status(HttpStatus.OK).send();
  }

  // --- Message Status Webhook ---
  @Post('status')
  handleMessageStatus(
    @Body() body: StatusUpdateDto, // Use DTO for validation
    @Req() req: Request,
    @Res() res: Response,
  ) {
    this.logger.log('Received message status webhook');
    // Body is validated by ValidationPipe
    // this.logger.debug('Validated Status Payload:', JSON.stringify(body, null, 2));

    // 1. Verify Signature (CRITICAL FOR SECURITY)
    // IMPORTANT: This requires enabling raw body parsing (Section 5.2)
    // and ensuring the verifyVonageSignature helper uses the raw body.
    if (!this.verifyVonageSignature(req)) {
        this.logger.error('Unauthorized status request: Invalid signature');
        return res.status(HttpStatus.UNAUTHORIZED).send('Invalid signature');
    }

    // 2. Process the status update (using validated DTO properties)
    const messageUuid = body.message_uuid;
    const status = body.status;
    const timestamp = body.timestamp;
    const toNumber = body.to.number;

    this.logger.log(
      `Status update for message ${messageUuid} to ${toNumber}: ${status} at ${timestamp}`,
    );

    // Add logic here: update message status in a database, trigger notifications, etc.
    // Example: Log specific statuses
    switch (status) {
        case 'delivered':
            this.logger.log(`Message ${messageUuid} delivered successfully.`);
            break;
        case 'read':
            this.logger.log(`Message ${messageUuid} read by recipient.`);
            break;
        case 'failed':
        case 'rejected':
            this.logger.error(
                `Message ${messageUuid} ${status}. Reason: ${
                    body.error?.reason || body.error?.code || 'Unknown'
                }`, body.error // Log full error object if present
            );
            break;
        // Add cases for other statuses like 'submitted', 'undeliverable' if needed
        default:
            this.logger.log(`Message ${messageUuid} status: ${status}`);
    }

    // 3. Respond to Vonage (CRITICAL)
    res.status(HttpStatus.OK).send();
  }
}

npm run start:dev
# Or using yarn:
# yarn start:dev

[Nest] 12345  - 04/20/2025, 10:00:00 AM     LOG [NestFactory] Starting Nest application...
[Nest] 12345  - 04/20/2025, 10:00:01 AM     LOG [InstanceLoader] ConfigModule dependencies initialized
... more modules ...
[Nest] 12345  - 04/20/2025, 10:00:02 AM     LOG [VonageService] Vonage client initialized successfully.
[Nest] 12345  - 04/20/2025, 10:00:02 AM     LOG [VonageService] Vonage client using default production API host. # Or sandbox host if configured
[Nest] 12345  - 04/20/2025, 10:00:03 AM     LOG [NestApplication] Nest application successfully started
# You might see errors related to rawBody or signature verification until Section 5.2 is fully implemented.

[Nest] 12345  - 04/20/2025, 10:05:00 AM     LOG [WebhooksController] Received inbound message webhook
[Nest] 12345  - 04/20/2025, 10:05:00 AM     LOG [WebhooksController] Valid JWT signature verified using raw body # If verification succeeds
[Nest] 12345  - 04/20/2025, 10:05:00 AM     LOG [WebhooksController] Received text message ""Hello NestJS!"" from 1xxxxxxxxxx
[Nest] 12345  - 04/20/2025, 10:05:00 AM     LOG [VonageService] Attempting to send WhatsApp message to 1xxxxxxxxxx
[Nest] 12345  - 04/20/2025, 10:05:01 AM     LOG [VonageService] Message sent successfully to 1xxxxxxxxxx. Message UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
[Nest] 12345  - 04/20/2025, 10:05:01 AM     LOG [WebhooksController] Reply sent to 1xxxxxxxxxx. Message UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

[Nest] 12345  - 04/20/2025, 10:05:05 AM     LOG [WebhooksController] Received message status webhook
[Nest] 12345  - 04/20/2025, 10:05:05 AM     LOG [WebhooksController] Valid JWT signature verified using raw body # If verification succeeds
[Nest] 12345  - 04/20/2025, 10:05:05 AM     LOG [WebhooksController] Status update for message a1b2c3d4-e5f6-7890-abcd-ef1234567890 to 1xxxxxxxxxx: submitted at ...
[Nest] 12345  - 04/20/2025, 10:05:06 AM     LOG [WebhooksController] Received message status webhook
[Nest] 12345  - 04/20/2025, 10:05:06 AM     LOG [WebhooksController] Valid JWT signature verified using raw body # If verification succeeds
[Nest] 12345  - 04/20/2025, 10:05:06 AM     LOG [WebhooksController] Status update for message a1b2c3d4-e5f6-7890-abcd-ef1234567890 to 1xxxxxxxxxx: delivered at ...
[Nest] 12345  - 04/20/2025, 10:05:07 AM     LOG [WebhooksController] Message a1b2c3d4-e5f6-7890-abcd-ef1234567890 delivered successfully.