> ## 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 do WhatsApp

> Referência interna para integração da API do WhatsApp Business — gerenciamento de sessões, emparelhamento de código QR, processamento de eventos de webhook, roteamento de conversas e envio de mensagens.

> **Documentação interna para desenvolvedores.** Esta página aborda a integração da API do WhatsApp Business: ciclo de vida da sessão, arquitetura de webhook e padrões de roteamento. Não se destina a usuários finais.

***

## Mapa de rotas

| Método     | Ponto final                    | Arquivo manipulador                             | Tipo                                 |
| ---------- | ------------------------------ | ----------------------------------------------- | ------------------------------------ |
| `POST`     | `/api/whatsapp/create-session` | `whatsapp/create-session/route.ts`              | Configuração                         |
| `GET`      | `/api/whatsapp/qr-code`        | `whatsapp/qr-code/route.ts`                     | Configuração                         |
| `GET/POST` | `/api/whatsapp/sessions`       | `whatsapp/sessions/route.ts`                    | Sessão CRUD                          |
| `POST`     | `/api/whatsapp/assign`         | `whatsapp/assign/route.ts`                      | Atribuição de agente                 |
| `POST`     | `/api/whatsapp/disconnect`     | `whatsapp/disconnect/route.ts`                  | Desmontagem da sessão                |
| `POST`     | `/api/whatsapp/resolve`        | `whatsapp/resolve/route.ts`                     | Resolução de conversa                |
| `GET/POST` | `/api/whatsapp/status`         | `whatsapp/status/route.ts`                      | Saúde da conexão                     |
| `POST`     | `/api/whatsapp/start-pairing`  | `whatsapp/start-pairing/route.ts`               | Emparelhamento de número de telefone |
| `POST`     | `/api/whatsapp/webhook`        | (tratado via roteamento de webhook do WhatsApp) | Webhook                              |
| `GET`      | `/api/whatsapp/callback`       | `whatsapp/callback/route.ts`                    | Retorno de chamada OAuth (Meta)      |

***

## Visão geral da arquitetura

```
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 da sessão

### 1. Emparelhamento (código QR ou número de telefone)

Dois métodos de emparelhamento:

**Fluxo do código QR:**

```
POST /api/whatsapp/create-session
  → Initializes WhatsApp session
  → Returns session token

GET /api/whatsapp/qr-code?sessionId=...
  → Returns QR code as image/JSON
  → Frontend polls until scanned or expired
```

**Emparelhamento de número de telefone:**

```
POST /api/whatsapp/start-pairing { phoneNumber }
  → Initiates WhatsApp phone number pairing
  → Returns pairing code
```

### 2. Estados de sessão

| Estado         | Descrição                                  |
| -------------- | ------------------------------------------ |
| `initializing` | Sessão criada, ainda não conectada         |
| `qr_pending`   | Código QR gerado, aguardando digitalização |
| `connected`    | WhatsApp ativo e recebendo mensagens       |
| `disconnected` | A sessão terminou ou expirou               |
| `error`        | Falha na sessão — precisa ser recriada     |

### 3. Desconecte

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

***

## Processamento de eventos de webhook

O WhatsApp envia todos os eventos (mensagens, atualizações de status, confirmações de leitura) para o endpoint do webhook.

**Obrigatório para webhook:**

* URL HTTPS público
* Verificado com o handshake desafio-resposta do Meta

**Tipos de eventos tratados:**

| Tipo de Evento | Ação                                                   |
| -------------- | ------------------------------------------------------ |
| `messages`     | Direcione para o mecanismo de conversação, acione a IA |
| `statuses`     | Atualizar status de entrega/leitura de mensagens       |
| `contacts`     | Criar/atualizar registro de contato                    |

**Verificação de assinatura:**

```ts theme={null}
const signature = req.headers.get('x-hub-signature-256');
// Verify using HMAC-SHA256 with WHATSAPP_APP_SECRET
```

***

## Atribuição 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
```

***

## Resolução de conversa

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

***

## Retorno de chamada Meta OAuth

Ao conectar uma conta comercial do WhatsApp via OAuth da 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
```

***

## Variáveis ​​de ambiente necessárias

| Variável                   | Descrição                                                   |
| -------------------------- | ----------------------------------------------------------- |
| `WHATSAPP_APP_ID`          | Meta ID do aplicativo                                       |
| `WHATSAPP_APP_SECRET`      | Meta App Secret (assinatura de webhook + OAuth)             |
| `WHATSAPP_VERIFY_TOKEN`    | Token estático para handshake de verificação de webhook     |
| `WHATSAPP_PHONE_NUMBER_ID` | ID do número de telefone padrão (se for de locatário único) |
| `WHATSAPP_ACCESS_TOKEN`    | Usuário do sistema ou token de acesso do usuário            |

***

## Problemas conhecidos/pegadinhas

* **Reentrega do webhook:** Meta tenta novamente a entrega do webhook se o seu servidor retornar diferente de 2xx. Garanta o processamento de mensagens idempotentes usando `whatsapp_message_id` como chave de desduplicação.
* **Expiração da sessão:** As sessões do WhatsApp (para números pessoais via API não oficial) expiram após 20 dias de inatividade. As sessões da Business API não expiram, mas os números de telefone podem ser desconectados.
* **Pesquisa de código QR:** O código QR tem vida curta (cerca de 60 segundos). O front-end deve ser regenerado se expirar antes da verificação.
* **Limites de taxas:** A API do WhatsApp Business impõe limites de taxas por número de telefone para mensagens enviadas. Monitore erros `131056` (limite de taxa de spam).
* **Janela de mensagens de 24 horas:** As empresas só podem enviar mensagens proativamente aos usuários que enviaram mensagens nas últimas 24 horas (sem modelos pré-aprovados).