Criar conta
← Blog

·

WhatsApp Flows: formulários dentro da conversa

Atualizado em 25/10/2026

WhatsApp Flows são formulários de uma ou várias telas que abrem dentro da conversa do WhatsApp, com campos de texto, listas de opção, datas e botões, sem mandar o cliente para um site. A empresa define as telas em um arquivo chamado Flow JSON, envia o Flow por mensagem interativa ou template, e recebe as respostas no mesmo webhook de mensagens. Não há preço próprio para Flows: a mensagem que carrega o Flow é cobrada pela regra da categoria dela.

Este guia explica para que servem, como montar um Flow simples, quando você precisa de um endpoint, como enviar e receber a resposta e quais limites observar.

Para que servem os Flows

A página de Flows da Meta cita geração de leads, recomendação de produtos e qualquer interação em que uma estrutura fixa seja mais confortável para o cliente do que uma troca de mensagens livre. Os guias oficiais trazem exemplos como pré-aprovação de empréstimo, cotação de seguro, coleta de interesse de compra e oferta personalizada.

Casos práticos em que um Flow costuma render mais que perguntas soltas no chat:

  • Cadastro e qualificação de lead: nome, e-mail, faixa de orçamento e interesse em uma só tela.
  • Agendamento: escolher serviço, data e horário. O assunto aparece em agendamento automático no WhatsApp.
  • Pesquisa de satisfação e NPS: nota e comentário sem o cliente precisar digitar números. Veja pós-venda e NPS pelo WhatsApp.
  • Suporte: formulário de abertura de chamado com categoria e descrição.

As categorias que um Flow pode receber na criação são SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY e OTHER.

Requisitos

Pelo guia de primeiros passos, você precisa da Cloud API configurada (app, conta do WhatsApp Business e número) e, para enviar Flows aos clientes, de empresa verificada e boa qualidade de mensagens. Os Flows podem ser criados de dois jeitos:

  • Flow Builder: no WhatsApp Manager, em Ferramentas da conta → Flows. O editor mostra uma prévia do Flow enquanto você edita.
  • Flows API: endpoints da Graph API para criar, enviar o JSON, publicar e descontinuar.

Anatomia do Flow JSON

O Flow JSON tem duas propriedades obrigatórias: version (versão do formato) e screens (as telas). Cada tela tem um id único, um layout com componentes e, na última, terminal: true e um componente Footer. A tabela de versões suportadas marca a 7.3 como recomendada para publicar.

Um Flow de captura de lead, com uma tela só:

{
  "version": "7.3",
  "screens": [
    {
      "id": "LEAD",
      "title": "Fale com a gente",
      "terminal": true,
      "success": true,
      "data": {},
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          { "type": "TextHeading", "text": "Conte um pouco sobre você" },
          { "type": "TextInput", "name": "nome", "label": "Nome", "input-type": "text", "required": true },
          { "type": "TextInput", "name": "email", "label": "E-mail", "input-type": "email", "required": true },
          {
            "type": "Dropdown",
            "name": "interesse",
            "label": "Interesse",
            "required": true,
            "data-source": [
              { "id": "planos", "title": "Conhecer os planos" },
              { "id": "suporte", "title": "Suporte técnico" },
              { "id": "parceria", "title": "Parceria" }
            ]
          },
          {
            "type": "Footer",
            "label": "Enviar",
            "on-click-action": {
              "name": "complete",
              "payload": {
                "nome": "${form.nome}",
                "email": "${form.email}",
                "interesse": "${form.interesse}"
              }
            }
          }
        ]
      }
    }
  ]
}

Os pontos que mais confundem:

  • ${form.campo} lê o que o cliente digitou na tela; ${data.campo} lê dados que você passou para a tela.
  • A ação complete encerra o Flow e manda o payload para o seu webhook. A Meta recomenda incluir só o que o usuário preencheu e manter o payload pequeno, sem imagens em base64.
  • navigate leva para outra tela sem chamar servidor. data_exchange chama o seu endpoint.
  • Alguns limites de componente: o TextInput aceita até 80 caracteres por padrão; o Dropdown aceita até 200 opções sem imagem, com título de até 30 caracteres.
  • Campos marcados em sensitive (a partir da versão 5.1) ficam ocultos no resumo que o cliente vê depois de enviar.

Com ou sem endpoint

Um Flow sem endpoint é estático: as telas, opções e a navegação estão todas no JSON. Serve para a maioria dos formulários.

Um Flow com endpoint consulta o seu servidor durante o preenchimento: por exemplo, para mostrar horários livres da agenda ou validar um CPF antes de seguir. Pela documentação de endpoint, a configuração tem quatro partes:

  1. Gerar um par de chaves RSA e enviar a chave pública para a Meta, que a assina.
  2. Publicar um endpoint HTTPS com certificado válido que aceite POST.
  3. Implementar a criptografia: cada requisição chega com encrypted_flow_data, encrypted_aes_key e initial_vector. A chave AES vem cifrada com RSA-OAEP (SHA-256), os dados vêm em AES-GCM, e a resposta precisa ser cifrada com a mesma chave AES e o vetor de inicialização com todos os bits invertidos.
  4. Ligar o endpoint ao Flow, com data_api_version no JSON e a URL do endpoint.

O endpoint recebe requisições quando o Flow abre com data_exchange, quando uma tela é enviada com data_exchange, quando o cliente volta com refresh_on_back, e também verificações de saúde periódicas ("action": "ping"), que devem ser respondidas com {"data": {"status": "active"}}. Se não conseguir decifrar uma requisição, o endpoint deve responder HTTP 421.

A própria Meta recomenda evitar o endpoint quando ele não é necessário, porque cada chamada adiciona latência. Para testar o endpoint na sua máquina, a técnica de túnel de testar webhook localmente também funciona aqui. A Meta mantém exemplos em Node.js no repositório WhatsApp-Flows-Tools.

Ciclo de vida: rascunho, publicado e problemas de saúde

EstadoO que significa
Draft (rascunho)Em edição. Só pode ser enviado para teste e mostra um aviso no topo. Pode ser excluído
Published (publicado)Pode ser enviado a clientes. Não pode ser excluído, só descontinuado
Deprecated (descontinuado)Não pode mais ser enviado. Respostas de mensagens antigas ainda podem chegar
Throttled (limitado)Definido pela Meta quando o endpoint ou a navegação estão com problemas. Envio limitado a 10 mensagens por hora
Blocked (bloqueado)Saúde piorou depois do Throttled. Não pode ser enviado nem aberto

Editar o JSON de um Flow publicado o devolve para rascunho; as mensagens já enviadas continuam com a versão anterior. A Meta mantém as últimas 5 versões. Para mudanças grandes, a recomendação é clonar o Flow. Os erros 132068 (Flow bloqueado) e 132069 (Flow limitado) aparecem quando você tenta enviar nesses estados; veja erros da API do WhatsApp.

Como enviar um Flow

Há dois caminhos, descritos em Sending a Flow.

Dentro da janela de atendimento, como mensagem interativa do tipo flow:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "body": { "text": "Leva menos de 1 minuto." },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "FLOW_ID",
        "flow_cta": "Preencher",
        "flow_token": "lead-8f2c1a",
        "flow_action": "navigate",
        "flow_action_payload": { "screen": "LEAD" }
      }
    }
  }
}

O flow_cta é o texto do botão (a Meta recomenda até 30 caracteres, sem emoji). O flow_token é um identificador que você gera; ele volta na resposta e é a forma de saber de qual envio ela veio, porque a resposta não traz o ID do Flow. Use valores imprevisíveis, como um ID de sessão.

Fora da janela, como template com botão do tipo FLOW. Na criação do template, o botão aponta para o Flow por flow_id, flow_name ou o próprio flow_json, e o texto do botão tem no máximo 25 caracteres. No envio, o componente button com sub_type: "flow" pode levar um flow_token e dados para a primeira tela. A categoria do template segue as regras normais, explicadas em templates da API do WhatsApp.

Recebendo a resposta no webhook

Quando o cliente toca no botão final, a resposta chega no webhook de mensagens como interactive do tipo nfm_reply:

{
  "from": "5584999999999",
  "id": "wamid.HBgL...",
  "type": "interactive",
  "interactive": {
    "type": "nfm_reply",
    "nfm_reply": {
      "name": "flow",
      "body": "Sent",
      "response_json": "{\"flow_token\": \"lead-8f2c1a\", \"nome\": \"Maria\", \"email\": \"maria@exemplo.com\", \"interesse\": \"planos\"}"
    }
  }
}

O response_json é uma string: faça o parse antes de gravar. A estrutura do webhook é a mesma das outras mensagens, explicada em webhooks da API do WhatsApp.

Quanto custa

A tabela de preços da Meta não tem linha para Flows. O custo depende de como o Flow foi enviado:

  • Template com botão de Flow: paga a categoria do template (marketing, utilidade ou autenticação), por mensagem entregue.
  • Mensagem interativa na janela de atendimento: é mensagem de serviço. Cada número tem 1.000 mensagens de serviço entregues grátis por mês; a partir da 1.001ª, há cobrança por mensagem.
  • A resposta do cliente (nfm_reply) não é cobrada: a Meta não cobra mensagens do usuário para a empresa.

Os valores em reais estão em quanto custa a API do WhatsApp no Brasil.

Como isso funciona na Vectalk

A Vectalk expõe a gestão de Flows na própria API, com token de instância: GET /api/flows para listar, POST /api/flows para criar (com nome, categorias e, opcionalmente, clone_flow_id), POST /api/flows/{flowId}/assets para enviar o flow.json, POST /api/flows/{flowId}/publish para publicar e POST /api/flows/{flowId}/deprecate para descontinuar. Os detalhes estão em Criar Flow e Assets do Flow.

O envio usa o mesmo POST /api/messages com o payload interactive do tipo flow mostrado acima, conforme a visão geral de mensagens, e a resposta nfm_reply chega nos webhooks registrados, no formato da Meta. Crie sua conta em apps.vectalk.com.br/register. Para o panorama da plataforma, veja o guia da API oficial do WhatsApp.

Perguntas frequentes

WhatsApp Flows é pago?

Não há cobrança específica por Flow. Você paga a mensagem que leva o Flow, conforme a categoria: template pela categoria dele, mensagem interativa na janela como mensagem de serviço. A resposta do cliente não é cobrada.

Preciso de servidor para usar Flows?

Não. Flows sem endpoint funcionam só com o Flow JSON, e a resposta chega no webhook que você já usa. O endpoint só é necessário quando as telas dependem de dados do seu sistema durante o preenchimento.

Posso enviar um Flow para quem não falou comigo nas últimas 24 horas?

Sim, por template com botão de Flow aprovado. Mensagens interativas do tipo flow só podem ser enviadas dentro da janela de atendimento.

Como sei de qual Flow veio a resposta?

A resposta não traz o ID do Flow. Use o flow_token, que você define no envio e volta no response_json, ou inclua um campo identificador no payload do complete.

Flows funcionam no WhatsApp Web?

Segundo o changelog da Meta, o suporte a Flows no WhatsApp Web começou a ser liberado a partir do início de dezembro de 2025, sem ação necessária da empresa.

Fontes oficiais consultadas em 25/10/2026: WhatsApp Flows, Get started with WhatsApp Flows, Flow JSON, Components, Implement endpoints for Flows, Lifecycle of a Flow, Send a Flow message, Flows webhooks, Changelog de Flows, Preços da plataforma, Flows na documentação da Vectalk.

Integre o WhatsApp oficial ao seu sistema

A Vectalk entrega a Cloud API da Meta com os mesmos payloads e webhooks, um token para todas as contas e documentação completa.

Criar conta grátis
Ler a documentação