ChatRAG

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.

Provider Selection

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

Fly.io

Recommended
  • Edge computing platform with global distribution
  • Low latency with regional deployments
  • Generous free tier for testing
  • Persistent volumes for session storage

Koyeb

  • Serverless platform with auto-scaling
  • Free tier available
  • Simple deployment process
  • GitHub integration

Setting Up Bailey's on Fly.io

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

1

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
2

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
3

Clone ChatRAG Bailey's Repository

Clone the ready-to-deploy Bailey's implementation:

git clone https://github.com/areia-ai/chatrag.git
cd chatrag
4

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
5

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

This ensures your WhatsApp sessions persist across deployments and restarts.

6

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
7

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
8

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:

  1. Sign up at koyeb.com
  2. Connect your GitHub account
  3. Create a new app and select the Bailey's repository
  4. Configure build settings (Node.js, install dependencies)
  5. Set environment variables if needed
  6. Deploy and copy the generated URL
  7. Configure ChatRAG with WHATSAPP_PROVIDER=koyeb

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:

  1. Go to Settings → Linked Devices
  2. Tap "Link a Device"
  3. 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
← Previous: MCP IntegrationNext: Branding & UI →