Розробка мобільного 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-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"}
Перший POST на /webhook під час налаштування — це верифікація: GET-запит з hub.challenge, який потрібно повернути дослівно. Без цього Meta не активує webhook.
Типи повідомлень та шаблони
WhatsApp розрізняє два типи розмов:
- Користувач-ініційований — користувач написав перший, бот може відповідати будь-яким текстом протягом 24 годин
- Бізнес-ініційований — бот пише перший, тільки через одобрені шаблони
Шаблон (message_template) потрібно створити і отримати схвалення від Meta (зазвичай 1–2 дні). Шаблон зі змінними:
{
"messaging_product": "whatsapp",
"to": "79001234567",
"type": "template",
"template": {
"name": "order_confirmation",
"language": { "code": "uk" },
"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.
Обмеження швидкості: 80 повідомлень на секунду на номер за замовчуванням. Для масової розсилки через шаблони — поступово збільшуйте обсяг (warm-up).
Процес розробки
Реєстрація Meta Business App та верифікація бізнес-аккаунту. Налаштування WABA та номера телефону. Розробка webhook-сервера. Створення та подання шаблонів на схвалення. Реалізація діалогових сценаріїв. Інтеграція з CRM або внутрішніми системами. Тестування через офіційний тестовий номер Meta.
Орієнтири за часом
Базовий бот з шаблонами та обробкою вхідних повідомлень — 2–3 тижні. Повнофункціональний conversational-бот з інтеграцією CRM, медіа та багатомовністю — 5–10 тижнів.