mkdir fastify-messagebird-whatsapp
cd fastify-messagebird-whatsapp

npm init -y

npm install fastify @messagebird/api dotenv @fastify/env

npm install --save-dev pino-pretty

{
  // ... other configurations
  "main": "src/server.js", // Specify entry point
  "scripts": {
    "start": "node src/server.js",
    "dev": "node src/server.js | pino-pretty" // Use pino-pretty for development
  },
  // ... other configurations
}

fastify-messagebird-whatsapp/
├── node_modules/
├── src/
│   ├── app.js         # Fastify application setup (plugins, routes)
│   ├── server.js      # Server instantiation and startup logic
│   └── routes/
│       └── whatsapp.js  # Routes related to WhatsApp actions
├── .env             # Local environment variables (DO NOT COMMIT)
├── .env.example     # Example environment variables (Commit this)
├── .gitignore       # Files/folders to ignore in Git
└── package.json

mkdir src
mkdir src/routes

# .gitignore

# Dependencies
node_modules/

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

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

# Build outputs
dist/
build/

# OS generated files
.DS_Store
Thumbs.db

# .env.example

# Server Configuration
PORT=3000
HOST=0.0.0.0

# MessageBird API Credentials
# Get from MessageBird Dashboard -> Developers -> API access
MESSAGEBIRD_API_KEY=YOUR_MESSAGEBIRD_LIVE_API_KEY

# MessageBird WhatsApp Channel Configuration
# Get from MessageBird Dashboard -> Channels -> WhatsApp -> Select Channel -> Copy Channel ID
MESSAGEBIRD_WHATSAPP_CHANNEL_ID=YOUR_WHATSAPP_CHANNEL_ID

# MessageBird Webhook Configuration
# Get when setting up the webhook in MessageBird Dashboard (Channels -> WhatsApp -> Edit -> Webhooks)
MESSAGEBIRD_WEBHOOK_SIGNING_KEY=YOUR_WEBHOOK_SIGNING_KEY

# (Optional) Custom secret for additional webhook verification layer if needed
# WEBHOOK_SECRET=YOUR_CUSTOM_WEBHOOK_SECRET

# .env - Keep this file secure and out of Git!

PORT=3000
HOST=0.0.0.0
MESSAGEBIRD_API_KEY=live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
MESSAGEBIRD_WHATSAPP_CHANNEL_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
MESSAGEBIRD_WEBHOOK_SIGNING_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# WEBHOOK_SECRET=a-very-strong-secret-if-used

// src/server.js
'use strict';

// Read the .env file.
require('dotenv').config();

const buildApp = require('./app');

const start = async () => {
  let app;
  try {
    // Build the Fastify app instance (registers plugins, routes)
    app = await buildApp({
      // Pass logger options suitable for production/development
      logger: {
        level: process.env.LOG_LEVEL || 'info',
        // Use pino-pretty only if explicitly enabled (e.g., not in production)
        transport: process.env.NODE_ENV !== 'production'
          ? { target: 'pino-pretty' }
          : undefined,
      },
    });

    // Start listening
    await app.listen({
      port: app.config.PORT, // Use validated port from @fastify/env
      host: app.config.HOST, // Use validated host from @fastify/env
    });

    // Optional: Log registered routes on startup (useful for debugging)
    // console.log(app.printRoutes());

  } catch (err) {
    if (app) {
      app.log.error(err);
    } else {
      console.error('Error during server startup:', err);
    }
    process.exit(1);
  }
};

start();

// src/app.js
'use strict';

const Fastify = require('fastify');
const fastifyEnv = require('@fastify/env');
const whatsappRoutes = require('./routes/whatsapp');

// Define the schema for environment variables
// See: https://github.com/fastify/fastify-env
const envSchema = {
  type: 'object',
  required: [
    'PORT',
    'HOST',
    'MESSAGEBIRD_API_KEY',
    'MESSAGEBIRD_WHATSAPP_CHANNEL_ID',
    'MESSAGEBIRD_WEBHOOK_SIGNING_KEY',
  ],
  properties: {
    PORT: { type: 'number', default: 3000 },
    HOST: { type: 'string', default: '0.0.0.0' },
    MESSAGEBIRD_API_KEY: { type: 'string' },
    MESSAGEBIRD_WHATSAPP_CHANNEL_ID: { type: 'string' },
    MESSAGEBIRD_WEBHOOK_SIGNING_KEY: { type: 'string' },
    // WEBHOOK_SECRET: { type: 'string' } // Uncomment if using custom secret
  },
};

async function buildApp(opts = {}) {
  const app = Fastify(opts);

  // Register @fastify/env to validate and load .env variables
  await app.register(fastifyEnv, {
    confKey: 'config', // Access variables via app.config
    schema: envSchema,
    dotenv: true, // Load .env file
  });

  // Initialize MessageBird SDK - makes it available across the app
  // We attach it to the Fastify instance for easy access in routes
  try {
    const messagebird = require('@messagebird/api')(app.config.MESSAGEBIRD_API_KEY);
    app.decorate('messagebird', messagebird);
    app.log.info('MessageBird SDK initialized successfully.');
  } catch (err) {
    app.log.error('Failed to initialize MessageBird SDK:', err);
    throw new Error('MessageBird SDK initialization failed.'); // Prevent startup if SDK fails
  }

  // Register routes
  app.register(whatsappRoutes, { prefix: '/api/whatsapp' }); // Prefix routes with /api/whatsapp

  // Basic root route
  app.get('/', async (request, reply) => {
    return { status: 'ok', timestamp: new Date().toISOString() };
  });

  // Add a health check endpoint (useful for monitoring)
  app.get('/health', async (request, reply) => {
    // Add more sophisticated checks if needed (e.g., DB connection)
    return { status: 'ok' };
  });

  return app;
}

module.exports = buildApp;

// src/routes/whatsapp.js
'use strict';

const crypto = require('crypto');

// Schema for the /send endpoint body validation
const sendMessageSchema = {
  body: {
    type: 'object',
    required: ['to', 'text'],
    properties: {
      to: {
        type: 'string',
        description: 'Recipient WhatsApp number in E.164 format (e.g., +14155552671)',
        // Example pattern - adjust if needed for stricter validation
        pattern: '^\\+[1-9]\\d{1,14}$'
      },
      text: {
        type: 'string',
        minLength: 1,
        description: 'The text message content',
      },
    },
  },
  response: {
    200: {
      type: 'object',
      properties: {
        status: { type: 'string' },
        messageId: { type: 'string' },
        details: { type: 'object' } // Include raw response for debugging if needed
      }
    },
    // Add schemas for error responses if desired
  }
};

// --- Webhook Verification Logic ---
// IMPORTANT: This function MUST use the RAW request body, BEFORE JSON parsing.
function verifyMessageBirdWebhook(request, reply, rawBody) {
  const server = request.server; // Access Fastify instance (app)
  const signature = request.headers['messagebird-signature-key'];
  const timestamp = request.headers['messagebird-request-timestamp'];
  const signingKey = server.config.MESSAGEBIRD_WEBHOOK_SIGNING_KEY;

  // 1. Check if headers are present
  if (!signature || !timestamp) {
    server.log.warn('Webhook received without required MessageBird headers.');
    reply.code(400).send({ error: 'Missing MessageBird signature headers' });
    return false; // Indicate verification failed
  }

  // 2. Construct the string to sign
  // Format: timestamp + '|' + rawBody
  const signedPayload = `${timestamp}|${rawBody.toString('utf-8')}`; // Ensure body is string

  // 3. Calculate the expected signature
  const expectedSignature = crypto
    .createHmac('sha256', signingKey)
    .update(signedPayload)
    .digest('hex');

  // 4. Compare signatures using a timing-safe method
  try {
    // Ensure buffers have the same length for timingSafeEqual
    const signatureBuffer = Buffer.from(signature, 'hex');
    const expectedBuffer = Buffer.from(expectedSignature, 'hex');

    if (signatureBuffer.length !== expectedBuffer.length) {
        server.log.warn('Webhook signature length mismatch.');
        reply.code(401).send({ error: 'Invalid signature' });
        return false;
    }

    const isValid = crypto.timingSafeEqual(signatureBuffer, expectedBuffer);

    if (!isValid) {
      server.log.warn('Webhook signature validation failed.');
      reply.code(401).send({ error: 'Invalid signature' });
      return false;
    }

  } catch (error) {
      server.log.error({ err: error }, 'Error during signature comparison.');
      reply.code(500).send({ error: 'Internal server error during verification' });
      return false;
  }

  server.log.info('Webhook signature verified successfully.');
  return true; // Indicate verification succeeded
}
// --- End Webhook Verification Logic ---


async function whatsappRoutes(fastify, options) {

  const { messagebird, config, log } = fastify; // Access decorated SDK, config, logger

  // === Endpoint to SEND a WhatsApp message ===
  fastify.post('/send', { schema: sendMessageSchema }, async (request, reply) => {
    const { to, text } = request.body;
    const channelId = config.MESSAGEBIRD_WHATSAPP_CHANNEL_ID;

    const params = {
      to: to,
      from: channelId, // Use Channel ID as the 'from'
      type: 'text',
      content: {
        text: text,
      },
      // Optional: Track message status via webhooks
      // reportUrl: 'YOUR_STATUS_WEBHOOK_URL' // Define another webhook for status updates
    };

    log.info(`Attempting to send WhatsApp message to ${to} via channel ${channelId}`);

    try {
      // Use the MessageBird SDK's conversation API
      // Ref: https://developers.messagebird.com/api/conversations/#send-message
      const result = await messagebird.conversations.send(params);

      log.info({ msgId: result.id, status: result.status }, `Message sent successfully to ${to}`);

      return reply.code(200).send({
        status: 'success',
        messageId: result.id, // Return MessageBird message ID
        details: result, // Optionally return full response
      });

    } catch (error) {
      log.error({ err: error, recipient: to }, 'Failed to send WhatsApp message via MessageBird');

      // Extract more specific error details if available
      const errorDetails = error.response?.body?.errors || [{ description: error.message }];

      // Determine appropriate status code (e.g., 400 for bad input, 500/503 for provider issues)
      const statusCode = error.statusCode && error.statusCode >= 400 && error.statusCode < 500 ? error.statusCode : 500;

      return reply.code(statusCode).send({
        status: 'error'_
        message: 'Failed to send message'_
        errors: errorDetails_
      });
    }
  });


  // === Endpoint to RECEIVE WhatsApp messages (Webhook) ===
  // IMPORTANT: We need the raw body for signature verification.
  // We configure Fastify to NOT parse JSON for this specific route initially.
  fastify.addContentTypeParser('application/json'_ { parseAs: 'buffer' }_ (req_ body_ done) => {
     // We'll parse JSON manually *after* verification if needed
     done(null, body);
  });

  fastify.post('/webhook', {
    // No body schema here initially, as we need the raw buffer first
    config: {
      // Optional: Add specific config for this route if needed
    }
  }, async (request, reply) => {
    const rawBody = request.body; // This is a Buffer due to the content type parser

    // 1. Verify the signature FIRST
    const isVerified = verifyMessageBirdWebhook(request, reply, rawBody);
    if (!isVerified) {
      // verifyMessageBirdWebhook already sent the reply on failure
      return;
    }

    // 2. Signature is valid, now parse the JSON payload
    let payload;
    try {
      payload = JSON.parse(rawBody.toString('utf-8'));
    } catch (error) {
      log.error({ err: error }, 'Failed to parse webhook JSON payload after verification.');
      return reply.code(400).send({ error: 'Invalid JSON payload' });
    }

    // 3. Process the valid webhook payload
    log.info({ webhookPayload: payload }, 'Received and verified MessageBird webhook');

    // Example: Log message details
    // Structure depends on the MessageBird webhook event type (e.g., message.created, message.updated)
    // Ref: https://developers.messagebird.com/api/conversations/#receiving-messages-and-status-updates
    if (payload.type === 'message.created' && payload.message) {
      const message = payload.message;
      log.info(`Received message type: ${message.type} from: ${message.from} content: ${JSON.stringify(message.content)}`);

      // --- Add your business logic here ---
      // - Store the message in a database
      // - Trigger a response based on content
      // - Forward to another service
      // Example: Echo back the text message (for testing)
      // if (message.type === 'text' && message.direction === 'received') {
      //   try {
      //      await messagebird.conversations.reply(payload.conversation.id, {
      //        type: 'text',
      //        content: { text: `You said: ${message.content.text}` }
      //      });
      //      log.info(`Sent echo reply to ${message.from}`);
      //   } catch (replyError) {
      //      log.error({ err: replyError }, 'Failed to send echo reply');
      //   }
      // }
      // ------------------------------------

    } else {
      log.info(`Received webhook event type: ${payload.type}`);
      // Handle other event types if necessary (e.g., message status updates)
    }

    // 4. Acknowledge the webhook receipt quickly
    // MessageBird expects a 200 OK response.
    return reply.code(200).send({ status: 'received' });
  });

  // Remove the custom parser after registering webhook route so it doesn't affect others
  fastify.restoreContentTypeParser('application/json');

}

module.exports = whatsappRoutes;

// Example using async-retry (install: npm install async-retry)
// Inside the /send route handler:

const retry = require('async-retry');

// ... inside the try block of /send handler

try {
  const result = await retry(
    async (bail, attemptNumber) => {
      log.info(`Attempt ${attemptNumber} to send message to ${to}`);
      const mbResult = await messagebird.conversations.send(params);
      log.info({ msgId: mbResult.id, status: mbResult.status }, `Message sent successfully on attempt ${attemptNumber}`);
      return mbResult; // Return result on success
    },
    {
      retries: 3, // Number of retries (total attempts = retries + 1)
      factor: 2, // Exponential backoff factor
      minTimeout: 1000, // Initial delay ms
      maxTimeout: 5000, // Max delay ms
      onRetry: (error, attemptNumber) => {
        log.warn({ err: error, attempt: attemptNumber }, `Retry attempt ${attemptNumber} failed for recipient ${to}. Retrying...`);
        // Use bail() to stop retrying for non-recoverable errors (e.g., 4xx client errors)
        if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
           log.error(`Non-recoverable error (status ${error.statusCode}) sending to ${to}. Aborting retries.`);
           bail(error); // Stop retrying
        }
      }
    }
  );

  // The rest of the success handling...
  log.info({ msgId: result.id_ status: result.status }_ `Message sent successfully to ${to}`);
  return reply.code(200).send({
    status: 'success'_
    messageId: result.id_
    details: result_
  });

} catch (error) {
  // This catch block now catches errors after all retries fail or if bail() is called.
  log.error({ err: error_ recipient: to }_ 'Failed to send WhatsApp message via MessageBird after retries');
  const errorDetails = error.response?.body?.errors || [{ description: error.message }];
  const statusCode = error.statusCode && error.statusCode >= 400 && error.statusCode < 500 ? error.statusCode : 500;
  return reply.code(statusCode).send({
    status: 'error',
    message: 'Failed to send message',
    errors: errorDetails,
  });
}
// ... rest of the route handler logic if any ...

CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    messagebird_conversation_id VARCHAR(255) UNIQUE, -- MessageBird's ID
    whatsapp_contact_id VARCHAR(255) NOT NULL,    -- End user's WhatsApp ID (e.g., +1415...)
    last_message_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
    messagebird_message_id VARCHAR(255) UNIQUE, -- MessageBird's ID for this message
    direction VARCHAR(10) NOT NULL CHECK (direction IN ('sent', 'received')), -- 'sent' or 'received' from app's perspective
    sender_id VARCHAR(255) NOT NULL,       -- Could be Channel ID or User WhatsApp ID
    recipient_id VARCHAR(255) NOT NULL,    -- Could be User WhatsApp ID or Channel ID
    message_type VARCHAR(50) NOT NULL,     -- 'text', 'image', 'audio', 'template', etc.
    content JSONB,                         -- Store message content (text, media URLs, etc.)
    status VARCHAR(50),                    -- 'pending', 'sent', 'delivered', 'read', 'failed' (from status webhooks)
    messagebird_created_at TIMESTAMPTZ,     -- Timestamp provided by MessageBird in the payload (message creation time)
    status_updated_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW()   -- Timestamp when the record was created in *our* database
);

-- Indexes for common lookups
CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
CREATE INDEX idx_messages_messagebird_message_id ON messages(messagebird_message_id);
CREATE INDEX idx_conversations_whatsapp_contact_id ON conversations(whatsapp_contact_id);