Build WhatsApp Integration with Vonage and NestJS: Complete Guide

node --version  # Should show v20.x.x or v22.x.x
npm --version   # Verify npm is installed
ngrok version   # Confirm ngrok is available

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_API_KEY_HERE
VONAGE_API_SECRET=YOUR_API_SECRET_HERE
VONAGE_APPLICATION_ID=YOUR_APPLICATION_ID_HERE
VONAGE_PRIVATE_KEY_PATH=./private.key # Path relative to project root
VONAGE_API_SIGNATURE_SECRET=YOUR_SIGNATURE_SECRET_HERE # 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)

# Vonage credentials
.env
.env.*
!.env.example
private.key
*.key

// 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';

@Module({
  imports: [ConfigModule], // Ensure ConfigService is available
  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;
  private readonly MAX_RETRIES = 3;
  private readonly RETRY_DELAY_MS = 1000;

  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);
      throw new Error(`Vonage initialization failed: ${error.message}`);
    }
  }

  /**
   * Sends a WhatsApp text message with automatic retry logic.
   * @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 after retries.
   */
  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}`);

    for (let attempt = 1; attempt &lt;= this.MAX_RETRIES; attempt++) {
      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) {
        // Check for rate limiting
        if (error.response?.status === 429) {
          const retryAfter = error.response.headers['retry-after'];
          const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : this.RETRY_DELAY_MS * attempt;
          this.logger.warn(
            `Rate limited. Attempt ${attempt}/${this.MAX_RETRIES}. Waiting ${waitTime}ms before retry.`_
          );

          if (attempt &lt; this.MAX_RETRIES) {
            await this.sleep(waitTime);
            continue;
          }
        }

        this.logger.error(`Error sending WhatsApp message to ${to}:`_ error);

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

        // Re-throw on final attempt
        if (attempt === this.MAX_RETRIES) {
          throw new Error(
            `Failed to send WhatsApp message after ${this.MAX_RETRIES} attempts: ${
              error.response?.data?.title || error.message
            }`_
          );
        }

        // Wait before retry
        await this.sleep(this.RETRY_DELAY_MS * attempt);
      }
    }
  }

  /**
   * Sends a WhatsApp message with media attachment.
   * @param to The recipient's phone number (E.164 format_ without leading '+').
   * @param mediaUrl The URL of the media to send (must be publicly accessible).
   * @param caption Optional caption for the media.
   * @returns The message UUID on success.
   */
  async sendWhatsAppMediaMessage(
    to: string_
    mediaUrl: string_
    caption?: string_
  ): Promise<string&gt; {
    if (!this.vonageClient) {
      throw new Error('Vonage client not available.');
    }

    this.logger.log(`Sending WhatsApp media message to ${to}`);

    try {
      const response = await this.vonageClient.messages.send({
        channel: 'whatsapp',
        message_type: 'image',
        to: to,
        from: this.vonageWhatsAppNumber,
        image: {
          url: mediaUrl,
          caption: caption,
        },
      });

      this.logger.log(
        `Media message sent successfully to ${to}. Message UUID: ${response.messageUuid}`,
      );
      return response.messageUuid;
    } catch (error) {
      this.logger.error(`Error sending media message to ${to}:`, error);
      throw new Error(
        `Failed to send media message: ${
          error.response?.data?.title || error.message
        }`,
      );
    }
  }

  /**
   * Sends a WhatsApp template message.
   * @param to The recipient's phone number (E.164 format, without leading '+').
   * @param templateName The name of the approved template.
   * @param parameters Template parameters (if required).
   * @returns The message UUID on success.
   */
  async sendWhatsAppTemplateMessage(
    to: string,
    templateName: string,
    parameters: string[] = [],
  ): Promise<string&gt; {
    if (!this.vonageClient) {
      throw new Error('Vonage client not available.');
    }

    this.logger.log(`Sending WhatsApp template "${templateName}" to ${to}`);

    try {
      const response = await this.vonageClient.messages.send({
        channel: 'whatsapp',
        message_type: 'template',
        to: to,
        from: this.vonageWhatsAppNumber,
        template: {
          name: templateName,
          parameters: parameters,
        },
      });

      this.logger.log(
        `Template message sent successfully to ${to}. Message UUID: ${response.messageUuid}`,
      );
      return response.messageUuid;
    } catch (error) {
      this.logger.error(`Error sending template message to ${to}:`, error);
      throw new Error(
        `Failed to send template message: ${
          error.response?.data?.title || error.message
        }`,
      );
    }
  }

  private sleep(ms: number): Promise<void&gt; {
    return new Promise(resolve =&gt; setTimeout(resolve, ms));
  }
}

nest g module webhooks
nest g controller webhooks --no-spec

// 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
    VonageModule, // Make VonageService available
  ],
  controllers: [WebhooksController],
})
export class WebhooksModule {}

// src/webhooks/dto/inbound-message.dto.ts
import {
  IsString,
  IsNotEmpty,
  IsOptional,
  ValidateNested,
  IsEnum,
} from 'class-validator';
import { Type } from 'class-transformer';

class FromDto {
  @IsString()
  @IsNotEmpty()
  type: string;

  @IsString()
  @IsNotEmpty()
  number: string;
}

class MessageContentDto {
  @IsString()
  @IsOptional()
  text?: string;

  @IsString()
  @IsOptional()
  image?: string;

  @IsString()
  @IsOptional()
  caption?: string;
}

class MessageDto {
  @ValidateNested()
  @Type(() => MessageContentDto)
  @IsOptional()
  content?: MessageContentDto;
}

export class InboundMessageDto {
  @IsString()
  @IsNotEmpty()
  message_uuid: string;

  @IsString()
  @IsNotEmpty()
  @IsEnum(['text', 'image', 'audio', 'video', 'file', 'location', 'button', 'list'])
  message_type: string;

  @IsString()
  @IsNotEmpty()
  timestamp: string;

  @ValidateNested()
  @Type(() => FromDto)
  from: FromDto;

  @ValidateNested()
  @Type(() => MessageDto)
  @IsOptional()
  message?: MessageDto;

  @IsString()
  @IsOptional()
  channel?: string;
}

// src/webhooks/dto/status-update.dto.ts
import {
  IsString,
  IsNotEmpty,
  IsOptional,
  ValidateNested,
  IsEnum,
} from 'class-validator';
import { Type } from 'class-transformer';

class ToDto {
  @IsString()
  @IsNotEmpty()
  type: string;

  @IsString()
  @IsNotEmpty()
  number: string;
}

class ErrorDto {
  @IsString()
  @IsOptional()
  code?: string;

  @IsString()
  @IsOptional()
  reason?: string;
}

export class StatusUpdateDto {
  @IsString()
  @IsNotEmpty()
  message_uuid: string;

  @IsString()
  @IsNotEmpty()
  @IsEnum(['submitted', 'delivered', 'read', 'failed', 'rejected', 'undeliverable'])
  status: string;

  @IsString()
  @IsNotEmpty()
  timestamp: string;

  @ValidateNested()
  @Type(() => ToDto)
  to: ToDto;

  @ValidateNested()
  @Type(() => ErrorDto)
  @IsOptional()
  error?: ErrorDto;

  @IsString()
  @IsOptional()
  channel?: string;
}

// src/webhooks/webhooks.controller.ts
import {
  Controller,
  Post,
  Body,
  Req,
  Res,
  HttpStatus,
  Logger,
  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 { StatusUpdateDto } from './dto/status-update.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;
  private readonly processedMessages = new Set<string&gt;(); // Simple idempotency tracking

  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');
      throw new Error('Server configuration error: Missing signature secret.');
    }
  }

  // --- Helper Method for Signature Verification ---
  private verifyVonageSignature(req: Request): boolean {
    try {
      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;
      }

      const rawBody = (req as any).rawBody;
      if (!rawBody) {
        this.logger.error(
          'Raw request body not available for signature verification. ' +
            'Ensure rawBody is enabled in main.ts (Section 5.2).',
        );
        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')
  async handleInboundMessage(
    @Body() body: InboundMessageDto,
    @Req() req: Request,
    @Res() res: Response,
  ) {
    this.logger.log('Received inbound message webhook');

    // 1. Verify Signature (CRITICAL FOR SECURITY)
    if (!this.verifyVonageSignature(req)) {
      this.logger.error('Unauthorized inbound request: Invalid signature');
      return res.status(HttpStatus.UNAUTHORIZED).send('Invalid signature');
    }

    // 2. Check for duplicate (idempotency)
    if (this.processedMessages.has(body.message_uuid)) {
      this.logger.warn(
        `Duplicate message received: ${body.message_uuid}. Ignoring.`,
      );
      return res.status(HttpStatus.OK).send(); // Still return 200 OK
    }

    // Mark as processed
    this.processedMessages.add(body.message_uuid);

    // Clean up old entries (simple approach for demo – use Redis in production)
    if (this.processedMessages.size &gt; 10000) {
      const iterator = this.processedMessages.values();
      for (let i = 0; i &lt; 1000; i++) {
        this.processedMessages.delete(iterator.next().value);
      }
    }

    // 3. Process the message
    const messageType = body.message_type;
    const fromNumber = body.from.number;
    const messageContent = body.message?.content?.text;

    try {
      switch (messageType) {
        case 'text':
          if (fromNumber && messageContent) {
            this.logger.log(
              `Received text message "${messageContent}" from ${fromNumber}`_
            );

            // Example: Simple echo reply
            const replyText = `You sent: "${messageContent}"`;
            const messageUuid = await this.vonageService.sendWhatsAppTextMessage(
              fromNumber_
              replyText_
            );
            this.logger.log(
              `Reply sent to ${fromNumber}. Message UUID: ${messageUuid}`_
            );
          }
          break;

        case 'image':
          const imageUrl = body.message?.content?.image;
          const caption = body.message?.content?.caption;
          this.logger.log(
            `Received image from ${fromNumber}: ${imageUrl} (Caption: ${caption || 'none'})`_
          );
          // Handle image processing here
          break;

        case 'location':
          this.logger.log(`Received location share from ${fromNumber}`);
          // Handle location data here
          break;

        default:
          this.logger.warn(
            `Received unsupported message type: ${messageType} from ${fromNumber}`_
          );
      }
    } catch (error) {
      this.logger.error(`Failed to process message from ${fromNumber}:`_ error);
      // Still return 200 OK to prevent retries
    }

    // 4. Respond to Vonage (CRITICAL)
    // Always send a 200 OK quickly to acknowledge receipt
    res.status(HttpStatus.OK).send();
  }

  // --- Message Status Webhook ---
  @Post('status')
  handleMessageStatus(
    @Body() body: StatusUpdateDto_
    @Req() req: Request_
    @Res() res: Response_
  ) {
    this.logger.log('Received message status webhook');

    // 1. Verify Signature (CRITICAL FOR SECURITY)
    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
    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.
    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_
        );
        break;
      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
[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.
[Nest] 12345  - 04/20/2025, 10:00:03 AM     LOG [NestApplication] Nest application successfully started

[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
[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
[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
[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.

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { Logger, ValidationPipe } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

async function bootstrap() {
  // Enable rawBody parsing for webhook signature verification
  const app = await NestFactory.create(AppModule, {
    rawBody: true, // &lt;<< Enable Raw Body
  });

  const configService = app.get(ConfigService);
  const port = configService.get<number&gt;('PORT', 3000);

  // Enable global validation pipe
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // Strip properties not in DTO
      transform: true, // Automatically transform payloads to DTO instances
      forbidNonWhitelisted: true, // Throw error if unknown properties are received
      transformOptions: {
        enableImplicitConversion: true, // Allow basic type conversions
      },
    }),
  );

  // Optional: Enable CORS if your setup requires it
  // app.enableCors();

  await app.listen(port);
  Logger.log(`Application is running on: http://localhost:${port}`);
}
bootstrap();

constructor(
  private configService: ConfigService,
  private vonageService: 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');
    throw new Error('Server configuration error: Missing signature secret.');
  }

  // Verification: This will log when the controller initializes
  this.logger.log('WebhooksController initialized with signature verification enabled');
}

npm install @nestjs/typeorm typeorm pg

// src/entities/message.entity.ts
import { Entity, Column, PrimaryColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';

@Entity('messages')
export class Message {
  @PrimaryColumn()
  messageUuid: string;

  @Column()
  from: string;

  @Column()
  to: string;

  @Column()
  messageType: string;

  @Column('text', { nullable: true })
  content: string;

  @Column({ default: 'submitted' })
  status: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @Column('jsonb', { nullable: true })
  metadata: any;
}

import { TypeOrmModule } from '@nestjs/typeorm';
import { Message } from './entities/message.entity';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DB_HOST || 'localhost',
      port: parseInt(process.env.DB_PORT) || 5432,
      username: process.env.DB_USERNAME,
      password: process.env.DB_PASSWORD,
      database: process.env.DB_DATABASE,
      entities: [Message],
      synchronize: process.env.NODE_ENV !== 'production', // Disable in production
    }),
    TypeOrmModule.forFeature([Message]),
    VonageModule,
    WebhooksModule,
  ],
  // …
})
export class AppModule {}

npm install @nestjs/bull bull
npm install @types/bull --save-dev

// app.module.ts
import { BullModule } from '@nestjs/bull';

@Module({
  imports: [
    // …
    BullModule.forRoot({
      redis: {
        host: process.env.REDIS_HOST || 'localhost',
        port: parseInt(process.env.REDIS_PORT) || 6379,
      },
    }),
    BullModule.registerQueue({
      name: 'messages',
    }),
    // …
  ],
})
export class AppModule {}

// src/webhooks/message.processor.ts
import { Processor, Process } from '@nestjs/bull';
import { Job } from 'bull';
import { Logger } from '@nestjs/common';
import { VonageService } from '../vonage/vonage.service';

@Processor('messages')
export class MessageProcessor {
  private readonly logger = new Logger(MessageProcessor.name);

  constructor(private vonageService: VonageService) {}

  @Process('inbound')
  async handleInboundMessage(job: Job) {
    const { from, content } = job.data;
    this.logger.log(`Processing inbound message from ${from}`);

    try {
      const replyText = `You sent: "${content}"`;
      await this.vonageService.sendWhatsAppTextMessage(from, replyText);
      this.logger.log(`Reply sent to ${from}`);
    } catch (error) {
      this.logger.error(`Failed to process message from ${from}:`, error);
      throw error; // Bull will retry
    }
  }
}

npm install nest-winston winston

// src/main.ts
import { WinstonModule } from 'nest-winston';
import * as winston from 'winston';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    rawBody: true,
    logger: WinstonModule.createLogger({
      transports: [
        new winston.transports.Console({
          format: winston.format.combine(
            winston.format.timestamp(),
            winston.format.json(),
          ),
        }),
        new winston.transports.File({
          filename: 'logs/error.log',
          level: 'error',
          format: winston.format.json(),
        }),
        new winston.transports.File({
          filename: 'logs/combined.log',
          format: winston.format.json(),
        }),
      ],
    }),
  });
  // …
}

npm install @nestjs/throttler

// app.module.ts
import { ThrottlerModule } from '@nestjs/throttler';

@Module({
  imports: [
    ThrottlerModule.forRoot([{
      ttl: 60000, // 60 seconds
      limit: 10, // 10 requests per minute
    }]),
    // …
  ],
})
export class AppModule {}

// webhooks.controller.ts
import { Throttle } from '@nestjs/throttler';

@Controller('webhooks')
export class WebhooksController {
  @Throttle({ default: { limit: 100, ttl: 60000 } }) // 100 requests per minute
  @Post('inbound')
  async handleInboundMessage(/* … */) {
    // …
  }
}

NODE_ENV=production
DB_HOST=your-db-host.com
DB_PORT=5432
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password
DB_DATABASE=vonage_whatsapp
REDIS_HOST=your-redis-host.com
REDIS_PORT=6379

FROM node:22-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/main"]

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: vonage_whatsapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

npm install @nestjs/terminus

// src/health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      () => this.db.pingCheck('database'),
    ]);
  }
}

npm install helmet

// main.ts
import helmet from 'helmet';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { rawBody: true });
  app.use(helmet());
  // …
}

// src/vonage/vonage.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { ConfigService } from '@nestjs/config';
import { VonageService } from './vonage.service';

describe('VonageService', () => {
  let service: VonageService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        VonageService,
        {
          provide: ConfigService,
          useValue: {
            get: jest.fn((key: string) => {
              const config = {
                VONAGE_API_KEY: 'test_key',
                VONAGE_API_SECRET: 'test_secret',
                VONAGE_APPLICATION_ID: 'test_app_id',
                VONAGE_PRIVATE_KEY_PATH: './test.key',
                VONAGE_WHATSAPP_NUMBER: '14155551234',
              };
              return config[key];
            }),
          },
        },
      ],
    }).compile();

    service = module.get<VonageService&gt;(VonageService);
  });

  it('should be defined', () =&gt; {
    expect(service).toBeDefined();
  });
});

// test/webhooks.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from './../src/app.module';

describe('WebhooksController (e2e)', () => {
  let app: INestApplication;

  beforeEach(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/webhooks/inbound (POST)', () => {
    return request(app.getHttpServer())
      .post('/webhooks/inbound')
      .send({
        message_uuid: 'test-uuid-123',
        message_type: 'text',
        timestamp: '2025-04-20T10:00:00.000Z',
        from: {
          type: 'whatsapp',
          number: '14155551234',
        },
        message: {
          content: {
            text: 'Test message',
          },
        },
      })
      .expect(200);
  });
});

{
  "info": {
    "name": "Vonage WhatsApp NestJS",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Inbound Webhook",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"message_uuid\": \"{{$guid}}\",\n  \"message_type\": \"text\",\n  \"timestamp\": \"{{$timestamp}}\",\n  \"from\": {\n    \"type\": \"whatsapp\",\n    \"number\": \"14155551234\"\n  },\n  \"message\": {\n    \"content\": {\n      \"text\": \"Hello World\"\n    }\n  }\n}"
        },
        "url": {
          "raw": "{{base_url}}/webhooks/inbound",
          "host": ["{{base_url}}"],
          "path": ["webhooks", "inbound"]
        }
      }
    }
  ]
}

curl https://cli-assets.heroku.com/install.sh | sh

heroku login
heroku create vonage-whatsapp-app
heroku addons:create heroku-postgresql:mini
heroku addons:create heroku-redis:mini
heroku config:set VONAGE_API_KEY=your_key
heroku config:set VONAGE_API_SECRET=your_secret
# … set other environment variables
git push heroku main

pip install awsebcli

eb init -p node.js vonage-whatsapp-app
eb create vonage-whatsapp-env
eb setenv VONAGE_API_KEY=your_key VONAGE_API_SECRET=your_secret
eb deploy

gcloud builds submit --tag gcr.io/PROJECT_ID/vonage-whatsapp
gcloud run deploy vonage-whatsapp \
  --image gcr.io/PROJECT_ID/vonage-whatsapp \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "VONAGE_API_KEY=your_key,VONAGE_API_SECRET=your_secret"

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

      - name: Deploy to Heroku
        uses: akhileshns/heroku-deploy@v3.12.14
        with:
          heroku_api_key: ${{secrets.HEROKU_API_KEY}}
          heroku_app_name: "vonage-whatsapp-app"
          heroku_email: "your-email@example.com"