WhatsApp AI Chatbot - Baileys & FastAPI

Description

An intelligent WhatsApp chatbot using Baileys for connectivity and FastAPI with DSPy for AI processing.

How it works

This project allows you to create an AI assistant on WhatsApp that can:

• Intelligently respond to private and group messages
• Perform real-time web searches
• Remember previous conversations
• Filter authorized contacts to interact with the bot

The architecture is simple: WhatsApp messages go through a Node.js bot that forwards them to a Python FastAPI API. The AI (DSPy + Mistral) generates responses using conversation history and can perform automatic web searches. For security reasons or others (prompt injection, safety, etc.), a basic filter is placed before and after the generation module.

Diagram

flowchart TD
    A[🚀 WhatsApp Bot Startup] --> B[📋 Loading environment variables]
    B --> C[🔧 Configuring contact filters]
    C --> D[🔐 Initializing authentication]
    
    D --> E{Auth files exist?}
    E -->|No| F[📱 Generating QR Code]
    E -->|Yes| G[🔄 Automatic connection]
    
    F --> H[👤 User scans QR]
    H --> I[✅ Bot connected]
    G --> I
    
    I --> J[👂 Listening to events]
    J --> K[📨 New message]
    
    K --> L{Message from bot?}
    L -->|Yes| J
    L -->|No| M[📋 Extracting content]
    
    M --> N{Contact in EXCLUDED?}
    N -->|Yes| O[🚫 Message ignored]
    N -->|No| P{INCLUDED_ONLY defined?}
    
    P -->|No| Q[✅ Contact authorized]
    P -->|Yes| R{Contact in INCLUDED_ONLY?}
    R -->|No| O
    R -->|Yes| Q
    
    Q --> S[📖 Mark as read]
    S --> T{Private conversation?}
    
    T -->|Yes| U[💬 Direct processing]
    T -->|No| V{Bot mentioned or command?}
    V -->|No| W[🔇 Ignored in group]
    V -->|Yes| U
    
    U --> X[⌨️ Typing indicator]
    X --> Y[🚀 Calling FastAPI]
    Y --> Z[🧠 AI processing]
    
    Z --> AA[⏱️ Simulation delay]
    AA --> BB{AI success?}
    BB -->|No| CC[⚠️ Error message]
    BB -->|Yes| DD{Conversation type?}
    
    DD -->|Private| EE[📤 Simple message]
    DD -->|Group| FF[📤 Message with mention]
    
    EE --> J
    FF --> J
    CC --> J
    O --> J
    W --> J
    
    GG[❌ Disconnection] --> HH{Disconnection reason?}
    HH -->|Logout| II[🛑 Final stop]
    HH -->|Other| JJ[🔄 Reconnection]
    JJ --> D
    
    I -.-> GG
    
    style A fill:#e3f2fd
    style I fill:#c8e6c9
    style O fill:#ffcdd2
    style W fill:#ffcdd2
    style II fill:#ffcdd2
    style Z fill:#fff3e0
    style EE fill:#e8f5e8
    style FF fill:#e8f5e8

Loading

Visual overview of filter operation

Features

Conversational AI

• DSPy engine with Mistral AI (configurable)
• Integrated web search (Wikipedia + general search)
• Audio message transcription (voice notes and audio files)
• Persistent conversation history (SQLite)
• Input/output validation by AI

Conversation Management

• Private messages: Automatically responds
• Groups: Responds only when mentioned with @ or to commands /
• Contact filtering: Configurable inclusion/exclusion lists

Access Control

• INCLUDED_ONLY: List of only authorized numbers
• EXCLUDED: List of numbers to block completely
• Support for international formats with automatic normalization

Project Structure

whatsapp-simple-bot/
├── app.js                    # Main WhatsApp bot (Node.js)
├── .env                      # Contact filtering configuration
├── api/                      # FastAPI API (Python)
│   ├── main.py              # FastAPI server + AI logic
│   ├── chat_history.db      # SQLite database
│   ├── requirements.txt     # Python dependencies
│   └── .env                 # AI environment variables
├── auth_info_baileys/       # WhatsApp authentication data
└── package.json             # Node.js dependencies

Installation

Prerequisites

• Node.js
• Python 3
• Mistral API key (or other LLM provider)

Setup

git clone <repo-url>
cd whatsapp-simple-bot

# Node.js installation
npm install

# Python installation
cd api
pip install -r requirements.txt

Configuration

File api/.env:

MISTRAL_API_KEY=your_mistral_api_key

File .env (contact filtering):

This configuration allows defining who the bot should respond to or not

# Allow only these numbers (optional)
INCLUDED_ONLY=+33123456789,+33987654321

# Block these numbers (optional)
EXCLUDED=+33111111111,+33222222222

Startup

1. Launch the FastAPI API

cd api
python main.py

2. Launch the WhatsApp bot

node app.js

3. WhatsApp Authentication
   • Scan the displayed QR code
   • WhatsApp → Settings → Linked devices → Link a device

Usage

Private messages

The bot automatically responds to all private messages except those from contacts you define yourself

Group messages

The bot responds only when:

• It is mentioned with @

Contact filtering

Personal bot (family/friends only):

INCLUDED_ONLY=+33123456789,+33987654321
EXCLUDED=

Block spammers:

INCLUDED_ONLY=
EXCLUDED=+33111111111,+33999999999

Advanced Configuration

Changing AI model

In api/main.py:

# Mistral (default)
lm = dspy.LM("openai/mistral-small-latest", api_key="...")

# OpenAI
lm = dspy.LM("gpt-4", api_key="...")

# Local Ollama
lm = dspy.LM('ollama_chat/llama3', api_base='http://localhost:11434')

API Endpoints

• POST /chat: Message processing
• GET /health: API status
• GET /stats: Usage statistics
• DELETE /history/{user_id}: Clear history

Troubleshooting

The bot doesn't respond:

1. Check the API: curl http://localhost:8000/health
2. Check the API key in api/.env
3. Check the logs

WhatsApp issues:

1. Delete the auth_info_baileys folder
2. Restart and rescan the QR code

Planned Improvements

• Better project file organization
• FastAPI endpoints
• MCP support for more flexibility and interoperability
• Enhanced security with advanced filters (see Guardrails AI for example)
• Langraph for advanced use cases
• Audio transcription with Whisper
• Advanced Web Search
• Image analysis
• Document processing (PDF, Word)
• Google Calendar/Gmail integrations
• Advanced semantic search
• Parallel processing of time-consuming tasks with RabbitMQ-Celery to keep the bot functional and notify when a task is completed

About Baileys

Baileys is a TypeScript/JavaScript library that allows interacting with WhatsApp Web via WebSockets. It provides a lightweight alternative to Selenium-based or browser automation solutions for creating WhatsApp bots and applications.

Main Features

• Optimized performance: Consumes significantly fewer resources than browser-based solutions (about 500 MB RAM saved)
• Direct connection: Communication via WebSocket with WhatsApp Web servers
• Multi-device support: Compatible with WhatsApp's multi-device API
• Flexible authentication: QR code or pairing code for connection

Supported Features

Messaging:

• Text, image, video, document, audio messages
• Messages with mentions and quoted replies
• Receipt management
• Presence indicators ("typing", "online")

Contact and group management:

• Contact and group information
• Message metadata (sender, timestamp, etc.)
• Group administration (add/remove members, permissions)

Authentication and security:

• Persistent sessions with automatic saving
• Automatic reconnection on disconnection
• Real-time connection event management

Installation

npm install @whiskeysockets/baileys

Important Note

The maintainers discourage the use of Baileys for practices that violate WhatsApp's terms of service, particularly spam or mass automated messaging.

Warning

WARNING: This bot uses WhatsApp's unofficial API via Baileys. Intensive use may result in:

• Temporary or permanent ban of your WhatsApp number
• Restrictions on WhatsApp Business features
• Rate limits imposed by WhatsApp

Recommendations

• Respect delays (max 10-15 messages/minute)
• Personal/family use recommended rather than commercial
• Avoid spam and unwanted solicitations
• Monitor logs to detect restrictions

The author disclaims all responsibility for WhatsApp bans, data loss, or violations of terms of service resulting from the use of this project.

By using this code, you accept these risks knowingly.

License