Разработка мобильного чат-бота для WhatsApp
WhatsApp Business API — единственный официальный способ автоматизировать WhatsApp. Неофициальные библиотеки (whatsapp-web.js и подобные) нарушают ToS и приводят к бану номера. Официальный путь: регистрация в Meta Business Suite, получение доступа к Cloud API или On-Premises API, верификация номера телефона.
Два варианта WhatsApp Business API
Cloud API (Meta-hosted) — инфраструктура Meta, не нужно разворачивать свой сервер. Лимит: 1000 бесплатных бизнес-инициированных разговоров в месяц. Подходит для большинства.
On-Premises API — сервер на вашей инфраструктуре. Дороже в обслуживании, зато данные не покидают ваш контур — критично для здравоохранения и финансов в РФ.
Для обоих вариантов — регистрация через Meta for Developers, создание WhatsApp Business App, верификация бизнес-аккаунта.
Webhooks и обработка сообщений
Cloud API отправляет обновления на ваш HTTPS-эндпоинт:
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"}
Первый POST на /webhook при настройке — это верификация: Telegram GET-запрос с hub.challenge, который нужно вернуть verbatim. Без этого Meta не активирует webhook.
Типы сообщений и шаблоны
WhatsApp различает два типа разговоров:
- Пользователь-инициированный — пользователь написал первым, бот может отвечать любым текстом 24 часа
- Бизнес-инициированный — бот пишет первым, только через одобренные шаблоны
Шаблон (message_template) нужно создать и получить одобрение от Meta (обычно 1–2 дня). Шаблон с переменными:
{
"messaging_product": "whatsapp",
"to": "79001234567",
"type": "template",
"template": {
"name": "order_confirmation",
"language": { "code": "ru" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Иван" },
{ "type": "text", "text": "ORD-12345" }
]
}
]
}
}
Интерактивные сообщения (кнопки, списки) доступны в рамках 24-часового окна и не требуют шаблонов:
{
"type": "interactive",
"interactive": {
"type": "button",
"body": { "text": "Выберите действие" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "confirm", "title": "Подтвердить" } },
{ "type": "reply", "reply": { "id": "cancel", "title": "Отменить" } }
]
}
}
}
Медиа: изображения, документы, аудио
WhatsApp поддерживает отправку и приём изображений, документов, аудио, видео. Для входящих медиа — скачиваем по media_id:
async def download_media(media_id: str) -> bytes:
# Шаг 1: получить 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"]
# Шаг 2: скачать файл
r2 = await client.get(media_url, headers={"Authorization": f"Bearer {WHATSAPP_TOKEN}"})
return r2.content
Срок жизни медиа-ссылки — 5 минут после первого запроса. Скачивайте и кешируйте сразу.
Ограничения и особенности платформы
Нет возможности редактировать отправленное сообщение (в отличие от Telegram). Нельзя получить список контактов пользователя. Один номер телефона = один WABA (WhatsApp Business Account). Статусы доставки (sent, delivered, read) приходят через те же webhooks.
Rate limits: 80 сообщений в секунду на номер по умолчанию. При массовой рассылке через шаблоны — нужно постепенно увеличивать объём (warm-up).
Процесс работы
Регистрация Meta Business App и верификация бизнес-аккаунта. Настройка WABA и номера телефона. Разработка webhook-сервера. Создание и подача шаблонов на одобрение. Реализация диалоговых сценариев. Интеграция с CRM или внутренними системами. Тестирование через официальный тестовый номер Meta.
Ориентиры по срокам
Базовый бот с шаблонами и обработкой входящих сообщений — 2–3 недели. Полноценный conversational-бот с интеграцией CRM, медиа и мультиязычностью — 5–10 недель.