WhatsApp Flows: como criar formulários e coletar dados dentro do WhatsApp

O WhatsApp Flows é um recurso da Cloud API que permite criar formulários de várias telas diretamente dentro de uma conversa do WhatsApp. Os usuários percorrem campos de entrada, menus suspensos e seletores de data sem sair do chat, e o seu sistema recebe os dados coletados como JSON estruturado. A Meta descreve os Flows como uma forma de criar interações estruturadas para mensagens comerciais, em tarefas como geração de leads e recomendação de produtos.[1] Se você desenvolve na WhatsApp Cloud API, os Flows oferecem uma forma nativa de coletar dados estruturados no próprio momento da conversa. Um Flow abre quando o usuário toca em um botão de call-to-action em uma mensagem interativa ou em uma mensagem de template (o tipo de mensagem pré-aprovada que uma empresa pode enviar a qualquer momento), e o formulário em si roda dentro do WhatsApp.

Principais conclusões

1. Os Flows exigem a WhatsApp Cloud API e uma conta do WhatsApp Business (WABA). A Meta está dividindo a WABA em duas contas: uma WhatsApp account, que contém o seu número de telefone comercial, e uma Messaging account, que contém os seus templates e o faturamento.
2. Um Flow sem endpoint de dados (uma URL no seu servidor que o Flow chama para obter dados em tempo real) coleta as respostas do formulário e as envia quando o usuário termina. Um Flow com endpoint troca dados com o seu servidor em tempo real.
3. Um Flow pode ter até 100 telas, mas a Meta recomenda que cada tarefa leve menos de 5 minutos e que cada tela se concentre em uma única tarefa.
4. Os Flows que trocam dados com o seu servidor precisam de um par de chaves RSA de 2048 bits, com a chave pública assinada pelo endpoint de criptografia da 360Dialog.
5. O custo de um Flow é o custo da mensagem que o transporta. A partir de 1º de outubro de 2026, a Meta também cobra pelas respostas enviadas dentro da janela de atendimento ao cliente de 24 horas, o período após a última mensagem do usuário em que você pode responder sem um template.

O que é o WhatsApp Flows e como ele funciona?

O WhatsApp Flows é um framework de interação estruturada integrado à WhatsApp Business Platform que permite às empresas definir formulários de várias telas com uma definição em JSON, exibir esses formulários de forma nativa dentro do WhatsApp e receber as respostas dos usuários como payloads JSON estruturados via webhook. O usuário nunca sai do chat. Os Flows são compostos por telas (cada tela é um nó em uma máquina de estados), componentes (os elementos de interface de cada tela) e ações (a lógica que avança entre as telas ou envia os dados).

Um Flow começa quando o usuário toca em um botão de call-to-action anexado a uma mensagem interativa (tipo "flow") ou a uma mensagem de template (tipo de botão FLOW). O botão abre a primeira tela, que contém o layout, os componentes e a lógica de navegação definidos no seu Flow JSON. O usuário preenche os campos e avança pelas telas. Na tela final, a ação complete envia os campos listados no payload dela de volta ao seu sistema, como um payload JSON entregue via webhook.

A principal diferença em relação a outros métodos de coleta de dados no WhatsApp:

Método	Estrutura dos dados	Experiência do usuário	Ideal para
WhatsApp Flows	Payload JSON estruturado	Telas de formulário tocáveis no chat	Captação de leads, agendamentos, pesquisas, formulários de pedido
Respostas rápidas em templates	Seleção de um único botão	O usuário toca em uma opção predefinida	Confirmações, opt-ins (consentimento para receber mensagens), roteamento simples
Coleta por texto livre	Texto não estruturado	O usuário digita respostas abertas	Feedback aberto, conversas de suporte

Os Flows resolvem um problema específico: coletar dados estruturados de usuários que já estão em uma conversa do WhatsApp. Se você precisa de um nome, um e-mail, uma data e uma preferência em uma única interação, os Flows permitem coletar os quatro em um só formulário tocável. A coleta por texto livre exige várias rodadas de mensagens e lógica de parsing no seu backend para extrair os mesmos campos.

Se você precisa de um número da Cloud API para começar a criar Flows, você pode começar a usar a API com a 360Dialog.

Flows estáticos ou dinâmicos: de qual tipo você precisa?

A distinção prática é se o seu Flow se conecta a um endpoint de dados. Um Flow sem endpoint de dados define todo o conteúdo no Flow JSON e coleta as entradas do usuário localmente. Um Flow com endpoint de dados envia requisições criptografadas ao seu servidor durante a execução e recebe os dados que preenchem a tela seguinte. Os dois rótulos descrevem abordagens de tratamento de dados que determinam quanta infraestrutura de backend você precisa.

Sem endpoint de dados: O Flow JSON define cada tela, componente e caminho de navegação na fase de design. As entradas do usuário são coletadas localmente e enviadas como um payload JSON quando o Flow é concluído. Essa abordagem funciona para formulários de captação de leads, pesquisas de feedback e fluxos de cadastro em que todos os campos são conhecidos de antemão. As principais ações são navigate (para avançar entre as telas) e complete (para encerrar o Flow e devolver os dados). O servidor só entra em ação quando o envio final chega via webhook.

Com endpoint de dados: O Flow envia requisições POST criptografadas ao seu endpoint HTTPS durante a execução, usando a ação data_exchange.[2][4] Seu servidor descriptografa a requisição, processa os dados e retorna o conteúdo da tela seguinte. Isso permite agendamento de consultas com disponibilidade em tempo real, catálogos de produtos com estoque em tempo real ou qualquer cenário em que o conteúdo da tela dependa das seleções anteriores do usuário ou do estado do seu backend. As requisições ao seu endpoint expiram após 10 segundos, e a Meta recomenda uma validade de 2 a 3 dias para o flow_token, para dar tempo aos usuários de interagir.[6]

As duas abordagens usam a mesma estrutura de Flow JSON e os mesmos componentes. A escolha depende de as suas telas precisarem de dados do seu servidor durante a execução.

Para conectar os envios de Flows à sua stack de automação atual, veja como funcionam as integrações do WhatsApp com a 360Dialog.

Quais componentes você pode usar em um Flow?

Os Flows oferecem mais de 20 tipos de componentes nas categorias de entrada, exibição, navegação e condicionais. Cada tela aceita até 50 componentes e usa um layout de coluna única (SingleColumnLayout, um flexbox vertical).[3] A Meta limita o conteúdo do próprio Flow JSON a 10 MB.

Principais componentes de entrada:

• TextInput: Texto de uma linha, e-mail, telefone, número, senha ou código de acesso. Aceita validação por regex (v6.2 ou posterior). Máximo de 80 caracteres por padrão.
• TextArea: Entrada de texto com várias linhas, 600 caracteres por padrão.
• Dropdown: Seleção única entre até 200 opções (100 com imagens).
• RadioButtonsGroup: Seleção única entre até 20 opções. A Meta recomenda um Dropdown quando você tem 8 opções ou mais.
• CheckboxGroup: Seleção múltipla entre até 20 opções.
• DatePicker: Seleção de data com formatação independente de fuso horário (v5.0 ou posterior).
• CalendarPicker: Seleção de uma data ou de um intervalo de datas (v6.1 ou posterior).
• OptIn: Caixa de seleção de consentimento, até 5 por tela.
• ChipsSelector: Seletor compacto de múltiplas opções, para 2 a 20 opções (v6.3 ou posterior).

Os componentes de exibição incluem TextHeading, TextSubheading, TextBody, TextCaption, RichText (v5.1 ou posterior, para textos mais longos formatados em markdown), Image (até 3 por tela) e ImageCarousel (v7.1 ou posterior).

Os componentes de navegação incluem Footer (obrigatório nas telas terminais, máximo de 35 caracteres), EmbeddedLink (até 2 por tela) e NavigationList (v6.2 ou posterior). Os componentes de upload de mídia (DocumentPicker e PhotoPicker, v4.0 ou posterior) permitem que os usuários anexem arquivos diretamente no Flow.

Os componentes condicionais (If e Switch, disponíveis a partir da v4.0) permitem mostrar ou ocultar elementos com base nas entradas do usuário ou em valores de dados, e os componentes If podem ser aninhados em até 3 níveis. A ação update_data (v6.0 ou posterior) atualiza a tela em tempo real com base nas interações do usuário, sem ida e volta ao servidor, o que é útil para dropdowns em cascata ou campos calculados.

Para ver as etapas de configuração na 360Dialog, consulte a nossa documentação de Flows em docs.360dialog.com. A referência completa de componentes está na documentação de componentes da Meta.

Como criar um Flow pela API? (O caminho com a 360Dialog)

Criar um Flow pela 360Dialog segue cinco etapas: gerar um par de chaves RSA, fazer o upload da chave pública, escrever o Flow JSON, configurar o endpoint e enviar o Flow aos usuários. As etapas 1, 2 e 4 só são necessárias para Flows que trocam dados com o seu servidor, e a Meta inclui o par de chaves na configuração do endpoint. O WhatsApp Manager também tem um Flows Builder com pré-visualização ao vivo, e o caminho pela API permite gerenciar o Flow JSON a partir dos seus próprios sistemas. Em qualquer um dos caminhos, um Flow pode ter até 100 telas.

1. Gere seu par de chaves RSA. Crie um par de chaves RSA de 2048 bits com o OpenSSL:

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Guarde a chave privada em segurança. Você vai usá-la para descriptografar os dados recebidos dos Flows.

2. Faça o upload da sua chave pública na 360Dialog. Assine e envie a chave pelo endpoint de criptografia da 360Dialog:[5]

POST https://waba-v2.360dialog.io/whatsapp_business_encryption

Envie a chave pública completa (incluindo os marcadores BEGIN e END) como business_public_key no corpo da requisição. O endpoint retorna {"success": true} em caso de sucesso. Você pode verificar o status da chave com uma requisição GET para a mesma URL.

3. Escreva o Flow JSON. Defina suas telas, layouts, componentes e ações de navegação. O JSON exige, no mínimo, um campo version e um array screens. Use a versão do Flow JSON que a Meta recomenda atualmente (7.3): as versões até a 5.0 estão congeladas e não podem mais ser publicadas.[7] Cada tela tem um id, um bloco layout e os campos opcionais data e title. Pelo menos uma tela deve ser marcada como terminal, e toda tela terminal precisa de um Footer. Para Flows com endpoint, defina também data_api_version (a Meta recomenda "4.0"; "3.0" ainda é aceito) e um routing_model que liste quais telas podem vir depois de cada uma.

4. Configure seu endpoint de dados (somente Flows dinâmicos). Defina o endpoint_uri pela Flows API. Seu endpoint deve aceitar requisições HTTPS POST com um certificado TLS/SSL válido. Todos os payloads são criptografados com RSA de 2048 bits (OAEP-SHA256) na troca de chaves e com AES-128-GCM no payload de dados. Valide as requisições recebidas com o cabeçalho X-Hub-Signature-256 e o app secret do seu aplicativo. Seu endpoint também deve responder aos pings de verificação de integridade (health check): {"action": "ping"} espera {"data": {"status": "active"}}.

5. Envie o Flow aos usuários. Anexe o Flow a uma mensagem interativa (tipo "flow") ou a uma mensagem de template (tipo de botão FLOW). Uma mensagem interativa de Flow precisa de flow_message_version definido como "3", do texto do botão em flow_cta e de um flow_id ou um flow_name.[8] O changelog da Meta lista o flow_token como opcional; defina um quando precisar associar cada resposta a uma sessão ou a um usuário. Com flow_action definido como "navigate" (o padrão), o flow_action_payload indica a primeira tela e pode preencher campos previamente quando você já conhece os dados do usuário pelo contexto da conversa.

A 360Dialog, como Official Meta Solution Partner, fornece o endpoint de criptografia e a infraestrutura de API que cuida do gerenciamento de chaves para os Flows. Exemplos de código para a descriptografia no endpoint estão disponíveis em Python, Node.js, PHP, Java, C# e Go na documentação para desenvolvedores da Meta.

Se a WhatsApp Business API é novidade para você, obtenha a aprovação da sua WhatsApp account antes de criar Flows.

Três exemplos práticos com Flow JSON

Os exemplos a seguir mostram a estrutura JSON de três casos de uso comuns. Todos usam a versão 7.3 do Flow JSON, a versão que a Meta recomenda atualmente. A referência completa de componentes e ações está na documentação de Flow JSON da Meta.

Formulário de captação de leads (uma tela, sem endpoint)

Um formulário mínimo de captação de leads, com um campo de nome, um seletor de interesse e uma caixa de seleção de consentimento:

{
  "version": "7.3",
  "screens": [{
    "id": "LEAD_FORM",
    "title": "Entre em contato",
    "terminal": true,
    "layout": {
      "type": "SingleColumnLayout",
      "children": [
        {"type": "TextInput", "name": "full_name",
         "label": "Nome completo", "required": true,
         "input-type": "text"},
        {"type": "RadioButtonsGroup", "name": "interest",
         "label": "Área de interesse", "required": true,
         "data-source": [
           {"id": "sales", "title": "Vendas"},
           {"id": "support", "title": "Suporte"},
           {"id": "partnership", "title": "Parceria"}
        ]},
        {"type": "OptIn", "name": "consent",
         "label": "Aceito receber novidades"},
        {"type": "Footer", "label": "Enviar",
         "on-click-action": {
           "name": "complete",
           "payload": {
             "full_name": "${form.full_name}",
             "interest": "${form.interest}",
             "consent": "${form.consent}"
           }
        }}
      ]
    }
  }]
}

A ação complete no Footer encerra o Flow e envia ao seu webhook os campos listados no payload dela, então liste todos os campos de que você precisa. O webhook entrega uma mensagem com tipo "interactive" e tipo interativo "nfm_reply", cujo campo response_json é uma string JSON que contém o flow_token e os valores desses campos.

Formulário de feedback (duas telas, sem endpoint)

Um formulário de feedback em duas telas coleta uma avaliação na primeira tela e comentários opcionais na segunda:

{
  "version": "7.3",
  "screens": [
    {
      "id": "RATING",
      "title": "Feedback 1 de 2",
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {"type": "TextHeading",
           "text": "Como foi sua experiência?"},
          {"type": "RadioButtonsGroup",
           "name": "rating", "label": "Avaliação",
           "required": true,
           "data-source": [
             {"id": "5", "title": "Excelente"},
             {"id": "4", "title": "Bom"},
             {"id": "3", "title": "Regular"},
             {"id": "2", "title": "Ruim"}
          ]},
          {"type": "Footer", "label": "Avançar",
           "on-click-action": {
             "name": "navigate",
             "next": {"type": "screen", "name": "COMMENTS"},
             "payload": {}
          }}
        ]
      }
    },
    {
      "id": "COMMENTS",
      "title": "Feedback 2 de 2",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {"type": "TextArea", "name": "comments",
           "label": "Comentários",
           "required": false},
          {"type": "Footer", "label": "Enviar",
           "on-click-action": {
             "name": "complete",
             "payload": {
               "rating": "${screen.RATING.form.rating}",
               "comments": "${form.comments}"
             }
          }}
        ]
      }
    }
  ]
}

A ação navigate leva o usuário à segunda tela com um payload vazio. A partir do Flow JSON v4.0, qualquer tela pode ler as entradas de outra tela com a sintaxe global ${screen.RATING.form.rating}, então a ação complete na última tela envia tanto a avaliação quanto os comentários.

Agendamento de consultas (dinâmico, com endpoint)

Um Flow dinâmico usa a ação data_exchange para solicitar ao seu servidor os horários disponíveis e depois os mostra em uma segunda tela:

{
  "version": "7.3",
  "data_api_version": "4.0",
  "routing_model": {
    "BOOKING": ["SLOTS"],
    "SLOTS": []
  },
  "screens": [
    {
      "id": "BOOKING",
      "title": "Agendar horário",
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {"type": "DatePicker", "name": "date",
           "label": "Selecione uma data", "required": true},
          {"type": "Footer",
           "label": "Ver disponibilidade",
           "on-click-action": {
             "name": "data_exchange",
             "payload": {"date": "${form.date}"}
          }}
        ]
      }
    },
    {
      "id": "SLOTS",
      "title": "Escolha um horário",
      "terminal": true,
      "data": {
        "available_slots": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {"type": "string"},
              "title": {"type": "string"}
            }
          },
          "__example__": [
            {"id": "1", "title": "08:00"},
            {"id": "2", "title": "09:00"}
          ]
        }
      },
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {"type": "Dropdown", "name": "slot",
           "label": "Horários disponíveis", "required": true,
           "data-source": "${data.available_slots}"},
          {"type": "Footer", "label": "Confirmar agendamento",
           "on-click-action": {
             "name": "complete",
             "payload": {
               "date": "${screen.BOOKING.form.date}",
               "slot": "${form.slot}"
             }
          }}
        ]
      }
    }
  ]
}

Quando o usuário seleciona uma data e toca no Footer, o Flow envia ao seu endpoint uma requisição POST criptografada com a data selecionada. Seu servidor descriptografa a requisição usando a sua chave privada RSA e AES-128-GCM, consulta os horários disponíveis e retorna uma resposta criptografada com a tela seguinte ("screen": "SLOTS") e um objeto data que contém available_slots. O usuário escolhe um horário, e a ação complete envia a data e o horário ao seu webhook. Envie este Flow com flow_action definido como "navigate" e a primeira tela definida como BOOKING, para que a abertura do Flow dispense uma chamada ao seu endpoint.

Como projetar um Flow que as pessoas concluam?

As boas práticas da Meta para Flows se concentram em manter cada tarefa curta e cada tela simples, para que os usuários terminem o que começaram. Para mensurar os seus próprios resultados, o Flows Builder no WhatsApp Manager mostra estatísticas de interação dos Flows publicados.

Boas práticas documentadas pela Meta:

• Mantenha cada tela com uma única tarefa e o Flow inteiro abaixo de 5 minutos.
• Escreva um CTA que diga ao usuário exatamente o que acontece quando ele tocar no botão. Mantenha o texto do botão curto: a nossa documentação define um limite de 20 caracteres, sem emoji.
• Use o componente certo para cada tipo de entrada: DatePicker para datas, Dropdown para 8 opções ou mais, RadioButtonsGroup para uma escolha única entre menos opções, CheckboxGroup para seleções múltiplas.
• Planeje para o cache: quando um usuário conclui uma tela e avança, o WhatsApp armazena em cache os dados daquela tela. Um usuário que sai perde o que digitou na tela atual, então várias telas curtas colocam menos dados em risco do que uma tela longa.
• Termine os Flows de várias etapas com uma tela de resumo, para que o usuário revise tudo antes de enviar.

Para entender melhor como os Flows se encaixam nos seus processos de mensagens, veja o nosso guia de automação no WhatsApp.

Quanto custam os Flows?

A Meta cobra por mensagem entregue, então o custo de um Flow é o custo da mensagem que leva o botão dele.[9] Os planos da 360Dialog têm preço por número por mês e não listam cobrança separada para Flows. Se você envia o Flow dentro de uma mensagem de template, paga a tarifa da categoria desse template (marketing, utilidade ou autenticação), que varia por país.

Se você envia o Flow como mensagem interativa em resposta a um usuário, ele sai dentro da janela de atendimento ao cliente de 24 horas. A partir de 1º de outubro de 2026, a Meta cobra essas respostas como mensagens de serviço, com a mesma tarifa das mensagens de utilidade e autenticação naquele mercado, e também cobra os templates de utilidade enviados dentro da janela.[10] As mensagens dos usuários, incluindo um Flow enviado por eles, são gratuitas. Para ver as tarifas atuais por mensagem em cada país, consulte a nossa página de preços.

Empresas de SaaS e revendedores que querem oferecer Flows nos próprios produtos podem integrar o WhatsApp no seu SaaS com a Partner Platform da 360Dialog, que fornece a infraestrutura de API para implantações multi-cliente.

Se você já quer criar seu primeiro Flow, o próximo passo é começar a usar a API com a 360Dialog e, se o seu Flow usar um endpoint, seguir as etapas de configuração do par de chaves na nossa documentação de Flows.

Perguntas frequentes

Posso enviar um Flow dentro de uma mensagem de template?

Sim. Você anexa um Flow a uma mensagem de template adicionando um botão do tipo FLOW durante a criação do template. O botão identifica o Flow pelo ID ou pelo nome e indica a primeira tela quando a ação do botão é navigate. Quando o usuário toca no botão, o Flow abre dentro do chat. O próprio template passa pelo processo padrão de aprovação de templates do WhatsApp, então garanta que o conteúdo do template e o objetivo do Flow estejam de acordo com as políticas de comércio e de mensagens da Meta.

O que você precisa para enviar um Flow?

Você precisa de um número de telefone comercial registrado na WhatsApp Cloud API. Qualquer empresa pode começar a criar Flows no WhatsApp Manager e, para publicá-los e enviá-los, a Meta exige uma empresa verificada e alta qualidade das mensagens.

Posso testar um Flow antes de publicar?

Sim. O Flows Builder no WhatsApp Manager tem uma pré-visualização interativa que se comporta como um dispositivo real e envia requisições reais ao seu endpoint, se o Flow tiver um. Você também pode enviar o rascunho para um telefone de teste, pela opção Send do Builder ou pela API com o modo definido como draft. As mensagens de rascunho mostram um banner de aviso no dispositivo, e o telefone de teste precisa ter enviado uma mensagem ao seu número nas últimas 24 horas. Os Flows criados desde novembro de 2024 continuam editáveis após a publicação, pela API ou pelo Builder, e mantêm o mesmo Flow ID.

O que acontece com os dados do usuário se ele fechar o Flow no meio?

O WhatsApp armazena em cache os dados de uma tela assim que o usuário a conclui e avança para a próxima. Os dados digitados na tela atual, antes de o usuário tocar no botão do Footer, se perdem se ele sair. Por isso a Meta recomenda dividir formulários com vários campos em várias telas curtas, para que menos dados fiquem em risco se o usuário sair antes de terminar.

Os dados são criptografados?

Sim. Todos os dados trocados entre o Flow e o seu endpoint usam troca de chaves RSA de 2048 bits (OAEP-SHA256) combinada com criptografia AES-128-GCM do payload. A requisição recebida contém três campos: encrypted_flow_data, encrypted_aes_key e initial_vector. Você descriptografa a chave AES com a sua chave privada RSA e depois descriptografa o payload com AES-GCM. Sua resposta é criptografada com a mesma chave AES, usando um vetor de inicialização invertido. O guia completo de implementação da criptografia, com exemplos de código em seis linguagens, está na documentação para desenvolvedores da Meta.

Fontes

[1] Meta, “WhatsApp Flows,” developers.facebook.com/docs/whatsapp/flows. Accessed September 29, 2026.

[2] Meta, “Flow JSON Reference,” developers.facebook.com/docs/whatsapp/flows/reference/flowjson. Accessed September 29, 2026.

[3] Meta, “Components Reference,” developers.facebook.com/docs/whatsapp/flows/reference/components. Accessed September 29, 2026.

[4] Meta, “Implementing Your Flow Endpoint,” developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint. Accessed September 29, 2026.

[5] 360Dialog, “Flows,” docs.360dialog.com/docs/messaging/flows. Accessed September 29, 2026.

[6] Meta, “Best Practices,” developers.facebook.com/docs/whatsapp/flows/guides/bestpractices. Accessed September 29, 2026.

[7] Meta, “Changelog,” developers.facebook.com/docs/whatsapp/flows/changelogs. Accessed September 29, 2026.

[8] Meta, “Sending a Flow,” developers.facebook.com/documentation/business-messaging/whatsapp/flows/guides/sendingaflow. Accessed September 29, 2026.

[9] Meta, “Pricing on the WhatsApp Business Platform,” developers.facebook.com/docs/whatsapp/pricing. Accessed September 29, 2026.

[10] Meta, “Upcoming Pricing Updates for Meta Business Agent, Service and Utility Messages,” developers.facebook.com/documentation/business-messaging/whatsapp/pricing/non-template-messages. Accessed September 29, 2026.