API de WhatsApp

Documentación interna para desarrolladores. Esta página cubre la integración de la API de WhatsApp Business: ciclo de vida de la sesión, arquitectura de webhook y patrones de enrutamiento. No está destinado a usuarios finales.

​

Mapa de ruta

​

Descripción general de la arquitectura

WhatsApp Business API (Meta)
        ↓ (webhook POST)
/api/whatsapp/webhook
        ↓
Message routing middleware
        ↓
┌─────────────────────────────┐
│ AI Employee handles message │
│   (via @zappway/lib/...    │
│    conversation engine)     │
└─────────────────────────────┘
        ↓ (if AI replies)
Send message via WABA API

​

Ciclo de vida de la sesión

​

1. Emparejamiento (código QR o número de teléfono)

​

2. Estados de sesión

​

3. Desconectar

// POST /api/whatsapp/disconnect { sessionId }
// Gracefully terminates WhatsApp session
// Marks session as disconnected in DB

​

Procesamiento de eventos de webhook

• URL HTTPS pública
• Verificado con el apretón de manos de desafío-respuesta de Meta

​

Asignación de agente

// POST /api/whatsapp/assign { sessionId, agentId }
// Associates a WhatsApp session with a specific AI Employee
// From that point, all incoming messages go to that agent

​

Resolución de conversación

// POST /api/whatsapp/resolve { conversationId }
// Marks conversation as resolved in ZappWay
// Does NOT send any message to WhatsApp

​

Devolución de llamada de Meta OAuth

User clicks "Connect WhatsApp" in settings
→ Redirect to Meta OAuth
→ Meta redirects to GET /api/whatsapp/callback?code=...&state=...
→ Server exchanges code for access token
→ Token stored encrypted in DB
→ Redirect to dashboard

​

Variables de entorno necesarias

​

Problemas conocidos / Problemas

• Reenvío de webhook: Meta reintenta la entrega de webhook si su servidor no devuelve 2xx. Garantice el procesamiento de mensajes idempotentes utilizando whatsapp_message_id como clave de desduplicación.
• Caducidad de la sesión: Las sesiones de WhatsApp (para números personales a través de API no oficial) caducan después de 20 días de inactividad. Las sesiones de Business API no caducan, pero los números de teléfono se pueden desconectar.
• Sondeo de código QR: El código QR tiene una duración breve (~60 segundos). La interfaz debe regenerarse si caducó antes del escaneo.
• Límites de tarifas: La API de WhatsApp Business aplica límites de tarifas por número de teléfono para los mensajes salientes. Supervise los errores 131056 (límite de tasa de spam).
• Ventana de mensajería de 24 horas: Las empresas solo pueden enviar mensajes de forma proactiva a los usuarios que enviaron mensajes dentro de las últimas 24 horas (sin plantillas previamente aprobadas).