Полное руководство по созданию интеллектуального бота для WhatsApp на Python: регистрация в Meta, Webhook-сервер на FastAPI, подключение LLM (OpenAI/DeepSeek) и деплой в продакшен
Схема взаимодействия: пользователь пишет в WhatsApp → Cloud API пересылает на Webhook → агент анализирует через LLM → ответ возвращается пользователю
Первый шаг — создание приложения в Meta for Developers и подключение WhatsApp Business Platform. Вам понадобится аккаунт Facebook Business и верифицированный номер телефона (не привязанный к существующему WhatsApp-аккаунту). После регистрации вы получите phone_number_id и временный access_token, который в продакшене заменяется на постоянный системный токен.
# Шаги регистрации: # 1. Перейти на https://developers.facebook.com/ # 2. «Создать приложение» → Тип: «Business» # 3. Добавить продукт «WhatsApp» → «API Setup» # 4. Выбрать тестовый номер или зарегистрировать новый # 5. Скопировать Phone Number ID и Temporary Access Token # Данные, которые понадобятся далее: WHATSAPP_PHONE_NUMBER_ID="123456789012345" WHATSAPP_ACCESS_TOKEN="EAAx..." WHATSAPP_VERIFY_TOKEN="my_custom_verify_token_123" WHATSAPP_API_VERSION="v19.0" # Получение постоянного токена (System User): # Business Settings → System Users → Add → # Назначить роли: WhatsApp → Manage # Generate Token → выбрать приложение → Never expires
WhatsApp Cloud API отправляет входящие сообщения через Webhook — POST-запрос на ваш публичный HTTPS-эндпоинт. Сервер должен пройти верификацию через hub.verify_token и обрабатывать JSON-уведомления. Используем FastAPI — легковесный асинхронный фреймворк на Python.
from fastapi import FastAPI, Request, Query from fastapi.responses import PlainTextResponse import os, json, requests app = FastAPI() VERIFY_TOKEN = os.getenv("WHATSAPP_VERIFY_TOKEN", "my_token") # Webhook верификация (GET-запрос от Meta) @app.get("/webhook") async def verify_webhook( hub_mode: str = Query(alias="hub.mode"), hub_challenge: int = Query(alias="hub.challenge"), hub_verify_token: str = Query(alias="hub.verify_token"), ): if hub_mode == "subscribe" and hub_verify_token == VERIFY_TOKEN: return PlainTextResponse(str(hub_challenge)) return PlainTextResponse("Verification failed", status_code=403) # Обработка входящих сообщений (POST от Meta) @app.post("/webhook") async def webhook(request: Request): body = await request.json() # Извлекаем сообщение из entry → changes → messages for entry in body.get("entry", []): for change in entry.get("changes", []): messages = change.get("value", {}).get("messages", []) for msg in messages: sender = msg["from"] text = msg.get("text", {}).get("body", "") # Вызов AI-агента и отправка ответа await process_and_reply(sender, text) return {"status": "ok"}
Отправка ответа пользователю — HTTP POST к graph.facebook.com/{version}/{phone_number_id}/messages. Сообщение должно быть в формате шаблона (для инициации диалога) или текстовым ответом на входящее. Ниже — функция на Python с использованием requests и пример curl-команды для отладки.
# Curl для тестирования (замените токен и phone_number_id): curl -X POST "https://graph.facebook.com/v19.0/1234567890/messages" \ -H "Authorization: Bearer EAAx..." \ -H "Content-Type: application/json" \ -d '{"messaging_product":"whatsapp","to":"79161234567","text":{"body":"Привет! Ответ от бота"}}' # Python-функция отправки сообщения: import os, requests def send_whatsapp_message(to: str, text: str): """Отправляет текстовое сообщение пользователю WhatsApp.""" phone_number_id = os.getenv("WHATSAPP_PHONE_NUMBER_ID") access_token = os.getenv("WHATSAPP_ACCESS_TOKEN") api_version = os.getenv("WHATSAPP_API_VERSION", "v19.0") url = f"https://graph.facebook.com/{api_version}/{phone_number_id}/messages" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json", } payload = { "messaging_product": "whatsapp", "recipient_type": "individual", "to": to, "type": "text", "text": {"preview_url": False, "body": text}, } resp = requests.post(url, headers=headers, json=payload, timeout=15) return resp.json()
Сердце AI-бота — языковая модель, которая понимает запросы клиентов и генерирует осмысленные ответы. Подойдут OpenAI API (gpt-4o-mini — дёшево и быстро) или DeepSeek API (deepseek-chat — отличный русский язык). Важно правильно настроить system prompt и хранить историю диалога для контекста.
from openai import AsyncOpenAI import os, json from collections import defaultdict # Хранение истории диалога (user_id → список сообщений) chat_history = defaultdict(list) # Системный промпт — душа агента SYSTEM_PROMPT = """Ты — AI-ассистент интернет-магазина «ТехноДом». Твои задачи: 1. Отвечать на вопросы о товарах (цены, наличие, характеристики) 2. Помогать с оформлением заказа и доставкой 3. Принимать жалобы и направлять в поддержку Правила: - Отвечай кратко, на русском языке, дружелюбным тоном - Если клиент хочет заказать — собери: товар, количество, адрес - Если вопрос вне компетенции — предложи переключиться на оператора - НЕ придумывай цены — используй только известные данные - Максимальная длина ответа — 300 символов""" client = AsyncOpenAI( api_key=os.getenv("OPENAI_API_KEY"), # Для DeepSeek: base_url="https://api.deepseek.com/v1" ) async def ask_llm(user_id: str, user_message: str) -> str: """Отправляет сообщение в LLM и возвращает ответ агента.""" history = chat_history[user_id] # Добавляем сообщение пользователя в историю history.append({"role": "user", "content": user_message}) # Формируем полный контекст: system + история messages = [{"role": "system", "content": SYSTEM_PROMPT}] + history[-15:] response = await client.chat.completions.create( model="gpt-4o-mini", # или "deepseek-chat" messages=messages, temperature=0.7, max_tokens=300, ) answer = response.choices[0].message.content # Сохраняем ответ ассистента в историю history.append({"role": "assistant", "content": answer}) # Обрезаем историю, чтобы не росла бесконечно if len(history) > 20: chat_history[user_id] = history[-15:] return answer
Обработчик webhook получает сырой JSON от Meta. Нужно извлечь текст сообщения, определить интент пользователя (заказ, поддержка, FAQ), вызвать LLM и отправить ответ. Ниже — функция process_and_reply, которую мы вызывали в секции #2.
import re # Простая классификация интентов по ключевым словам def classify_intent(text: str) -> str: text_lower = text.lower() if re.search(r'заказ|купить|оформи|доставк|цена|стоимост', text_lower): return "order" elif re.search(r'проблем|ошибк|не работает|жалоб|вернут|брак', text_lower): return "support" else: return "faq" async def process_and_reply(sender_id: str, message_text: str): """Основной обработчик: классификация → LLM → ответ.""" if not message_text.strip(): return intent = classify_intent(message_text) # Модифицируем промпт под интент if intent == "order": prefix = "[ЗАКАЗ] Клиент хочет оформить заказ. " elif intent == "support": prefix = "[ПОДДЕРЖКА] Жалоба клиента. Если проблема серьёзная — предложи оператора. " else: prefix = "" # Получаем ответ от LLM-агента и отправляем reply = await ask_llm(sender_id, prefix + message_text) result = send_whatsapp_message(sender_id, reply) # Логирование (опционально) print(f"[{intent}] {sender_id}: {message_text[:50]} → {reply[:50]}") return result
WhatsApp Cloud API требует HTTPS-эндпоинт для Webhook. Для локальной разработки используйте ngrok (создаёт публичный HTTPS-туннель). Для продакшена — Docker-контейнер с FastAPI за Nginx (SSL через Let's Encrypt). Nginx проксирует запросы на внутренний порт FastAPI и обеспечивает HTTPS-терминацию.
# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] # requirements.txt fastapi==0.109.0 uvicorn[standard]==0.27.0 requests==2.31.0 openai==1.12.0 # docker-compose.yml version: "3.8" services: whatsapp-bot: build: . ports: - "8000:8000" env_file: .env restart: unless-stopped # Локальная разработка — ngrok (открывает HTTPS-туннель): ngrok http 8000 # Вывод: Forwarding https://abc123.ngrok-free.app -> http://localhost:8000 # Скопируйте https://abc123.ngrok-free.app/webhook в поле Callback URL # в настройках Webhook в Meta Developer Console
WhatsApp Business API использует модель оплаты за диалоги (conversation-based pricing), а не за отдельные сообщения. Бесплатные 1000 диалогов/месяц для тестового номера. Альтернативы — библиотека whatsapp-web.js (работает через WhatsApp Web, без Cloud API, но требует постоянного браузера) и Twilio API for WhatsApp (более высокий уровень абстракции, но дороже).
# Стоимость WhatsApp Cloud API (на 2026): # • Marketing-диалоги: ~$0.05/диалог (инициирует бизнес) # • Service-диалоги: ~$0.03/диалог (инициирует клиент) # • Authentication: ~$0.02/диалог (OTP, верификация) # • Бесплатно: 1000 диалогов/месяц для тестового номера # • Лимит: 250 сообщений/сек на номер (Business API) # Альтернатива 1: whatsapp-web.js (Node.js, не требует Cloud API) # Плюсы: бесплатно, работает с обычным WhatsApp Web # Минусы: нестабильно, нужен Puppeteer/браузер, риск блокировки номера npm install whatsapp-web.js qrcode-terminal # QR-код → сканировать телефоном → бот подключен к WhatsApp Web # Альтернатива 2: Twilio WhatsApp API # Плюсы: песочница бесплатно, простой REST API # Минусы: $0.005/сообщение, медленная верификация номера from twilio.rest import Client client = Client("ACCOUNT_SID", "AUTH_TOKEN") client.messages.create( from_="whatsapp:+14155238886", # Twilio sandbox to="whatsapp:+79161234567", body="Привет от Twilio бота!" )
Следуя этому руководству, вы создали полноценного AI-агента для WhatsApp с нуля: зарегистрировали приложение в Meta, настроили Webhook-сервер на FastAPI с верификацией, реализовали отправку сообщений через Cloud API и подключили LLM-модель (OpenAI или DeepSeek) для осмысленных диалогов. Бот хранит историю разговора, классифицирует интенты пользователя (заказ/поддержка/FAQ) и масштабируется через Docker.
Рекомендация: для стартапов и малого бизнеса — начинайте с Cloud API (1000 бесплатных диалогов/месяц хватит для тестирования). Для личных проектов и прототипов — whatsapp-web.js быстрее и не требует верификации номера. Продакшен-решениям — только Cloud API с постоянным токеном и HTTPS через Nginx + Let's Encrypt.