WhatsApp Chatbot Mobile Development
WhatsApp Business API is the only official way to automate WhatsApp. Unofficial libraries (whatsapp-web.js and similar) violate ToS and lead to account bans. The official path: register with Meta Business Suite, gain access to Cloud API or On-Premises API, verify your phone number.
Two WhatsApp Business API Options
Cloud API (Meta-hosted) — Meta's infrastructure, no need to deploy your own server. Limit: 1000 free business-initiated conversations per month. Suits most use cases.
On-Premises API — server on your infrastructure. More costly to maintain, but data never leaves your control — critical for healthcare and finance in regulated markets.
For both options — register via Meta for Developers, create a WhatsApp Business App, and verify your business account.
Webhooks and Message Processing
Cloud API sends updates to your HTTPS endpoint:
from fastapi import FastAPI, Request
import httpx
app = FastAPI()
VERIFY_TOKEN = "your_verify_token"
WHATSAPP_TOKEN = "your_permanent_token"
PHONE_NUMBER_ID = "your_phone_number_id"
@app.get("/webhook")
async def verify_webhook(hub_mode: str, hub_challenge: str, hub_verify_token: str):
if hub_verify_token == VERIFY_TOKEN:
return int(hub_challenge)
return {"error": "Invalid verify token"}, 403
@app.post("/webhook")
async def receive_message(request: Request):
body = await request.json()
for entry in body.get("entry", []):
for change in entry.get("changes", []):
value = change.get("value", {})
for message in value.get("messages", []):
await handle_message(message, value.get("contacts", [{}])[0])
return {"status": "ok"}
The first POST to /webhook during setup is verification: a GET request with hub.challenge that you must return verbatim. Without this, Meta won't activate the webhook.
Message Types and Templates
WhatsApp distinguishes two conversation types:
- User-initiated — user messages first, bot can reply with any text for 24 hours
- Business-initiated — bot sends first, only via approved templates
A template (message_template) must be created and approved by Meta (typically 1–2 days). Template with variables:
{
"messaging_product": "whatsapp",
"to": "79001234567",
"type": "template",
"template": {
"name": "order_confirmation",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "John" },
{ "type": "text", "text": "ORD-12345" }
]
}
]
}
}
Interactive messages (buttons, lists) are available within the 24-hour window and don't require templates:
{
"type": "interactive",
"interactive": {
"type": "button",
"body": { "text": "Choose an action" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
{ "type": "reply", "reply": { "id": "cancel", "title": "Cancel" } }
]
}
}
}
Media: Images, Documents, Audio
WhatsApp supports sending and receiving images, documents, audio, and video. For incoming media — download using media_id:
async def download_media(media_id: str) -> bytes:
# Step 1: get URL
async with httpx.AsyncClient() as client:
r = await client.get(
f"https://graph.facebook.com/v18.0/{media_id}",
headers={"Authorization": f"Bearer {WHATSAPP_TOKEN}"}
)
media_url = r.json()["url"]
# Step 2: download file
r2 = await client.get(media_url, headers={"Authorization": f"Bearer {WHATSAPP_TOKEN}"})
return r2.content
Media URL lifetime is 5 minutes after the first request. Download and cache immediately.
Limitations and Platform Specifics
No ability to edit sent messages (unlike Telegram). Cannot retrieve user contact lists. One phone number = one WABA (WhatsApp Business Account). Delivery statuses (sent, delivered, read) arrive via the same webhooks.
Rate limits: 80 messages per second per number by default. For bulk template distribution — gradually increase volume (warm-up).
Development Process
Registering Meta Business App and verifying business account. Setting up WABA and phone number. Developing webhook server. Creating and submitting templates for approval. Implementing dialog flows. CRM or internal system integration. Testing via Meta's official test number.
Timeline Estimates
A basic bot with templates and incoming message handling — 2–3 weeks. A full conversational bot with CRM integration, media, and multi-language support — 5–10 weeks.