Developer Guide: Integrating MessageBird WhatsApp with Next.js and Node.js

+-----------------+      +---------------------+      +-----------------+      +----------+
| User/Client App |----->| Next.js Application |----->| MessageBird API |----->| WhatsApp |
| (Browser/API)   |      | (API Routes)        |<-----| (Webhooks)      |<-----|          |
+-----------------+      +---------------------+      +-----------------+      +----------+
                         |                     |
                         | (Optional)          |
                         | +-----------------+ |
                         | | Database        | |
                         | | (Prisma)        | |
                         | +-----------------+ |
                         +---------------------+

npx create-next-app@latest messagebird-whatsapp-nextjs --typescript --eslint --tailwind --src-dir --app --import-alias "@/*"
cd messagebird-whatsapp-nextjs

npm install messagebird dotenv
# Optional: Install Prisma for database logging (Prisma 6.7.0+ compatible with Next.js 15.3.1+)
npm install prisma @prisma/client
# Optional: Initialize Prisma (choose your database provider)
npx prisma init --datasource-provider postgresql # or sqlite_ mysql_ etc.

# .env.local

# MessageBird Credentials (Get from MessageBird Dashboard -> Developers -> API Access)
MESSAGEBIRD_API_KEY="YOUR_LIVE_OR_TEST_API_KEY"

# MessageBird WhatsApp Channel ID (Get from MessageBird Dashboard -> Channels -> WhatsApp -> Your Channel)
MESSAGEBIRD_CHANNEL_ID="YOUR_WHATSAPP_CHANNEL_ID"

# MessageBird Webhook Signing Secret (Generate/Get from Webhook settings in MessageBird Dashboard)
MESSAGEBIRD_WEBHOOK_SECRET="YOUR_WEBHOOK_SIGNING_SECRET"

# (Optional) Database URL for Prisma
# Example for PostgreSQL using Docker Compose (see section 6)
DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"
# Example for SQLite
# DATABASE_URL="file:./dev.db"

# Base URL for your deployed application (needed for setting the webhook)
# For local development with ngrok, this might be like: https://xxxxx.ngrok-free.app
# For production, it will be your domain: https://yourapp.com
NEXT_PUBLIC_APP_URL="http://localhost:3000" # Default, update as needed

messagebird-whatsapp-nextjs/
├── src/
│   ├── app/
│   │   ├── api/                    # API Routes
│   │   │   ├── send-whatsapp/      # Endpoint for sending messages
│   │   │   │   └── route.ts
│   │   │   ├── messagebird-webhook/ # Endpoint for receiving messages
│   │   │   │   └── route.ts
│   │   │   └── health/             # Basic health check
│   │   │       └── route.ts
│   │   ├── page.tsx                # Example frontend page (optional)
│   │   └── layout.tsx
│   ├── lib/                        # Utility functions/SDK initialization
│   │   ├── messagebird.ts
│   │   └── prisma.ts              # (Optional) Prisma client instance
│   └── ... (other Next.js files)
├── prisma/                         # (Optional) Prisma schema and migrations
│   └── schema.prisma
├── .env.local                      # Environment variables (DO NOT COMMIT)
├── next.config.mjs
├── package.json
└── tsconfig.json

// src/lib/messagebird.ts
import messagebird from 'messagebird';

// Ensure environment variable is loaded (though Next.js handles .env.local automatically)
if (!process.env.MESSAGEBIRD_API_KEY) {
  throw new Error("Missing MESSAGEBIRD_API_KEY environment variable");
}

const mbClient = messagebird(process.env.MESSAGEBIRD_API_KEY);

export default mbClient;

// src/app/api/send-whatsapp/route.ts
import { NextRequest, NextResponse } from 'next/server';
import mbClient from '@/lib/messagebird'; // Import initialized client
import { MessageBird } from 'messagebird/types'; // Import types for better DX

// Define expected request body structure (using interface or Zod for validation)
interface SendMessageRequestBody {
  to: string; // Recipient phone number in E.164 format (e.g., +14155552671). Required: +[country code][number], up to 15 digits. Excludes short codes and numbers from Crimea, Cuba, Iran, North Korea, Syria.
  text?: string; // For simple text messages
  template?: { // For template messages
    name: string; // Approved template name
    language: string; // e.g., 'en_US'
    components?: MessageBird.MessageRequestTemplate['components']; // Parameters
  };
}

export async function POST(request: NextRequest) {
  console.log(""Received request to /api/send-whatsapp""); // Note: Replace with structured logger in production

  let body: SendMessageRequestBody;
  try {
    body = await request.json();
    console.log(""Request body:"", body); // Note: Replace with structured logger in production

    // Basic validation (consider using Zod for robust validation)
    if (!body.to || (!body.text && !body.template)) {
      console.error(""Validation failed: Missing 'to' or message content ('text'/'template')""); // Note: Replace with structured logger in production
      return NextResponse.json({ error: ""Missing 'to' or message content ('text'/'template')"" }, { status: 400 });
    }
    if (!process.env.MESSAGEBIRD_CHANNEL_ID) {
        console.error(""Configuration error: Missing MESSAGEBIRD_CHANNEL_ID""); // Note: Replace with structured logger in production
        return NextResponse.json({ error: ""Server configuration error: Channel ID missing"" }, { status: 500 });
    }

  } catch (error) {
    console.error(""Failed to parse request body:"", error); // Note: Replace with structured logger in production
    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
  }

  const params: MessageBird.MessageRequest = {
    to: body.to,
    from: process.env.MESSAGEBIRD_CHANNEL_ID, // Your MessageBird WhatsApp Channel ID
    type: 'text', // Default to text, override if template is present
    content: {},
  };

  // Construct message content based on request
  if (body.template) {
    params.type = 'hsm'; // HSM (Highly Structured Message) is used for templates
    params.content = {
      hsm: {
        // IMPORTANT: Replace with your WABA (WhatsApp Business Account) template namespace!
        // Find in MessageBird Dashboard > Templates > Template Details (e.g., 'cdb2df51_9816_c754_c5a4_64cdabdcad3e')
        // The namespace is a bundle of language packs for your business, required for template message routing.
        namespace: 'your_messagebird_template_namespace', // Get this from MessageBird template details
        templateName: body.template.name,
        language: {
          policy: 'deterministic',
          code: body.template.language,
        },
        components: body.template.components || [], // Pass parameters if provided
      },
    };
    console.log(""Sending template message:"", params); // Note: Replace with structured logger in production
  } else if (body.text) {
    params.type = 'text';
    params.content = { text: body.text };
    console.log(""Sending text message:"", params); // Note: Replace with structured logger in production
  } else {
      // This case should be caught by initial validation, but good to have defensive coding
      console.error(""No message content provided.""); // Note: Replace with structured logger in production
      return NextResponse.json({ error: ""No message content provided"" }, { status: 400 });
  }


  try {
    // Wrap the callback-based SDK method in a Promise
    const result = await new Promise<MessageBird.Message&gt;((resolve, reject) =&gt; {
      mbClient.messages.create(params, (err, response) =&gt; {
        if (err) {
          console.error(""MessageBird API Error:"", err); // Note: Replace with structured logger in production
          // Extract more specific error info if available
          const errorDetails = err.errors ? JSON.stringify(err.errors) : err.message;
          reject(new Error(`MessageBird API Error: ${errorDetails}`));
        } else if (response) {
          console.log(""MessageBird API Success:"", response); // Note: Replace with structured logger in production
          resolve(response);
        } else {
          reject(new Error(""MessageBird API returned undefined response""));
        }
      });
    });

    return NextResponse.json({ success: true, messageId: result.id, status: result.status }, { status: 201 }); // 201 Created is suitable

  } catch (error: any) {
    console.error(""Error sending message:"", error); // Note: Replace with structured logger in production
    // Return a generic error to the client, log the specific error server-side
    return NextResponse.json({ success: false, error: 'Failed to send message', details: error.message }, { status: 500 });
  }
}

// Optional: Add a GET handler for basic testing or documentation
export async function GET() {
  return NextResponse.json({ message: ""POST to this endpoint to send a WhatsApp message."" });
}

// src/app/api/messagebird-webhook/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';
import { MessageBird } from 'messagebird/types'; // Webhook payload types
// Optional: Import Prisma client if logging messages
// import prisma from '@/lib/prisma';

// --- Webhook Signature Verification ---
async function verifySignature(request: NextRequest): Promise<boolean&gt; {
  // MessageBird signs webhooks using HMAC-SHA256 with MessageBird-Signature-JWT header (updated 2024)
  const signature = request.headers.get('messagebird-signature');
  const timestamp = request.headers.get('messagebird-request-timestamp');
  const webhookSecret = process.env.MESSAGEBIRD_WEBHOOK_SECRET;

  if (!signature || !timestamp || !webhookSecret) {
    console.warn('Webhook verification failed: Missing signature, timestamp, or secret'); // Note: Replace with structured logger in production
    return false;
  }

  // Clone the request to read the body safely
  const requestClone = request.clone();
  const bodyText = await requestClone.text(); // Read body as raw text

  // Construct the signed payload string (MessageBird format: timestamp.secret.body)
  const signedPayload = `${timestamp}.${webhookSecret}.${bodyText}`;

  // Calculate the expected signature using HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload)
    .digest('hex');

  // Compare signatures securely using timing-safe comparison to prevent timing attacks
  const isValid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));

  if (!isValid) {
      console.warn('Webhook verification failed: Invalid signature'); // Note: Replace with structured logger in production
      console.log(`Received Signature: ${signature}`); // Note: Replace with structured logger in production
      console.log(`Expected Signature: ${expectedSignature}`); // Note: Replace with structured logger in production
      // console.log(`Timestamp: ${timestamp}`); // Be cautious logging timestamps if needed for debugging
      // console.log(`Body: ${bodyText}`); // Be very cautious logging raw body content
  }


  return isValid;
}

// --- Main Webhook Handler ---
export async function POST(request: NextRequest) {
  console.log("Received POST request to /api/messagebird-webhook"); // Note: Replace with structured logger in production

  // 1. Verify the signature FIRST
  const isVerified = await verifySignature(request);
  if (!isVerified) {
    console.error("Webhook signature verification failed."); // Note: Replace with structured logger in production
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  console.log("Webhook signature verified successfully."); // Note: Replace with structured logger in production

  // 2. Parse the JSON body (only after verification)
  let payload: MessageBird.WebhookPayload;
  try {
    payload = await request.json();
    console.log('Received webhook payload:', JSON.stringify(payload, null, 2)); // Log the full payload for debugging - Replace with structured logger in production
  } catch (error) {
    console.error('Failed to parse webhook payload:', error); // Note: Replace with structured logger in production
    return NextResponse.json({ error: 'Invalid payload' }, { status: 400 });
  }

  // 3. Process the event based on type
  try {
    switch (payload.type) {
      case 'message.created':
      case 'message.updated': // Handle status updates (sent, delivered, read)
        const messageEvent = payload as MessageBird.MessageEvent; // Type assertion
        console.log(`Processing ${payload.type} event for message ID: ${messageEvent.message.id}`); // Note: Replace with structured logger in production
        console.log(`Direction: ${messageEvent.message.direction}, Status: ${messageEvent.message.status}`); // Note: Replace with structured logger in production

        // Only process incoming messages ('mo' - mobile originated)
        if (messageEvent.message.direction === 'mo') {
          console.log(`Received message from ${messageEvent.message.originator}:`); // Note: Replace with structured logger in production
          console.log(`Type: ${messageEvent.message.content.type}, Content:`, messageEvent.message.content); // Note: Replace with structured logger in production

          // --- Optional: Log incoming message to Database ---
          /*
          if (prisma) {
              try {
                  await prisma.messageLog.create({
                      data: {
                          messageId: messageEvent.message.id,
                          channelId: messageEvent.message.channelId,
                          conversationId: messageEvent.message.conversationId,
                          direction: 'incoming',
                          status: messageEvent.message.status ?? 'received',
                          sender: messageEvent.message.originator ?? 'unknown',
                          recipient: messageEvent.message.recipient, // Your number/channel
                          content: JSON.stringify(messageEvent.message.content), // Store full content as JSON string
                          receivedAt: new Date(messageEvent.message.createdDatetime ?? Date.now()),
                          platform: 'whatsapp'
                      }
                  });
                  console.log(`Logged incoming message ${messageEvent.message.id} to DB`); // Note: Replace with structured logger in production
              } catch (dbError) {
                  console.error("Failed to log incoming message to DB:", dbError); // Note: Replace with structured logger in production
                  // Decide if you should still return 200 OK to MessageBird
              }
          }
          */
          // --- End Optional DB Log ---

          // TODO: Implement your business logic here based on the incoming message
          // Example: Route to support, trigger automated reply, etc.

        } else if (messageEvent.message.direction === 'mt') { // Mobile Terminated (outgoing) status updates
            console.log(`Status update for outgoing message ${messageEvent.message.id}: ${messageEvent.message.status}`); // Note: Replace with structured logger in production
            // --- Optional: Update message status in Database ---
            /*
            if (prisma) {
                 try {
                    await prisma.messageLog.updateMany({ // Use updateMany in case the initial record wasn't created yet
                        where: { messageId: messageEvent.message.id },
                        data: {
                            status: messageEvent.message.status ?? 'unknown',
                            // Optionally update other fields like deliveredAt, readAt based on status
                        }
                    });
                    console.log(`Updated status for message ${messageEvent.message.id} to ${messageEvent.message.status} in DB`); // Note: Replace with structured logger in production
                } catch (dbError) {
                    console.error("Failed to update message status in DB:", dbError); // Note: Replace with structured logger in production
                }
            }
            */
           // --- End Optional DB Log ---
        }
        break;

      // Handle other event types if needed (e.g., conversation events)
      // case 'conversation.created':
      //   // Handle conversation events
      //   break;

      default:
        console.log(`Received unhandled event type: ${payload.type}`); // Note: Replace with structured logger in production
    }

    // 4. Acknowledge receipt to MessageBird
    // It's crucial to respond quickly with a 200 OK, even if background processing continues.
    return NextResponse.json({ success: true }, { status: 200 });

  } catch (processingError) {
    console.error('Error processing webhook payload:', processingError); // Note: Replace with structured logger in production
    // Still return 200 OK if possible to prevent MessageBird retries,
    // but log the error for investigation. Use a 500 for critical failures.
    // Depending on the error, you might want to respond differently.
    return NextResponse.json({ success: false, error: 'Failed to process webhook' }, { status: 500 });
  }
}

// Optional: Add GET handler for basic testing/verification during webhook setup
export async function GET() {
  console.log("Received GET request to /api/messagebird-webhook"); // Note: Replace with structured logger in production
  // MessageBird doesn't typically use GET for verification, but it can be useful for simple reachability tests.
  return NextResponse.json({ message: "MessageBird Webhook endpoint is active. Use POST for events." });
}

// Example: src/lib/logger.ts (Basic Pino Setup)
import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport: process.env.NODE_ENV !== 'production'
    ? { target: 'pino-pretty' } // Pretty print in development
    : undefined, // Default JSON output in production
});

export default logger;

// Usage in API routes:
// import logger from '@/lib/logger';
// logger.info('Processing request...');
// logger.error({ err: error }, 'Failed to send message');