Implementing Infobip SMS with Delivery Callbacks in NestJS

+-------------+       +----------------------+       +-----------------+
| Your Client | ----> | NestJS API           | ----> | Infobip API     |
| (Web/Mobile)|       | (Send SMS Endpoint)  |       | (Send Message)  |
+-------------+       +----------------------+       +-----------------+
                          |         ^
                          | Stores  | Receives
                          v         |
                      +-------------+
                      | Database    |
                      | (Message   |
                      |  Status)   |
                      +-------------+
                          ^         |
                          | Updates | Sends
                          |         v
                      +----------------------+       +-----------------+
                      | NestJS API           | <---- | Infobip Callback|
                      | (Callback Endpoint)  |       | (Delivery Status)|
                      +----------------------+       +-----------------+

npm install -g @nestjs/cli

nest new nestjs-infobip-sms
cd nestjs-infobip-sms

npm install @infobip-api/sdk @nestjs/config class-validator class-transformer prisma @prisma/client
npm install --save-dev @types/node prisma

npx prisma init --datasource-provider sqlite

# .env

# --- Database ---
# Prisma automatically sets this based on your choice in `npx prisma init`
DATABASE_URL=""file:./dev.db""

# --- Infobip ---
# Obtain from your Infobip account dashboard (API Keys section)
INFOBIP_API_KEY=""YOUR_INFOBIP_API_KEY""
# Find your Base URL on the Infobip dashboard homepage or API documentation
INFOBIP_BASE_URL=""YOUR_INFOBIP_BASE_URL"" # e.g., yxpv6d.api.infobip.com

# --- Application ---
# The base URL where your NestJS app will be publicly accessible.
# Use ngrok URL during development, e.g., https://your-ngrok-subdomain.ngrok.io
APP_BASE_URL=""http://localhost:3000""

// 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 later

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

// prisma/schema.prisma

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

datasource db {
  provider = ""sqlite"" // Or ""postgresql"", ""mysql""
  url      = env(""DATABASE_URL"")
}

// Enum for delivery status based on Infobip's common statuses
enum MessageStatus {
  PENDING       // Initial state before sending or confirmation
  SENT          // Successfully sent to Infobip API
  DELIVERED     // Confirmed delivery to handset
  UNDELIVERABLE // Failed delivery after retries
  EXPIRED       // Message validity period expired
  REJECTED      // Rejected by carrier or Infobip
  UNKNOWN       // Status could not be determined
}

model SmsMessage {
  id               String        @id @default(uuid()) // Our internal unique ID
  recipient        String        // Phone number SMS was sent to
  senderId         String?       // 'from' field used (e.g., 'InfoSMS')
  text             String        // Message content
  infobipMessageId String?       @unique // ID from Infobip API response (can be null initially)
  infobipBulkId    String?       // Bulk ID if sent as part of a batch
  status           MessageStatus @default(PENDING) // Current delivery status
  callbackData     String        @unique // Unique data sent to Infobip to correlate callbacks
  sentAt           DateTime      @default(now()) // When we initiated the send
  statusUpdatedAt  DateTime      @updatedAt // When the status was last updated

  @@index([status])
  @@index([recipient])
}

# Generate migration files based on schema changes
npx prisma migrate dev --name init-sms-message

# (Optional) Apply migrations to a production database later
# npx prisma migrate deploy

nest g module prisma --flat
nest g service prisma --flat

// src/prisma.service.ts
import { Injectable, OnModuleInit, INestApplication } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    // Optional: Connect to the database when the module initializes
    await this.$connect();
  }

  // Optional: Disconnect gracefully on shutdown
  async enableShutdownHooks(app: INestApplication) {
    process.on('beforeExit', async () => {
      await app.close();
      await this.$disconnect();
    });
  }
}

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

@Global() // Make PrismaService available globally
@Module({
  providers: [PrismaService],
  exports: [PrismaService], // Export PrismaService 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
// Import other modules later (e.g., SmsModule)

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

nest g module sms
nest g service sms/services/sms --no-spec
nest g controller sms/controllers/sms --no-spec

// src/sms/services/sms.service.ts
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Infobip, AuthType } from '@infobip-api/sdk';
import { PrismaService } from '../../prisma/prisma.service';
import { MessageStatus, Prisma } from '@prisma/client';
import { randomUUID } from 'crypto'; // For generating unique callbackData
import { InfobipCallbackDto, InfobipResultDto } from '../dto/infobip-report.dto'; // Import Callback DTO

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

  constructor(
    private configService: ConfigService,
    private prisma: PrismaService,
  ) {}

  onModuleInit() {
    const apiKey = this.configService.get<string>('INFOBIP_API_KEY');
    const baseUrl = this.configService.get<string>('INFOBIP_BASE_URL');
    this.appBaseUrl = this.configService.get<string>('APP_BASE_URL');

    if (!apiKey || !baseUrl || !this.appBaseUrl) {
      this.logger.error(
        'Infobip API Key, Base URL, or App Base URL missing in configuration.',
      );
      throw new Error('Missing Infobip or App configuration.');
    }

    this.infobipClient = new Infobip({
      baseUrl: baseUrl,
      apiKey: apiKey,
      authType: AuthType.ApiKey,
    });
    this.logger.log('Infobip client initialized.');
  }

  // --- Method to Send SMS ---
  async sendSingleSms(recipient: string, text: string, sender = 'InfoSMS') {
    this.logger.log(`Attempting to send SMS to ${recipient}`);

    // 1. Generate unique callback data for correlation
    const uniqueCallbackData = randomUUID();

    // 2. Create initial record in DB *before* sending
    let smsRecord;
    try {
      smsRecord = await this.prisma.smsMessage.create({
        data: {
          recipient: recipient,
          text: text,
          senderId: sender,
          status: MessageStatus.PENDING, // Initial status
          callbackData: uniqueCallbackData, // Store the unique ID
        },
      });
      this.logger.log(`Created initial SMS record ${smsRecord.id}`);
    } catch (error) {
      this.logger.error(
        `Failed to create initial SMS record for ${recipient}: ${error.message}`,
        error.stack,
      );
      // Rethrow or handle appropriately - cannot proceed without DB record
      throw new Error('Database error while preparing SMS.');
    }

    // 3. Prepare Infobip Payload
    const payload = {
      messages: [
        {
          destinations: [{ to: recipient }],
          from: sender,
          text: text,
          // CRUCIAL: Tell Infobip where to send the delivery report
          notifyUrl: `${this.appBaseUrl}/sms/callback/infobip`, // Our callback endpoint
          notifyContentType: 'application/json',
          // CRUCIAL: Include our unique ID
          callbackData: uniqueCallbackData,
        },
      ],
    };

    // 4. Send SMS via Infobip API
    try {
      const infobipResponse =
        await this.infobipClient.channels.sms.send(payload);
      const messageResponse = infobipResponse.data.messages[0]; // Assuming single message response

      this.logger.log(
        `Infobip response received for ${recipient}: Status ${messageResponse.status.groupName}, Message ID ${messageResponse.messageId}`,
      );

      // 5. Update DB record with Infobip's message ID and initial status from API
      const updatedRecord = await this.prisma.smsMessage.update({
        where: { id: smsRecord.id },
        data: {
          infobipMessageId: messageResponse.messageId,
          infobipBulkId: infobipResponse.data.bulkId,
          // Update status based on initial Infobip acceptance (e.g., PENDING or potentially REJECTED if immediate failure)
          status: this.mapInfobipStatus(messageResponse.status.groupName),
        },
      });

      this.logger.log(
        `Updated SMS record ${updatedRecord.id} with Infobip Message ID ${updatedRecord.infobipMessageId}`,
      );

      return {
        internalMessageId: updatedRecord.id,
        infobipMessageId: updatedRecord.infobipMessageId,
        infobipStatus: messageResponse.status.groupName,
      };
    } catch (error) {
      this.logger.error(
        `Failed to send SMS via Infobip for record ${smsRecord.id}: ${error.message}`,
        error.response?.data || error.stack, // Log Infobip error details if available
      );

      // Update DB record to indicate failure
      await this.prisma.smsMessage.update({
        where: { id: smsRecord.id },
        data: {
          status: MessageStatus.REJECTED, // Or another appropriate failure status
        },
      });

      // Rethrow or return error information
      throw new Error(`Infobip API Error: ${error.message}`);
    }
  }

  // --- Helper to map Infobip status groups to our enum ---
  private mapInfobipStatus(infobipStatusGroup: string): MessageStatus {
    // It is crucial to verify this mapping against the current Infobip documentation for status groups to ensure accurate tracking.
    switch (infobipStatusGroup?.toUpperCase()) {
      case 'PENDING':
        return MessageStatus.PENDING;
      case 'SENT': // Note: Infobip 'SENT' might just mean accepted by them, not delivered. PENDING might be safer initial state.
        return MessageStatus.SENT;
      case 'DELIVERED':
        return MessageStatus.DELIVERED;
      case 'UNDELIVERABLE':
        return MessageStatus.UNDELIVERABLE;
      case 'EXPIRED':
        return MessageStatus.EXPIRED;
      case 'REJECTED':
        return MessageStatus.REJECTED;
      default:
        this.logger.warn(`Unknown Infobip status group: ${infobipStatusGroup}`);
        return MessageStatus.UNKNOWN;
    }
    // Note: Adapt this based on the specific statuses you care about from Infobip's documentation.
  }

  // --- Method to Handle Delivery Callbacks ---
  async handleDeliveryReport(reportDto: InfobipCallbackDto) {
    this.logger.log(`Processing ${reportDto.results.length} delivery report(s) from Infobip.`);

    for (const result of reportDto.results) {
        // --- Find the matching message using callbackData ---
        // CallbackData is the most reliable way to correlate
        if (!result.callbackData) {
          this.logger.warn(`Received delivery report without callbackData for messageId ${result.messageId}. Cannot correlate reliably.`);
          // Optional: Fallback to trying messageId, but less reliable if IDs collide or weren't stored yet
          continue;
        }

        try {
          const message = await this.prisma.smsMessage.findUnique({
            where: { callbackData: result.callbackData },
          });

          if (!message) {
            this.logger.warn(`Received delivery report with callbackData ${result.callbackData}, but no matching message found in DB. MessageId: ${result.messageId}. Maybe already processed or test data?`);
            continue; // Skip if no matching record found
          }

          // --- Idempotency Check ---
          // Avoid processing the same final status update multiple times if Infobip retries
          const newStatus = this.mapInfobipStatus(result.status.groupName);
          const isFinalStatus = [
              MessageStatus.DELIVERED,
              MessageStatus.UNDELIVERABLE,
              MessageStatus.EXPIRED,
              MessageStatus.REJECTED,
          ].includes(message.status);

          // Check if the status in DB is already final AND the incoming status is the same
          if (isFinalStatus && message.status === newStatus) {
              this.logger.log(`Message ${message.id} (CallbackData: ${result.callbackData}) already has final status ${message.status}. Ignoring duplicate report.`);
              continue; // Skip processing this result
          }

          // If the status is new or not final, proceed with update
          if (!isFinalStatus || message.status !== newStatus) {
            this.logger.log(
              `Updating message ${message.id} (CallbackData: ${result.callbackData}) from ${message.status} to ${newStatus}. Infobip Status: ${result.status.groupName} (${result.status.name})`,
            );

            await this.prisma.smsMessage.update({
              where: { id: message.id },
              data: {
                status: newStatus,
                // Optionally store more details from the report if needed
                // e.g., infobipDetailedStatus: result.status.name,
                //       errorCode: result.error?.name,
                //       statusUpdatedAt: result.doneAt // Use Infobip's timestamp if preferred
              },
            });
            this.logger.log(`Successfully updated message ${message.id}.`);
          }
        } catch (error) {
          this.logger.error(
            `Error processing delivery report for callbackData ${result.callbackData} (MessageId: ${result.messageId}): ${error.message}`,
            error.stack,
          );
          // Decide if you need to retry or just log the error.
          // Returning 204 to Infobip even on error prevents retries unless the error is temporary network issue.
        }
    } // End loop through results
  } // End handleDeliveryReport method
}

// src/sms/sms.module.ts
import { Module } from '@nestjs/common';
import { SmsService } from './services/sms.service';
import { SmsController } from './controllers/sms.controller';
// PrismaModule is global, ConfigModule is global - no need to import here

@Module({
  controllers: [SmsController],
  providers: [SmsService],
  exports: [SmsService], // Export if needed by other modules
})
export class SmsModule {}

// src/app.module.ts
// ... other imports
import { SmsModule } from './sms/sms.module'; // Import SmsModule

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

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

export class SendSmsDto {
  @IsNotEmpty()
  @IsPhoneNumber(null) // Basic phone number validation (adapt region if needed)
  @IsString()
  recipient: string;

  @IsNotEmpty()
  @IsString()
  @MaxLength(160) // Standard SMS limit (adjust if using concatenation)
  text: string;

  @IsString()
  @MaxLength(11) // Alphanumeric sender ID limit
  @IsOptional() // Make optional if you have a default sender
  sender?: string; // Optional sender ID. If not provided, a default (e.g., 'InfoSMS') might be used by the service.
}

// src/sms/controllers/sms.controller.ts
import { Controller, Post, Body, ValidationPipe, UsePipes, Logger, HttpCode, HttpStatus } from '@nestjs/common';
import { SmsService } from '../services/sms.service';
import { SendSmsDto } from '../dto/send-sms.dto';
import { InfobipCallbackDto } from '../dto/infobip-report.dto'; // Import Callback DTO

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

  constructor(private readonly smsService: SmsService) {}

  @Post('send') // Endpoint: POST /sms/send
  @UsePipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })) // Enable validation locally if not global
  @HttpCode(HttpStatus.ACCEPTED) // Return 202 Accepted - processing started
  async sendSms(@Body() sendSmsDto: SendSmsDto) {
    this.logger.log(`Received request to send SMS to ${sendSmsDto.recipient}`);
    try {
      const result = await this.smsService.sendSingleSms(
        sendSmsDto.recipient,
        sendSmsDto.text,
        sendSmsDto.sender, // Pass sender if provided (service handles default)
      );
      this.logger.log(`SMS queued for sending with internal ID: ${result.internalMessageId}`);
      // Return relevant IDs
      return {
        message: 'SMS submitted successfully.',
        internalMessageId: result.internalMessageId,
        infobipMessageId: result.infobipMessageId,
      };
    } catch (error) {
      this.logger.error(`Error in /sms/send endpoint: ${error.message}`, error.stack);
      // Let NestJS default error handling or implement custom Exception Filters
      throw error;
    }
  }

  // --- Callback Endpoint ---
  @Post('callback/infobip') // Endpoint: POST /sms/callback/infobip
  @HttpCode(HttpStatus.NO_CONTENT) // Acknowledge receipt, no body needed
  @UsePipes(new ValidationPipe({ validateCustomDecorators: true, transform: true, whitelist: true })) // Validate callback payload
  async handleInfobipCallback(@Body() reportDto: InfobipCallbackDto) {
      this.logger.log(`Received Infobip callback request.`);
      // Delegate to service
      await this.smsService.handleDeliveryReport(reportDto);
      // Return 204 No Content to Infobip automatically due to @HttpCode
  }
}

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe, Logger } from '@nestjs/common';
import { PrismaService } from './prisma/prisma.service'; // Import PrismaService

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const logger = new Logger('Bootstrap');

  // Enable CORS if your client is on a different domain
  app.enableCors();

  // Global Validation Pipe
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true, // Automatically transform payloads to DTO instances
      transformOptions: {
        enableImplicitConversion: true, // Allow basic type conversions
      },
    }),
  );

  // Graceful shutdown hooks for Prisma
  const prismaService = app.get(PrismaService);
  await prismaService.enableShutdownHooks(app);

  const port = process.env.PORT || 3000;
  await app.listen(port);
  logger.log(`Application listening on port ${port}`);
  logger.log(`API Base URL: ${process.env.APP_BASE_URL || `http://localhost:${port}`}`);
  logger.log(`Infobip Callback URL: ${process.env.APP_BASE_URL || `http://localhost:${port}`}/sms/callback/infobip`);

}
bootstrap();

curl -X POST http://localhost:3000/sms/send \
-H ""Content-Type: application/json"" \
-d '{
  ""recipient"": ""+12345678900"",
  ""text"": ""Hello from NestJS and Infobip!"",
  ""sender"": ""MyApp""
}'

# Expected Response (202 Accepted):
# {
#  ""message"": ""SMS submitted successfully."",
#  ""internalMessageId"": ""..."", # UUID generated by your app
#  ""infobipMessageId"": ""..."" # ID from Infobip
# }

// src/sms/dto/infobip-report.dto.ts
import { Type } from 'class-transformer';
import { IsArray, IsDate, IsEnum, IsNotEmpty, IsNumber, IsObject, IsOptional, IsString, ValidateNested, IsBoolean } from 'class-validator';

// Define nested objects based on Infobip's documentation

class InfobipPriceDto {
  @IsNumber()
  pricePerMessage: number;

  @IsString()
  currency: string;
}

class InfobipStatusDto {
  @IsNumber()
  groupId: number;

  @IsString()
  groupName: string; // e.g., ""DELIVERED"", ""UNDELIVERABLE"", ""PENDING""

  @IsNumber()
  id: number;

  @IsString()
  name: string; // More specific status name

  @IsString()
  description: string;
}

class InfobipErrorDto {
  @IsNumber()
  groupId: number;

  @IsString()
  groupName: string;

  @IsNumber()
  id: number;

  @IsString()
  name: string;

  @IsString()
  description: string;

  @IsBoolean()
  permanent: boolean;
}


class InfobipResultDto {
  @IsString()
  bulkId: string;

  @IsString()
  messageId: string;

  @IsString()
  to: string;

  @IsDate()
  @Type(() => Date) // Transform string date from JSON to Date object
  sentAt: Date;

  @IsDate()
  @Type(() => Date)
  doneAt: Date; // Time of final status update

  @IsNumber()
  smsCount: number; // Number of SMS segments

  @IsOptional() // Price might not always be included
  @ValidateNested()
  @Type(() => InfobipPriceDto)
  price?: InfobipPriceDto;

  @ValidateNested()
  @Type(() => InfobipStatusDto)
  status: InfobipStatusDto;

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

  @IsString()
  @IsOptional() // Should be present if we sent it
  callbackData?: string;
}

// Main DTO for the callback payload
export class InfobipCallbackDto {
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => InfobipResultDto)
  results: InfobipResultDto[];
}