Production-Ready WhatsApp Integration with Node.js, Express, and Sinch Conversation API

mkdir sinch-whatsapp-integration
cd sinch-whatsapp-integration

npm init -y

npm install express dotenv axios crypto
# Or using yarn:
# yarn add express dotenv axios crypto

sinch-whatsapp-integration/
├── src/
│   ├── controllers/
│   │   ├── messageController.js
│   │   └── webhookController.js
│   ├── routes/
│   │   ├── messageRoutes.js
│   │   └── webhookRoutes.js
│   ├── services/
│   │   └── sinchService.js
│   ├── middleware/
│   │   └── verifySinchWebhook.js
│   └── app.js              # Express app setup
├── .env                    # Environment variables (DO NOT COMMIT)
├── .gitignore              # Git ignore file
└── package.json

# .gitignore
node_modules/
.env
*.log
prisma/migrations/*.sql # If using Prisma

# .env - Fill these values from Sinch dashboard
PORT=3000
NODE_ENV=development # Set to 'production' in deployment

# Sinch Credentials
SINCH_PROJECT_ID=YOUR_SINCH_PROJECT_ID
SINCH_ACCESS_KEY_ID=YOUR_SINCH_ACCESS_KEY_ID
SINCH_ACCESS_SECRET=YOUR_SINCH_ACCESS_SECRET
WHATSAPP_SENDER_ID=YOUR_WHATSAPP_SENDER_ID_FROM_SINCH # The ID for your WhatsApp number

# Webhook Secret (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
SINCH_WEBHOOK_SECRET=YOUR_STRONG_RANDOM_SECRET_FOR_WEBHOOK_VERIFICATION

# Sinch API Region (us or eu - check your app config in dashboard)
SINCH_REGION=us # or eu

# Optional: Database URL (if using Prisma)
# DATABASE_URL="postgresql://user:password@host:port/database?schema=public"

# Optional: Logging Level
# LOG_LEVEL=info

// src/services/sinchService.js
const axios = require('axios');
const crypto = require('crypto');
require('dotenv').config();

const {
    SINCH_PROJECT_ID,
    SINCH_ACCESS_KEY_ID,
    SINCH_ACCESS_SECRET,
    WHATSAPP_SENDER_ID,
    SINCH_REGION // 'us' or 'eu'
} = process.env;

// Input validation
if (!SINCH_PROJECT_ID || !SINCH_ACCESS_KEY_ID || !SINCH_ACCESS_SECRET || !WHATSAPP_SENDER_ID || !SINCH_REGION) {
    console.error("FATAL ERROR: Missing required Sinch environment variables.");
    process.exit(1);
}

const CONVERSATION_API_URL_BASE = `https://${SINCH_REGION}.conversation.api.sinch.com/v1/projects/${SINCH_PROJECT_ID}`;

// --- Authentication Helper ---
/**
 * Generates the Sinch Authentication Header value.
 * IMPORTANT: Verify stringToSign format against current Sinch documentation:
 * https://developers.sinch.com/docs/conversation/api-reference/#authentication/application-signed-requests
 *
 * @param {string} method - HTTP Method (POST, GET, etc.)
 * @param {string} path - Request path (e.g., /messages:send)
 * @param {string} [requestBody=''] - Stringified JSON request body or empty string for GET
 * @returns {string} - Authorization header value
 */
const generateSinchAuthHeader = (method, path, requestBody = '') => {
    const httpVerb = method.toUpperCase();
    const contentMd5 = crypto.createHash('md5').update(requestBody, 'utf-8').digest('base64');
    const contentType = requestBody ? 'application/json; charset=utf-8' : '';
    const timestamp = new Date().toISOString();
    const canonicalizedHeaders = `x-timestamp:${timestamp}`;
    const canonicalizedResource = path;

    const stringToSign = `${httpVerb}\n${contentMd5}\n${contentType}\n${canonicalizedHeaders}\n${canonicalizedResource}`;

    // IMPORTANT: SINCH_ACCESS_SECRET from dashboard is Base64-encoded
    const signature = crypto.createHmac('sha256', Buffer.from(SINCH_ACCESS_SECRET, 'base64'))
        .update(stringToSign, 'utf-8')
        .digest('base64');

    return `Application ${SINCH_ACCESS_KEY_ID}:${signature}`;
};

// --- Sending Logic ---

/**
 * Send a message via Sinch Conversation API
 * @param {string} recipientPhoneNumber - E.164 formatted phone number
 * @param {object} messagePayload - Sinch message object (e.g., { text_message: { text: 'Hello!' } })
 * @returns {Promise<object&gt;} - Response data from Sinch API
 * @throws {Error} - If API call fails
 */
const sendMessage = async (recipientPhoneNumber, messagePayload) =&gt; {
    const path = '/messages:send';
    const url = `${CONVERSATION_API_URL_BASE}${path}`;
    const method = 'POST';

    // Note: Using contact_id for WhatsApp is standard.
    // Alternative: identified_by: { channel: 'WHATSAPP', identity: recipientPhoneNumber }
    const body = {
        app_id: WHATSAPP_SENDER_ID,
        recipient: {
            contact_id: recipientPhoneNumber
        },
        message: messagePayload,
        channel_priority_order: ["WHATSAPP"]
    };

    const requestBodyString = JSON.stringify(body);
    const authorization = generateSinchAuthHeader(method, path, requestBodyString);
    const timestamp = new Date().toISOString();

    try {
        console.log(`Sending message to ${recipientPhoneNumber} via Sinch…`);
        const response = await axios({
            method: method,
            url: url,
            data: requestBodyString,
            headers: {
                'Content-Type': 'application/json; charset=utf-8',
                'x-timestamp': timestamp,
                'Authorization': authorization
            }
        });
        console.log('Sinch API Response:', response.data);
        return response.data;
    } catch (error) {
        console.error('Error sending message via Sinch:', error.response ? JSON.stringify(error.response.data, null, 2) : error.message);
        if (error.response) {
             error.statusCode = error.response.status;
        }
        throw error;
    }
};

/**
 * Send a simple text message
 * @param {string} recipientPhoneNumber
 * @param {string} text
 */
const sendTextMessage = async (recipientPhoneNumber, text) =&gt; {
    const messagePayload = {
        text_message: { text: text }
    };
    return sendMessage(recipientPhoneNumber, messagePayload);
};

/**
 * Send a pre-approved template message
 * Required when initiating conversations or outside the 24-hour window
 * @param {string} recipientPhoneNumber
 * @param {string} templateId - Approved template ID
 * @param {string[]} [params] - Optional parameters for template placeholders
 */
const sendTemplateMessage = async (recipientPhoneNumber, templateId, params = []) =&gt; {
    // Verify parameter names in your Sinch dashboard template definition
    const parameters = params.reduce((acc, value, index) =&gt; {
        acc[`param${index + 1}`] = value;
        return acc;
    }, {});

    const messagePayload = {
        template_message: {
            omni_template: {
                template_id: templateId,
                version: "latest",
                language_code: "en_US",
                parameters: parameters
            }
        }
    };
    return sendMessage(recipientPhoneNumber, messagePayload);
};

module.exports = {
    sendMessage,
    sendTextMessage,
    sendTemplateMessage,
    generateSinchAuthHeader
};

// src/middleware/verifySinchWebhook.js
const crypto = require('crypto');
require('dotenv').config();

const { SINCH_WEBHOOK_SECRET } = process.env;

/**
 * Express middleware to verify Sinch webhook signatures
 * IMPORTANT: Verify stringToSign format against Sinch documentation:
 * https://developers.sinch.com/docs/conversation/webhook-verification/
 */
const verifySinchWebhook = (req, res, next) => {
    if (!SINCH_WEBHOOK_SECRET) {
        console.error('CRITICAL: SINCH_WEBHOOK_SECRET not set. Webhook verification cannot proceed.');
        return res.status(500).send('Webhook secret not configured');
    }

    const signatureHeader = req.headers['x-sinch-signature'];
    const timestampHeader = req.headers['x-sinch-timestamp'];

    if (!signatureHeader || !timestampHeader) {
        console.error('Webhook Error: Missing signature headers (x-sinch-signature or x-sinch-timestamp)');
        return res.status(400).send('Missing signature headers');
    }

    // Validate timestamp (within 5 minutes)
    const requestTimestamp = parseInt(timestampHeader, 10);
    const currentTimestamp = Math.floor(Date.now() / 1000);
    const timestampTolerance = 300; // 5 minutes in seconds

    if (isNaN(requestTimestamp) || Math.abs(currentTimestamp - requestTimestamp) > timestampTolerance) {
        console.error(`Webhook Error: Timestamp validation failed. Request: ${requestTimestamp}, Current: ${currentTimestamp}`);
        return res.status(400).send('Timestamp validation failed');
    }

    // CRITICAL: req.rawBody required. Ensure express.raw() runs BEFORE express.json()
    if (!req.rawBody || req.rawBody.length === 0) {
         console.error('Webhook Error: Missing req.rawBody. Configure raw body parser BEFORE JSON parser.');
         return res.status(500).send('Internal server error: Raw body not available');
    }

    const stringToSign = `${req.rawBody}|${timestampHeader}`;

    try {
        const expectedSignature = crypto.createHmac('sha256', SINCH_WEBHOOK_SECRET)
                                       .update(stringToSign)
                                       .digest('base64');

        const signatures = signatureHeader.split(',');
        const providedSignature = signatures[0].trim();

        if (signatures.length > 1) {
            console.warn(`Multiple signatures received. Verifying first: ${providedSignature}`);
        }

        const signaturesMatch = crypto.timingSafeEqual(
            Buffer.from(providedSignature),
            Buffer.from(expectedSignature)
        );

        if (!signaturesMatch) {
            console.error('Webhook Error: Invalid signature');
            return res.status(403).send('Invalid signature');
        }

        console.log('Sinch webhook signature verified successfully');
        next();

    } catch (error) {
        console.error('Webhook Error: Exception during signature verification:', error);
        return res.status(500).send('Internal server error during signature verification');
    }
};

module.exports = verifySinchWebhook;

// src/controllers/webhookController.js
const sinchService = require('../services/sinchService');

const handleIncomingEvent = async (req, res) => {
    const event = req.body;

    console.log(`Received Verified Sinch Webhook Event: ${event.event_id || 'Unknown ID'}`);

    try {
        if (event.message_inbound) {
            await handleInboundMessage(event.message_inbound);
        } else if (event.message_delivery) {
            await handleDeliveryReceipt(event.message_delivery);
        } else if (event.contact_create) {
            console.log(`Contact created: ${event.contact_create.contact_id}`);
        } else if (event.contact_merge) {
            console.log(`Contacts merged: ${event.contact_merge.merged_contact_ids} into ${event.contact_merge.contact_id}`);
        } else if (event.conversation_start) {
             console.log(`Conversation started: ${event.conversation_start.conversation_id}`);
        }

        res.status(200).send('Webhook received and processed successfully');

    } catch (error) {
        console.error(`Error processing webhook event ${event.event_id || 'Unknown ID'}:`, error);
        res.status(500).send('Error processing webhook event');
    }
};

// --- Specific Event Handlers ---

const handleInboundMessage = async (inboundEvent) => {
    console.log('Handling Inbound Message:', inboundEvent.message_id);

    const contactId = inboundEvent.contact_message?.contact_id;
    const appId = inboundEvent.app_id;
    const message = inboundEvent.contact_message?.message;
    const messageId = inboundEvent.message_id;

    if (!contactId || !message || !messageId) {
        console.error("Inbound message missing critical fields. Skipping.", inboundEvent);
        return;
    }

    // Example: Echo Bot with 24-hour window awareness
    if (message.text_message) {
        const receivedText = message.text_message.text;
        console.log(`Received text from ${contactId}: "${receivedText}"`);

        // IMPORTANT: Production apps MUST track last interaction time in database
        const isWithinWindow = true; // Replace with: checkDbForRecentInteraction(contactId)

        if (isWithinWindow) {
            if (receivedText.trim().toUpperCase() === 'STOP') {
                console.log(`Opt-out request from ${contactId}`);
                // Mark user as opted-out in database
                await sinchService.sendTextMessage(contactId, "You have been opted out of messages.");
            } else {
                try {
                    const replyText = `You said: "${receivedText}"`;
                    await sinchService.sendTextMessage(contactId, replyText);
                    console.log(`Sent reply to ${contactId}`);
                } catch (error) {
                    console.error(`Failed to send reply to ${contactId}:`, error);
                }
            }
        } else {
            console.log(`Message from ${contactId} outside 24-hour window. Cannot send free-form reply.`);
            // Send template message if appropriate
        }

    } else if (message.media_message) {
        console.log(`Received media from ${contactId}: ${message.media_message.url}`);
        // Handle media (download, process, store URL)

    } else if (message.choice_response_message) {
         console.log(`Received button/list reply from ${contactId}: ${message.choice_response_message.choice_id}`);
         // Handle interactive message replies

    } else {
        const messageType = Object.keys(message)[0];
        console.log(`Received ${messageType} from ${contactId}`);
    }
};

const handleDeliveryReceipt = async (deliveryEvent) => {
    console.log('Handling Delivery Receipt:', deliveryEvent.message_id);

    const messageId = deliveryEvent.message_id;
    const contactId = deliveryEvent.contact_id;
    const status = deliveryEvent.status; // DELIVERED, FAILED, READ, PENDING
    const timestamp = deliveryEvent.processed_time;
    const reason = deliveryEvent.reason;

    console.log(`Message ${messageId} to ${contactId}: ${status} at ${timestamp}`);

    // Update message status in database

    if (status === 'FAILED') {
        console.error(`Message ${messageId} FAILED: ${reason?.code || 'N/A'} - ${reason?.description || 'No description'}`);
        // Trigger alerts for failed messages
    } else if (status === 'READ') {
         console.log(`Message ${messageId} was READ at ${timestamp}`);
         // Trigger analytics or follow-up logic
    }
};

module.exports = {
    handleIncomingEvent
};

// src/routes/webhookRoutes.js
const express = require('express');
const webhookController = require('../controllers/webhookController');
const verifySinchWebhook = require('../middleware/verifySinchWebhook');

const router = express.Router();

// IMPORTANT: Configure express.raw() in app.js BEFORE express.json() for this route

router.post(
    '/',
    verifySinchWebhook, // Verifies using req.rawBody
    express.json(), // Parses verified body into req.body
    webhookController.handleIncomingEvent
);

module.exports = router;

// src/controllers/messageController.js
const sinchService = require('../services/sinchService');

const sendMessageApi = async (req, res, next) => {
    const { to, type, text, templateId, params } = req.body;

    if (!to || !type) {
        return res.status(400).json({ error: 'Missing required fields: "to" and "type"' });
    }

    // Validate E.164 phone number format
    if (!/^\+?[1-9]\d{1,14}$/.test(to)) {
         return res.status(400).json({ error: 'Invalid phone number format. Use E.164 (e.g., +14155552671)' });
    }

    try {
        let result;

        if (type === 'text') {
            if (!text) {
                return res.status(400).json({ error: 'Missing "text" field for type "text"' });
            }
            console.log(`API request to send text to ${to}`);
            result = await sinchService.sendTextMessage(to, text);

        } else if (type === 'template') {
            if (!templateId) {
                return res.status(400).json({ error: 'Missing "templateId" field for type "template"' });
            }
            if (params && !Array.isArray(params)) {
                 return res.status(400).json({ error: '"params" must be an array of strings' });
            }
            const templateParams = params || [];
            console.log(`API request to send template ${templateId} to ${to}`);
            result = await sinchService.sendTemplateMessage(to, templateId, templateParams);

        } else {
            return res.status(400).json({ error: 'Invalid message type. Use "text" or "template"' });
        }

        // Store sent message in database

        return res.status(200).json({
            success: true,
            message: 'Message sent successfully',
            messageId: result.message_id,
            conversationId: result.conversation_id
        });

    } catch (error) {
        console.error('Error in sendMessageApi:', error);
        const statusCode = error.statusCode || 500;
        return res.status(statusCode).json({
            success: false,
            error: error.message || 'Failed to send message'
        });
    }
};

module.exports = {
    sendMessageApi
};