Send SMS with Sinch and Fastify: Complete Node.js Integration Guide

graph LR
    Client -- POST /sms/send --> FastifyAPI[Fastify API];
    FastifyAPI -- sendSms(to, message) --> SinchService[Sinch Service Module];
    SinchService -- Send SMS Request --> SinchPlatform[Sinch Platform API];
    SinchPlatform -- SMS --> RecipientPhone[Recipient Phone];
    SinchPlatform -- API Response --> SinchService;
    SinchService -- Success/Error --> FastifyAPI;
    FastifyAPI -- HTTP Response --> Client;

# 1. Create a project directory
mkdir fastify-sinch-sms
cd fastify-sinch-sms

# 2. Generate a basic Fastify project
fastify generate .

# Respond to the prompts (defaults are usually fine for this guide)
# Choose standard JavaScript

# 3. Install necessary production dependencies
npm install @sinch/sdk-client dotenv @fastify/env @fastify/helmet @fastify/rate-limit

# 4. Install development dependencies
npm install --save-dev tap sinon # Fastify's default test runner and mocking library

# 5. (Optional) If not using fastify-cli, initialize npm and install core fastify
# npm init -y
# npm install fastify @sinch/sdk-client dotenv @fastify/env @fastify/helmet @fastify/rate-limit
# npm install --save-dev tap sinon

fastify-sinch-sms/
├── node_modules/
├── routes/
│   └── sms/
│       └── index.js      # Your SMS sending route
├── services/
│   └── sinchService.js   # Logic for interacting with Sinch SDK
├── plugins/              # For Fastify plugins if needed later
├── test/                 # Test files (e.g., routes/sms.test.js)
│   ├── routes/
│   │   └── sms.test.js
│   └── helper.js         # Test helper for building the app
├── app.js                # Main application entry point
├── package.json
├── package-lock.json
├── .env                  # Environment variables (DO NOT COMMIT)
└── .gitignore            # Git ignore file

# .gitignore

# Node dependencies
node_modules/

# Environment variables
.env
*.env
.env.*

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Build output
dist
build

# OS generated files
.DS_Store
Thumbs.db

# .env

# Sinch Credentials – Get from Sinch Dashboard > API & SDK > SDK Keys
SINCH_PROJECT_ID=YOUR_SINCH_PROJECT_ID
SINCH_KEY_ID=YOUR_SINCH_KEY_ID
SINCH_KEY_SECRET=YOUR_SINCH_KEY_SECRET

# Sinch Settings
SINCH_REGION=us # Or eu, au, br, ca. Check Sinch docs for available regions.
SINCH_NUMBER=+1xxxxxxxxxx # Your purchased/assigned Sinch SMS number

# Application Settings
PORT=3000
HOST=0.0.0.0 # Listen on all available network interfaces
LOG_LEVEL=info # Pino log level (trace, debug, info, warn, error, fatal)

// app.js (or server.js)
'use strict'

const path = require('node:path')
const AutoLoad = require('@fastify/autoload')
const fastifyEnv = require('@fastify/env')

// Define schema for environment variables using @fastify/env
// This ensures required variables are present and have the correct type.
const envSchema = {
  type: 'object',
  required: [
    'PORT',
    'HOST',
    'SINCH_PROJECT_ID',
    'SINCH_KEY_ID',
    'SINCH_KEY_SECRET',
    'SINCH_REGION',
    'SINCH_NUMBER'
  ],
  properties: {
    PORT: { type: 'string', default: 3000 },
    HOST: { type: 'string', default: '0.0.0.0' },
    LOG_LEVEL: { type: 'string', default: 'info'},
    SINCH_PROJECT_ID: { type: 'string' },
    SINCH_KEY_ID: { type: 'string' },
    SINCH_KEY_SECRET: { type: 'string' },
    SINCH_REGION: { type: 'string' },
    SINCH_NUMBER: { type: 'string' } // Keep as string to preserve leading +
  },
  // Make NODE_ENV available if needed, with a default
  // NODE_ENV: { type: 'string', default: 'development' }
};

const envOptions = {
  confKey: 'config', // Access variables via `fastify.config`
  schema: envSchema,
  dotenv: true // Tells @fastify/env to load .env file(s) using dotenv
};


module.exports = async function (fastify, opts) {
  // Register @fastify/env FIRST to load and validate config
  // Other plugins/routes can then safely access fastify.config
  await fastify.register(fastifyEnv, envOptions);

  // Set logger level based on validated config
  // Do this early so subsequent logs respect the level
  fastify.log.level = fastify.config.LOG_LEVEL;

  // Standard Fastify setup
  // Place here your custom code! (e.g., other plugins like Helmet, Rate Limit)

  // Do not touch the following lines provided by fastify-cli

  // This loads all plugins defined in plugins
  // those should be support plugins that are reused
  // through your application
  fastify.register(AutoLoad, {
    dir: path.join(__dirname, 'plugins'),
    options: Object.assign({}, opts) // Pass opts, which now includes fastify.config
  })

  // This loads all plugins defined in routes
  // define your routes in one of these
  fastify.register(AutoLoad, {
    dir: path.join(__dirname, 'routes'),
    options: Object.assign({}, opts) // Pass opts, including fastify.config
  })

}

// Export the options for fastify-cli
module.exports.options = {
  // Pass logger options: https://getpino.io/#/docs/api?id=options
  // Use Fastify's default Pino logger, level set above from config
  logger: true
}

// services/sinchService.js
'use strict'

const { SinchClient } = require('@sinch/sdk-client');

// Note: For better testability and centralized logging/config,
// pass `fastify.log` and `fastify.config` into this service,
// perhaps during instantiation or via request decoration.
// This example accesses process.env directly for simplicity,
// assuming @fastify/env has already populated it via dotenv: true.

// Initialize Sinch Client using environment variables
// These should have been validated by @fastify/env already
const sinchClient = new SinchClient({
  projectId: process.env.SINCH_PROJECT_ID,
  keyId: process.env.SINCH_KEY_ID,
  keySecret: process.env.SINCH_KEY_SECRET,
  // The `region` parameter for the client might affect internal SDK defaults,
  // but explicitly setting the `baseUrl` in the API call (below) is often
  // the most reliable way to target the correct regional API endpoint.
});

/**
 * Sends an SMS message using the Sinch SDK.
 * @param {string} recipientPhoneNumber – The full recipient phone number in E.164 format (e.g., +15551234567).
 * @param {string} messageText – The text content of the SMS.
 * @param {object} [logger=console] – Optional logger instance (defaults to console). Pass request.log for contextual logging.
 * @returns {Promise<object&gt;} – An object containing success status and the result from the Sinch API (e.g., batch ID).
 * @throws {Error} – Throws an error if the SMS sending fails at the API level or due to configuration issues.
 */
async function sendSms(recipientPhoneNumber, messageText, logger = console) {
  const senderNumber = process.env.SINCH_NUMBER;
  const region = process.env.SINCH_REGION; // Used to construct the base URL

  // Basic validation (though route schema should catch most issues)
  if (!recipientPhoneNumber || !messageText) {
    throw new Error('Recipient phone number and message text are required.');
  }
  if (!senderNumber) {
    // This should ideally be caught by @fastify/env on startup
    logger.error('Sinch sender number (SINCH_NUMBER) is not configured.');
    throw new Error('Internal configuration error: Sinch sender number missing.');
  }
  if (!region) {
      // This should ideally be caught by @fastify/env on startup
      logger.error('Sinch region (SINCH_REGION) is not configured.');
      throw new Error('Internal configuration error: Sinch region missing.');
  }

  // Construct the correct base URL for the Sinch SMS API based on the region.
  // This is crucial for routing the request correctly.
  // Refer to Sinch documentation for exact regional endpoints:
  // https://developers.sinch.com/docs/sms/api-reference/
  const baseUrl = `https://${region}.sms.api.sinch.com`;

  logger.info(`Attempting to send SMS via Sinch from ${senderNumber} to ${recipientPhoneNumber} via region ${region} (${baseUrl})`);

  try {
    // Use the 'batches' endpoint for sending SMS via the SDK
    const response = await sinchClient.sms.batches.send(
        // smsSendBatchRequest payload:
        {
            to: [recipientPhoneNumber],
            from: senderNumber,
            body: messageText,
            // Optional parameters can be added here (e.g., delivery_report: 'summary', client_reference: 'your_unique_id')
        },
        // RequestOptions: Explicitly setting the `baseUrl` here overrides any SDK default
        // and ensures the request hits the correct regional API endpoint. This is recommended
        // as SDK behavior regarding the client's `region` parameter might vary.
        {
            baseUrl: baseUrl,
        }
    );

    // The exact structure of the success response might vary slightly based on SDK version.
    // Check the SDK documentation or log the response during development.
    // A `batch_id` is typically present on successful submission.
    logger.info({ sinchResponse: response }, 'Sinch API Response Received');

    if (response?.batch_id) {
      logger.info(`SMS batch submitted successfully. Batch ID: ${response.batch_id}`);
      // Return a consistent success object
      return { success: true, batchId: response.batch_id, details: response };
    } else {
      // This case might indicate an unexpected successful (e.g., 2xx) response format from Sinch
      logger.warn({ sinchResponse: response }, 'Sinch API response successful but missing expected batch_id.');
      // Treat as failure since we can't confirm the batch ID
      throw new Error('Sinch API response did not contain the expected batch_id.');
    }

  } catch (error) {
    // Log the detailed error from the Sinch SDK/API
    // error.response often contains details from the API response on HTTP errors
    logger.error({
        err: error,
        responseData: error?.response?.data,
        responseStatus: error?.response?.status
      },
      'Error sending SMS via Sinch'
    );

    // Re-throw a more context-specific error for the route handler to catch
    // Avoid leaking raw Sinch error details unless necessary/safe
    const errorMessage = error?.response?.data?.error?.text || // Sinch specific error text
                         error?.response?.data?.message ||      // General error message
                         error.message;                        // Fallback error message
    throw new Error(`Failed to send SMS via Sinch: ${errorMessage}`);
  }
}

module.exports = {
  sendSms
};

// routes/sms/index.js
'use strict'

const sinchService = require('../../services/sinchService'); // Adjust path if needed

// Schema for request body validation using Fastify's built-in JSON Schema support
const sendSmsBodySchema = {
  type: 'object',
  required: ['to', 'message'],
  properties: {
    to: {
      type: 'string',
      description: 'Recipient phone number in E.164 format (e.g., +15551234567)',
      // E.164 regex: Starts with +, then 1–9, then 1 to 14 digits.
      pattern: '^\\+[1-9]\\d{1,14}$'
    },
    message: {
      type: 'string',
      description: 'The text message content',
      minLength: 1,
      maxLength: 1600 // Max length for concatenated SMS; adjust as needed. GSM-7: ~10 segments (153×10 + 7 chars). UCS-2: ~24 segments (67×24 - 7 chars).
    }
  },
  additionalProperties: false // Disallow properties not defined in the schema
};

// Schema for the success response (2xx)
const successResponseSchema = {
  type: 'object',
  properties: {
    success: { type: 'boolean', const: true },
    message: { type: 'string' },
    batchId: { type: 'string', description: 'Sinch Batch ID for the sent message(s)' }
  }
};

// Schema for generic error responses (e.g., 4xx, 5xx)
const errorResponseSchema = {
    type: 'object',
    properties: {
        success: { type: 'boolean', const: false },
        message: { type: 'string' },
        // Optionally include error code or details in non-production environments
        // error: { type: 'string' }
    }
};

// Combine response schemas for documentation/validation
const sendSmsResponseSchema = {
  200: successResponseSchema, // Use specific code for success
  // Define schemas for expected error codes for better API contracts
  400: errorResponseSchema, // Validation errors (handled by Fastify)
  500: errorResponseSchema  // Server/Service errors
};


module.exports = async function (fastify, opts) {

  // Route definition with schema validation and response schema documentation
  fastify.post('/send', {
    schema: {
      description: 'Sends an SMS message via Sinch.',
      tags: ['sms'],
      summary: 'Send SMS',
      body: sendSmsBodySchema,
      response: sendSmsResponseSchema
    }
  }, async function (request, reply) {
    // `request.body` is automatically validated against `sendSmsBodySchema` by Fastify.
    // If validation fails, Fastify sends a 400 response automatically.
    const { to, message } = request.body;

    // Use the contextual logger from the request object
    const log = request.log;

    // Log securely – avoid logging full message content in production if sensitive
    log.info({ recipient: to }, `Received request to send SMS`);

    try {
      // Call the service function, passing the contextual logger
      const result = await sinchService.sendSms(to, message, log);

      // If sinchService.sendSms completes without throwing, assume success based on its contract.
      // The service already verified the presence of batchId or threw an error.
      log.info({ batchId: result.batchId }, 'SMS batch submitted successfully via Sinch');

      // Send a 200 OK response with the success payload
      return reply.code(200).send({
        success: true,
        message: 'SMS submitted successfully.',
        batchId: result.batchId
      });

    } catch (error) {
      // Catch errors thrown by sinchService.sendSms or other unexpected issues
      log.error({ err: error, recipient: to }, 'Error processing send SMS request');

      // Send a 500 Internal Server Error for unexpected failures
      // Avoid leaking sensitive internal error details to the client in production
      const errorMessage = (process.env.NODE_ENV !== 'production')
                           ? error.message
                           : 'Internal server error while attempting to send SMS.';

      return reply.code(500).send({
         success: false,
         message: errorMessage
      });
    }
  })
}

// services/sinchService.js – Conceptual Retry Addition
// Ensure you install: npm install async-retry
const retry = require('async-retry');
const crypto = require('node:crypto'); // For unique client_reference

// Modify sendSms or create a wrapper function
async function sendSmsWithRetry(recipientPhoneNumber, messageText, logger = console) {
  const uniqueMessageId = crypto.randomUUID(); // Generate unique ID for this message attempt
  logger.info({ clientReference: uniqueMessageId }, 'Generated client_reference for idempotency');

  return retry(
    async (bail, attemptNumber) => {
      // bail(error) is called to stop retrying on non-retryable errors
      // Throwing an error triggers a retry if attempts remain

      logger.info(`Attempt ${attemptNumber} to send SMS to ${recipientPhoneNumber} (Ref: ${uniqueMessageId})`);

      const senderNumber = process.env.SINCH_NUMBER;
      const region = process.env.SINCH_REGION;
      // Basic validation (should be done before retry ideally)
      if (!recipientPhoneNumber || !messageText || !senderNumber || !region) {
         const missingConfigError = new Error('Internal configuration error detected before sending.');
         logger.error(missingConfigError);
         bail(missingConfigError); // Stop retrying on config issues
         return; // Needed after bail
      }

      const baseUrl = `https://${region}.sms.api.sinch.com`;

      try {
        const response = await sinchClient.sms.batches.send(
          { // Payload
            to: [recipientPhoneNumber],
            from: senderNumber,
            body: messageText,
            client_reference: uniqueMessageId, // Use the same ID for all retries of this message
          },
          { // RequestOptions
            baseUrl: baseUrl,
          }
        );

        logger.info({ sinchResponse: response, attempt: attemptNumber }, 'Sinch API Response Received');
        if (response?.batch_id) {
          logger.info(`SMS batch submitted successfully on attempt ${attemptNumber}. Batch ID: ${response.batch_id}`);
          return { success: true, batchId: response.batch_id, details: response };
        } else {
          logger.warn({ sinchResponse: response, attempt: attemptNumber }, 'Sinch API response successful but missing batch_id.');
          // Treat as potentially retryable internal issue or unexpected format
          throw new Error('Sinch API response did not contain expected batch_id.');
        }

      } catch (error) {
        const statusCode = error?.response?.status;
        logger.warn({ err: error, status: statusCode, attempt: attemptNumber }, `Attempt ${attemptNumber} failed`);

        // Decide if error is retryable
        if (statusCode === 429 || (statusCode >= 500 && statusCode <= 599)) {
          logger.info(`Retrying due to status code ${statusCode}…`);
          throw error; // Throw error to trigger retry by async-retry
        } else {
          // Don't retry on other errors (4xx client errors_ config errors_ etc.)
          logger.error(`Not retrying for status code ${statusCode || 'N/A'}. Bailing.`);
          bail(error); // Stop retrying and pass the error up
          // Note: bail() throws the error passed to it_ so no explicit throw needed here.
        }
      }
    }_
    { // async-retry options
      retries: 3_          // Number of retries (total attempts = retries + 1)
      factor: 2_           // Exponential backoff factor
      minTimeout: 1000_    // Minimum delay in ms
      maxTimeout: 5000_    // Maximum delay in ms
      onRetry: (error_ attemptNumber) => {
        logger.warn(`Retrying SMS send (attempt ${attemptNumber}). Error: ${error.message}`);
      },
    }
  );
}

// Remember to update the route handler to call sendSmsWithRetry instead of sendSms
// And update the module exports if needed
// module.exports = { sendSms: sendSmsWithRetry }; // Or export both
module.exports = { sendSms, sendSmsWithRetry }; // Example: export both