---
title: "WhatsApp Flows pela API: formulários e telas dentro da conversa"
description: "Como enviar um WhatsApp Flow pela API: o endpoint, os campos flowId e flowAction, e quando um formulário nativo bate um menu de texto ou uma lista."
url: "https://wame.api.br/blog/whatsapp-flows-api-formularios"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-16"
modified_time: "2026-09-16"
author: "Raphael Serafim"
keywords: "whatsapp flows api, formulario dentro do whatsapp, tela interativa whatsapp business api, criar flow whatsapp api, whatsapp flows exemplo, agendamento whatsapp flow, flows meta whatsapp"
reading_time: "7 min de leitura"
---

# WhatsApp Flows pela API: formulários e telas dentro da conversa

> Como enviar um WhatsApp Flow pela API: o endpoint, os campos flowId e flowAction, e quando um formulário nativo bate um menu de texto ou uma lista.

**WhatsApp Flow é uma tela de formulário nativa que abre dentro da conversa — o cliente preenche campos, navega entre passos e envia, sem sair do WhatsApp e sem abrir um link.** Pela API, você não desenha a tela na chamada: referencia um Flow já criado e aprovado, e manda uma mensagem interativa com o botão que o abre.

## Quando um Flow vale mais que uma lista ou um link

Antes de desenhar a tela, vale a pergunta inversa: o caso realmente precisa de um formulário nativo?

| Se você precisa de... | Use |
| --- | --- |
| Uma escolha simples entre poucas opções | [Botões ou lista](/blog/como-enviar-mensagem-whatsapp-api) |
| Confirmar ou cancelar algo | Botão de resposta rápida |
| Coletar vários campos (nome, endereço, data) numa etapa | **Flow** |
| Um formulário com passos condicionais (pergunta B só se A for "sim") | **Flow** |
| Uma página completa fora do WhatsApp (checkout de site) | Link externo |

Flow ganha exatamente no meio: quando um link externo seria fricção demais (o cliente sai do app, talvez não volte) mas botão e lista são simples demais para o que precisa ser coletado.

## O endpoint

O envio é um POST para o endpoint de mensagem de Flow da sua instância, com os campos que definem qual Flow abrir e como:

```bash
curl -X POST "https://server.wame.api.br/{key}/message/flow" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "flowId": "1605871230584440",
    "flowCta": "Agendar horário",
    "header": "Agende sua consulta",
    "body": "Toque no botão abaixo para escolher data e horário.",
    "footer": "Resposta em até 1 dia útil",
    "flowAction": "navigate",
    "screen": "WELCOME",
    "mode": "published"
  }'
```

Campo a campo:

| Campo | Obrigatório | O que faz |
| --- | --- | --- |
| `to` | Sim | Número do destinatário, com DDI |
| `flowId` | Sim | ID do Flow já criado e aprovado |
| `flowCta` | Sim | Texto do botão que abre a tela (ex: "Agendar horário") |
| `header` / `body` / `footer` | Não | Texto ao redor do botão, antes de abrir o Flow |
| `flowAction` | Não | `navigate` (abre a primeira tela) ou `data_exchange` (troca dados com seu backend a cada passo) |
| `screen` | Não | Tela inicial, quando o Flow tem mais de uma |
| `data` | Não | Dados que você já quer pré-preenchidos na tela |
| `mode` | Não | `draft` para testar antes de publicar, `published` em produção |

## `navigate` vs `data_exchange`

Essa é a decisão que muda a arquitetura do que você constrói:

**`navigate`** — o Flow é estático: as telas e a navegação entre elas já estão definidas na publicação, e no fim você recebe os dados coletados numa única mensagem de retorno. Serve bem para formulários fechados: cadastro, pesquisa de satisfação, coleta de dados de contato.

**`data_exchange`** — cada passo do Flow chama o seu endpoint, e a próxima tela pode depender da resposta. É o modo certo quando o formulário precisa de lógica: mostrar horários disponíveis de verdade (consultando sua agenda), validar um CEP, ou pular uma pergunta com base na resposta anterior.

```js
// Endpoint que o WhatsApp chama a cada passo, em modo data_exchange
app.post("/webhook/flow", async (req, res) => {
  const { screen, data } = req.body;

  if (screen === "ESCOLHER_DATA") {
    const horarios = await consultarAgendaDisponivel(data.dataEscolhida);
    return res.json({
      screen: "ESCOLHER_HORARIO",
      data: { horariosDisponiveis: horarios },
    });
  }

  // ...demais telas
});
```

## Recebendo a resposta

Quando o cliente conclui o Flow, os dados chegam pelo mesmo webhook onde chegam suas outras mensagens — como um evento do tipo `interactive`, com os campos preenchidos no corpo. O parser que você já usa para [ler mensagens no formato padrão da Meta](/blog/webhook-whatsapp-instagram-messenger-padrao-meta) só precisa reconhecer esse tipo adicional.

## Onde isso é útil de verdade

**Agendamento.** Data, horário e serviço numa tela só, sem trocar cinco mensagens de texto para chegar ao mesmo resultado — e sem o cliente esquecer de responder no meio, o problema que [lembretes com confirmação por botão](/blog/lembretes-agendamento-confirmacao-whatsapp) já reduz, mas um Flow resolve num passo a mais.

**Cadastro e atualização de dados.** Nome, endereço, CPF — campos estruturados, com validação, em vez de interpretar texto livre com IA para extrair a mesma informação.

**Pesquisa com lógica condicional.** NPS que só pergunta "o que faltou?" quando a nota é baixa, por exemplo — sem enviar uma sequência de mensagens de texto para simular o mesmo comportamento.

## Conclusão

Flow é a ferramenta certa quando o formulário tem mais de um ou dois campos, ou quando a navegação depende de lógica — abaixo disso, botão e lista continuam mais simples de implementar e de manter. A chamada pela API é direta: `flowId` do que já foi publicado, `flowCta` no texto do botão, e a escolha entre `navigate` e `data_exchange` decidindo se o formulário é estático ou conversa com seu backend em tempo real.

## Perguntas frequentes

### O que é um WhatsApp Flow?

É uma tela nativa que abre dentro da própria conversa do WhatsApp, com campos de formulário, seleção e navegação entre passos — sem sair do app e sem abrir um link externo. É usado para agendamento, pesquisa, cadastro e checkout guiado.

### Como envio um Flow pela API?

Você manda uma mensagem interativa referenciando o flowId (o identificador do Flow já criado e aprovado no Gerenciador do WhatsApp Business), junto com o texto do botão que abre a tela (flowCta). A API expõe isso como um tipo de mensagem próprio, separado de texto, botão ou lista.

### Preciso criar o Flow em algum lugar antes de usar a API?

Sim. O Flow em si — as telas, os campos, a navegação — é definido e publicado no Gerenciador do WhatsApp Business (ou via API de Flows da Meta), de forma parecida com a aprovação de um template. A chamada pela API só dispara um Flow que já existe e já foi publicado.

### Qual a diferença entre Flow, lista e botões?

Botões e listas continuam dentro do fluxo de mensagens — cada toque gera uma nova mensagem trocada. Um Flow abre uma tela própria, com múltiplos campos e passos, e só devolve os dados no fim (ou a cada etapa, se configurado como data_exchange). Use lista para 'escolha uma opção entre poucas'; use Flow para 'preencha um formulário'.

### Flow funciona na API não oficial?

Flows são um recurso da Cloud API oficial da Meta, ligado à conta verificada. Antes de desenhar um fluxo em cima de Flows, confirme na documentação da sua instância se o suporte está disponível para o tipo de conta que você está usando.