# WhatsApp Flows

> Criar, publicar e mandar Flows, receber as respostas e usar o endpoint de data exchange do Messajo, que cuida da criptografia da Meta.

Um [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) é um formulário de várias telas que abre dentro do WhatsApp. O Messajo cria e publica o Flow na sua conta de mensagens, manda o Flow numa mensagem, entrega a resposta como evento e, se o Flow busca dados no seu sistema, **hospeda o endpoint** que a Meta chama: a criptografia RSA/AES fica com o Messajo e o seu servidor recebe JSON em texto claro, assinado.

## Antes de começar

- Uma conexão de WhatsApp ativa. O Flow pertence à conta de mensagens (WABA) dela.
- Chave com a permissão `templates` (criar, editar, publicar) e `read` (ler e ver as trocas).
- No webhook do app da Meta, o campo `flows` assinado.

## Criar e editar o JSON

```bash
curl https://api.messajo.com/v1/flows \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "name": "agendamento",
    "categories": ["APPOINTMENT_BOOKING"],
    "flow_json": { "version": "7.0", "screens": [ ... ] }
  }'
```

O Flow nasce `DRAFT` (`flw_…`). Categorias: `SIGN_UP`, `SIGN_IN`, `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY` e `OTHER`.

- `PUT /v1/flows/{id}/json` troca o JSON (corpo cru, até 10 MiB). O Messajo confere o básico (JSON válido, `version` e `screens`) e a Meta valida o resto: os erros dela voltam em `422` [`flow_invalid_json`](/errors#flow_invalid_json), com `details[].path` no formato `flow_json:<linha>:<coluna>`.
- Só um `DRAFT` muda. Publicado → `409` [`flow_not_editable`](/errors#flow_not_editable); faça `POST /v1/flows/{id}/clone` e edite a cópia.
- `POST /v1/flows/{id}/preview` devolve `preview_url` e `expires_at` para abrir o Flow no navegador.
- `POST /v1/flows/{id}/publish` publica; `…/deprecate` aposenta; `DELETE` apaga (só `DRAFT`); `…/sync` relê o status da Meta.

No painel, **Flows** tem a lista, o editor de JSON com prévia e o link para o construtor visual da Meta.

## Mandar o Flow

```json
{
  "connection_id": "conn_...",
  "to": "5511999990001",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "body": { "text": "Escolha o melhor horário" },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "flw_...",
        "flow_cta": "Agendar",
        "flow_action": "navigate",
        "flow_action_payload": { "screen": "INICIO" }
      }
    }
  }
}
```

`flow_id` aceita o `flw_…` do Messajo ou o id da Meta. `flow_cta` vai até 20 caracteres. Sem `flow_token`, o Messajo gera um (`mjft_…`) e guarda com o contato, a conversa e a mensagem, para o endpoint saber de quem é a troca. Um Flow num template (botão **FLOW**) funciona igual.

## Receber as respostas

Quando o contato termina o Flow, chegam `message.received` (conteúdo `reply` com `kind: "flow"`) e `flow.response`:

```json
{
  "type": "flow.response",
  "data": {
    "flow": { "id": "flw_...", "external_id": "1234567890", "name": "agendamento" },
    "flow_token": "mjft_...",
    "response": { "data": "2026-11-20", "horario": "09:00" },
    "message": { "id": "msg_..." },
    "contact": { "id": "ctc_..." },
    "conversation": { "id": "cnv_..." }
  }
}
```

Outros eventos: `flow.status_changed` (a Meta publicou, bloqueou ou limitou o Flow), `flow.endpoint_alert` (alerta de saúde do endpoint: taxa de erro, latência, disponibilidade) e `flow.endpoint_error` (o app do contato avisou um erro no endpoint).

## O endpoint de data exchange do Messajo

Flow que busca dados (tela dinâmica, validação, agendamento) precisa de um endpoint. Dê ao Flow um `endpoint` com a URL do **seu** handler:

```json
{ "endpoint": { "url": "https://app.suaempresa.com/flows/agendamento", "headers": [{ "name": "X-Tenant", "value": "loja-1" }] } }
```

O Messajo cadastra na Meta o endereço `https://api.messajo.com/meta/flows/<flw_id>` e devolve o `handler_secret` **uma vez** (gire com `POST /v1/flows/{id}/rotate-handler-secret`). Sem handler, um Flow com endpoint volta `422` [`flow_handler_required`](/errors#flow_handler_required). A URL do handler segue as regras dos [destinos](/webhooks/destinations/): `https` e endereço público.

A cada troca, a Meta chama o Messajo; o Messajo confere a assinatura da Meta, decifra, responde sozinho o `ping` e as notificações de erro, e repassa `INIT`, `BACK` e `data_exchange` para o seu handler:

```http
POST https://app.suaempresa.com/flows/agendamento
Content-Type: application/json
Messajo-Signature: t=1763000000,v1=5257a869…
Messajo-Flow-Id: flw_...
Messajo-Request-Id: req_...
User-Agent: Messajo-Flows/1

{
  "type": "flow.data_exchange",
  "flow": { "id": "flw_...", "external_id": "1234567890", "name": "agendamento" },
  "action": "data_exchange",
  "screen": "INICIO",
  "data": { "data": "2026-11-20" },
  "flow_token": "mjft_...",
  "context": { "connection_id": "conn_...", "contact_id": "ctc_...", "message_id": "msg_..." },
  "version": "3.0"
}
```

Responda `200` com a próxima tela, no formato da Meta:

```json
{ "screen": "HORARIOS", "data": { "horarios": [{ "id": "09", "title": "09:00" }] } }
```

- `context` vem `null` quando o Flow não saiu pelo Messajo (sem `flow_token` conhecido).
- `flow_token` que você não reconhece → responda `{ "error": "flow_token_invalid" }`: o Messajo devolve `427` à Meta e o app mostra que o Flow expirou.
- Tempo máximo do handler: **7 s**; resposta até 256 KiB. Erro, demora ou resposta sem `screen` → a Meta recebe `500` e o contato vê um erro genérico. Cada troca fica em `GET /v1/flows/{id}/exchanges` por 7 dias (sem os dados), com o resultado e o tempo.

### Verificar a assinatura do handler

O `Messajo-Signature` é igual ao dos webhooks, com o `handler_secret` como chave: HMAC-SHA256 de `${t}.${corpo cru}`, comparação em tempo constante e tolerância de 5 minutos. Detalhes em [Verificar a assinatura](/webhooks/verify-signature/).

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

<Code code={pythonSnippet} lang="python" title="verify.py" />

### Códigos que a Meta recebe

| HTTP | Quando | O que o app do contato faz |
|---|---|---|
| `200` | resposta cifrada | segue o Flow |
| `421` | o Messajo não decifrou com a chave atual nem com a anterior | baixa a chave pública de novo e repete |
| `427` | o handler respondeu `flow_token_invalid` | mostra que o Flow não vale mais |
| `432` | a assinatura da Meta (`X-Hub-Signature-256`) não confere | erro |
| `429` | mais de 1.200 trocas por minuto no Flow | erro |
| `500` | o handler falhou | erro genérico |

### Chave e rotação

A Meta cifra cada troca com a **chave pública da conta de mensagens**. O Messajo gera um par RSA 2048 na primeira vez que um Flow da conta usa o endpoint, envia a chave a todos os números ativos e confere todo dia se a Meta ainda tem a chave certa (reenvia sozinho se faltar). Para trocar: `POST /v1/connections/{id}/flow-key/rotate` (chave `admin`); a chave anterior continua decifrando por **24 horas**. Publicar sem a chave enviada a pelo menos um número → `409` [`flow_key_not_uploaded`](/errors#flow_key_not_uploaded).

Pelo [espelho](/operate/migrate/), `whatsapp_business_encryption` fica bloqueado (`403 mirror_path_blocked`) quando a chave é do Messajo, para ninguém trocar a chave por fora.

## Erros

| Código | Quando |
|---|---|
| [`flow_not_found`](/errors#flow_not_found) | o Flow não existe ou é de outra organização |
| [`flow_invalid_json`](/errors#flow_invalid_json) | JSON recusado (Meta `139001`) |
| [`flow_error`](/errors#flow_error) | outro erro `139xxx` da Meta |
