← Back to Blog
WhatsApp & Automation13 min read

Baileys WhatsApp Bot Tutorial (2026): Production Setup & Code

Learn to build a production-grade WhatsApp bot with Baileys, Node.js, and PM2. Step-by-step tutorial with rate-limiting, custom queues, and VPS deployment.

Naveen Gaur
Naveen Gaur
May 27, 2026

WhatsApp has become the default operating system for daily communication in regions like India. For modern web platforms—particularly in EdTech, local logistics, or localized services—forcing users to log into a complex desktop portal often results in a steep drop-off in user engagement.

When building LoopLearnX (an automated homework evaluation and tutoring tool for CBSE students), we realized that students rarely log in to a web dashboard on a desktop to upload their homework. Instead, they do their homework on physical notebooks, snap a picture, and expect instant grading.

LoopLearnX AI Homework Evaluation Dashboard Real-world implementation: The LoopLearnX student conversational interface and teacher assessment dashboard, driven by the custom Baileys gateway.

The LoopLearnX CBSE Evaluation Flow

  1. WhatsApp Submission: A student takes a photo of their handwritten maths or science homework and sends it directly to our WhatsApp bot JID.
  2. Buffer Stream Downloader: The headless Baileys daemon running on our Oracle VPS intercepts the payload, downloads the encrypted media buffer from WhatsApp servers, and streams it as a base64 payload to our serverless Next.js endpoint.
  3. Gemini AI Vision Evaluation: The serverless Next.js route triggers the Gemini-2.5-Flash API, feeding the base64 image along with structured CBSE grading schema. The model parses handwritten math symbols, evaluates correctness, and isolates the specific steps where the student made mistakes.
  4. Resilient Queued Delivery: The JSON response is saved to Supabase and dispatched back to the VPS queue, which uses a random 1.5–3.0 second human-like delay to send the homework feedback card to the student.

Integrating this custom, self-hosted WhatsApp interface directly into our Next.js application was not just a convenience—it was the single most critical driver of student engagement.

This guide details the technical blueprint of how we built a resilient, memory-aware WhatsApp AI Bot using @whiskeysockets/baileys and Next.js, hosted on an Oracle Cloud VPS. We will cover the exact production failures we encountered, lessons learned, and why custom self-hosting beats off-the-shelf agent frameworks.

[!NOTE] Quick Answer (TL;DR): Setting up @whiskeysockets/baileys in production requires:

  1. Persistent Authentication: Use useMultiFileAuthState to save credentials in a local storage container.
  2. Process Management: Deploy via PM2 (pm2 start index.js) on a VPS to ensure automatic connection restarts.
  3. Rate Limiting & Queue: Implement a message dispatch queue with random delays (1.5 - 3.0s) to simulate human sending speed and avoid WhatsApp API account bans.

⚡ Quick Start: 5-Minute Minimal Connection Setup

If you just want to get a Baileys client up and running locally, scan a QR code, and verify your connection, here is a minimal single-file script.

Step 1: Install Dependencies

Initialize a clean project and install the library along with the terminal QR code renderer:

mkdir whatsapp-quickstart && cd whatsapp-quickstart
npm init -y
npm install @whiskeysockets/baileys qrcode-terminal @hapi/boom pino

Step 2: Create quickstart.js

Create a file named quickstart.js and paste the following snippet:

// quickstart.js
const { default: makeWASocket, useMultiFileAuthState, DisconnectReason } = require("@whiskeysockets/baileys");
const { Boom } = require("@hapi/boom");
const qrcode = require("qrcode-terminal");

async function start() {
  // Save login credentials to 'auth_info' directory to avoid repeated scanning
  const { state, saveCreds } = await useMultiFileAuthState("auth_info");

  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: false, // We will manually draw it with qrcode-terminal
  });

  sock.ev.on("connection.update", (update) => {
    const { connection, lastDisconnect, qr } = update;
    
    // Generate QR code in terminal for scanner
    if (qr) {
      qrcode.generate(qr, { small: true });
    }

    if (connection === "close") {
      const shouldReconnect = (lastDisconnect.error instanceof Boom)
        ? lastDisconnect.error.output?.statusCode !== DisconnectReason.loggedOut
        : true;
      
      console.log("Connection closed. Reconnecting...", shouldReconnect);
      if (shouldReconnect) start();
    } else if (connection === "open") {
      console.log("✅ Baileys client connected successfully!");
    }
  });

  sock.ev.on("creds.update", saveCreds);

  // Echo back any incoming text message
  sock.ev.on("messages.upsert", async ({ messages, type }) => {
    if (type !== "notify") return;
    const msg = messages[0];
    if (!msg.message || msg.key.fromMe) return;

    const text = msg.message.conversation || msg.message.extendedTextMessage?.text;
    console.log(`Received message from ${msg.key.remoteJid}: ${text}`);

    if (text) {
      await sock.sendMessage(msg.key.remoteJid, { text: `Echo: ${text}` });
    }
  });
}

start();

Step 3: Run and Scan

Run the script and link your account:

node quickstart.js

Once the QR code prints in the terminal, open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the QR. Your terminal will display ✅ Baileys client connected successfully! and echo back any received text.

Why Choose @whiskeysockets/baileys for Custom WhatsApp Bots?

The Engagement Multiplier

For many demographics, WhatsApp represents friction-free engagement. Users don't need to remember passwords, manage active sessions, or learn a new user interface. By bringing our platform inside a messaging channel, we instantly enabled frictionless student homework submissions.

The Bot Core: Why Baileys?

To connect an application to WhatsApp, you have two primary routes:

  1. The Official WhatsApp Business Cloud API: Extremely restrictive, expensive (per-conversation pricing), and requires Facebook Business Verification. It strictly forbids sending arbitrary free-form text or non-template messages outside a 24-hour window.
  2. Baileys (@whiskeysockets/baileys): A high-performance, headless, WebSocket-based implementation of the WhatsApp Web protocol. It allows you to programmatically control a WhatsApp account (including standard consumer or business accounts) with full messaging flexibility, zero per-message charges, and native support for modern features like multi-file authentication state.

The Hybrid Architecture

To keep operations lightweight, we split the application into a two-tier architecture:

  • The Gateway (Ubuntu VPS): Runs a lightweight Node.js daemon using Baileys to maintain WebSocket connections with WhatsApp servers 24/7. It listens to incoming messages, handles media download streams, and converts payloads into clean base64 data to pass forward.
  • The Logic Engine (Vercel Serverless): A secure Next.js API route that handles heavy database transactions (Supabase), state transitions, and LLM evaluations (Gemini-2.5-Flash).
[Student WhatsApp]
       │
       ▼ (WebSocket 24/7 connection)
[Node.js VPS Gateway (Baileys + PM2)]
       │
       ▼ (HTTP POST with x-bot-secret)
[Next.js Serverless Route (Vercel)]
  ├── 1. Authenticate Request
  ├── 2. Query Student Profile & History (Supabase)
  ├── 3. Classify & Evaluate Intent (Gemini API)
  └── 4. Write new Submission Record (Supabase)
       │
       ▼ (JSON Reply)
[Node.js VPS Gateway (Safe Queued Output)] ──► Sent back to Student WhatsApp

Step-by-Step Node.js Code Walkthrough with Baileys

Part A: Setting up the Baileys Client (index.js)

The core responsibilities of index.js on the VPS are maintaining the WebSocket session, managing authentication states, rendering QR codes for linking, and mounting an Express endpoint to monitor status.

// index.js
require("dotenv").config();
const {
  default: makeWASocket,
  useMultiFileAuthState,
  DisconnectReason,
} = require("@whiskeysockets/baileys");
const { Boom } = require("@hapi/boom");
const pino = require("pino");
const express = require("express");
const qrcodeTerminal = require("qrcode-terminal");
const qrcode = require("qrcode");
const { handleIncomingMessage } = require("./bridge");

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

let sock = null;
let botStatus = "starting";
let currentQrImage = null;

async function connectToWhatsApp() {
  // 1. Initialize multi-file authentication state
  const { state, saveCreds } = await useMultiFileAuthState("auth_info_baileys");

  sock = makeWASocket({
    auth: state,
    printQRInTerminal: false, // We render custom QR inside terminal & web UI
    logger: pino({ level: "silent" }),
  });

  // 2. Listen for connection state updates
  sock.ev.on("connection.update", async (update) => {
    const { connection, lastDisconnect, qr } = update;

    if (qr) {
      botStatus = "qr_needed";
      // Render QR in terminal
      qrcodeTerminal.generate(qr, { small: true });
      // Generate Data URL QR for web UI status page
      currentQrImage = await qrcode.toDataURL(qr);
    }

    if (connection === "close") {
      const shouldReconnect =
        lastDisconnect?.error instanceof Boom
          ? lastDisconnect.error.output?.statusCode !==
            DisconnectReason.loggedOut
          : true;

      botStatus = shouldReconnect ? "disconnected" : "logged_out";
      console.log("Connection closed. Reconnecting...", shouldReconnect);

      if (shouldReconnect) {
        connectToWhatsApp();
      }
    } else if (connection === "open") {
      botStatus = "connected";
      console.log("✅ WhatsApp WebSocket Connected successfully!");
    }
  });

  // 3. Save updated credentials on session changes
  sock.ev.on("creds.update", saveCreds);

  // 4. Mount incoming message listener
  sock.ev.on("messages.upsert", async (m) => {
    if (m.type === "notify") {
      for (const msg of m.messages) {
        if (!msg.key.fromMe) {
          await handleIncomingMessage(sock, msg);
        }
      }
    }
  });
}

// Simple web UI endpoint for linking & status monitoring
app.get("/", (req, res) => {
  res.send(`
        <html>
        <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 100px;">
            <h1>LoopLearnX Bot Status</h1>
            <p>Current Status: <strong>${botStatus}</strong></p>
            ${botStatus === "qr_needed" && currentQrImage ? `<img src="${currentQrImage}" alt="Scan QR Code" />` : ""}
        </body>
        </html>
    `);
});

app.listen(PORT, () => {
  console.log(`Express status server running on port ${PORT}`);
  connectToWhatsApp();
});

Part B: Creating a Resilient Message Handler (bridge.js)

The bridge.js file handles payload filtering, captures typed text, and handles complex media streams.

One of the biggest issues in production is text messages arriving empty at Vercel. WhatsApp packs text differently based on messaging schemas. We wrote a nested parser that extracts text under all possible client payloads. Additionally, when receiving an image, the bot downloads the file buffer, converts it to base64, and triggers our serverless endpoint:

// bridge.js
const axios = require("axios");
const { downloadMediaMessage } = require("@whiskeysockets/baileys");

const API_URL = process.env.LOOPLEARN_API_URL;
const BOT_SECRET = process.env.WHATSAPP_BOT_SECRET;

async function handleIncomingMessage(sock, msg) {
  const jid = msg.key.remoteJid;
  if (!jid || jid.endsWith("@g.us")) return; // Skip group chats

  const phone = jid.replace("@s.whatsapp.net", "");
  const content = msg.message;

  const imageMsg = content?.imageMessage;
  const isText = !!(
    content?.conversation || content?.extendedTextMessage?.text
  );

  // 1. Text Message Processing Route
  if (isText) {
    const textBody =
      content?.conversation || content?.extendedTextMessage?.text || "";

    if (!textBody.trim()) return;

    await callApi("/api/whatsapp/receive", {
      phone,
      messageType: "text",
      textBody: textBody.trim(),
    })
      .then((data) => {
        if (data?.replyText) queueMessage(sock, jid, data.replyText);
      })
      .catch(() => {
        queueMessage(sock, jid, "⚠️ System check failed. Please try again.");
      });
    return;
  }

  // 2. Multimodal Photo Homework Route
  if (imageMsg) {
    queueMessage(
      sock,
      jid,
      "📸 Photo mila! Evaluate ho raha hai... thodi der ruko. ⏳",
    );

    let imageBuffer;
    try {
      // Securely download the encrypted media buffer from WhatsApp servers
      imageBuffer = await downloadMediaMessage(msg, "buffer", {});
    } catch (e) {
      console.error("Image download error:", e.message);
      queueMessage(sock, jid, "❌ Photo download fail. Please try again.");
      return;
    }

    const imageBase64 = imageBuffer.toString("base64");
    const mimeType = imageMsg.mimetype || "image/jpeg";

    await callApi("/api/whatsapp/receive", {
      phone,
      imageBase64,
      mimeType,
      messageType: "image",
    })
      .then((data) => {
        const reply =
          data?.replyText ?? "⚠️ Evaluation failed. Dobara try karo.";
        queueMessage(sock, jid, reply);
      })
      .catch((e) => {
        console.error("API error:", e.message);
        queueMessage(
          sock,
          jid,
          "⚠️ Server connection timeout. Please try again.",
        );
      });
    return;
  }
}

async function callApi(path, body) {
  const res = await axios.post(`${API_URL}${path}`, body, {
    headers: {
      "Content-Type": "application/json",
      "x-bot-secret": BOT_SECRET,
    },
    timeout: 90000, // 90-second timeout — Gemini Vision can be slow
  });
  return res.data;
}

Preventing WhatsApp Account Bans & Socket Crashes (Rate-Limiting Queues)

If your bot sends multiple API calls instantly to the same recipient or pushes bulk updates simultaneously, WhatsApp will trigger a session ban. We mitigated this risk using an asynchronous, rate-limited memory queue:

const sendQueue = [];
let sending = false;

function queueMessage(sock, jid, text) {
  sendQueue.push({ jid, text });
  processSendQueue(sock);
}

async function processSendQueue(sock) {
  if (sending || !sendQueue.length) return;
  sending = true;

  while (sendQueue.length) {
    const { jid, text } = sendQueue.shift();
    try {
      await sock.sendMessage(jid, { text });
    } catch (e) {
      console.error("WebSocket send error:", e.message);
    }
    // Artificial delay mimicking natural human interaction patterns
    await sleep(1500 + Math.random() * 1500);
  }
  sending = false;
}

Production VPS Deployment & Management

To run the Node.js Baileys gateway in a professional VPS environment, you must secure your server with PM2 process monitors and fail-safes.

Step 1: Install VPS Dependencies

Connect to your Ubuntu server:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pm2

Step 2: PM2 Configuration (ecosystem.config.js)

Create a custom configuration file. Warning: You must run only 1 instance to prevent authorization lock conflicts:

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: "looplearnX-bot",
      script: "index.js",
      instances: 1, // DO NOT USE MAX (Cluster mode breaks Baileys)
      autorestart: true,
      watch: false,
      max_memory_restart: "500M",
      restart_delay: 5000, // Wait 5s before rebooting on crash
      env: {
        NODE_ENV: "production",
      },
    },
  ],
};

Start the bot and make it persistent across system updates:

pm2 start ecosystem.config.js
pm2 save
pm2 startup

To monitor logs and check performance status:

pm2 logs looplearnX-bot
pm2 status

Why Build Custom Instead of Using Off-the-Shelf Agents (Hermes, Landbot)?

When setting up a WhatsApp integration, many teams consider wrapper services like Hermes, Coze, or standard flow builders like Landbot. Here is a technical breakdown of why we rejected off-the-shelf agents in favor of a custom Baileys/Next.js stack:

Evaluation MetricOff-The-Shelf Agents (e.g. Hermes, Landbot)Custom Self-Hosted Stack (Baileys + Next.js)
API & Database IntegrationRestricted to webhooks and limited UI components.Direct access to server-side Postgres (Supabase client), executing transactions natively.
Memory ArchitectureGeneric system chat history (context window size limitations).Custom Memory Context Routing. We query previous attempts for that exact homework plan ID and feed that specific context straight to Gemini.
Hinglish & Direct Tone TuningVery hard to enforce strict localized prompt guidelines consistently.Full controller prompts. The model speaks in second-person direct Hinglish ("Aapne" instead of "Student ne").
Pricing ScalingPer-message/per-run markup pricing (can grow to thousands of dollars).$0 SaaS Fees. You only pay for a $3 VPS (Oracle/Hetzner) and raw token consumption on Gemini API.

❓ Frequently Asked Questions (FAQ)

How do you prevent a WhatsApp account ban when using Baileys?

To prevent your bot from getting banned, you must implement a rate-limiting message queue. Avoid sending bulk messages concurrently, and inject artificial random delays (e.g., 1.5 to 3 seconds) between sent payloads to mimic natural human typing and sending patterns.

Does Baileys support multi-device authentication?

Yes, @whiskeysockets/baileys natively supports multi-device logins. It uses multi-file authentication state folders to store credentials, allowing the socket to reconnect automatically without scanning the QR code every session.

Summary

Integrating the Baileys WhatsApp Bot with Next.js on an Oracle Cloud VPS completely transformed the adoption curve of our LoopLearnX EdTech platform. Instead of fighting friction on desktops, students now have an active personal AI tutor in their pockets.

Self-hosting using Baileys gives you total database sovereignty, complete control over token pricing, and the ability to customize your conversational workflows with zero platform restrictions. The key to operational success is keeping your VPS thread-safe, deploying rate-limited queues, and handling serverless timeout boundaries gracefully.

Need a resilient, custom WhatsApp system integrated into your SaaS or enterprise product? Let’s hook up your database, optimize your hosting pipelines, and build a solid automation channel. Request a Free Scoping Audit here.

Related Case Studies & Guides

Get in Touch →

Leave a Comment

Comments are moderated before appearing on the site.

Need help with your WordPress site?

I fix WordPress crashes, remove malware, and optimize performance for small businesses. Fast turnaround, direct access, no agency overhead.

Get in Touch →