Implementing Two-Way SMS Messaging with Infobip and NestJS

+-------------+        +---------------------+        +-----------------+        +-------------+
| User / API  |        |   NestJS Backend    |        |   Infobip API   |        | User's Phone|
|   Client    |------->| (Controller,Service)|<------>|  (SMS Sending)  |<------>|             |
+-------------+        |                     |        +-----------------+        +-------------+
                       |  +---------------+  |                                       ^
                       |  | Infobip SDK   |  |                                       | SMS
                       |  +---------------+  |                                       | Reply
                       |                     |                                       |
                       |  +---------------+  |        +------------------+           |
                       |  | Prisma Client |<------>| PostgreSQL DB    |           |
                       |  +---------------+  |        | (Message Logs)   |           v
                       |                     |        +------------------+   +-----------------+
                       |  +---------------+  |                               |   Infobip       |
                       |  | Webhook Handler|<-------------------------------| (Inbound SMS via|
                       |  | (Controller)  |                               |    Webhook)     |
                       |  +---------------+  |                               +-----------------+
                       +---------------------+

# Ensure you have NestJS CLI installed: npm install -g @nestjs/cli
npx @nestjs/cli new nestjs-infobip-sms
cd nestjs-infobip-sms

# Infobip SDK
npm install @infobip-api/sdk

# Prisma ORM
npm install @prisma/client
npm install prisma --save-dev

# NestJS Config Module (for environment variables)
npm install @nestjs/config

# Class Validator & Transformer (for DTO validation)
npm install class-validator class-transformer

# (Optional_ but recommended for webhook security)
npm install @nestjs/throttler # For rate limiting

# (Optional_ for real-time updates via WebSockets)
# npm install @nestjs/websockets @nestjs/platform-socket.io

npx prisma init --datasource-provider postgresql

src/
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts

# .env

# Database
# Replace user_ password_ host_ port_ dbname with your actual local/dev settings
# Example for local setup:
DATABASE_URL=""postgresql://user:password@localhost:5432/mydb?schema=public""
# Example for Docker setup will be shown later_ pointing to the 'db' service name.

# Infobip Credentials
# Get these from your Infobip account dashboard (API Keys section)
INFOBIP_API_KEY=""YOUR_INFOBIP_API_KEY""
# Find your specific Base URL in the Infobip dashboard (often like xyz.api.infobip.com)
INFOBIP_BASE_URL=""YOUR_INFOBIP_BASE_URL""

# Application Port
PORT=3000

# Webhook Security (A simple shared secret)
# Generate a strong random string for this
INFOBIP_WEBHOOK_SECRET=""YOUR_STRONG_RANDOM_SECRET""

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule
import { AppController } from './app.controller';
import { AppService } from './app.service';
// We will create these modules later
// import { PrismaModule } from './prisma/prisma.module';
// import { InfobipModule } from './infobip/infobip.module';
// import { MessagingModule } from './messaging/messaging.module';
// import { WebhookModule } from './webhook/webhook.module';

@Module({
  imports: [
    ConfigModule.forRoot({ // Configure ConfigModule
      isGlobal: true_ // Make config available globally
      envFilePath: '.env'_ // Specify the env file path
    })_
    // PrismaModule_ // Will uncomment later
    // InfobipModule_ // Will uncomment later
    // MessagingModule_ // Will uncomment later
    // WebhookModule_ // Will uncomment later
  ]_
  controllers: [AppController]_ // Keep default controller for now
  providers: [AppService]_ // Keep default service for now
})
export class AppModule {}

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL") // Reads from .env file
}

// Define the Message model
model Message {
  id          String    @id @default(cuid()) // Unique identifier
  externalId  String?   @unique // Infobip message ID (optional for initial save_ unique once set)
  direction   Direction // INBOUND or OUTBOUND
  sender      String    // Sender phone number or identifier
  recipient   String    // Recipient phone number
  text        String    // Message content
  status      String?   // Status from Infobip (e.g._ PENDING_ DELIVERED_ FAILED)
  rawResponse Json?     // Store raw Infobip response/webhook payload if needed
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
}

// Enum for message direction
enum Direction {
  INBOUND
  OUTBOUND
}

# This creates a migration file and applies it to the database
npx prisma migrate dev --name init-message-model

# Create module and service files
mkdir src/prisma
touch src/prisma/prisma.module.ts
touch src/prisma/prisma.service.ts

// src/prisma/prisma.service.ts
import { Injectable_ OnModuleInit_ OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit_ OnModuleDestroy {
  async onModuleInit() {
    // Connect to the database when the module is initialized
    await this.$connect();
  }

  async onModuleDestroy() {
    // Disconnect from the database when the application shuts down
    await this.$disconnect();
  }
}

// src/prisma/prisma.module.ts
import { Global_ Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global() // Make PrismaService available globally
@Module({
  providers: [PrismaService]_
  exports: [PrismaService]_ // Export the service for injection
})
export class PrismaModule {}

// 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 { PrismaModule } from './prisma/prisma.module'; // Import PrismaModule
// ... other imports

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true_
      envFilePath: '.env'_
    })_
    PrismaModule_ // Add PrismaModule here
    // InfobipModule_
    // MessagingModule_
    // WebhookModule_
  ]_
  controllers: [AppController]_
  providers: [AppService]_
})
export class AppModule {}

mkdir src/infobip
touch src/infobip/infobip.module.ts
touch src/infobip/infobip.service.ts

// src/infobip/infobip.service.ts
import { Injectable_ Logger_ OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Infobip_ AuthType } from '@infobip-api/sdk';

@Injectable()
export class InfobipService implements OnModuleInit {
  private readonly logger = new Logger(InfobipService.name);
  private infobipClient: Infobip;

  constructor(private configService: ConfigService) {}

  onModuleInit() {
    const apiKey = this.configService.get<string&gt;('INFOBIP_API_KEY');
    const baseUrl = this.configService.get<string&gt;('INFOBIP_BASE_URL');

    if (!apiKey || !baseUrl) {
      this.logger.error('Infobip API Key or Base URL not configured. SMS functionality disabled.');
      // You might throw an error here if Infobip is essential for startup
      return;
    }

    try {
      this.infobipClient = new Infobip({
        baseUrl: baseUrl,
        apiKey: apiKey,
        authType: AuthType.ApiKey,
      });
      this.logger.log('Infobip client initialized successfully.');
    } catch (error) {
      this.logger.error('Failed to initialize Infobip client:', error);
    }
  }

  async sendSms(to: string, text: string, from?: string): Promise<any&gt; {
    if (!this.infobipClient) {
        this.logger.error('Infobip client not initialized. Cannot send SMS.');
        throw new Error('Infobip service is not available.');
    }

    // **IMPORTANT: Sender ID (`from`)**
    // If 'from' is not provided, use a default or one from config.
    // - Alphanumeric Sender IDs (e.g., 'InfoSMS', 'MyApp'): Cannot receive replies. Good for alerts/notifications.
    // - Purchased/Verified Numbers: Required for two-way communication (receiving replies). Must be obtained via Infobip.
    // Regulations vary by country. Using 'InfoSMS' as a default might be misleading if replies are expected.
    const sender = from || 'InfoSMS'; // Example default. Configure appropriately.

    // Ensure 'to' number is in international E.164 format (e.g., 447123456789)
    // **WARNING:** The regex below is extremely basic and insufficient for production validation.
    // It does NOT properly validate E.164 (missing '+', country code checks, etc.).
    // Strongly consider using a robust library like 'libphonenumber-js' for reliable validation.
    if (!/^\d{11,15}$/.test(to.replace('+', ''))) {
         this.logger.warn(`Recipient phone number format validation is basic and might be inaccurate: ${to}. Consider using a dedicated library. Attempting to send anyway.`);
         // For stricter validation, you might throw an error here:
         // throw new Error(`Invalid recipient phone number format: ${to}`);
    }

    this.logger.log(`Attempting to send SMS to ${to} from ${sender}`);

    try {
      const response = await this.infobipClient.channels.sms.send({
        messages: [
          {
            destinations: [{ to: to }],
            from: sender,
            text: text,
          },
        ],
      });

      this.logger.log(`SMS sent successfully via Infobip. Bulk ID: ${response.data.bulkId}`);
      // Consider logging specific message IDs if needed: response.data.messages[0]?.messageId
      return response.data; // Return the response data from Infobip
    } catch (error) {
      this.logger.error('Failed to send SMS via Infobip:', error.response?.data || error.message);
      // Rethrow or handle the error appropriately
      throw error;
    }
  }
}

// src/infobip/infobip.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config'; // ConfigModule is needed here if not global
import { InfobipService } from './infobip.service';

@Module({
  imports: [ConfigModule], // Ensure ConfigService is available
  providers: [InfobipService],
  exports: [InfobipService], // Export the service
})
export class InfobipModule {}

// 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 { PrismaModule } from './prisma/prisma.module';
import { InfobipModule } from './infobip/infobip.module'; // Import
// ... other imports

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    PrismaModule,
    InfobipModule, // Add InfobipModule
    // MessagingModule,
    // WebhookModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

mkdir src/messaging
touch src/messaging/messaging.module.ts
touch src/messaging/messaging.service.ts
touch src/messaging/dto/send-sms.dto.ts # DTO for sending SMS
touch src/messaging/dto/infobip-incoming.dto.ts # DTO for incoming webhook

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

export class SendSmsDto {
  @IsNotEmpty()
  @IsPhoneNumber(null) // Use null for generic international format check
  @Length(10, 15) // Adjust length constraints as needed
  readonly to: string;

  @IsNotEmpty()
  @IsString()
  @Length(1, 160) // Standard SMS length limit (or more for concatenated)
  readonly text: string;

  // Optional: Allow specifying sender ID if needed and configured
  // @IsOptional()
  // @IsString()
  // readonly from?: string;
}

// src/messaging/dto/infobip-incoming.dto.ts
// Based on common Infobip webhook structure for SMS MO (Mobile Originated)
// **IMPORTANT:** This DTO is an *example*. You MUST inspect the actual JSON payload
// sent by Infobip to your webhook endpoint (e.g., using webhook.site or logging
// the raw request body) and adjust this structure accordingly. Infobip's payload
// structure can vary based on account configuration and message type.
// Refer to Infobip documentation for the exact 'SMS Message Received' structure.
import { Type } from 'class-transformer';
import { IsArray, IsDateString, IsNotEmpty, IsNumber, IsObject, IsOptional, IsString, ValidateNested } from 'class-validator';

class MessageResult {
  @IsNotEmpty()
  @IsString()
  messageId: string;

  @IsNotEmpty()
  @IsString()
  from: string; // Sender's number

  @IsNotEmpty()
  @IsString()
  to: string; // Your Infobip number

  @IsNotEmpty()
  @IsString()
  text: string; // Message content

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

  @IsOptional()
  @IsDateString()
  receivedAt?: string; // Or use @Type(() => Date) if transforming

  @IsOptional()
  @IsNumber()
  smsCount?: number;

  // Add other potential fields based on Infobip docs (price, networkCode etc.)
}

class IncomingSmsPayload {
    // This nested structure is common but verify it!
    @IsNotEmpty()
    @IsArray()
    @ValidateNested({ each: true })
    @Type(() => MessageResult)
    results: MessageResult[];

    @IsOptional()
    @IsNumber()
    messageCount?: number;

    @IsOptional()
    @IsNumber()
    pendingMessageCount?: number;
}

// The top-level DTO for the webhook payload
export class InfobipIncomingSmsDto {
    // Assuming the payload looks like { "results": [...] }
    // **VERIFY THIS STRUCTURE AGAINST ACTUAL INFOBIP PAYLOADS**
    @IsNotEmpty()
    @IsArray()
    @ValidateNested({ each: true })
    @Type(() => MessageResult)
    results: MessageResult[];
}

// --- ALTERNATIVE If payload is directly the array ---
// export class InfobipIncomingSmsDto extends Array<MessageResult&gt; {}
// You would need to adjust validation pipes for arrays if using this.

// src/messaging/messaging.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { InfobipService } from '../infobip/infobip.service';
import { SendSmsDto } from './dto/send-sms.dto';
import { InfobipIncomingSmsDto, MessageResult } from './dto/infobip-incoming.dto';
import { Direction } from '@prisma/client'; // Import enum from generated client

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

  constructor(
    private readonly prisma: PrismaService,
    private readonly infobip: InfobipService,
  ) {}

  async handleOutgoingSms(sendSmsDto: SendSmsDto): Promise<{ messageId: string | null; dbId: string }> {
    this.logger.log(`Handling outgoing SMS request to ${sendSmsDto.to}`);

    let dbMessage;
    try {
        // 1. Save initial record to DB (optional, could save after sending)
        dbMessage = await this.prisma.message.create({
            data: {
                direction: Direction.OUTBOUND,
                recipient: sendSmsDto.to,
                sender: 'SYSTEM', // Or the specific sender ID used
                text: sendSmsDto.text,
                status: 'PENDING_SEND', // Initial status
            },
        });
        this.logger.log(`Saved initial outgoing message record with ID: ${dbMessage.id}`);

        // 2. Send SMS via Infobip
        const infobipResponse = await this.infobip.sendSms(sendSmsDto.to, sendSmsDto.text /*, sendSmsDto.from */);

        // 3. Update DB record with Infobip details
        const messageInfo = infobipResponse.messages?.[0];
        if (messageInfo) {
            await this.prisma.message.update({
                where: { id: dbMessage.id },
                data: {
                    externalId: messageInfo.messageId,
                    status: messageInfo.status?.name || 'SENT_TO_INFOBIP', // Use status from response
                    sender: messageInfo.from || 'SYSTEM', // Update sender if available in response
                    // Using `as any` bypasses type safety. Pragmatic for storing raw external data,
                    // but consider defining a basic interface for `infobipResponse` or using
                    // `unknown` with type guards for better practice if structure is known/stable.
                    rawResponse: infobipResponse as any,
                },
            });
             this.logger.log(`Updated message ${dbMessage.id} with Infobip ID: ${messageInfo.messageId}`);
            return { messageId: messageInfo.messageId, dbId: dbMessage.id };
        } else {
             this.logger.warn(`Infobip response did not contain message details for DB record ${dbMessage.id}`);
             await this.prisma.message.update({ where: {id: dbMessage.id }, data: { status: 'SENT_NO_DETAILS'}});
             return { messageId: null, dbId: dbMessage.id }; // Indicate success but no ID
        }

    } catch (error) {
        this.logger.error(`Error handling outgoing SMS to ${sendSmsDto.to}:`, error);
        // Update DB record to reflect failure if it was created
        if (dbMessage) {
            await this.prisma.message.update({
                where: { id: dbMessage.id },
                data: { status: 'FAILED_TO_SEND' },
            }).catch(updateError => this.logger.error(`Failed to update message status after error: ${updateError}`));
        }
        // Rethrow the error to be handled by the controller/exception filter
        throw error;
    }
  }

  async handleIncomingSms(payload: InfobipIncomingSmsDto): Promise<void&gt; {
    this.logger.log(`Handling incoming SMS payload with ${payload.results?.length || 0} message(s)`);

    if (!payload || !payload.results || payload.results.length === 0) {
      this.logger.warn('Received empty or invalid incoming SMS payload.');
      return;
    }

    for (const message of payload.results) {
      try {
        const existingMessage = await this.prisma.message.findUnique({
          where: { externalId: message.messageId },
        });

        if (existingMessage) {
          this.logger.warn(`Received duplicate incoming message with Infobip ID: ${message.messageId}. Skipping.`);
          continue; // Avoid processing duplicates
        }

        await this.prisma.message.create({
          data: {
            externalId: message.messageId,
            direction: Direction.INBOUND,
            sender: message.from,
            recipient: message.to,
            text: message.text,
            status: 'RECEIVED', // Or map from a status field in the webhook if available
            // Using `as any` bypasses type safety here too. Consider a basic interface
            // or `unknown` for the `message` object if its structure is reliable.
            rawResponse: message as any, // Store the specific message part
            createdAt: message.receivedAt ? new Date(message.receivedAt) : new Date(), // Use receivedAt if available
          },
        });
        this.logger.log(`Saved incoming message from ${message.from} with Infobip ID: ${message.messageId}`);

        // --- Optional: Trigger further actions ---
        // e.g., Notify other services, process commands in the message text, emit WebSocket event
        // this.eventEmitter.emit('sms.received', savedMessage);

      } catch (error) {
        this.logger.error(`Error processing incoming message ${message.messageId || 'N/A'} from ${message.from}:`, error);
        // Continue processing other messages in the batch
      }
    }
  }
}

// src/messaging/messaging.module.ts
import { Module } from '@nestjs/common';
import { MessagingService } from './messaging.service';
// Import PrismaModule and InfobipModule if they are not global
// import { PrismaModule } from '../prisma/prisma.module';
// import { InfobipModule } from '../infobip/infobip.module';

@Module({
  // imports: [PrismaModule, InfobipModule], // Needed if not global
  providers: [MessagingService],
  exports: [MessagingService], // Export service for use in Controllers
})
export class MessagingModule {}

// 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 { PrismaModule } from './prisma/prisma.module';
import { InfobipModule } from './infobip/infobip.module';
import { MessagingModule } from './messaging/messaging.module'; // Import
// ... other imports

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    PrismaModule,
    InfobipModule,
    MessagingModule, // Add MessagingModule
    // WebhookModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// src/app.controller.ts
import { Controller, Post, Body, HttpCode, HttpStatus, Logger, UsePipes, ValidationPipe } from '@nestjs/common';
// Remove AppService if not used
// import { AppService } from './app.service';
import { MessagingService } from './messaging/messaging.service';
import { SendSmsDto } from './messaging/dto/send-sms.dto';

@Controller('api/v1/messaging') // Define a base path for messaging endpoints
export class AppController {
  private readonly logger = new Logger(AppController.name);

  constructor(private readonly messagingService: MessagingService) {}

  // Remove default GET endpoint if not needed
  // @Get()
  // getHello(): string {
  //   return this.appService.getHello();
  // }

  @Post('sms/send')
  @HttpCode(HttpStatus.ACCEPTED) // Use 202 Accepted as sending is asynchronous
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true })) // Validate incoming DTO
  async sendSms(@Body() sendSmsDto: SendSmsDto) {
    this.logger.log(`Received request to send SMS to ${sendSmsDto.to}`);
    try {
      const result = await this.messagingService.handleOutgoingSms(sendSmsDto);
      this.logger.log(`SMS queued for sending. DB ID: ${result.dbId}, Infobip ID: ${result.messageId || 'N/A'}`);
      return {
        message: 'SMS submitted successfully.',
        databaseId: result.dbId,
        infobipMessageId: result.messageId, // Can be null if Infobip response was unexpected
      };
    } catch (error) {
      this.logger.error(`API Error sending SMS: ${error.message}`, error.stack);
      // HttpExceptionFilter (added later) will handle formatting the error response
      throw error; // Re-throw for the global filter
    }
  }
}

curl -X POST http://localhost:3000/api/v1/messaging/sms/send \
-H ""Content-Type: application/json"" \
-d '{
  ""to"": ""+12345678900"", # Replace with a valid E.164 number
  ""text"": ""Hello from NestJS and Infobip! Test at '""`date`""'""
}'

# Expected Response (approximate):
# {
#   ""message"": ""SMS submitted successfully."",
#   ""databaseId"": ""cl..."",
#   ""infobipMessageId"": ""2034...""
# }