AI导哈

WhatsApp对话代理后端

一个基于Python的后端服务，通过WhatsApp Business API、MCP协议和OpenAI GPT实现智能对话代理功能，适用于业务咨询和数据处理场景。

  • by Julius266
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Julius266/MCP-Backend-Billease

使用说明

🤖 Backend WhatsApp con MCP + OpenAI

Backend de Python para crear un agente conversacional en WhatsApp que utiliza:

  • WhatsApp Business API (Meta) para mensajería
  • MCP (Model Context Protocol) para ejecutar herramientas/consultas a bases de datos
  • OpenAI GPT para generar respuestas en lenguaje natural

📋 Flujo del Sistema

Usuario envía: "¿Cuántos usuarios activos tengo?"
      ↓
[WhatsApp] → Webhook Meta
      ↓
[Backend] Recibe mensaje JSON
      ↓
[Backend] Detecta keyword "usuarios"
      ↓
[Backend] → MCP: POST /messages
            { method: "tools/call", params: { name: "read_users_preview" } }
      ↓
[MCP] Ejecuta query PostgreSQL (u otra herramienta)
      ↓
[MCP] → Backend: { result: "[{id:1, nombre:'Juan'}, ...]" }
      ↓
[Backend] → OpenAI: "Usuario pregunta: '¿Cuántos usuarios?' Contexto: [datos]"
      ↓
[OpenAI] → Backend: "Hay 50 usuarios activos en el sistema..."
      ↓
[Backend] → WhatsApp API (Meta)
      ↓
Usuario recibe: "Hay 50 usuarios activos en el sistema..."

🚀 Configuración

1. Instalar dependencias

pip install -r requirements.txt

2. Configurar variables de entorno

Edita el archivo .env:

# OpenAI API
OPENAI_API_KEY=sk-proj-tu_clave_aqui

# WhatsApp Meta API
WHATSAPP_TOKEN=EAAxxxxxxxxxxxx  # Token de acceso desde Meta Developers
WHATSAPP_PHONE_NUMBER_ID=123456789  # ID del número de teléfono
WHATSAPP_VERIFY_TOKEN=mi_token_secreto_123  # Token que tú elijas

# MCP Server
MCP_SERVER_URL=http://localhost:8080  # URL de tu servidor MCP

3. Obtener credenciales de WhatsApp (Meta)

  1. Ve a Meta for Developers
  2. Crea una app → Elige "WhatsApp Business"
  3. En la sección WhatsApp → Getting Started:
    • Copia el Token de acceso temporal → WHATSAPP_TOKEN
    • Copia el Phone number ID → WHATSAPP_PHONE_NUMBER_ID
  4. Para producción, genera un token permanente en System Users

4. Configurar webhook en Meta

  1. En Meta Developers → Tu App → WhatsApp → Configuration
  2. En Webhook:
    • Callback URL: https://tu-dominio.com/webhook/whatsapp
    • Verify token: El mismo que pusiste en WHATSAPP_VERIFY_TOKEN
    • Webhook fields: Marca messages
  3. Haz clic en Verify and Save

5. Exponer tu servidor local (desarrollo)

Para desarrollo local, usa ngrok:

ngrok http 8000

Copia la URL pública (ej: https://abc123.ngrok.io) y úsala como Callback URL en Meta.

6. Iniciar el servidor

python main.py

El servidor inicia en http://0.0.0.0:8000

🧪 Probar el sistema

Verificar salud del servidor

curl http://localhost:8000/health

Listar herramientas disponibles en MCP

curl http://localhost:8000/mcp/tools

Enviar mensaje de prueba desde WhatsApp

  1. Envía un mensaje al número de WhatsApp configurado
  2. Prueba con palabras clave como:
    • "¿Cuántos usuarios tengo?"
    • "Muéstrame la lista de clientes"
    • "Dame información de usuarios"

📁 Estructura del Proyecto

.
├── main.py                 # FastAPI app principal con webhooks
├── requirements.txt        # Dependencias Python
├── .env                    # Variables de entorno
└── services/
    ├── whatsapp.py        # Cliente de WhatsApp Meta API
    ├── mcp_client.py      # Cliente para conectar con MCP
    ├── llm_service.py     # Cliente de OpenAI GPT
    └── chat_manager.py    # (Vacío - para futuras mejoras)

🔧 Personalización

Agregar más palabras clave para MCP

Edita main.py en la función process_user_message:

keywords_mcp = ["usuarios", "clientes", "datos", "ventas", "reportes"]

Cambiar modelo de OpenAI

Edita services/llm_service.py:

model="gpt-4-turbo"  # o "gpt-3.5-turbo" para más velocidad

Llamar diferentes herramientas del MCP

Edita main.py:

# Para llamar otra herramienta:
sales_data = mcp.call_tool("get_sales_report", {"period": "monthly"})

🐛 Troubleshooting

Error: "No se pudo conectar al servidor MCP"

✅ Verifica que tu servidor MCP esté corriendo en http://localhost:8080 ✅ Prueba: curl http://localhost:8080/messages -X POST

Error: "403 Verificación fallida" en webhook

✅ Verifica que WHATSAPP_VERIFY_TOKEN en .env coincida con el token en Meta Developers

Error: "Authorization failed" al enviar mensajes

✅ Verifica que WHATSAPP_TOKEN sea válido (tokens temporales expiran en 24hrs) ✅ Genera un token permanente para producción

No recibo mensajes

✅ Verifica que tu URL pública (ngrok) esté activa ✅ Verifica que en Meta → Webhooks esté suscrito a messages ✅ Revisa logs del servidor con python main.py

📚 Recursos

🔐 Seguridad en Producción

  • ✅ Usa tokens permanentes de WhatsApp
  • ✅ Valida webhooks con x-hub-signature-256 header
  • ✅ Usa HTTPS (no HTTP)
  • ✅ Mantén .env fuera del control de versiones
  • ✅ Limita rate limiting en endpoints públicos

📝 Licencia

MIT

相关 MCP