How to Track Twilio SMS Delivery Status with NestJS: Complete Webhook Guide

# Install NestJS CLI if you haven't already (NestJS v11.x)
npm install -g @nestjs/cli

# Create the project (choose npm or yarn)
nest new nestjs-twilio-sms-delivery-status-callbacks
cd nestjs-twilio-sms-delivery-status-callbacks

# Core dependencies
npm install twilio@^5.0.0 dotenv @nestjs/config class-validator class-transformer

# Optional database dependencies (using PostgreSQL with TypeORM 0.3.27)
npm install @nestjs/typeorm typeorm@^0.3.27 pg

#.env

# Twilio Credentials
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_xxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+15551234567 # Your Twilio number

# Application Settings
APP_PORT=3000
# Base URL for callbacks (use ngrok URL during development)
APP_BASE_URL=https://your-ngrok-subdomain.ngrok-free.app

# Optional Database Credentials (if using TypeORM)
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password
DB_DATABASE=twilio_callbacks

#.env.example

# Twilio Credentials
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_PHONE_NUMBER=

# Application Settings
APP_PORT=3000
APP_BASE_URL=

# Optional Database Credentials
DB_HOST=
DB_PORT=
DB_USERNAME=
DB_PASSWORD=
DB_DATABASE=

// 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 other modules (like Twilio, SMS, TypeOrm) here later

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Makes ConfigModule available globally
      envFilePath: '.env', // Specify the env file path
    }),
    // Add other modules here
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get(ConfigService);
  const port = configService.get<number>('APP_PORT', 3000); // Default to 3000

  // Enable global validation pipe
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true, // Strip properties not defined in DTO
    transform: true, // Automatically transform payloads to DTO instances
    forbidNonWhitelisted: true, // Throw error if extra properties are present
  }));

  await app.listen(port);
  console.log(`Application is running on: ${await app.getUrl()}`);
}
bootstrap();

nest g module twilio
nest g service twilio/twilio --no-spec # No spec file for simplicity here

// src/twilio/twilio.service.ts
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import twilio, { Twilio } from 'twilio';

@Injectable()
export class TwilioService implements OnModuleInit {
  private readonly logger = new Logger(TwilioService.name);
  private client: Twilio;
  private twilioPhoneNumber: string;
  private appBaseUrl: string;

  constructor(private readonly configService: ConfigService) {}

  onModuleInit() {
    const accountSid = this.configService.get<string>('TWILIO_ACCOUNT_SID');
    const authToken = this.configService.get<string>('TWILIO_AUTH_TOKEN');
    this.twilioPhoneNumber = this.configService.get<string>(
      'TWILIO_PHONE_NUMBER',
    );
    this.appBaseUrl = this.configService.get<string>('APP_BASE_URL');

    if (!accountSid || !authToken || !this.twilioPhoneNumber || !this.appBaseUrl) {
      this.logger.error('Twilio credentials or Base URL not configured in .env');
      throw new Error('Twilio credentials or Base URL are missing.');
    }

    this.client = twilio(accountSid, authToken);
    this.logger.log('Twilio client initialized');
  }

  getClient(): Twilio {
    return this.client;
  }

  getTwilioPhoneNumber(): string {
    return this.twilioPhoneNumber;
  }

  // Method to construct the callback URL
  getStatusCallbackUrl(): string {
    // Ensure the base URL doesn't end with a slash and the path starts with one
    const baseUrl = this.appBaseUrl.endsWith('/') ? this.appBaseUrl.slice(0, -1) : this.appBaseUrl;
    const path = '/twilio/status'; // Our designated callback endpoint path
    return `${baseUrl}${path}`;
  }

  // Method to send SMS
  async sendSms(to: string, body: string): Promise<string> {
    try {
      const message = await this.client.messages.create({
        body: body,
        from: this.twilioPhoneNumber,
        to: to,
        // Provide the URL for status updates
        statusCallback: this.getStatusCallbackUrl(),
        // Optionally specify which events trigger the callback
        // statusCallbackEvent: ['queued', 'sent', 'failed', 'delivered', 'undelivered'],
        // Defaults to 'completed' status (delivered/undelivered/failed)
      });

      this.logger.log(`SMS sent to ${to}. SID: ${message.sid}`);
      return message.sid; // Return the Message SID
    } catch (error) {
      this.logger.error(`Failed to send SMS to ${to}: ${error.message}`, error.stack);
      // Re-throw or handle specific Twilio errors
      throw new Error(`Twilio API Error: ${error.message}`);
    }
  }

  // Note: Request validation is handled by TwilioRequestValidatorMiddleware (Section 7)
}

// src/twilio/twilio.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { TwilioService } from './twilio.service';

@Module({
  imports: [ConfigModule], // Import ConfigModule if not global or needed here
  providers: [TwilioService],
  exports: [TwilioService], // Export service for other modules to use
})
export class TwilioModule {}

// 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 { TwilioModule } from './twilio/twilio.module'; // Import TwilioModule
// Import other modules (SMS, TypeOrm) here later

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    TwilioModule, // Add TwilioModule here
    // Add other modules (SMS, TypeOrm) later
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

nest g module sms
nest g controller sms --no-spec

// src/sms/dto/send-sms.dto.ts
import { IsNotEmpty, IsString, IsPhoneNumber } from 'class-validator';

export class SendSmsDto {
  @IsNotEmpty()
  @IsPhoneNumber() // Validates E.164 format (e.g., +15551234567)
  readonly to: string;

  @IsNotEmpty()
  @IsString()
  readonly body: string;
}

// src/sms/sms.controller.ts
import { Controller, Post, Body, HttpCode, HttpStatus, Logger } from '@nestjs/common';
import { TwilioService } from '../twilio/twilio.service';
import { SendSmsDto } from './dto/send-sms.dto';

@Controller('sms')
export class SmsController {
  private readonly logger = new Logger(SmsController.name);

  constructor(private readonly twilioService: TwilioService) {}

  @Post('send')
  @HttpCode(HttpStatus.ACCEPTED) // Use 202 Accepted as sending is asynchronous
  async sendSms(@Body() sendSmsDto: SendSmsDto): Promise<{ message: string; sid: string }> {
    this.logger.log(`Received request to send SMS to ${sendSmsDto.to}`);
    try {
      const messageSid = await this.twilioService.sendSms(sendSmsDto.to, sendSmsDto.body);
      return {
        message: 'SMS send request accepted.',
        sid: messageSid,
      };
    } catch (error) {
      this.logger.error(`Error in sendSms endpoint: ${error.message}`, error.stack);
      // Consider throwing specific HTTP exceptions based on error type
      throw error; // Re-throw for NestJS default exception handling
    }
  }
}

// src/sms/sms.module.ts
import { Module } from '@nestjs/common';
import { TwilioModule } from '../twilio/twilio.module'; // Import TwilioModule
import { SmsController } from './sms.controller';

@Module({
  imports: [TwilioModule], // Make TwilioService available
  controllers: [SmsController],
})
export class SmsModule {}

// 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 { TwilioModule } from './twilio/twilio.module';
import { SmsModule } from './sms/sms.module'; // Import SmsModule
// Import other modules (TypeOrm) here later

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    TwilioModule,
    SmsModule, // Add SmsModule here
    // Add other modules (TypeOrm) later
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

nest g controller twilio/twilio --flat --no-spec # Add controller to existing twilio module

// src/twilio/twilio.controller.ts
import { Controller, Post, Req, Res, Body, Headers, HttpCode, HttpStatus, Logger } from '@nestjs/common';
import { Request, Response } from 'express'; // Import express types
// Import DB service later if needed

@Controller('twilio') // Base path for Twilio related endpoints
export class TwilioController {
  private readonly logger = new Logger(TwilioController.name);

  // Constructor for injecting services (like DB service later)
  constructor(
    // Inject services here, e.g., private readonly messageLogService: MessageLogService
  ) {}

  @Post('status') // Matches the statusCallback URL path
  @HttpCode(HttpStatus.NO_CONTENT) // Twilio expects 200 OK or 204 No Content on success
  handleStatusCallback(
    @Body() body: any, // Body will contain status info (MessageSid, MessageStatus, etc.)
    @Headers('X-Twilio-Signature') twilioSignature: string, // Signature for validation (uses HMAC-SHA1 with AuthToken)
    @Req() request: Request, // Access underlying express request (needed for middleware/raw body later)
    @Res() response: Response // Access underlying express response
  ) {
    this.logger.log(`Received Twilio Status Callback for SID: ${body.MessageSid}, Status: ${body.MessageStatus}`);
    this.logger.debug(`Callback Body: ${JSON.stringify(body)}`);
    this.logger.debug(`Twilio Signature: ${twilioSignature}`);

    // --- CRITICAL SECURITY WARNING ---
    // Validate the incoming request using the Twilio signature header (X-Twilio-Signature).
    // This signature is generated using HMAC-SHA1 with your AuthToken as the key.
    // Twilio strongly recommends using the official SDK's validateRequest method.
    // This ensures the request genuinely comes from Twilio and prevents unauthorized webhook calls.
    // Implement this using middleware in Section 7.
    // Until then, this endpoint is technically insecure if exposed publicly.
    // --- END WARNING ---

    // --- IMPORTANT: CALLBACK ORDERING ---
    // Twilio does NOT guarantee status callbacks arrive in the order they were sent.
    // Your callback handler must handle out-of-order events (e.g., receiving "delivered" before "sent").
    // Use timestamps and proper state management to handle this correctly.
    // --- END ORDERING NOTE ---

    const messageSid = body.MessageSid;
    const messageStatus = body.MessageStatus;
    const errorCode = body.ErrorCode; // Present ONLY if status is 'failed' or 'undelivered'
    const errorMessage = body.ErrorMessage; // Present ONLY if status is 'failed' or 'undelivered'

    // Process the status update (e.g., log, update database)
    // Add database interaction in Section 6.
    this.logger.log(`Processing status '${messageStatus}' for message ${messageSid}. ErrorCode: ${errorCode || 'N/A'}`);

    // Example: Update database (implement MessageLogService later)
    // try {
    //   await this.messageLogService.updateStatus(messageSid, messageStatus, errorCode, errorMessage);
    //   this.logger.log(`Successfully updated status for ${messageSid} in DB.`);
    // } catch (error) {
    //   this.logger.error(`Failed to update DB for ${messageSid}: ${error.message}`, error.stack);
    //   // Decide how to handle DB errors. Maybe retry? Log critical error?
    //   // For now, still respond 204 to Twilio to acknowledge receipt.
    // }

    // Respond to Twilio – IMPORTANT: Respond quickly (within 15 seconds)
    // NestJS handles sending the response automatically with @HttpCode(204)
    // If you need more control, use the @Res() decorator and response.status(204).send();
  }
}

// src/twilio/twilio.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { TwilioService } from './twilio.service';
import { TwilioController } from './twilio.controller'; // Import the controller

@Module({
  imports: [ConfigModule],
  providers: [TwilioService],
  exports: [TwilioService],
  controllers: [TwilioController], // Add the controller here
})
export class TwilioModule {}

npm install @nestjs/typeorm typeorm@^0.3.27 pg

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { TwilioModule } from './twilio/twilio.module';
import { SmsModule } from './sms/sms.module';
// Do NOT import MessageLog or MessageLogModule yet

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        type: 'postgres',
        host: configService.get<string>('DB_HOST'),
        port: configService.get<number>('DB_PORT'),
        username: configService.get<string>('DB_USERNAME'),
        password: configService.get<string>('DB_PASSWORD'),
        database: configService.get<string>('DB_DATABASE'),
        // entities: [__dirname + '/../**/*.entity{.ts,.js}'], // Alternative: Use path matching for auto-discovery
        entities: [], // Add MessageLog entity explicitly later
        synchronize: true, // DEV ONLY: Automatically creates schema. Disable in prod and use migrations.
        logging: configService.get<string>('NODE_ENV') === 'development', // Log SQL in dev
      }),
      inject: [ConfigService],
    }),
    TwilioModule,
    SmsModule,
    // MessageLogModule will be added later
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

nest g module message-log
nest g service message-log/message-log --no-spec

// src/message-log/message-log.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn, Index } from 'typeorm';

export enum MessageTransportStatus {
  ACCEPTED = 'accepted', // Initial status upon API acceptance
  QUEUED = 'queued',
  SENDING = 'sending',
  SENT = 'sent',
  FAILED = 'failed',
  DELIVERED = 'delivered',
  UNDELIVERED = 'undelivered',
  RECEIVING = 'receiving', // For incoming messages, if tracked
  RECEIVED = 'received',   // For incoming messages, if tracked
  READ = 'read',         // If read receipts are implemented (e.g., WhatsApp)
  UNKNOWN = 'unknown',
}

@Entity('message_logs') // Table name
export class MessageLog {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Index() // Index for faster lookups
  @Column({ type: 'varchar', length: 34, unique: true }) // Twilio SIDs are typically 34 chars (SM…)
  messageSid: string;

  @Column({ type: 'varchar', length: 20 })
  to: string;

  @Column({ type: 'varchar', length: 20 })
  from: string;

  @Column({ type: 'text', nullable: true })
  body?: string; // Body might not be relevant for all logs, or could be large

  @Column({
    type: 'enum',
    enum: MessageTransportStatus,
    default: MessageTransportStatus.ACCEPTED,
  })
  status: MessageTransportStatus;

  @Column({ type: 'varchar', length: 5, nullable: true }) // E.g., 30006
  errorCode?: string;

  @Column({ type: 'text', nullable: true })
  errorMessage?: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}