WhatsApp Integration

Connect ChatRAG to WhatsApp using Bailey's (open-source WhatsApp Web API). Deploy on Fly.io or Koyeb and start messaging with your AI assistant.

Included in ChatRAG Monorepo

Bailey's WhatsApp integration is included in your ChatRAG fork at baileys-whatsapp/. Deploy it alongside your main app on Fly.io, Railway, or Render - no separate repository needed!

Provider Selection

ChatRAG supports multiple cloud providers for hosting Bailey's. Choose based on your preference:

Fly.io

Recommended

Edge computing with global distribution
Persistent volumes for session storage
Generous free tier for testing

Railway

Simple monorepo deployment
Automatic builds from Git
Easy environment configuration

Render

Infrastructure as Code (render.yaml)
Subdirectory support
Automatic scaling

Koyeb

Serverless with auto-scaling
Free tier available
GitHub integration

Setting Up Bailey's on Fly.io

Follow these steps to deploy the ChatRAG-ready Bailey's implementation on Fly.io.

Install Fly CLI

Install the Fly.io command-line tool:

macOS/Linux:

curl -L https://fly.io/install.sh | sh

Windows:

pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

Verify installation:

flyctl version

Sign Up and Authenticate

Create a Fly.io account and log in:

# Sign up (opens browser)
flyctl auth signup

# Or log in if you already have an account
flyctl auth login

You'll need to add a credit card, but Fly.io offers a generous free tier that's sufficient for testing and small-scale deployments.

Clone ChatRAG Bailey's Repository

Navigate to the Bailey's directory in your ChatRAG fork:

# Already included in your ChatRAG fork!
cd baileys-whatsapp

The baileys-whatsapp/ directory contains everything you need:

Pre-configured fly.toml for Fly.io
Production-ready Dockerfile
Webhook integration
Session persistence
QR code generation

Launch Fly.io Application

Initialize and deploy your Bailey's instance:

# Launch the app (follow the prompts)
flyctl launch

# When prompted:
# - App name: choose a unique name (e.g., baileys-chatrag)
# - Region: select closest to your users
# - Postgres: No
# - Redis: No

Configuration Notes

The repository includes a pre-configured fly.toml file with:

Node.js runtime settings
Volume mounts for session storage
Health check endpoints
HTTP service configuration

Create Persistent Volume

Create a volume to store WhatsApp session data:

# Create volume for session persistence
flyctl volumes create baileys_data --size 1 --region <your-region>

# Example:
flyctl volumes create baileys_data --size 1 --region iad

Critical: Configure Mounts in fly.toml

Ensure your fly.toml includes the mounts configuration:

[mounts]
  source = "baileys_data"
  destination = "/app/baileys_auth_info"
  processes = ["app"]

This mounts the persistent volume to the auth directory, ensuring your WhatsApp sessions survive deployments and restarts.

Deploy the Application

Deploy your Bailey's instance:

# Deploy to Fly.io
flyctl deploy

# Your app will be available at:
# https://your-app-name.fly.dev

Configure ChatRAG

Update your ChatRAG configuration with the Fly.io URL:

# Open Config UI
npm run config

# Set these values:
WHATSAPP_PROVIDER=flyio
FLYIO_BAILEYS_URL=https://your-app-name.fly.dev
FLYIO_API_KEY=  # Optional: set if you configured auth

# Save and restart ChatRAG
npm run dev

Set Up Webhook

Configure the webhook so Bailey's can send messages to ChatRAG:

For local development (recommended):

Use ngrok to expose your local ChatRAG instance:

# Install ngrok: https://ngrok.com
# Start ngrok
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)
# Set in Config UI:
WHATSAPP_WEBHOOK_URL=https://abc123.ngrok-free.app
WHATSAPP_WEBHOOK_SECRET=chatrag-whatsapp-secret-2025

For production:

WHATSAPP_WEBHOOK_URL=https://your-chatrag-domain.com
WHATSAPP_WEBHOOK_SECRET=your-secure-secret

Setting Up Bailey's on Koyeb (Alternative)

If you prefer Koyeb over Fly.io, follow these steps:

Sign up at koyeb.com
Connect your GitHub account
Create a new app and select your ChatRAG fork
Set Root Directory to baileys-whatsapp
Configure build settings (Node.js, install dependencies)
Set environment variables if needed
Deploy and copy the generated URL
Configure ChatRAG with WHATSAPP_PROVIDER=koyeb

Setting Up Bailey's on Railway

Railway offers simple monorepo deployments with automatic builds. (See Railway Docs)

Step 1: Create Project

Go to railway.app and create a new project
Connect your ChatRAG GitHub repository
Select "Deploy from a subdirectory"

Step 2: Configure Service

In Railway dashboard → Service Settings:

Set Root Directory to baileys-whatsapp
Build Command: yarn install && yarn build
Start Command: node lib/server.js

Step 3: Add Environment Variables

In Variables section, add your webhook URL and any API keys needed.

Setting Up Bailey's on Render

Render supports monorepo deployments with YAML configuration. (See Render Docs)

Option A: render.yaml

Add to your repository root:

services:
  - type: web
    name: baileys-whatsapp
    env: node
    rootDir: baileys-whatsapp
    buildCommand: yarn install && yarn build
    startCommand: node lib/server.js
    envVars:
      - key: NODE_ENV
        value: production
      - key: PORT
        value: 8080

Option B: Manual Setup

Go to render.com → New → Web Service
Connect your ChatRAG repository
Set Root Directory to baileys-whatsapp
Build: yarn install && yarn build
Start: node lib/server.js

Connecting Your WhatsApp Account

Once Bailey's is deployed and configured, connect your WhatsApp account:

Step 1: Initiate Connection

In ChatRAG, navigate to WhatsApp settings and click "Connect WhatsApp"

Step 2: Scan QR Code

A QR code will appear. Open WhatsApp on your phone:

Go to Settings → Linked Devices
Tap "Link a Device"
Scan the QR code displayed in ChatRAG

Step 3: Confirm Connection

Once scanned, your WhatsApp will be connected to ChatRAG. You'll see a "Connected" status.

Step 4: Test Messaging

Send a test message from WhatsApp to verify the integration:

Send a message to any contact
ChatRAG should receive and process it
AI response will be sent back via WhatsApp

WhatsApp Features

Multi-Device Support

Use WhatsApp on phone while ChatRAG handles messages

Session Persistence

Stay connected across deployments and restarts

Auto-Reconnection

Automatically reconnects if connection drops

Message Queue

Handles message bursts with configurable queue size

Webhook Delivery

Reliable message delivery with tracking

Health Monitoring

Track connection status and uptime

Configuration Options

Basic Settings

NEXT_PUBLIC_WHATSAPP_ENABLED=true
WHATSAPP_PROVIDER=flyio  # or koyeb
FLYIO_BAILEYS_URL=https://baileys-chatrag.fly.dev
WHATSAPP_WEBHOOK_URL=https://your-chatrag-url.com
WHATSAPP_WEBHOOK_SECRET=chatrag-whatsapp-secret-2025

AI Model Settings

WHATSAPP_DEFAULT_MODEL=openai/gpt-4o-mini
WHATSAPP_MAX_TOKENS=2048

Use concise models for WhatsApp to keep responses brief and mobile-friendly

Feature Toggles

WHATSAPP_ENABLE_MCP=false  # Enable MCP tools in WhatsApp
WHATSAPP_ENABLE_WEB_SEARCH=false  # Enable web search

Session & Queue Management

WHATSAPP_MAX_SESSIONS_PER_USER=5
WHATSAPP_MESSAGE_QUEUE_SIZE=10

Best Practices

Use WhatsApp-Optimized Prompts

Configure the "WhatsApp Conversational" system prompt template for concise, mobile-friendly responses

Monitor Connection Health

Regularly check the connection status in ChatRAG's WhatsApp settings

Keep Webhook URL Public

Ensure your webhook URL is accessible from the internet (use ngrok for local dev)

Limit Token Usage

Set WHATSAPP_MAX_TOKENS to a lower value (1024-2048) for faster, cheaper responses

Backup Session Data

Fly.io volumes persist data, but keep backups of your session credentials

Troubleshooting

QR code not generating

Solutions:

Verify Bailey's is deployed and accessible at your FLYIO_BAILEYS_URL
Check Fly.io logs: flyctl logs
Ensure the service is running: flyctl status
Restart the app: flyctl apps restart

Messages not reaching ChatRAG

Solutions:

Verify WHATSAPP_WEBHOOK_URL is publicly accessible
Check webhook secret matches on both sides
Test webhook endpoint: curl https://your-webhook-url/api/whatsapp/webhook
Check ChatRAG logs for webhook errors

Connection keeps dropping

Solutions:

Verify persistent volume is mounted correctly
Check Fly.io app isn't sleeping (scale to prevent auto-sleep)
Ensure phone has stable internet connection
Don't log out of WhatsApp Web on other devices

Responses are too slow

Solutions:

Lower WHATSAPP_MAX_TOKENS (try 1024-1500)
Use faster model (gpt-4o-mini instead of gpt-4)
Use WhatsApp-optimized system prompt
Deploy Fly.io app in region closer to users

WhatsApp Integration Architecture

ChatRAG's WhatsApp integration includes:

Provider Factory: Automatic provider selection (Fly.io/Koyeb)
Session Manager: Persistent WhatsApp Web sessions
Webhook Handler: Real-time message processing (27KB handler)
Message Converter: Format conversion between WhatsApp and ChatRAG
Connection Monitor: Health checks and auto-reconnection
12 API Endpoints: Full WhatsApp control (connect, disconnect, QR, status, etc.)

← Previous: MCP Integration Next: Branding & UI →