How to Integrate Sinch WhatsApp with Next.js: Complete Developer Guide

npx create-next-app@latest sinch-whatsapp-nextjs
# Follow the prompts (e.g., select TypeScript: No, ESLint: Yes, Tailwind CSS: No, `src/` directory: No, App Router: Yes (Recommended), Import alias: No)
cd sinch-whatsapp-nextjs

# .env.local

# Sinch Project & API Access Credentials
# Found in Sinch Dashboard -> Your Project -> API Keys
SINCH_PROJECT_ID=YOUR_SINCH_PROJECT_ID
SINCH_KEY_ID=YOUR_SINCH_ACCESS_KEY_ID
SINCH_KEY_SECRET=YOUR_SINCH_ACCESS_KEY_SECRET

# Sinch Conversation API App Credentials
# Found in Sinch Dashboard -> Conversation API -> Your App
SINCH_APP_ID=YOUR_CONVERSATION_APP_ID
# Typically 'us', 'eu', or 'br' - Match your Conversation API App region
SINCH_REGION=us

# Sinch WhatsApp Channel Credentials (Specific to your configured WhatsApp Sender)
# Found during WhatsApp Sender setup or in App Configuration
SINCH_WHATSAPP_SENDER_ID=YOUR_WHATSAPP_SENDER_ID # Often the phone number in E.164 format
# Note: This token is essential for configuring the WhatsApp channel in the Sinch App (dashboard setup).
# The API calls in this guide use Basic Authentication derived from SINCH_KEY_ID/SECRET for sending.
SINCH_WHATSAPP_BEARER_TOKEN=YOUR_WHATSAPP_SENDER_BEARER_TOKEN # Provided during sender setup

# Application URL (Needed for Webhook setup in Sinch Dashboard)
# Use your deployed URL in production. For local dev, use an ngrok URL.
NEXT_PUBLIC_APP_URL=http://localhost:3000 # Replace with deployment or ngrok URL later

sinch-whatsapp-nextjs/
├── app/
│   ├── api/
│   │   ├── send-whatsapp/
│   │   │   └── route.js      # Endpoint to send messages
│   │   └── sinch-webhook/
│   │       └── route.js      # Endpoint to receive webhooks
│   ├── layout.js
│   └── page.js             # Optional simple UI for testing
├── .env.local              # Your secret credentials (DO NOT COMMIT)
├── .env.local.example      # Example structure for others (Commit this)
├── .gitignore
├── next.config.js
├── package.json
└── README.md

// app/api/send-whatsapp/route.js
import { NextResponse } from 'next/server';

// Basic Authentication Token Generation (cache in production)
function getSinchAuthToken() {
    const keyId = process.env.SINCH_KEY_ID;
    const keySecret = process.env.SINCH_KEY_SECRET;
    if (!keyId || !keySecret) {
        throw new Error("Sinch Key ID or Secret not configured in environment variables.");
    }
    const credentials = `${keyId}:${keySecret}`;
    return `Basic ${Buffer.from(credentials).toString('base64')}`;
    // Note: For production, consider Sinch OAuth for better security & rotation
    // See: https://developers.sinch.com/docs/conversation/authentication/
}

export async function POST(request) {
    const { to, text } = await request.json();

    // --- 1. Input Validation ---
    if (!to || !text) {
        return NextResponse.json({ error: 'Missing "to" phone number or "text" message.' }, { status: 400 });
    }
    // Basic E.164 format check (adjust regex as needed for stricter validation)
    if (!/^\+\d{11,15}$/.test(to)) {
         return NextResponse.json({ error: 'Invalid "to" phone number format. Use E.164 (e.g., +15551234567).' }, { status: 400 });
    }

    const projectId = process.env.SINCH_PROJECT_ID;
    const sinchAppId = process.env.SINCH_APP_ID;
    const senderId = process.env.SINCH_WHATSAPP_SENDER_ID; // Used in payload, ensure it's set
    const region = process.env.SINCH_REGION || 'us'; // Default to 'us' if not set

    if (!projectId || !sinchAppId || !senderId) {
         return NextResponse.json({ error: 'Sinch Project ID, App ID, or Sender ID not configured.' }, { status: 500 });
    }

    const sinchApiUrl = `https://${region}.conversation.api.sinch.com/v1/projects/${projectId}/messages:send`;

    const payload = {
        app_id: sinchAppId,
        recipient: {
            contact_id: to // Using contact_id for direct E.164 number sending
            // Alternatively, use channel_identity for specific channel/number pair:
            // channel_identity: { channel: 'WHATSAPP', identity: to }
        },
        message: {
            text_message: {
                text: text
            }
            // For Template Messages, use:
            // template_message: {
            //    template_id: "your_template_id", // The registered template name/ID
            //    version: "your_template_version", // e.g., "1"
            //    language_code: "en_US", // Or relevant language
            //    parameters: { /* template parameters if any */ }
            // }
        },
        channel_priority_order: ["WHATSAPP"] // Ensure WhatsApp is prioritized
    };

    try {
        // --- 2. API Call to Sinch ---
        const response = await fetch(sinchApiUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': getSinchAuthToken() // Use Basic Auth or OAuth
            },
            body: JSON.stringify(payload),
        });

        const responseData = await response.json();

        // --- 3. Response Handling ---
        if (!response.ok) {
            console.error('Sinch API Error:', response.status, responseData);
            return NextResponse.json(
                { error: 'Failed to send message via Sinch.', details: responseData },
                { status: response.status }
            );
        }

        console.log('Sinch Send Success:', responseData);
        return NextResponse.json({ success: true, messageId: responseData.message_id });

    } catch (error) {
        // --- 4. Error Handling ---
        console.error('Error sending WhatsApp message:', error);
        return NextResponse.json({ error: 'Internal server error.' }, { status: 500 });
    }
}

// app/api/sinch-webhook/route.js
import { NextResponse } from 'next/server';

export async function POST(request) {
    try {
        const payload = await request.json();

        console.log('Received Sinch Webhook');
        console.log('Payload:', JSON.stringify(payload, null, 2)); // Log the full payload for inspection

        // --- 1. Identify Event Type & Process based on Payload Structure ---
        // Sinch uses different payload structures for different events.
        // Inspect payloads in the Sinch Dashboard or your logs to handle each relevant case.

        if (payload.message_inbound_event) {
            // --- 2. Handle Incoming Messages ---
            const event = payload.message_inbound_event;
            const message = event.message;
            const contactId = event.contact_id; // Sender's phone number (usually)
            const appId = event.app_id;

            console.log(`---> Incoming Message from ${contactId} in App ${appId}`);

            if (message.text_message) {
                console.log(`    Text: ${message.text_message.text}`);
                // TODO: Add your logic here:
                // - Store the message in a database
                // - Trigger automated replies
                // - Forward to a support system
            } else if (message.media_message) {
                console.log(`    Media URL: ${message.media_message.url}`);
                // TODO: Handle incoming media (images, videos, etc.)
            }
            // Add handling for other message types (location, contacts, etc.) as needed

        } else if (payload.message_delivery_event) {
            // --- 3. Handle Delivery Receipts ---
            const event = payload.message_delivery_event;
            const messageId = event.message_id;
            const status = event.status; // e.g., DELIVERED, FAILED, READ
            const reason = event.reason; // Reason for failure, if any

            console.log(`---> Delivery Status for Message ${messageId}: ${status}`);
            if (reason) {
                console.log(`     Reason: ${reason}`);
            }
            // TODO: Update message status in your database

        } else {
            // Log other event types you might receive but aren't explicitly handling yet
            const eventType = Object.keys(payload)[0]; // Basic way to guess event type key
            console.warn(`Received unhandled webhook event type: ${eventType || 'Unknown'}`);
        }

        // --- 4. Acknowledge Receipt ---
        // Respond quickly to Sinch to acknowledge receipt.
        // Process heavy logic asynchronously (e.g., using queues or background jobs).
        return NextResponse.json({ success: true });

    } catch (error) {
        console.error('Error processing Sinch webhook:', error);
        // Avoid sending detailed errors back in the webhook response
        return NextResponse.json({ error: 'Webhook processing failed.' }, { status: 500 });
    }
}

// --- Optional: GET handler for verification ---
// Some services require a GET request check during webhook setup.
// Sinch doesn't typically require this, but it's useful for health checks.
export async function GET(request) {
    console.log('Received GET request on webhook endpoint.');
    return NextResponse.json({ message: 'Sinch webhook endpoint is active.' });
}

npm install async-retry

// Inside app/api/send-whatsapp/route.js (conceptual integration)
import { NextResponse } from 'next/server';
import retry from 'async-retry';

// ... getSinchAuthToken function ...

export async function POST(request) {
    // ... input validation ...
    // ... variable setup (projectId, sinchApiUrl, payload) ...

    try {
        // Wrap the fetch call within the retry block
        const result = await retry(
            async (bail, attempt) => {
                console.log(`Attempting Sinch API call (attempt ${attempt})...`);
                const response = await fetch(sinchApiUrl, {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'Authorization': getSinchAuthToken()
                    },
                    body: JSON.stringify(payload),
                });

                if (!response.ok) {
                    const status = response.status;
                    // Don't retry on client errors (4xx)
                    if (status >= 400 && status < 500) {
                        // Use bail to stop retrying and propagate the error immediately
                        const errorData = await response.json();
                        const clientError = new Error(`Sinch API client error: ${status}`);
                        clientError.originalStatus = status;
                        clientError.details = errorData;
                        bail(clientError); // Stop retrying
                        return; // Bail prevents further execution here
                    }
                    // For server errors (5xx) or other network issues_ throw to trigger retry
                    const serverError = new Error(`Sinch API server error or network issue: ${status}`);
                    serverError.originalStatus = status;
                    try { serverError.details = await response.json(); } catch { /* ignore parsing error */ }
                    throw serverError; // Trigger retry
                }

                // If response is OK_ parse and return the data
                const responseData = await response.json();
                console.log('Sinch Send Success within retry block:'_ responseData);
                return responseData; // Return successful data
            }_
            {
                retries: 3_ // Number of retries
                factor: 2_ // Exponential backoff factor
                minTimeout: 1000_ // Initial timeout in ms (1 second)
                onRetry: (error_ attempt) => {
                    console.warn(`Retrying Sinch API call (attempt ${attempt}) due to: ${error.message}`);
                }
            }
        );

        // If retry succeeded, 'result' holds the responseData
        return NextResponse.json({ success: true, messageId: result.message_id });

    } catch (error) {
        // This catches errors after all retries failed, or if bail was called
        console.error('Error sending WhatsApp message after retries:', error.message);
        // Log details if available (e.g., from clientError or last serverError)
        const status = error.originalStatus || 500;
        const details = error.details || null;
        return NextResponse.json(
            { error: 'Failed to send message via Sinch after retries.', details: details },
            { status: status }
        );
    }
}

npm install prisma --save-dev
npm install @prisma/client
npx prisma init --datasource-provider postgresql # Or your preferred DB

// prisma/schema.prisma
datasource db {
  provider = "postgresql" // Or "mysql", "sqlite", "sqlserver", "mongodb"
  url      = env("DATABASE_URL")
}

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

model Contact {
  id        String   @id @default(cuid())
  phone     String   @unique // E.164 format
  name      String?
  createdAt DateTime @default(now())
  messages  Message[]
}

model Message {
  id             String    @id @default(cuid())
  sinchMessageId String?   @unique // ID from Sinch API response/webhook
  contactId      String
  contact        Contact   @relation(fields: [contactId], references: [id])
  appId          String?   // Sinch App ID associated with the message
  direction      String    // "INBOUND" or "OUTBOUND"
  channel        String    // e.g., "WHATSAPP"
  status         String?   // e.g., "SENT", "DELIVERED", "READ", "FAILED", "RECEIVED"
  content        Json      // Store text, media URLs, templates etc.
  timestamp      DateTime  // Time of the event (from Sinch or DB creation)
  createdAt      DateTime  @default(now())
  updatedAt      DateTime  @updatedAt
  reason         String?   // Failure reason from delivery receipt
}

npx prisma migrate dev --name init # Creates migration and applies to DB
npx prisma generate              # Generates Prisma Client

// Example in app/api/sinch-webhook/route.js
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

// ... inside POST function, after parsing payload ...

if (payload.message_inbound_event) {
    const event = payload.message_inbound_event;
    const messageData = event.message;
    const contactPhone = event.contact_id; // Assuming this is the E.164 phone
    const sinchMsgId = event.message_id; // Check if inbound events provide a unique ID

    // Perform DB operations asynchronously (move outside the immediate response if heavy)
    try {
        await prisma.message.create({
            data: {
                sinchMessageId: sinchMsgId, // Ensure this is unique or handle conflicts
                contact: {
                    connectOrCreate: {
                        where: { phone: contactPhone },
                        create: { phone: contactPhone },
                    },
                },
                appId: event.app_id,
                direction: 'INBOUND',
                channel: event.channel, // Make sure channel is in the event payload
                content: messageData, // Store the whole message object
                timestamp: new Date(event.accepted_time), // Use Sinch timestamp
                status: 'RECEIVED', // Custom status
            },
        });
        console.log(`Saved inbound message ${sinchMsgId} from ${contactPhone}`);
    } catch (dbError) {
        console.error('Database error saving inbound message:', dbError);
        // Decide how to handle DB errors – perhaps queue for later retry?
    }
} else if (payload.message_delivery_event) {
     const event = payload.message_delivery_event;
     const sinchMsgId = event.message_id;
     // Perform DB operations asynchronously
     try {
        const updatedMessage = await prisma.message.update({
            where: { sinchMessageId: sinchMsgId },
            data: {
                status: event.status,
                reason: event.reason,
                timestamp: new Date(event.processed_time), // Use Sinch timestamp
            },
        });
        console.log(`Updated status for message ${sinchMsgId} to ${event.status}`);
     } catch (dbError) {
        // Handle cases where the message might not exist (e.g., if outbound save failed)
        if (dbError.code === 'P2025') { // Prisma code for RecordNotFound
            console.warn(`Message with sinchMessageId ${sinchMsgId} not found for status update.`);
        } else {
            console.error('Database error updating message status:', dbError);
        }
        // Decide how to handle DB errors
     }
}

// Handle prisma client connection properly (e.g., singleton pattern)
// https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices