Build Production WhatsApp & SMS Integration with Vonage, Node.js & Express

[ User ] <---- SMS/WhatsApp ----> [ Vonage Platform ] <---- API Calls/Webhooks ----> [ Your Node.js/Express App ] <---- Prisma ----> [ PostgreSQL DB ]
    ^                                    |
    |--- ( ngrok tunnel during dev ) ----|

# Create a new directory for your project
mkdir vonage-messaging-app
cd vonage-messaging-app

# Initialize a new Node.js project
npm init -y

# Install runtime dependencies
npm install express @vonage/server-sdk dotenv pg @prisma/client

# Install development dependencies (Prisma CLI, nodemon for auto-restarts)
npm install --save-dev prisma nodemon

npx prisma init --datasource-provider postgresql

# .env

# Database Connection (Adjust based on your PostgreSQL setup)
# Example: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
DATABASE_URL="postgresql://your_db_user:your_db_password@localhost:5432/vonage_messages?schema=public"

# Vonage API Credentials
VONAGE_API_KEY="YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET="YOUR_VONAGE_API_SECRET"

# Vonage Application Credentials
VONAGE_APPLICATION_ID="YOUR_VONAGE_APPLICATION_ID"
# Path relative to your project root where you save the private key
VONAGE_PRIVATE_KEY_PATH="./private.key"

# Vonage Numbers / Senders
# Your Vonage virtual number capable of sending SMS
VONAGE_SMS_FROM_NUMBER="YOUR_VONAGE_SMS_NUMBER"
# Your Vonage WhatsApp Sender ID (often the same as SMS number or a dedicated one)
VONAGE_WHATSAPP_FROM_NUMBER="YOUR_VONAGE_WHATSAPP_NUMBER" # Use the sandbox number initially (e.g., 14157386102)

# Vonage Webhook Security
# Generate a secure random string for this
VONAGE_SIGNATURE_SECRET="YOUR_WEBHOOK_SIGNATURE_SECRET"

# Server Configuration
PORT=3000 # Or any port you prefer

# .gitignore

# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Environment Variables
.env

# Vonage Private Key
private.key

# Build Output (if applicable)
dist/
build/

# OS generated files
.DS_Store
Thumbs.db

vonage-messaging-app/
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── src/
│   ├── services/
│   │   └── vonage.service.js
│   ├── routes/
│   │   ├── api.routes.js
│   │   └── webhooks.routes.js
│   ├── middleware/
│   │   └── verifySignature.js
│   ├── controllers/
│   │   ├── message.controller.js
│   │   └── webhook.controller.js
│   ├── utils/
│   │   └── logger.js
│   ├── db.js          # Prisma client instance
│   └── server.js      # Express server setup
├── .env
├── .gitignore
├── package.json
├── package-lock.json
└── private.key        # <-- Store your downloaded private key here

{
  "name": "vonage-messaging-app",
  "version": "1.0.0",
  "description": "",
  "main": "src/server.js",
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "db:migrate": "npx prisma migrate dev",
    "db:generate": "npx prisma generate",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@prisma/client": "^5.x.x",
    "@vonage/server-sdk": "^3.x.x",
    "dotenv": "^16.x.x",
    "express": "^4.x.x",
    "pg": "^8.x.x"
  },
  "devDependencies": {
    "nodemon": "^3.x.x",
    "prisma": "^5.x.x"
  }
}

// src/db.js
const { PrismaClient } = require('@prisma/client');

const prisma = new PrismaClient();

module.exports = prisma;

// src/utils/logger.js
const logger = {
    log: (...args) => console.log('[LOG]', ...args),
    error: (...args) => console.error('[ERROR]', ...args),
    warn: (...args) => console.warn('[WARN]', ...args),
    info: (...args) => console.info('[INFO]', ...args),
};
module.exports = logger;

// src/services/vonage.service.js
require('dotenv').config(); // Ensure env vars are loaded
const { Vonage } = require('@vonage/server-sdk');
const { Message } = require('@vonage/server-sdk/dist/messages/message'); // Adjusted path if needed
const logger = require('../utils/logger'); // Import the logger
const prisma = require('../db');

// Initialize Vonage client with v3.x syntax (Promise-based)
const vonage = new Vonage({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET,
    applicationId: process.env.VONAGE_APPLICATION_ID,
    privateKey: process.env.VONAGE_PRIVATE_KEY_PATH,
});

/**
 * Sends a message via the Vonage Messages API.
 * @param {string} to - Recipient phone number (E.164 format).
 * @param {string} text - Message content.
 * @param {'sms' | 'whatsapp'} channel - Messaging channel.
 * @returns {Promise<object>} - The Vonage API response.
 */
async function sendMessage(to, text, channel) {
    const from = channel === 'sms'
        ? process.env.VONAGE_SMS_FROM_NUMBER
        : process.env.VONAGE_WHATSAPP_FROM_NUMBER;

    if (!from) {
        logger.error(`Vonage 'from' number/ID not configured for channel: ${channel}`);
        throw new Error(`Sender ID not configured for ${channel}`);
    }

    logger.info(`Attempting to send ${channel} message from ${from} to ${to}`);

    try {
        // Use the Message builder for flexibility
        const message = new Message(
            { type: 'text', text: text }, // Content
            { number: to },               // To
            { type: channel, number: from } // From
        );

        const response = await vonage.messages.send(message);
        logger.info('Message sent successfully:', response);

        // Store outbound message record (async, don't block response)
        prisma.message.create({
            data: {
                vonageMessageId: response.message_uuid,
                direction: 'outbound',
                channel: channel,
                to: to,
                from: from,
                text: text,
                status: 'submitted', // Initial status from Vonage
                timestamp: new Date(), // Use current time as submission time
            }
        }).catch(dbError => logger.error('Failed to save outbound message to DB:', dbError));


        return response; // Contains message_uuid
    } catch (error) {
        const errorData = error?.response?.data || { message: error.message };
        logger.error('Error sending Vonage message:', errorData);

        // Attempt to store failed submission
         prisma.message.create({
            data: {
                vonageMessageId: `failed_${Date.now()}`, // Placeholder ID
                direction: 'outbound',
                channel: channel,
                to: to,
                from: from,
                text: text,
                status: 'failed_submission',
                timestamp: new Date(),
                errorDetails: JSON.stringify(errorData),
            }
        }).catch(dbError => logger.error('Failed to save FAILED outbound message to DB:', dbError));

        throw error; // Re-throw for the controller to handle
    }
}

module.exports = {
    sendMessage,
    vonage // Export instance if needed elsewhere (e.g., for signature verification)
};

// src/server.js
require('dotenv').config();
const express = require('express');
const logger = require('./utils/logger');
const apiRoutes = require('./routes/api.routes');
const webhookRoutes = require('./routes/webhooks.routes');
const prisma = require('./db'); // Import to ensure connection pool is ready (optional)

const app = express();
const PORT = process.env.PORT || 3000;

// --- IMPORTANT: Raw Body Middleware for Webhook Verification ---
// This MUST come BEFORE the webhook routes are defined and BEFORE express.json()
// if you want the default JSON parser to run afterwards on those routes.
// However, it's safer to put it just before the webhook router is used.
// We will configure it more precisely in section 7.1.
// For now, let's use the standard JSON parser first.

// Standard Middleware
// Note: We will modify express.json() later in Section 7.1 for webhook signature verification
app.use(express.json()); // Parse JSON bodies
app.use(express.urlencoded({ extended: true })); // Parse URL-encoded bodies

// Simple Request Logger Middleware
app.use((req, res, next) => {
    logger.info(`${req.method} ${req.url}`);
    next();
});

// Routes
app.use('/api', apiRoutes);
app.use('/webhooks', webhookRoutes); // Webhook routes will include specific body parsing/verification

// Basic Root Route
app.get('/', (req, res) => {
    res.send('Vonage Messaging App is running!');
});

// Global Error Handler (Basic)
app.use((err, req, res, next) => {
    logger.error('Unhandled Error:', err);
    res.status(500).json({ error: 'Internal Server Error' });
});

// Start Server and store the server instance
const server = app.listen(PORT, () => {
    logger.log(`Server listening on port ${PORT}`);
    logger.log(`Local URL: http://localhost:${PORT}`);
    // Remind about ngrok for webhooks
    logger.warn('Remember to run ngrok and update Vonage webhook URLs if testing locally!');
    logger.warn(`Example ngrok command: ngrok http ${PORT}`);
});

// Graceful Shutdown (Optional but Recommended)
process.on('SIGTERM', async () => {
    logger.info('SIGTERM signal received. Closing HTTP server.');
    // Close the server (requires the 'server' variable assigned above)
    server.close(async () => {
        logger.info('HTTP server closed.');
        // Disconnect Prisma Client
        try {
            await prisma.$disconnect();
            logger.info('Prisma Client disconnected.');
        } catch (e) {
            logger.error('Error disconnecting Prisma:', e);
        } finally {
            process.exit(0);
        }
    });
});

// src/controllers/message.controller.js
const vonageService = require('../services/vonage.service');
const logger = require('../utils/logger');

async function handleSendMessage(req, res) {
    const { to, text, channel } = req.body;

    // Basic Validation
    if (!to || !text || !channel) {
        return res.status(400).json({ error: 'Missing required fields: to, text, channel' });
    }

    if (channel !== 'sms' && channel !== 'whatsapp') {
        return res.status(400).json({ error: 'Invalid channel. Must be "sms" or "whatsapp".' });
    }

    // Decide whether to reject or attempt anyway based on format
    // Stricter E.164 format check (requires '+', country code, and subscriber number)
    if (!/^\+\d{10,15}$/.test(to)) {
        logger.error(`Invalid 'to' number format received: ${to}`);
        return res.status(400).json({ error: 'Invalid "to" number format. Use E.164 standard (e.g., "+15551234567").' });
    }


    try {
        const response = await vonageService.sendMessage(to, text, channel);
        res.status(202).json({ // 202 Accepted - request initiated
            message: `Message sending initiated via ${channel}.`,
            message_uuid: response.message_uuid
        });
    } catch (error) {
        logger.error(`Failed to send message via API: ${error.message}`);
        // Determine appropriate status code based on error type if possible
        const statusCode = error.response?.status || 500;
        const errorDetails = error.response?.data?.title || error.message;
        res.status(statusCode).json({
            error: 'Failed to send message',
            details: errorDetails
        });
    }
}

module.exports = {
    handleSendMessage,
};

// src/routes/api.routes.js
const express = require('express');
const messageController = require('../controllers/message.controller');
// Add rate limiting later (Section 7)

const router = express.Router();

// POST /api/send-message
router.post('/send-message', messageController.handleSendMessage);

// Add a simple health check endpoint
router.get('/health', (req, res) => {
    res.status(200).json({ status: 'UP' });
});


module.exports = router;

curl -X POST http://localhost:3000/api/send-message \
-H "Content-Type: application/json" \
-d '{
  "to": "+15551234567",
  "text": "Hello from Node.js via Vonage SMS!",
  "channel": "sms"
}'

curl -X POST http://localhost:3000/api/send-message \
-H "Content-Type: application/json" \
-d '{
  "to": "+15551234567",
  "text": "Hello from Node.js via Vonage WhatsApp Sandbox!",
  "channel": "whatsapp"
}'

{
  "message": "Message sending initiated via sms.",
  "message_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

{
  "error": "Invalid \"to\" number format. Use E.164 standard (e.g., \"+15551234567\")."
}

{
  "error": "Failed to send message",
  "details": "Authentication failure"
}

# Replace 3000 if you used a different PORT in .env
ngrok http 3000

Session Status                online
Account                       Your Name (Plan: Free)
Version                       x.x.x
Region                        United States (us-cal-1)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://xxxxxxxxxxxx.ngrok-free.app -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

// In vonage.service.js (already added)
logger.info('Message sent successfully:', response);
logger.error('Error sending Vonage message:', error?.response?.data || error.message);

// In message.controller.js (already added)
logger.error(`Failed to send message via API: ${error.message}`);

// In webhook controller (add in Section 6)
logger.info('Received inbound message webhook:', JSON.stringify(req.body, null, 2));
logger.error('Error processing inbound webhook:', error);

// prisma/schema.prisma

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

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Message {
  id              String    @id @default(cuid()) // Unique ID for the DB record
  vonageMessageId String    @unique // The UUID from Vonage (important for idempotency)
  direction       String    // 'inbound' or 'outbound'
  channel         String    // 'sms', 'whatsapp', etc.
  from            String    // Sender number/ID (E.164 or WhatsApp ID)
  to              String    // Recipient number/ID (E.164 or WhatsApp ID)
  text            String?   // Message content (nullable if it's not text)
  status          String    // Vonage status (e.g., 'submitted', 'delivered', 'read', 'inbound', 'failed')
  timestamp       DateTime  // Timestamp from Vonage webhook or submission time
  errorDetails    Json?     // Store error info if status is 'failed' or 'rejected'
  imageUrl        String?   // Store image URL for MMS/WhatsApp images

  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt
}

# Ensure your DATABASE_URL in .env is correct and the DB is running
npm run db:migrate -- --name init-messages-table

npm run db:generate

// src/controllers/webhook.controller.js
const prisma = require('../db');
const logger = require('../utils/logger');

/**
 * Handles inbound message webhooks (/webhooks/inbound)
 */
async function handleInboundMessage(req, res) {
    const payload = req.body;
    logger.info('Received /inbound webhook:', JSON.stringify(payload, null, 2));

    // Respond quickly to Vonage
    res.status(200).send('OK');

    // --- Asynchronous Processing ---
    (async () => {
        try {
            // Basic validation - ensure essential fields exist
            if (!payload.message_uuid || !payload.from || !payload.to || !payload.channel) {
                logger.warn('Inbound webhook missing essential fields.', payload);
                return; // Don't process incomplete data
            }

            // Idempotency Check: See if we already processed this message UUID
            const existingMessage = await prisma.message.findUnique({
                where: { vonageMessageId: payload.message_uuid },
            });

            if (existingMessage) {
                logger.warn(`Duplicate inbound message webhook received: ${payload.message_uuid}. Ignoring.`);
                return;
            }

            // Extract sender/recipient numbers correctly (can be object or string)
            const fromNumber = typeof payload.from === 'object' ? payload.from.number : payload.from;
            const toNumber = typeof payload.to === 'object' ? payload.to.number : payload.to;

            // Determine text content, handling different payload structures
            let textContent = null;
            if (payload.message?.content?.type === 'text') {
                textContent = payload.message.content.text;
            } else if (payload.text) { // Fallback for older/different structures
                textContent = payload.text;
            }

            // Determine image URL, handling different payload structures
            let imageUrlContent = null;
            if (payload.message?.content?.type === 'image') {
                imageUrlContent = payload.message.content.url;
            } else if (payload.image?.[0]?.url) { // Fallback for potential alternative structure
                imageUrlContent = payload.image[0].url;
            }

            // Store the inbound message
            await prisma.message.create({
                data: {
                    vonageMessageId: payload.message_uuid,
                    direction: 'inbound',
                    channel: payload.channel,
                    from: fromNumber,
                    to: toNumber,
                    text: textContent,
                    status: 'inbound', // Custom status for received messages
                    timestamp: payload.timestamp ? new Date(payload.timestamp) : new Date(),
                    imageUrl: imageUrlContent,
                    // Add more fields from the payload if needed (e.g., payload.message.content for various types)
                },
            });
            logger.info(`Inbound message ${payload.message_uuid} saved to DB.`);

        } catch (error) {
            logger.error(`Error processing inbound webhook ${payload.message_uuid}:`, error);
            // Consider sending an alert here (e.g., to Sentry)
        }
    })(); // Immediately invoke the async function
}

/**
 * Handles message status webhooks (/webhooks/status)
 */
async function handleMessageStatus(req, res) {
    const payload = req.body;
    logger.info('Received /status webhook:', JSON.stringify(payload, null, 2));

     // Respond quickly to Vonage
    res.status(200).send('OK');

    // --- Asynchronous Processing ---
    (async () => {
        try {
            if (!payload.message_uuid || !payload.status) {
                 logger.warn('Status webhook missing essential fields.', payload);
                return;
            }

            // Find the original outbound message by Vonage UUID
            const message = await prisma.message.findUnique({
                where: { vonageMessageId: payload.message_uuid },
            });

            if (!message) {
                // This can happen if the webhook arrives before the initial send record is saved,
                // or if it's a status for an inbound message (which we might not track status for).
                logger.warn(`Received status update for unknown message UUID: ${payload.message_uuid}. Status: ${payload.status}`);
                return;
            }

            // Update the message status
            await prisma.message.update({
                where: { vonageMessageId: payload.message_uuid },
                data: {
                    status: payload.status.toLowerCase(), // Normalize status
                    timestamp: payload.timestamp ? new Date(payload.timestamp) : new Date(), // Update timestamp to status time
                    // Optionally store error details if the status indicates failure
                    errorDetails: (payload.status === 'failed' || payload.status === 'rejected') ? payload.error || payload : undefined,
                    updatedAt: new Date(), // Explicitly set updatedAt
                },
            });
            logger.info(`Updated status for message ${payload.message_uuid} to ${payload.status}.`);

        } catch (error) {
            logger.error(`Error processing status webhook ${payload.message_uuid}:`, error);
            // Consider sending an alert here
        }
    })(); // Immediately invoke the async function
}

module.exports = {
    handleInboundMessage,
    handleMessageStatus,
};

// src/routes/webhooks.routes.js
const express = require('express');
const webhookController = require('../controllers/webhook.controller');
// Webhook signature verification middleware will be added in Section 7

const router = express.Router();

// POST /webhooks/inbound - Receive incoming messages
router.post('/inbound', webhookController.handleInboundMessage);

// POST /webhooks/status - Receive message status updates
router.post('/status', webhookController.handleMessageStatus);

module.exports = router;

// Check if message UUID already exists before creating
const existingMessage = await prisma.message.findUnique({
    where: { vonageMessageId: payload.message_uuid },
});

if (existingMessage) {
    logger.warn(`Duplicate webhook: ${payload.message_uuid}. Ignoring.`);
    return;
}