---
title: "WhatsApp Flows pela API: formulários no chat"
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://api-wa.me/blog/whatsapp-flows-api-formularios"
language: "pt-BR"
og:type: "article"
og:site_name: "WAME API"
---

[Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/WhatsApp Flows pela API: formulários e telas dentro da conversa

Raphael Serafim· Publicado em 16 de setembro de 2026· 7 min de leitura

Compartilhar

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

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/whatsapp-flows-api-formularios.md)

**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](https://api-wa.me/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

Copiar

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

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

javascript

Copiar

```
// 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](https://api-wa.me/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](https://api-wa.me/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.

### Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

[Começar grátis](https://portal.api-wa.me/sign-up)

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

## Continue lendo

[### Automatizar grupos de WhatsApp pela API: guia completo

Como automatizar grupos de WhatsApp pela API: criar, adicionar participante, moderar entrada e enviar aviso automático, com exemplos práticos em cURL.](https://api-wa.me/blog/automatizar-grupos-whatsapp-api)[### Catálogo com carrinho no WhatsApp: como vender sem sair da conversa via API

Veja como popular o catálogo de produtos via API do WhatsApp e montar um fluxo de carrinho nativo, sem redirecionar o cliente pra fora da conversa.](https://api-wa.me/blog/catalogo-carrinho-whatsapp-api-vendas)[### Checklist de compliance para WhatsApp API em 2026

Checklist prático de compliance para WhatsApp API: opt-in, LGPD, Quality Rating e política de template — o que auditar antes de escalar o envio em 2026.](https://api-wa.me/blog/checklist-compliance-whatsapp-api-2026)

[Voltar ao blog](https://api-wa.me/blog)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "WAME API",
  "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram e Messenger",
  "url": "https://api-wa.me",
  "inLanguage": "pt-BR",
  "publisher": {
    "@id": "https://api-wa.me/#organization",
    "@type": "Organization",
    "name": "WAME API",
    "url": "https://api-wa.me"
  }
}
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://api-wa.me/#organization",
  "name": "WAME API",
  "alternateName": [
    "WAME",
    "Wame API",
    "wame.api.br",
    "api-wa.me"
  ],
  "url": "https://api-wa.me",
  "logo": {
    "@type": "ImageObject",
    "url": "https://api-wa.me/images/web-app-manifest-512x512.png",
    "width": 512,
    "height": 512
  },
  "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.",
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "INPI-BR",
    "name": "Pedido de registro de marca (INPI, classe NCL 42)",
    "value": "944724159"
  },
  "foundingDate": "2017",
  "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram e Messenger numa instância só. Desde 2017.",
  "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.",
  "knowsAbout": [
    "WhatsApp Cloud API oficial (Meta)",
    "API oficial de Instagram (Direct)",
    "API oficial de Messenger",
    "API multicanal Meta",
    "Meta Business Partner",
    "WhatsApp API",
    "API não oficial de WhatsApp",
    "automação de WhatsApp",
    "números virtuais",
    "webhooks"
  ],
  "sameAs": [
    "https://github.com/wame-api",
    "https://www.linkedin.com/company/wameapi",
    "https://www.instagram.com/wame.api/",
    "https://www.youtube.com/@wameapi"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "url": "https://api-wa.me/contact",
    "availableLanguage": [
      "Portuguese"
    ]
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "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.",
  "image": "https://api-wa.me/blog/whatsapp-flows-api-formularios/opengraph-image",
  "datePublished": "2026-09-16",
  "dateModified": "2026-09-16",
  "author": {
    "@type": "Person",
    "name": "Raphael Serafim",
    "url": "https://github.com/raphaelvserafim",
    "sameAs": [
      "https://github.com/raphaelvserafim"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "api-wa.me",
    "logo": {
      "@type": "ImageObject",
      "url": "https://api-wa.me/images/screenshot.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://api-wa.me/blog/whatsapp-flows-api-formularios"
  },
  "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",
  "inLanguage": "pt-BR"
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://api-wa.me"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog da API do WhatsApp",
      "item": "https://api-wa.me/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "WhatsApp Flows pela API: formulários e telas dentro da conversa",
      "item": "https://api-wa.me/blog/whatsapp-flows-api-formularios"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "O que é um WhatsApp Flow?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "É 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."
      }
    },
    {
      "@type": "Question",
      "name": "Como envio um Flow pela API?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Preciso criar o Flow em algum lugar antes de usar a API?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Qual a diferença entre Flow, lista e botões?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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'."
      }
    },
    {
      "@type": "Question",
      "name": "Flow funciona na API não oficial?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    }
  ]
}
```