> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de WhatsApp

> Referencia interna para la integración de la API de WhatsApp Business: gestión de sesiones, emparejamiento de códigos QR, procesamiento de eventos de webhook, enrutamiento de conversaciones y envío de mensajes.

> **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

| Método     | Punto final                    | Archivo de controlador                                       | Tipo                                  |
| ---------- | ------------------------------ | ------------------------------------------------------------ | ------------------------------------- |
| `POST`     | `/api/whatsapp/create-session` | `whatsapp/create-session/route.ts`                           | Configuración                         |
| `GET`      | `/api/whatsapp/qr-code`        | `whatsapp/qr-code/route.ts`                                  | Configuración                         |
| `GET/POST` | `/api/whatsapp/sessions`       | `whatsapp/sessions/route.ts`                                 | Sesión CRUD                           |
| `POST`     | `/api/whatsapp/assign`         | `whatsapp/assign/route.ts`                                   | Asignación de agente                  |
| `POST`     | `/api/whatsapp/disconnect`     | `whatsapp/disconnect/route.ts`                               | Desmontaje de la sesión               |
| `POST`     | `/api/whatsapp/resolve`        | `whatsapp/resolve/route.ts`                                  | Resolución de conversación            |
| `GET/POST` | `/api/whatsapp/status`         | `whatsapp/status/route.ts`                                   | Estado de la conexión                 |
| `POST`     | `/api/whatsapp/start-pairing`  | `whatsapp/start-pairing/route.ts`                            | Emparejamiento de números de teléfono |
| `POST`     | `/api/whatsapp/webhook`        | (manejado a través del enrutamiento del webhook de WhatsApp) | Gancho web                            |
| `GET`      | `/api/whatsapp/callback`       | `whatsapp/callback/route.ts`                                 | Devolución de llamada de OAuth (Meta) |

***

## 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)

Dos métodos de emparejamiento:

**Flujo de códigos QR:**
***CÓDIGO\_BLOQUE\_1***

**Emparejamiento de números de teléfono:**
***CÓDIGO\_BLOQUE\_2***

### 2. Estados de sesión

| Estado         | Descripción                                       |
| -------------- | ------------------------------------------------- |
| `initializing` | Sesión creada, aún no conectada                   |
| `qr_pending`   | Código QR generado, pendiente de escaneo          |
| `connected`    | WhatsApp activo y recibiendo mensajes             |
| `disconnected` | La sesión finalizó o se agotó el tiempo de espera |
| `error`        | La sesión falló: necesita recreación              |

### 3. Desconectar

```ts theme={null}
// POST /api/whatsapp/disconnect { sessionId }
// Gracefully terminates WhatsApp session
// Marks session as disconnected in DB
```

***

## Procesamiento de eventos de webhook

WhatsApp envía todos los eventos (mensajes, actualizaciones de estado, confirmaciones de lectura) al punto final del webhook.

**Requerido para el webhook:**

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

**Tipos de eventos manejados:**

| Tipo de evento | Acción                                              |
| -------------- | --------------------------------------------------- |
| `messages`     | Ruta al motor de conversación, activa la IA         |
| `statuses`     | Actualizar el estado de entrega/lectura del mensaje |
| `contacts`     | Crear/actualizar registro de contacto               |

**Verificación de firma:**
***CÓDIGO\_BLOQUE\_4***

***

## Asignación de agente

```ts theme={null}
// 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

```ts theme={null}
// 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

Al conectar una cuenta empresarial de WhatsApp a través de OAuth de Meta:

```
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

| Variables                  | Descripción                                                           |
| -------------------------- | --------------------------------------------------------------------- |
| `WHATSAPP_APP_ID`          | ID de metaaplicación                                                  |
| `WHATSAPP_APP_SECRET`      | Secreto de metaaplicación (firma de webhook + OAuth)                  |
| `WHATSAPP_VERIFY_TOKEN`    | Token estático para el protocolo de enlace de verificación de webhook |
| `WHATSAPP_PHONE_NUMBER_ID` | ID de número de teléfono predeterminado (si es un solo inquilino)     |
| `WHATSAPP_ACCESS_TOKEN`    | Usuario del sistema o token de acceso de usuario                      |

***

## 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).