Send WhatsApp Messages with Sinch API in Node.js using Fastify

+-----------------+       +----------------------+       +-----------------+       +----------+
| Your Application|------>| Fastify Backend     |<----->| Sinch API       |<----->| WhatsApp |
| (e.g., Frontend)|       | (Node.js, Sinch SDK)|       | (Conversation API)|       | Platform |
+-----------------+       +----------------------+       +-----------------+       +----------+
                           ^     | Webhook Call         ^     | Message Delivery
                           |     v                      |     v
                           +-----+----------------------+-----+
                                 | Incoming Message Notification
                                 | (WhatsApp -> Sinch -> ngrok -> Fastify)

// src/services/sinch.ts (or sinch.js)
import SinchClient from "@sinch/sdk-core";
import dotenv from 'dotenv';

dotenv.config(); // Load environment variables

// Ensure required environment variables are set
const requiredEnvVars = [
  'SINCH_PROJECT_ID',
  'SINCH_KEY_ID',
  'SINCH_KEY_SECRET',
  'SINCH_APP_ID',
  'WHATSAPP_SENDER_ID',
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    console.error(`Error: Environment variable ${envVar} is not set.`);
    process.exit(1); // Exit if critical config is missing
  }
}

// Initialize Sinch Client
const sinchClient = new SinchClient({
  projectId: process.env.SINCH_PROJECT_ID!,
  keyId: process.env.SINCH_KEY_ID!,
  keySecret: process.env.SINCH_KEY_SECRET!,
});

/**
 * Sends a WhatsApp text message via the Sinch Conversation API.
 * @param recipientPhoneNumber - The recipient's phone number in E.164 format (e.g., 12223334444).
 * @param textContent - The content of the text message.
 * @returns The Sinch message ID if successful.
 * @throws Error if the message sending fails.
 */
export const sendWhatsAppTextMessage = async (
  recipientPhoneNumber: string,
  textContent: string
): Promise<string | undefined&gt; =&gt; {
  console.log(`Attempting to send message to: ${recipientPhoneNumber}`);
  try {
    const response = await sinchClient.conversationApi.message.send({
      app_id: process.env.SINCH_APP_ID!,
      message: {
        channel_identity: {
          channel: 'WHATSAPP',
          identity: process.env.WHATSAPP_SENDER_ID!, // Your Sinch WhatsApp Number
        },
        content: {
          text_message: {
            text: textContent,
          },
        },
      },
      recipient: {
        contact_id: `waid:${recipientPhoneNumber}`, // Use 'waid:' prefix for WhatsApp ID
      },
    });

    console.log('Sinch send message response:', response);
    if (response.accepted_message_id) {
      console.log(`Message successfully sent with ID: ${response.accepted_message_id}`);
      return response.accepted_message_id;
    } else {
      // Handle cases where the message might be rejected immediately (though less common)
      console.error('Message sending accepted but no message ID returned.', response);
      throw new Error('Sinch API accepted the request but did not return a message ID.');
    }
  } catch (error: any) {
    console.error('Error sending WhatsApp message via Sinch:');
    // Log detailed error information if available
    if (error.response) {
      console.error('Status:', error.response.status);
      console.error('Headers:', error.response.headers);
      console.error('Data:', error.response.data);
    } else {
      console.error('Error message:', error.message);
    }
    // Rethrow or handle the error appropriately for the calling function
    throw new Error(`Failed to send WhatsApp message: ${error.message}`);
  }
};

// Add functions for other message types (images, templates) as needed.
// Example: sendWhatsAppTemplateMessage, sendWhatsAppImageMessage etc.

// src/server.ts (or server.js)
import Fastify, { FastifyRequest, FastifyReply } from 'fastify';
import dotenv from 'dotenv';
import webhookRoutes from './routes/webhooks'; // Import webhook routes

dotenv.config();

const server = Fastify({
  logger: true, // Enable built-in Pino logger
});

// --- Add Raw Body Access (Needed for Signature Verification) ---
// This is crucial because Fastify parses the body by default *before* the handler.
// Signature verification needs the *raw*, unparsed body string.
// Option 1: Using a plugin (if available/needed)
// import fastifyRawBody from 'fastify-raw-body';
// server.register(fastifyRawBody, {
//   field: 'rawBody', // field name accessible in request object
//   global: false, // apply only to routes that need it
//   encoding: 'utf8', // set it to utf8 to get string right away
//   runFirst: true // ensure it runs before Fastify's parser
// });
// Option 2: Using Fastify's built-in capabilities (v3/v4+)
// Add a content type parser to store the raw body before JSON parsing
// Note: This approach might require careful ordering or route-specific config.
// server.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
//   try {
//     req.rawBody = body; // Store raw body
//     const json = JSON.parse(body as string); // Parse JSON
//     done(null, json);
//   } catch (err: any) {
//     err.statusCode = 400;
//     done(err, undefined);
//   }
// });
// **For this guide, we'll assume rawBody is made available via one of these methods.**
// **The verifySinchSignature function will expect `request.rawBody`.**

// --- Global Error Handler ---
// Catches unhandled errors in routes
server.setErrorHandler((error: Error, request: FastifyRequest, reply: FastifyReply) => {
  server.log.error(error); // Log the full error

  // Send a generic error response to the client
  // Avoid leaking sensitive error details in production
  reply.status(500).send({
    statusCode: 500,
    error: 'Internal Server Error',
    message: 'An unexpected error occurred.',
  });
});

// --- Register Routes ---
server.register(webhookRoutes, { prefix: '/webhooks' }); // Register webhook routes under /webhooks

// --- Health Check Route ---
server.get('/health', async (request, reply) => {
  return { status: 'ok', timestamp: new Date().toISOString() };
});

// --- Start Server ---
const start = async () => {
  try {
    const port = parseInt(process.env.PORT || '8000', 10);
    const host = process.env.HOST || '0.0.0.0';
    await server.listen({ port, host });
    server.log.info(`Server listening on http://${host}:${port}`);
    server.log.info(`Webhook endpoint available at /webhooks/inbound`);
    server.log.info(`Webhook status endpoint available at /webhooks/status`);
    server.log.info(`Make sure ngrok forwards to this port.`);
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
};

start();

// src/routes/webhooks.ts (or webhooks.js)
import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
import crypto from 'crypto';
import { sendWhatsAppTextMessage } from '../services/sinch'; // Import the sending function

// --- Type Definitions (Recommended Best Practice) ---
// Define interfaces for expected Sinch payloads for better type safety.
// These are examples; refer to Sinch docs for exact structures.
interface SinchMessageContent {
    text_message?: { text: string };
    // Add other content types (media_message, etc.) as needed
}

interface SinchContactMessage {
    sender_id?: string; // e.g., ""waid:1234567890""
    // Add other fields if needed
}

interface SinchInboundMessage {
    contact_message?: SinchContactMessage;
    content?: SinchMessageContent;
    // Add other fields from the inbound message payload
}

interface SinchDeliveryReport {
    message_id?: string;
    status?: 'DELIVERED' | 'FAILED' | 'QUEUED' | 'SENT' | 'READ'; // Example statuses
    reason?: string;
    // Add other fields from the delivery report payload
}

interface SinchWebhookPayload {
    event: 'MESSAGE_INBOUND' | 'MESSAGE_DELIVERY' | string; // Allow other event types
    app_id?: string;
    timestamp?: string; // ISO 8601 format
    message?: SinchInboundMessage;
    message_delivery_report?: SinchDeliveryReport;
    // Add other potential top-level fields
}

// --- Helper: Verify Sinch Webhook Signature ---
// IMPORTANT: Use the ""Application Secret"" from your Sinch App settings
// This function now assumes request.rawBody contains the raw request body string.
// Ensure rawBody is populated correctly in server.ts (see comments there).
const verifySinchSignature = (request: FastifyRequest & { rawBody?: string }): boolean => {
  const sinchSignature = request.headers['x-sinch-signature'] as string;
  const timestamp = request.headers['x-sinch-timestamp'] as string;
  const applicationSecret = process.env.SINCH_APPLICATION_SECRET;
  const requestBody = request.rawBody; // Use the raw body string

  if (!sinchSignature || !timestamp || !applicationSecret) {
    request.log.warn('Missing signature headers or application secret for webhook validation.');
    return false;
  }

  // Check if rawBody is available
  if (typeof requestBody !== 'string') {
      request.log.error('Raw request body is not available for signature verification. Ensure it is populated before this handler.');
      // If Sinch *does* sign the stringified JSON (less common), you might revert to:
      // const requestBody = JSON.stringify(request.body);
      // But this needs confirmation based on Sinch's signing method.
      return false;
  }

  // 1. Construct the string to sign: raw_request_body + timestamp
  const stringToSign = requestBody + timestamp;

  // 2. Calculate the HMAC-SHA256 hash
  const hmac = crypto.createHmac('sha256', applicationSecret);
  const calculatedSignature = hmac.update(stringToSign).digest('base64');

  // 3. Compare calculated signature with the one from the header
  if (calculatedSignature !== sinchSignature) {
    request.log.warn(`Signature mismatch. Calculated: ${calculatedSignature}, Received: ${sinchSignature}`);
    // Log parts of the stringToSign for debugging if needed, be careful with sensitive data
    // request.log.debug(`String signed: ${stringToSign.substring(0, 100)}... Timestamp: ${timestamp}`);
    return false;
  }

  // Optional: Check timestamp validity to prevent replay attacks
  // Sinch timestamp is usually ISO 8601 string (e.g., ""2023-10-27T10:00:00.123Z"")
  // Or sometimes Unix epoch seconds string. Adapt parsing as needed.
  let requestTimestampSeconds: number;
  try {
    // Attempt parsing as ISO 8601 date string first
    const requestDate = new Date(timestamp);
    if (isNaN(requestDate.getTime())) {
        // If not a valid date string, try parsing as Unix epoch seconds
        requestTimestampSeconds = parseInt(timestamp, 10);
        if (isNaN(requestTimestampSeconds)) {
            throw new Error('Timestamp is not a valid ISO 8601 date string or Unix epoch seconds.');
        }
    } else {
        requestTimestampSeconds = Math.floor(requestDate.getTime() / 1000);
    }
  } catch (e: any) {
      request.log.warn(`Could not parse timestamp '${timestamp}': ${e.message}`);
      return false; // Invalid timestamp format
  }

  const currentTimestampSeconds = Math.floor(Date.now() / 1000);
  const fiveMinutesInSeconds = 5 * 60;

  if (Math.abs(currentTimestampSeconds - requestTimestampSeconds) > fiveMinutesInSeconds) {
     request.log.warn(`Timestamp validation failed. Request time (epoch sec): ${requestTimestampSeconds}, Current time (epoch sec): ${currentTimestampSeconds}. Difference > 5 minutes.`);
     return false; // Or handle as potentially stale but valid signature if needed
  }


  request.log.info('Sinch webhook signature verified successfully.');
  return true;
};

// --- Define Webhook Routes ---
async function webhookRoutes(fastify: FastifyInstance) {

  // Endpoint for INCOMING messages from users
  fastify.post('/inbound', async (request: FastifyRequest, reply: FastifyReply) => {
    fastify.log.info('Received POST request on /webhooks/inbound');
    // Avoid logging raw body in production unless necessary for debugging specific issues,
    // as it might contain sensitive information. Log parsed body instead if needed.
    fastify.log.info({ headers: request.headers }, 'Request Headers');
    // fastify.log.info({ rawBody: (request as any).rawBody }, 'Raw Request Body'); // If rawBody is attached
    fastify.log.info({ body: request.body }, 'Parsed Request Body');

    // 1. Verify Signature (SECURITY CRITICAL)
    // Cast request type assertion to include rawBody if using that approach
    if (!verifySinchSignature(request as FastifyRequest & { rawBody?: string })) {
      fastify.log.error('Invalid webhook signature received.');
      return reply.status(403).send({ error: 'Forbidden', message: 'Invalid signature.' });
    }

    // 2. Process the webhook payload
    // Using the defined interface for better type checking.
    const payload = request.body as SinchWebhookPayload;

    if (payload.event === 'MESSAGE_INBOUND' && payload.message) {
      const message = payload.message;
      const sender = message.contact_message?.sender_id; // Extract sender ID (e.g., waid:12223334444)
      const content = message.content?.text_message?.text; // Extract text content

      if (sender && content) {
        fastify.log.info(`Received message from ${sender}: ""${content}""`);

        // Example: Simple echo bot logic
        try {
          // Extract phone number from sender_id (remove 'waid:')
          const recipientPhoneNumber = sender.replace(/^waid:/, '');
          await sendWhatsAppTextMessage(recipientPhoneNumber, `You said: ""${content}""`);
          fastify.log.info(`Sent echo reply to ${recipientPhoneNumber}`);
        } catch (error) {
           fastify.log.error(error, 'Failed to send echo reply');
           // Decide if you need to signal an error back to Sinch (usually 200 OK is still preferred)
        }

      } else {
        fastify.log.warn('Received MESSAGE_INBOUND but could not parse sender or content.');
      }
    // Removed MESSAGE_DELIVERY handling from here - it belongs in /status
    // } else if (payload.event === 'MESSAGE_DELIVERY') { ... }
    } else {
      fastify.log.warn(`Received unhandled webhook event type on /inbound: ${payload.event ?? 'Unknown'}`);
    }

    // 3. Acknowledge Receipt
    // Always send a 200 OK quickly to Sinch to prevent retries.
    // Process the message asynchronously if needed.
    reply.status(200).send({ message: 'Webhook received successfully.' });
  });

  // Endpoint for message STATUS updates (Delivery reports, failures etc.)
  // Configure this URL in your Sinch App settings as well.
  fastify.post('/status', async (request: FastifyRequest, reply: FastifyReply) => {
      fastify.log.info('Received POST request on /webhooks/status');
      fastify.log.info({ headers: request.headers }, 'Request Headers');
      fastify.log.info({ body: request.body }, 'Parsed Request Body');

      // 1. Verify Signature (SECURITY CRITICAL)
      if (!verifySinchSignature(request as FastifyRequest & { rawBody?: string })) {
        fastify.log.error('Invalid webhook signature received for status update.');
        return reply.status(403).send({ error: 'Forbidden', message: 'Invalid signature.' });
      }

      // 2. Process the status payload
      const payload = request.body as SinchWebhookPayload;

      if (payload.event === 'MESSAGE_DELIVERY' && payload.message_delivery_report) {
          const report = payload.message_delivery_report;
          const status = report.status;
          const messageId = report.message_id;
          const reason = report.reason; // If failed

          if (messageId && status) {
             fastify.log.info(`Received delivery status via /status for message ${messageId}: ${status} ${reason ? `(Reason: ${reason})` : ''}`);
             // Update message status in your database here using messageId, status, and reason
             // Example: await updateMessageStatus(messageId, status, undefined, reason);
          } else {
             fastify.log.warn('Received MESSAGE_DELIVERY status but messageId or status was missing.', report);
          }
      } else {
          fastify.log.warn(`Received unhandled event type on /status: ${payload.event ?? 'Unknown'}`);
      }

      // 3. Acknowledge Receipt
      reply.status(200).send({ message: 'Status webhook received successfully.' });
  });

}

export default webhookRoutes;