+-----------------+      +-------------------+      +-----------------+      +-------------------+
|                 |----->|                   |----->|                 |----->|                   |
| Your Application|      | NestJS Backend    |      | Sinch Platform  |      | WhatsApp User     |
| (e.g., Frontend)|      | (This Guide)      |      | (Conversation API)|<-----|                   |
|                 |<-----|                   |<-----|                 |<-----|                   |
+-----------------+      +-------------------+      +-----------------+      +-------------------+
       |  (API Call to Send)         ^                      |  (API Call)              ^
       |                             | (Webhook Post)       |                          |
       +-----------------------------+                      +--------------------------+
                                  (Receive Message)                     (Send/Receive)

nest new sinch-whatsapp-integration
cd sinch-whatsapp-integration

# Core Dependencies
npm install @nestjs/config axios class-validator class-transformer body-parser @types/body-parser

# Optional Database Dependencies
npm install @nestjs/mongoose mongoose

# .env

# === IMPORTANT ===
# The values starting with 'YOUR_' below are placeholders.
# You MUST replace them with your actual credentials from the Sinch portal.
# Do NOT commit this file with real secrets to version control.

# Sinch API Credentials
SINCH_SERVICE_PLAN_ID=YOUR_SINCH_SERVICE_PLAN_ID # Replace with your Service Plan ID from Sinch
SINCH_API_TOKEN=YOUR_SINCH_API_TOKEN           # Replace with your API Token from Sinch
SINCH_PROJECT_ID=YOUR_SINCH_PROJECT_ID         # Replace with your Project ID (often same as Service Plan ID_ verify in Sinch portal)

# Sinch WhatsApp Sender ID (Phone Number associated with your WABA)
# Replace with your actual approved WhatsApp sender number in E.164 format (e.g._ +12345550100)
SINCH_WHATSAPP_SENDER_ID=+12345678900 # EXAMPLE ONLY - REPLACE THIS

# Webhook Secret (Generate a strong random string for security)
# This is used to verify incoming webhooks from Sinch. You MUST provide the same secret in the Sinch portal webhook config.
SINCH_WEBHOOK_SECRET=YOUR_STRONG_RANDOM_SECRET # Replace with a strong_ unique secret

# Application Port
PORT=3000

# Optional: Database Connection String (if using Mongoose)
# DATABASE_URL=mongodb://user:password@host:port/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 (Sinch, Webhook, Database) here later

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

src/
├── app.controller.ts
├── app.module.ts
├── app.service.ts
├── main.ts
├── config/              # Configuration related files (optional)
│   └── sinch.config.ts
├── sinch/               # Module for Sinch API interaction
│   ├── sinch.module.ts
│   ├── sinch.service.ts
│   └── dto/             # Data Transfer Objects for Sinch API
│       ├── send-message.dto.ts
│       └── sinch-send-response.dto.ts # DTO for Sinch send response
├── webhook/             # Module for handling incoming Sinch webhooks
│   ├── webhook.module.ts
│   ├── webhook.controller.ts
│   ├── webhook.service.ts
│   ├── guards/          # Custom guards (e.g., for webhook verification)
│   │   └── sinch-webhook.guard.ts
│   └── dto/             # DTOs for incoming webhook payloads
│       └── sinch-webhook.dto.ts # Renamed for clarity
└── database/            # Optional: Module for database interaction
    ├── database.module.ts
    ├── schemas/
    │   └── message.schema.ts
    └── services/
        └── message-persistence.service.ts

nest generate module sinch
nest generate service sinch

// src/config/sinch.config.ts
import { registerAs } from '@nestjs/config';

export default registerAs('sinch', () => ({
  servicePlanId: process.env.SINCH_SERVICE_PLAN_ID,
  apiToken: process.env.SINCH_API_TOKEN,
  projectId: process.env.SINCH_PROJECT_ID || process.env.SINCH_SERVICE_PLAN_ID, // Fallback if separate Project ID isn't used
  whatsappSenderId: process.env.SINCH_WHATSAPP_SENDER_ID,
  webhookSecret: process.env.SINCH_WEBHOOK_SECRET,
  // Ensure the region (us, eu, etc.) in the URL matches your account's region
  apiUrl: `https://us.conversation.api.sinch.com/v1/projects/${process.env.SINCH_PROJECT_ID || process.env.SINCH_SERVICE_PLAN_ID}`,
}));

// src/sinch/sinch.service.ts
import { Injectable, Logger, Inject } from '@nestjs/common';
import { ConfigType } from '@nestjs/config';
import axios, { AxiosInstance, AxiosError } from 'axios'; // Import AxiosError
import * as crypto from 'crypto'; // Use ES6 import for crypto
import sinchConfig from '../config/sinch.config'; // Import the typed config
import { SinchSendMessageResponseDto } from './dto/sinch-send-response.dto'; // Import response DTO

@Injectable()
export class SinchService {
  private readonly logger = new Logger(SinchService.name);
  private readonly httpClient: AxiosInstance;

  constructor(
    @Inject(sinchConfig.KEY) // Inject the typed config
    private config: ConfigType<typeof sinchConfig&gt;,
  ) {
    // Crucial check for essential configuration
    if (!config.projectId || !config.apiToken || !config.whatsappSenderId || !config.webhookSecret) {
      this.logger.error('Sinch configuration incomplete. Check .env file for SINCH_PROJECT_ID, SINCH_API_TOKEN, SINCH_WHATSAPP_SENDER_ID, and SINCH_WEBHOOK_SECRET.');
      throw new Error('Sinch Service configuration is incomplete. Please check environment variables.');
    }

    this.httpClient = axios.create({
      baseURL: config.apiUrl,
      headers: {
        Authorization: `Bearer ${config.apiToken}`,
        'Content-Type': 'application/json',
      },
    });
  }

  /**
   * Sends a WhatsApp text message via the Sinch Conversation API.
   * @param recipientPhoneNumber - The recipient's phone number in E.164 format (e.g., +15551234567).
   * @param textContent - The text message content.
   * @returns A promise resolving to the structured Sinch API response.
   */
  async sendWhatsAppTextMessage(
    recipientPhoneNumber: string,
    textContent: string,
  ): Promise<SinchSendMessageResponseDto&gt; { // Use specific Response DTO
    const endpoint = '/messages:send';

    // Payload structure based on common Sinch Conversation API usage for WhatsApp.
    // **Important Note:** Verify this payload structure against the latest official
    // Sinch Conversation API documentation before using in production.
    // Specifically, confirm the usage of `app_id` vs. sender ID and `contact_id` for recipients.
    const payload = {
      app_id: this.config.whatsappSenderId, // Using sender ID as app_id reference for WhatsApp
      recipient: {
        contact_id: recipientPhoneNumber, // Use phone number directly for WhatsApp via contact_id
      },
      message: {
        text_message: {
          text: textContent,
        },
      },
      channel_priority_order: ['WHATSAPP'], // Ensure it uses WhatsApp channel
    };

    this.logger.log(`Sending WhatsApp message to ${recipientPhoneNumber} via app_id ${this.config.whatsappSenderId}`);

    try {
      const response = await this.httpClient.post<SinchSendMessageResponseDto&gt;(endpoint, payload);
      this.logger.log(`Message sent successfully. Message ID: ${response.data?.message_id}`);
      return response.data;
    } catch (error) {
      const axiosError = error as AxiosError; // Type assertion for better error handling
      const errorDetails = axiosError.response?.data || axiosError.message;
      this.logger.error(
        `Failed to send WhatsApp message to ${recipientPhoneNumber}. Status: ${axiosError.response?.status}. Details: ${JSON.stringify(errorDetails)}`,
        axiosError.stack // Include stack trace for better debugging
      );
      // Re-throw or handle specific Sinch errors (consider using a custom exception class)
      throw error; // Re-throw the original error to be handled by the controller
    }
  }

  // Add methods for other message types (templates, media) as needed
  // based on Sinch Conversation API documentation.
  // Example: sendTemplateMessage, sendMediaMessage etc.

  /**
   * Verifies the signature of an incoming webhook request from Sinch.
   * @param rawBody - The raw request body buffer.
   * @param signatureHeader - The value of the 'x-sinch-signature' header.
   * @param timestampHeader - The value of the 'x-sinch-timestamp' header.
   * @returns True if the signature is valid, false otherwise.
   */
   verifyWebhookSignature(
    rawBody: Buffer,
    signatureHeader: string | undefined,
    timestampHeader: string | undefined,
  ): boolean {
    if (!signatureHeader || !timestampHeader || !this.config.webhookSecret) {
      this.logger.warn('Webhook verification failed: Missing signature, timestamp, or webhook secret.');
      return false;
    }

    try {
      const hmac = crypto.createHmac('sha256', this.config.webhookSecret);
      const [signatureTimestamp, receivedSignature] = signatureHeader.split(',');

      // Validate the timestamp format in the header part
      if (!signatureTimestamp || !receivedSignature || signatureTimestamp !== `t=${timestampHeader}`) {
          this.logger.warn(`Webhook verification failed: Malformed or mismatched timestamp in signature header. Header: ""${signatureHeader}"", Timestamp: ""${timestampHeader}""`);
          return false;
      }

      // Construct the payload string exactly as Sinch signs it: timestamp + ""."" + rawBody
      const signedPayload = `${timestampHeader}.${rawBody.toString('utf8')}`;
      const expectedSignature = hmac.update(signedPayload).digest('base64'); // Sinch uses Base64 encoding for the signature

      // Use timingSafeEqual for security against timing attacks
      const receivedSigBuffer = Buffer.from(receivedSignature, 'base64');
      const expectedSigBuffer = Buffer.from(expectedSignature, 'base64');

      // Ensure buffers are valid and have the same length before comparing
      if (receivedSigBuffer.length === expectedSigBuffer.length &&
          receivedSigBuffer.length &gt; 0 && // Ensure non-empty buffers
          crypto.timingSafeEqual(receivedSigBuffer, expectedSigBuffer)) {
        this.logger.debug('Webhook signature verified successfully.');
        return true;
      } else {
        this.logger.warn(`Webhook verification failed: Invalid signature. Received: ""${receivedSignature}"", Expected: ""${expectedSignature}"" (Base64)`);
        return false;
      }

    } catch (error) {
      this.logger.error('Error during webhook signature verification:', error);
      return false;
    }
  }
}

// src/sinch/sinch.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule
import { SinchService } from './sinch.service';
import sinchConfig from '../config/sinch.config'; // Import the config loader

@Module({
  imports: [
    ConfigModule.forFeature(sinchConfig), // Register the specific config
  ],
  providers: [SinchService],
  exports: [SinchService], // Export if needed in other modules
})
export class SinchModule {}

// 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 { SinchModule } from './sinch/sinch.module'; // Import SinchModule
// import { WebhookModule } from './webhook/webhook.module'; // Import WebhookModule later

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    SinchModule, // Add SinchModule here
    // WebhookModule will be added later
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

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

export class SendMessageDto {
  @IsNotEmpty({ message: 'Recipient phone number should not be empty.' })
  @IsPhoneNumber(null, { message: 'Recipient phone number must be a valid E.164 format phone number (e.g., +15551234567).' }) // Use null for international format validation
  readonly recipientPhoneNumber: string;

  @IsNotEmpty({ message: 'Message text should not be empty.' })
  @IsString()
  @MaxLength(1600, { message: 'WhatsApp message text cannot exceed 1600 characters.' }) // WhatsApp message length limit
  readonly messageText: string;
}

// src/sinch/dto/sinch-send-response.dto.ts
// Basic DTO for the expected successful response from Sinch /messages:send
// Flesh this out based on the actual fields returned by Sinch API
export class SinchSendMessageResponseDto {
  message_id: string;
  accepted_time?: string; // Example optional field
  // Add other fields as documented by Sinch
}

// src/app.controller.ts (Example adding to AppController)
import { Controller, Get, Post, Body, UsePipes, ValidationPipe, HttpCode, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { AppService } from './app.service';
import { SinchService } from './sinch/sinch.service'; // Import SinchService
import { SendMessageDto } from './sinch/dto/send-message.dto'; // Import Request DTO
import { AxiosError } from 'axios';

@Controller()
export class AppController {
  private readonly logger = new Logger(AppController.name); // Add logger

  constructor(
    private readonly appService: AppService,
    private readonly sinchService: SinchService, // Inject SinchService
  ) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

  @Post('send-whatsapp')
  @HttpCode(HttpStatus.ACCEPTED) // Return 202 Accepted on success
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })) // Enable validation
  async sendWhatsAppMessage(@Body() sendMessageDto: SendMessageDto) {
    try {
      const result = await this.sinchService.sendWhatsAppTextMessage(
        sendMessageDto.recipientPhoneNumber,
        sendMessageDto.messageText,
      );
      // Return only essential info, like the message ID
      return { success: true, messageId: result.message_id };
    } catch (error) {
      // Handle potential errors from SinchService (e.g., Axios errors)
      if (error instanceof AxiosError && error.response) {
          // Log the detailed error internally but return a generic message externally
          this.logger.error(`Sinch API Error: Status ${error.response.status}, Data: ${JSON.stringify(error.response.data)}`);
          throw new HttpException(
              `Failed to send message via Sinch: ${error.response.data?.message || error.response.statusText || 'API error'}`,
              error.response.status || HttpStatus.BAD_GATEWAY
          );
      } else if (error instanceof Error) {
          this.logger.error(`Internal Error: ${error.message}`, error.stack);
          throw new HttpException(`Internal server error: ${error.message}`, HttpStatus.INTERNAL_SERVER_ERROR);
      } else {
          this.logger.error('Unknown Error sending message', error);
          throw new HttpException('An unexpected error occurred', HttpStatus.INTERNAL_SERVER_ERROR);
      }
    }
  }
}

npm run start:dev

curl -X POST http://localhost:3000/send-whatsapp \
-H 'Content-Type: application/json' \
-d '{
  "recipientPhoneNumber": "+15551234567",
  "messageText": "Hello from NestJS via Sinch!"
}'

{
  "success": true,
  "messageId": "01HXXXX..."
}

{
  "statusCode": 400,
  "message": [
    "Recipient phone number must be a valid E.164 format phone number (e.g., +15551234567)."
  ],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Failed to send message via Sinch: Invalid recipient phone number"
}

+-------------------------------------------------+
| Sinch App Configuration                         |
+-------------------------------------------------+
| App Name: My WhatsApp Service                   |
| App ID: <your_app_id&gt;                           |
|                                                 |
| Webhook Settings:                               |
|   Callback URL: [ https://<your_domain&gt;/webhook/sinch ] | (Must be HTTPS)
|   Webhook Secret: [ *************************** ] | &lt;--- Paste your exact secret here
|                                                 |
| Subscribed Events:                              |
|   [x] MESSAGE_INBOUND                           |
|   [x] MESSAGE_DELIVERY                          |
|   [ ] CONTACT_CREATE                            |
|   ...                                           |
|                                                 |
|   [ Save Changes ]                              |
+-------------------------------------------------+

nest generate module webhook
nest generate controller webhook
nest generate service webhook

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { Logger } from '@nestjs/common'; // Removed unused ValidationPipe import
import { ConfigService } from '@nestjs/config';
// Import NestExpressApplication if you need specific Express types_ otherwise not strictly needed
// import { NestExpressApplication } from '@nestjs/platform-express';

async function bootstrap() {
  // No need for { rawBody: true } here when using selective middleware
  const app = await NestFactory.create(AppModule);
  // const app = await NestFactory.create<NestExpressApplication&gt;(AppModule); // Use if needing Express types

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

  // Global pipes can be applied here if needed for other routes
  // app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));

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

// src/webhook/guards/sinch-webhook.guard.ts
import { Injectable, CanActivate, ExecutionContext, Logger, RawBodyRequest, BadRequestException, ForbiddenException } from '@nestjs/common';
import { Observable } from 'rxjs';
import { Request } from 'express'; // Assuming Express adapter
import { SinchService } from '../../sinch/sinch.service';

@Injectable()
export class SinchWebhookGuard implements CanActivate {
  private readonly logger = new Logger(SinchWebhookGuard.name);

  constructor(private readonly sinchService: SinchService) {}

  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean&gt; | Observable<boolean&gt; {
    const request = context.switchToHttp().getRequest<RawBodyRequest<Request>&gt;(); // Get request with potential rawBody

    // Access the raw body buffer attached by the middleware
    const rawBody = request.rawBody;
    if (!rawBody) {
        // This should not happen if the middleware is configured correctly
        this.logger.error('Webhook Guard Error: Raw body not available. Ensure raw body parsing middleware is applied correctly to the webhook route.');
        // Throw an exception to signal a server configuration issue
        throw new BadRequestException('Server configuration error: Raw body not available for webhook verification.');
    }

    const signature = request.headers['x-sinch-signature'] as string | undefined;
    const timestamp = request.headers['x-sinch-timestamp'] as string | undefined;

    this.logger.debug(`Verifying webhook signature. Timestamp: ${timestamp}, Signature Header: ${signature ? signature.substring(0, 10) + '...' : 'MISSING'}`); // Avoid logging full signature

    const isValid = this.sinchService.verifyWebhookSignature(
      rawBody,
      signature,
      timestamp,
    );

    if (!isValid) {
      this.logger.warn(`Invalid webhook signature received from IP: ${request.ip}. Blocking request.`);
      // Throw ForbiddenException to clearly indicate an authentication/authorization failure
      throw new ForbiddenException('Invalid webhook signature.');
    }

    this.logger.log('Webhook signature verified successfully.');
    return true; // Allow request to proceed to the controller
  }
}

// src/webhook/webhook.module.ts
import { Module, MiddlewareConsumer, NestModule, RequestMethod } from '@nestjs/common';
import { WebhookController } from './webhook.controller';
import { WebhookService } from './webhook.service';
import { SinchModule } from '../sinch/sinch.module'; // Import SinchModule to use SinchService
import * as bodyParser from 'body-parser'; // Import body-parser

@Module({
  imports: [SinchModule], // Import SinchModule to inject SinchService into the Guard
  controllers: [WebhookController],
  providers: [WebhookService], // Guard is provided where used (@UseGuards)
})
export class WebhookModule implements NestModule { // Implement NestModule
  configure(consumer: MiddlewareConsumer) {
    consumer
      // Apply raw body parser *only* for the Sinch webhook POST route
      .apply(bodyParser.raw({ type: 'application/json' })) // Ensure this matches the Content-Type Sinch sends
      .forRoutes({ path: 'webhook/sinch', method: RequestMethod.POST });
  }
}

// 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 { SinchModule } from './sinch/sinch.module';
import { WebhookModule } from './webhook/webhook.module'; // Import WebhookModule
// MongooseModule if used

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    SinchModule,
    WebhookModule, // Add WebhookModule here
    // MongooseModule.forRootAsync(...) // Example if using DB
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// src/webhook/dto/sinch-webhook.dto.ts
import { Type } from 'class-transformer';
import { IsString, IsNotEmpty, ValidateNested, IsOptional, IsEnum, Allow, IsObject } from 'class-validator';

// --- Nested DTOs (Simplify or expand based on needs and Sinch Docs) ---

class ContactIdentifier {
  @IsOptional() @IsString() phone?: string;
  @IsOptional() @IsString() user_id?: string;
  @IsOptional() @IsString() whatsapp_id?: string; // Common for WhatsApp
}

class RecipientInfo {
  // Use @Allow() if validation isn't strictly needed or structure varies
  @Allow() contact_id?: ContactIdentifier | string; // Can be object or just ID string sometimes
  @IsOptional() @IsString() identified_by?: string; // Alternative way Sinch might identify
}

class SenderInfo {
  @Allow() contact_id?: ContactIdentifier | string;
  @IsOptional() @IsString() user_display_name?: string;
}

class TextMessageContent {
  @IsNotEmpty() @IsString() text: string;
}

// Add other content types as needed (MediaMessageContent, ChoiceMessageContent, etc.)
// class MediaMessageContent { ... }

class MessageContent {
  @IsOptional() @ValidateNested() @Type(() => TextMessageContent)
  text_message?: TextMessageContent;

  // Add other message types here
  // @IsOptional() @ValidateNested() @Type(() => MediaMessageContent)
  // media_message?: MediaMessageContent;
}

class MessageMetadata {
    @IsOptional() @IsString() locale?: string;
    // Add other metadata fields
}

// --- Payload for MESSAGE_INBOUND ---
// This structure might vary slightly based on Sinch API version and specific event.
// Always refer to the official Sinch documentation for the exact payload structure.
class InboundMessagePayload {
  @IsNotEmpty() @IsString() id: string; // Sinch message ID

  @IsOptional() @IsString() direction?: 'INBOUND'; // Should be INBOUND

  @IsNotEmpty() @ValidateNested() @Type(() => RecipientInfo)
  recipient: RecipientInfo; // Your App/Sender ID info

  @IsNotEmpty() @ValidateNested() @Type(() => SenderInfo)
  sender: SenderInfo; // The end-user info

  @IsNotEmpty() @ValidateNested() @Type(() => MessageContent)
  message: MessageContent;

  @IsNotEmpty() @IsString() @IsEnum(['WHATSAPP', 'SMS', 'MESSENGER'], { message: 'Channel must be a valid Sinch channel' })
  channel: string; // Expecting 'WHATSAPP' mostly

  @IsNotEmpty() @IsString() // Consider @IsISO8601() for stricter validation
  timestamp: string; // ISO 8601 timestamp

  @IsOptional() @ValidateNested() @Type(() => MessageMetadata)
  metadata?: MessageMetadata;

  @IsOptional() @IsString() app_id?: string; // The Sinch App ID

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

  @IsOptional() @IsString() contact_id?: string; // Might be present at top level too

  @IsOptional() @IsString() processing_mode?: string; // e.g., 'CONVERSATION'
}

// Add other payload types like DeliveryReportPayload, ContactCreatePayload etc.

// --- Main Webhook DTO ---
// This DTO uses the 'trigger' field to determine which payload type to expect.
// You might need a more sophisticated approach (e.g., custom validation) if triggers aren't always present
// or if payloads share common base fields. For simplicity, we assume distinct payloads per trigger.
export class SinchWebhookDto {
  @IsNotEmpty() @IsString() trigger: string; // e.g., 'MESSAGE_INBOUND', 'MESSAGE_DELIVERY'

  @IsNotEmpty() @IsString() app_id: string; // Sinch App ID

  @IsNotEmpty() @IsString() // Consider @IsISO8601()
  accepted_time: string; // When Sinch accepted the event

  // Use @ValidateNested based on the trigger type.
  // This basic example assumes only MESSAGE_INBOUND for simplicity.
  // In a real app, you'd likely have a union type or conditional validation.
  @IsOptional() @ValidateNested() @Type(() => InboundMessagePayload)
  message_inbound?: InboundMessagePayload;

  // Add other potential payloads based on triggers
  // @IsOptional() @ValidateNested() @Type(() => DeliveryReportPayload)
  // message_delivery?: DeliveryReportPayload;

  // Allow other fields that might be present but not strictly validated
  [key: string]: any;
}