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

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?

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:

curl -X POST "https://us.api-wa.me/{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:

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.

// 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 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 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.