Hardening WhatsApp Bots for Production: WebSockets, Timeouts, and Reconnects

When we first deployed the custom WhatsApp bot for LoopLearnX, the initial architecture felt solid. We had a lightweight @whiskeysockets/baileys Node.js daemon running on a free-tier Oracle VPS, passing payloads to a Vercel serverless Next.js API for Gemini AI evaluation.

It worked flawlessly—until the first real-world network hiccup.

In production, networks drop, servers restart, and APIs time out. A bot that works perfectly on localhost will quickly unravel when exposed to the chaotic reality of mobile networks and distributed infrastructure.

This article details the exact failure points we encountered while running a production WhatsApp bot and the engineering strategies we implemented to harden the system against silent failures, infinite reconnection loops, and serverless timeouts.

The Architecture: Oracle VPS + Vercel

Before diving into the fixes, here is a quick recap of our architecture:

1. The Gateway (Oracle VPS): A PM2-managed Node.js process running Baileys. It maintains a 24/7 WebSocket connection to WhatsApp, intercepts messages, downloads media, and forwards structured JSON to our backend.
2. The Brain (Vercel): A Next.js serverless route that receives the webhook, queries Supabase for student context, sends images to Gemini-2.5-Flash for grading, and returns the response payload.

This split architecture is cost-effective and scalable, but it introduces network boundaries where things can (and will) go wrong.

1. The Zombie Socket (Heartbeats vs. Heuristics)

The Problem

WhatsApp WebSockets occasionally enter a "ghost connected" state. The Baileys library reports the connection as open, but incoming messages simply stop arriving.

Our initial fix was a heuristic "Deaf-Session Watchdog": If the bot claims to be connected but hasn't processed a message in 2 hours, force a reconnect.

The flaw? If it's a genuinely quiet night with zero student activity, the bot would unnecessarily sever and re-establish the connection every two hours, generating useless logs and risking WhatsApp rate limits.

The Fix: Direct Socket Polling

Instead of guessing based on message volume, we shifted to querying the underlying WebSocket state directly. Node.js WebSocket objects expose a readyState property.

// Check every 60 seconds
setInterval(() => {
    if (botStatus !== 'connected') return;

    // Check socket-level health directly
    const wsReadyState = sock?.ws?.readyState;
    
    // readyState 1 means OPEN. Anything else means the socket is dead.
    if (wsReadyState !== undefined && wsReadyState !== 1) {
        console.warn(`⚠️ WebSocket not OPEN (readyState: ${wsReadyState}) — forcing reconnect.`);
        botStatus = 'disconnected';
        if (sock) { try { sock.end(undefined); } catch (_) {} }
        scheduleReconnect();
    }
}, 60 * 1000);

This requires zero network traffic to WhatsApp's servers (it's a pure in-memory check) but instantly detects when the connection has silently dropped.

2. The Reconnection Storm (Exponential Backoff)

The Problem

When the Oracle VPS experienced a temporary network outage, Baileys immediately tried to reconnect. And failed. So it tried again 5 seconds later. And failed.

Within a 10-minute outage, the bot bombarded WhatsApp's servers with over 120 rapid-fire connection attempts. This aggressive behavior is a massive red flag for anti-spam systems and can easily lead to a permanent number ban.

The Fix: Circuit Breakers and Jitter

We replaced the fixed 5-second retry with an exponential backoff algorithm incorporating randomized jitter, capped at a maximum number of attempts.

let reconnectAttempts = 0;
const MAX_RECONNECT_ATTEMPTS = 10;

function getReconnectDelay() {
    const base = 5000;
    // 5s → 10s → 20s → 40s → 80s, capped at 120s
    const delay = Math.min(base * Math.pow(2, reconnectAttempts), 120000);
    // Add jitter to avoid thundering herd problems
    return delay + (Math.random() * 1000); 
}

function scheduleReconnect() {
    reconnectAttempts++;
    if (reconnectAttempts > MAX_RECONNECT_ATTEMPTS) {
        console.error(`🚨 Circuit breaker triggered. Manual restart required.`);
        sendErrorAlert('Bot offline: Max reconnects reached');
        return;
    }
    setTimeout(connectToWhatsApp, getReconnectDelay());
}

If the network is truly down, the bot gracefully backs off and eventually goes dormant, alerting an admin rather than getting itself banned.

3. The Silent Serverless Timeout

The Problem

Evaluating handwritten math homework via Gemini Vision takes time. Complex, multi-page submissions occasionally took up to 45 seconds to process.

We suddenly noticed students complaining that the bot was ignoring them. The VPS logs showed the request going out to Vercel, but no response ever came back.

The culprit was Vercel's default function execution limits. On many plans, if you don't explicitly declare a maxDuration, Vercel silently kills the execution after 10 to 15 seconds. The student receives absolute silence because the code that sends the fallback error message was also killed.

The Fix: maxDuration and Promise.race

First, explicitly tell Vercel to allow longer executions (Pro plans allow up to 300s).

// Add to the top of your Next.js API route
export const maxDuration = 120;

Second, never let the platform hard-kill your function. We wrapped the heavy AI workload in a Promise.race set to 55 seconds. If the AI takes too long, our code wins the race, catches the timeout, and sends a friendly message back to the student before Vercel shuts off the lights.

const timeoutMs = 55000; // 55 seconds

try {
    const result = await Promise.race([
        processWhatsAppSubmission({ phone, images }),
        new Promise<never>((_, reject) =>
            setTimeout(() => reject(new Error('EVALUATION_TIMEOUT')), timeoutMs)
        )
    ]);
    return NextResponse.json({ success: true, replyText: result.feedbackText });
    
} catch (error) {
    if (error.message === 'EVALUATION_TIMEOUT') {
        return NextResponse.json({
            success: false,
            replyText: '⏳ Evaluation is taking longer than usual. Please type DONE again in a moment.',
        });
    }
    // Handle other errors...
}

4. The Stuck State Machine (Retry Logic)

The Problem

Even with timeouts handled, APIs fail. If a network blip caused the Vercel API call to fail, the VPS logged the error and told the student "System error."

However, the database on Supabase still had the student's session marked as "Processing." When the student tried to submit again, the system was confused because the state machine had fractured.

The Fix: Transient Error Retries

Not all errors are fatal. We implemented a robust retry wrapper on the VPS side specifically for transient errors (like 502 Bad Gateway or 504 Gateway Timeout), while immediately failing on permanent errors (like 401 Unauthorized).

async function callApi(endpoint, body, retries = 2) {
    let lastError;
    for (let attempt = 0; attempt <= retries; attempt++) {
        try {
            const res = await axios.post(`${API_URL}${endpoint}`, body, { timeout: 90000 });
            return res.data;
        } catch (e) {
            lastError = e;
            const status = e.response?.status;
            
            // Never retry permanent errors
            if (status === 400 || status === 401 || status === 403) throw e;
            
            if (attempt < retries) {
                console.warn(`[API] Attempt ${attempt + 1} failed. Retrying in 5s...`);
                await new Promise(r => setTimeout(r, 5000));
            }
        }
    }
    throw lastError;
}

This simple loop eliminated 90% of our "System Error" complaints. The system quietly retries in the background, and the student just experiences a slightly longer loading time.

5. Security: Don't Expose Your Dashboard

We built a beautiful Express.js Command Center to run alongside the bot on port 3000, allowing us to view live logs and scan QR codes from a browser instead of SSHing into the server.

The glaring security hole? It was open to the public internet. Anyone who found the IP address could read student phone numbers in the live logs or trigger a session wipe.

A simple Express Basic Auth middleware is mandatory for utility endpoints:

const DASHBOARD_USER = process.env.DASHBOARD_USERNAME;
const DASHBOARD_PASS = process.env.DASHBOARD_PASSWORD;

function basicAuth(req, res, next) {
    if (!DASHBOARD_PASS) return next(); // Skip in local dev
    
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Basic ')) {
        res.setHeader('WWW-Authenticate', 'Basic realm="Bot Command Center"');
        return res.status(401).send('Authentication required.');
    }
    
    const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
    const [user, pass] = decoded.split(':');
    
    if (user !== DASHBOARD_USER || pass !== DASHBOARD_PASS) {
        res.setHeader('WWW-Authenticate', 'Basic realm="Bot Command Center"');
        return res.status(401).send('Invalid credentials.');
    }
    next();
}

app.use(basicAuth); // Protect all routes

Summary

Building a prototype WhatsApp bot is easy. Keeping it alive in production is a totally different discipline.

By implementing direct socket polling, exponential backoff, strict serverless timeout handling, and smart retry logic, we transformed our fragile prototype into a resilient infrastructure that handles thousands of automated homework evaluations without constant manual intervention.

When bridging persistent protocols (WebSockets) with ephemeral architectures (Serverless), always assume the network will fail, and design your failure states to be invisible to the end user.