WhatsApp Multilingual Chatbot

A production-ready WhatsApp chatbot built with Python + Flask + Claude AI that automatically detects and responds in the user's language from English to French, Swahili, Arabic, Spanish, Shona, and more.

Features

Feature	Details
Multilingual replies	Detects language automatically, responds in kind
Conversation memory	Remembers context across messages per user
Signature verification	Validates every request came from Meta
Async processing	Returns 200 immediately, prevents Meta retries
Rate limiting	Sliding window per-user throttle
Input sanitization	Strips whitespace, enforces max length
Retry logic	Exponential backoff on Claude 529 overload errors
Full test suite	17 pytest tests, Claude API mocked
Deploy-ready	Procfile for Railway / Render / Heroku

Project Structure

whatsapp-bot/
├── app/
│   ├── __init__.py
│   ├── main.py        # App factory — load_dotenv() + logging + startup validation
│   ├── routes.py      # Webhook endpoints + async processing + deduplication
│   ├── whatsapp.py    # Meta Graph API helpers (send, parse, mark-read)
│   ├── chatbot.py     # Claude AI + conversation memory + retry logic
│   └── security.py   # Signature verification + rate limiting + sanitization
├── tests/
│   └── test_app.py    # Full pytest suite (17 tests)
├── .env.example       # All required environment variables documented
├── requirements.txt
├── Procfile           # For Railway / Render / Heroku
└── README.md

Quick Start

1. Clone and install

git clone https://github.com/YOUR_USERNAME/whatsapp-multilingual-bot.git
cd whatsapp-multilingual-bot
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install --upgrade anthropic httpx #Only if you are using a Python version that is too new for the current packages  

2. Configure environment variables

cp .env.example .env
# Open .env and fill in all values

Variable	Where to get it
WHATSAPP_ACCESS_TOKEN	Meta Dev Console → WhatsApp → API Setup
WHATSAPP_PHONE_NUMBER_ID	Meta Dev Console → WhatsApp → API Setup
WHATSAPP_APP_SECRET	Meta Dev Console → App Settings → Basic
VERIFY_TOKEN	Choose your own secure random string
ANTHROPIC_API_KEY	https://console.anthropic.com

Generate a secure VERIFY_TOKEN:

python -c "import secrets; print(secrets.token_hex(32))"

3. Run locally

python -m app.main

4. Expose with ngrok

ngrok http 5000
# Copy the https://xxxx.ngrok.io URL

In Meta Developer Console → WhatsApp → Configuration → Webhook:

• Callback URL: https://xxxx.ngrok.io/webhook
• Verify Token: your VERIFY_TOKEN value
• Subscribe to: messages

5. Run tests

pytest tests/ -v

How It Works

WhatsApp User
     │
     ▼ sends message
Meta Cloud API  →  POST /webhook
     │
     ▼
routes.py
  1. Verify X-Hub-Signature-256    ← blocks spoofed requests
  2. Parse payload
  3. Return 200 OK immediately      ← prevents Meta retries
  4. Background thread:
       a. Deduplicate by message ID
       b. Rate limit check
       c. Sanitize input
       d. Mark message as read (blue ticks)
       e. Call Claude AI
       f. Send reply
     │
     ▼
chatbot.py
  - Retrieve conversation history
  - System prompt: "detect language, reply in same language"
  - Claude claude-sonnet-4 generates reply
  - Save to history
     │
     ▼
WhatsApp User ← receives reply in their language

Security Architecture

Layer	Implementation
Webhook authentication	HMAC-SHA256 signature verification (security.py)
Rate limiting	Sliding window per phone number (security.py)
Input validation	Length cap + whitespace sanitization (security.py)
Secret management	Environment variables only, never hardcoded
Duplicate prevention	Message ID dedup set in routes.py
Retry safety	Exponential backoff in chatbot.py

Deployment (Railway)

1. Push to GitHub
2. railway.app → New Project → Deploy from GitHub
3. Add all .env variables in the Variables tab
4. Railway detects Procfile and deploys automatically
5. Copy the deployment URL → update your Meta webhook URL

Supported Languages

English · French · Spanish · Portuguese · Arabic · Swahili · Shona · Ndebele · Zulu · Hausa · Yoruba · Igbo · Amharic · Hindi · Chinese · and any other language Claude supports.

Contact

Built by RootedDreamsBlog (https://www.rooteddreams.net) or read the full article on How to Build a WhtasApp Multilingual Chatbot at https://www.rooteddreams.net/build-whatsapp-multilingual-chatbot-python/

License

MIT