🤖

AI-агент для WhatsApp: создание бота с искусственным интеллектом

Полное руководство по созданию интеллектуального бота для WhatsApp на Python: регистрация в Meta, Webhook-сервер на FastAPI, подключение LLM (OpenAI/DeepSeek) и деплой в продакшен

🤖 AI-агенты ⏱ 25 мин
Архитектура AI-бота для WhatsApp 👤 Пользователь WhatsApp WhatsApp Cloud API graph.facebook.com Webhook FastAPI verify + process LLM-агент OpenAI / DeepSeek API 🗄 Память/БД Redis / SQLite HTTP POST /webhook запрос ответ HTTPS (ngrok / Docker + Nginx) | Токен доступа Meta | verify_token для Webhook | System Prompt агента

Схема взаимодействия: пользователь пишет в WhatsApp → Cloud API пересылает на Webhook → агент анализирует через LLM → ответ возвращается пользователю

# 1. Регистрация приложения в Meta и получение токена доступа

Первый шаг — создание приложения в 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

# 2. Настройка Webhook-сервера на FastAPI

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"}

# 3. Отправка сообщений через WhatsApp Cloud API

Отправка ответа пользователю — 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()

# 4. Подключение LLM-агента: OpenAI, DeepSeek и системный промпт

Сердце 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

# 5. Обработка входящих сообщений и классификация интентов

Обработчик 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

# 6. Деплой на сервер: Docker, ngrok и HTTPS

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

# 7. Стоимость, лимиты WhatsApp Business API и альтернативы

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.

🔗 Полезные ссылки

📖 WhatsApp Cloud API Docs 🟢 whatsapp-web.js 📱 Twilio WhatsApp API 🤖 OpenAI API Reference 🧠 DeepSeek API Docs