Flows

Construir e gerenciar WhatsApp Flows - experiências interativas multi-etapas para formulários, agendamentos, pesquisas e mais.

Listar todos os flows

get

Recupera uma lista paginada de WhatsApp Flows associados à conta WhatsApp Business.

O que são WhatsApp Flows?

WhatsApp Flows são experiências estruturadas e interativas que conduzem usuários por processos multi-etapas diretamente no WhatsApp. São usados para:

Geração de leads e formulários de cadastro
Pesquisas e coleta de feedback
Agendamento de compromissos e reservas
Configuração de produtos e pedidos
Triagem de suporte ao cliente

Status dos Flows

Status

Descrição

DRAFT

Flow em edição e não publicado

PUBLISHED

Flow ativo com envio permitido aos usuários

DEPRECATED

Flow não é mais enviado a novos usuários, sessões existentes continuam

BLOCKED

Flow bloqueado por violação de políticas

THROTTLED

Flow limitado temporariamente devido a alta taxa de erros

Categorias de Flow

SIGN_UP: Fluxos de registro e onboarding
SIGN_IN: Fluxos de autenticação e login
APPOINTMENT_BOOKING: Fluxos de agendamento e reservas
LEAD_GENERATION: Coleta de contatos e informações
CONTACT_US: Fluxos de suporte e contato
CUSTOMER_SUPPORT: Fluxos de resolução de problemas
SURVEY: Fluxos de pesquisa e questionários
OTHER: Fluxos de uso geral

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Respostas

200

Lista de flows recuperada com sucesso

application/json

401

Não autorizado.

application/json

get

/flows

GET /v1/flows HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "status": "text",
      "categories": [
        "text"
      ]
    }
  ]
}

Criar um novo flow

post

Cria um novo WhatsApp Flow. Flows são criados em status DRAFT e devem ser publicados antes de serem enviados aos usuários.

Criação do Flow

A criação ocorre de duas maneiras:

Do zero: Informar nome e categorias, depois enviar a definição JSON
Por clonagem: Informar o ID de um flow existente para criar uma cópia

Estrutura JSON do Flow

Após a criação, a definição JSON deve ser enviada usando o endpoint de atualização. O JSON define:

Telas e layout
Componentes de entrada (campos de texto, dropdowns, seletores de data)
Navegação entre telas
Regras de validação de dados
Botões de ação e comportamentos

Endpoint URI

Se o flow requer dados dinâmicos ou precisa submeter dados ao servidor, o endpoint HTTPS recebe:

Requisições de inicialização do flow com contexto do usuário
Dados de transição de tela
Dados de submissão de formulários

O endpoint deve responder em até 10 segundos com JSON válido.

Boas Práticas

Usar nomes descritivos que reflitam o propósito do flow
Selecionar categorias apropriadas para melhor organização
Testar os flows completamente em DRAFT antes de publicar
Manter os flows simples, preferencialmente com 3-5 telas

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Corpo

namestring · máx: 200Obrigatório

Nome único do flow. Deve ser alfanumérico com underscores, máximo de 200 caracteres. Este nome fica visível aos usuários.

Example: MeuNovoFlow

clone_flow_idstringOpcional

ID de um flow existente para clonar. Quando fornecido, o novo flow é criado com a mesma definição JSON do flow fonte.

Example: 123456789987456321

endpoint_uristring · uriOpcional

URL HTTPS que trata a troca de dados do flow. Obrigatório para flows dinâmicos. Deve ser publicamente acessível e responder em até 10 segundos.

Example: https://example.com/flow-endpoint

Respostas

201

Flow criado com sucesso

application/json

400

Parâmetros de requisição inválidos

application/json

401

Não autorizado.

application/json

post

/flows

POST /v1/flows HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 133

{
  "name": "MeuNovoFlow",
  "categories": [
    "OTHER"
  ],
  "clone_flow_id": "123456789987456321",
  "endpoint_uri": "https://example.com/flow-endpoint"
}

{
  "id": "text"
}

Excluir um flow

delete

Exclui permanentemente um WhatsApp Flow pelo ID.

Considerações Importantes

A ação é irreversível e flows excluídos não podem ser recuperados
Não é possível excluir um flow com status PUBLISHED
O flow deve ser deprecated antes da exclusão
Mensagens que referenciam o flow excluído apresentam erro aos usuários
Dados analíticos do flow também são removidos

Fluxo Recomendado

Deprecate o flow para interromper novas sessões
Aguardar a conclusão das sessões existentes (normalmente 24-48 horas)
Excluir o flow

O fluxo evita a interrupção de usuários ativos.

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de consulta

flow_idstringObrigatório

Identificador único do Flow do WhatsApp.

Obtido a partir de:

Resposta do endpoint de criação de flow
Resposta do endpoint de listagem de flows

IDs de flow são strings numéricas e permanecem constantes durante o ciclo de vida do flow.

Example: 123456789012345678Pattern: ^[0-9]+$

Respostas

200

Flow excluído com sucesso

application/json

successstringOpcionalExample: true

401

Não autorizado.

application/json

409

Não é possível excluir um flow publicado

application/json

delete

/flows

DELETE /v1/flows?flow_id=text HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "success": "true"
}

Obter detalhes do flow

get

Recupera informações detalhadas sobre um Flow específico do WhatsApp, incluindo configuração, status, erros de validação e metadados.

Campos Disponíveis

O parâmetro fields solicita informações específicas:

Campo

Descrição

Identificador único do flow

name

Nome de exibição do flow

Erros de Validação

O campo validation_errors lista problemas que precisam ser corrigidos antes da publicação. Erros comuns incluem:

Estrutura JSON inválida
Elementos obrigatórios de tela ausentes
Referências de navegação inválidas
Configurações de componentes não suportadas

URLs de Visualização

O campo preview fornece URLs para testes do flow em:

WhatsApp mobile (requer dispositivo de teste)
WhatsApp Web (verificação visual)

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de consulta

flow_idstringObrigatório

Identificador único do Flow do WhatsApp.

Obtido a partir de:

Resposta do endpoint de criação de flow
Resposta do endpoint de listagem de flows

IDs de flow são strings numéricas e permanecem constantes durante o ciclo de vida do flow.

Example: 123456789012345678Pattern: ^[0-9]+$

fieldsstringOpcional

Lista separada por vírgulas dos campos específicos a retornar. Se não especificado, retorna todos os campos disponíveis.

Example: id,name,categories,preview,status,validation_errors,json_version,data_api_version

Respostas

200

Detalhes do flow recuperados com sucesso

application/json

idstringOpcional

namestringOpcional

statusstringOpcional

categoriesstring[]Opcional

validation_errorsobject[]Opcional

json_versionstringOpcional

data_api_versionstringOpcional

data_channel_uristringOpcional

401

Não autorizado.

application/json

404

Flow não encontrado

application/json

get

/flows/details

GET /v1/flows/details?flow_id=text HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "status": "text",
  "categories": [
    "text"
  ],
  "validation_errors": [
    {}
  ],
  "json_version": "text",
  "data_api_version": "text",
  "data_channel_uri": "text"
}

Publicar um flow

post

Publica um WhatsApp Flow para torná-lo disponível para envio aos usuários.

Pré-requisitos

Antes da publicação, verificar:

O JSON do flow é válido e não possui erros de validação
Todas as telas possuem navegação corretamente configurada
O endpoint URI (quando usado) está acessível e funcional
O flow foi testado usando o recurso de visualização

Processo de Publicação

O WhatsApp valida a estrutura JSON do flow
Quando existe endpoint URI configurado, a conectividade é verificada
O status do flow muda de DRAFT para PUBLISHED
O flow passa a estar disponível para envio em mensagens

Pós-Publicação

Flows publicados não podem ser editados; uma nova versão é necessária
É possível deprecar um flow publicado para interromper novas sessões
Métricas e análises ficam disponíveis após a publicação
Alterações no endpoint URI exigem nova versão do flow

Estratégia de Rollback

Quando problemas são identificados após a publicação:

Criar e publicar uma versão corrigida
Atualizar a lógica de envio de mensagens para usar o novo flow
Deprecate o flow problemático

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de consulta

flow_idstringObrigatório

Identificador único do Flow do WhatsApp.

Obtido a partir de:

Resposta do endpoint de criação de flow
Resposta do endpoint de listagem de flows

IDs de flow são strings numéricas e permanecem constantes durante o ciclo de vida do flow.

Example: 123456789012345678Pattern: ^[0-9]+$

Respostas

200

Status do flow alterado com sucesso

application/json

successstringOpcional

400

Flow possui erros de validação e não pode ser publicado

application/json

401

Não autorizado.

application/json

post

/flows/publish

POST /v1/flows/publish?flow_id=text HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "success": "true"
}

Deprecate um flow

post

Deprecate um Flow publicado do WhatsApp. Flows deprecated não podem mais ser enviados para novos usuários, mas sessões ativas existentes continuam funcionando.

Quando Depreciar

Existe uma nova versão do flow publicada
O flow não é mais necessário para o negócio
Problemas foram identificados e exigem um novo flow
Alterações de conformidade ou política exigem descontinuação

Comportamento da Depreciação

Cenário

Comportamento

Nova mensagem com flow

O flow não é incluído

Usuário em sessão ativa

A sessão continua normalmente

Usuário tenta reiniciar

Não é possível iniciar nova sessão

Dados de sessão existentes

Permanecem acessíveis

Expiração da Sessão

Sessões ativas normalmente expiram após:

24 horas de inatividade
Usuário fechar explicitamente o flow
Endpoint do flow retornar sinal de término

Recuperação

A depreciação é reversível e um flow deprecated pode ser republicado se ainda estiver em estado válido. A prática recomendada é:

Criar uma nova versão corrigida
Publicar a nova versão
Manter o flow deprecated para referência analítica

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de consulta

flow_idstringObrigatório

Identificador único do Flow do WhatsApp.

Obtido a partir de:

Resposta do endpoint de criação de flow
Resposta do endpoint de listagem de flows

IDs de flow são strings numéricas e permanecem constantes durante o ciclo de vida do flow.

Example: 123456789012345678Pattern: ^[0-9]+$

Respostas

200

Flow deprecated com sucesso

application/json

successstringOpcionalExample: true

401

Não autorizado.

application/json

post

/flows/deprecate

POST /v1/flows/deprecate?flow_id=text HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "success": "true"
}

Atualizar um flow

patch

Atualiza propriedades ou a definição JSON de um WhatsApp Flow existente.

Propriedades Atualizáveis

name: Altera o nome de exibição (não altera o flow ID)
categories: Atualiza categorias de classificação
endpoint_uri: Atualiza o endpoint de troca de dados

Atualização do JSON do Flow

Para atualizar telas e lógica do flow, envie uma nova definição JSON. O JSON deve estar conforme o schema JSON de WhatsApp Flows.

Restrições Importantes

Flows publicados não podem ser atualizados; deprecar antes ou criar novo flow
Flows DRAFT podem ser modificados livremente
Flows BLOCKED ou THROTTLED podem ter restrições de atualização

Gestão de Versões

WhatsApp Flows não possui versionamento nativo. Para uso em produção:

Usar convenções como "meu_flow_v2"
Manter o controle de IDs de flow por versão
Documentar alterações entre versões

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de rota

FLOW_IDstringObrigatório

Identificador único do Flow do WhatsApp como parâmetro de rota. Usado em endpoints que operam sobre um recurso de flow específico.

Example: 123456789012345678Pattern: ^[0-9]+$

Corpo

namestring · máx: 200Opcional

Novo nome de exibição do flow

Example: NomeFlowAtualizado

categoriesstring[]Opcional

Categorias atualizadas do flow

Example: ["OTHER"]

endpoint_uristring · uriOpcional

Novo endpoint URI para troca de dados

Example: https://example.com/updated-endpoint

Respostas

200

Flow atualizado com sucesso

application/json

successstringOpcionalExample: true

401

Não autorizado.

application/json

409

Não é possível atualizar um flow publicado

application/json

patch

/flows/{FLOW_ID}

PATCH /v1/flows/{FLOW_ID} HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 106

{
  "name": "NomeFlowAtualizado",
  "categories": [
    "OTHER"
  ],
  "endpoint_uri": "https://example.com/updated-endpoint"
}

{
  "success": "true"
}

Obter definição JSON do flow

get

Recupera a definição JSON completa de um WhatsApp Flow. O JSON contém toda a estrutura do flow, incluindo telas, componentes e lógica.

Visão Geral da Estrutura JSON

O JSON do flow contém:

version: Versão do schema (ex.: "3.0")
screens: Array de definições de telas
routing_model: Configuração de navegação
data_api_version: Versão para comunicação com o endpoint

Componentes de Tela

Cada tela pode conter:

Textos e títulos
Campos de entrada (texto, dropdown, seletor de data, checkbox)
Elementos de mídia (imagens)
Botões de navegação
Ações de envio

Troca de Dados

Quando há endpoint configurado:

O JSON inclui referências de binding de dados
Conteúdo dinâmico é obtido em tempo de execução
Entradas do usuário são enviadas ao endpoint

Casos de Uso

Backup de definições de flow
Controle de versões de flows
Migração de flows entre contas
Análise programática da estrutura do flow

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de rota

FLOW_IDstringObrigatório

Identificador único do Flow do WhatsApp como parâmetro de rota. Usado em endpoints que operam sobre um recurso de flow específico.

Example: 123456789012345678Pattern: ^[0-9]+$

Respostas

200

JSON do flow recuperado com sucesso

application/json

statusintegerOpcional

Código de status HTTP

Example: 200

401

Não autorizado.

application/json

404

O recurso solicitado não foi encontrado

application/json

get

/flows/assets/{FLOW_ID}

GET /v1/flows/assets/{FLOW_ID} HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "status": 200,
  "data": {
    "flow": {
      "version": "3.0",
      "screens": [
        {
          "id": "WELCOME",
          "title": "Bem-vindo",
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              {
                "type": "TextHeading",
                "text": "Bem-vindo ao serviço"
              },
              {
                "type": "TextBody",
                "text": "Continue para iniciar"
              },
              {
                "type": "Footer",
                "label": "Continuar",
                "on-click-action": {
                  "name": "navigate",
                  "next": {
                    "type": "screen",
                    "name": "MAIN_FORM"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Enviar chave pública de criptografia

post

Envia uma chave pública para criptografia ponta a ponta em WhatsApp Flows. A chave criptografa dados sensíveis trocados entre o WhatsApp e o endpoint.

Arquitetura de Segurança

WhatsApp Flows usa criptografia assimétrica para dados sensíveis:

O par de chaves RSA é gerado e a chave pública é enviada
O WhatsApp criptografa dados sensíveis usando a chave pública
O endpoint descriptografa dados usando a chave privada
As respostas são criptografadas usando a chave pública do WhatsApp

Requisitos da Chave

Par de chaves RSA de 2048 bits no mínimo (4096 bits recomendado)
Chave no formato PEM
Chave privada armazenada com segurança nos servidores
A chave privada não deve ser compartilhada ou transmitida

Exemplo de Geração de Chaves

Geração do par de chaves com OpenSSL:

openssl genrsa -out private_key.pem 2048
openssl rsa -pubout -in private_key.pem -out public_key.pem

Rotação de Chaves

Enviar uma nova chave pública para rotação
Chaves antiga e nova permanecem válidas durante a transição
A rotação a cada 90 dias é recomendada como boa prática de segurança

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Corpo

business_public_keystringObrigatório

Chave pública RSA no formato PEM. Deve ter 2048 bits ou mais. Incluir os marcadores BEGIN e END.

Example: -----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----

Respostas

200

Chave pública enviada com sucesso

application/json

successstringOpcionalExample: true

400

Formato de chave inválido

401

Não autorizado.

application/json

post

/flows/upload-public-key

POST /v1/flows/upload-public-key HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 129

"business_public_key='-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\\n-----END PUBLIC KEY-----'"

{
  "success": "true"
}

Obter chave pública atual

post

Recupera a chave pública configurada para criptografia de WhatsApp Flows, junto com o status de validação de assinatura.

Campos da Resposta

business_public_key: Chave pública RSA enviada
business_public_key_signature_status: Status de validação
- VALID: Chave configurada corretamente com assinaturas válidas
- MISMATCH: Assinatura não confere (possível adulteração)

Solução de Problemas

Se o status for MISMATCH:

Verificar se o par de chaves está correto
Reenviar a chave pública
Validar se houve corrupção no envio
Confirmar o formato PEM

Verificação de Segurança

Este endpoint permite:

Verificar o envio bem-sucedido da chave
Confirmar que a chave não foi adulterada
Validar a configuração de criptografia antes de publicar flows

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Respostas

200

Chave pública recuperada com sucesso

application/json

business_public_keystringOpcional

Chave pública RSA no formato PEM

Example: -----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----

business_public_key_signature_statusstring · enumOpcional

Indica se a assinatura da chave é válida. VALID indica que a chave está configurada corretamente. MISMATCH indica problema.

Valores possíveis:

401

Não autorizado.

application/json

post

/flows/get-public-key

POST /v1/flows/get-public-key HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "business_public_key": "-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\\n-----END PUBLIC KEY-----",
  "business_public_key_signature_status": "VALID"
}

AnteriorTemplates PróximoCalling

Atualizado há 1 mês

Isto foi útil?

Boa tarde

hashtagListar todos os flows

hashtagO que são WhatsApp Flows?

hashtagStatus dos Flows

hashtagCategorias de Flow

hashtagCriar um novo flow

hashtagCriação do Flow

hashtagEstrutura JSON do Flow

hashtagEndpoint URI

hashtagBoas Práticas

hashtagExcluir um flow

hashtagConsiderações Importantes

hashtagFluxo Recomendado

hashtagObter detalhes do flow

hashtagCampos Disponíveis

hashtagErros de Validação

hashtagURLs de Visualização

hashtagPublicar um flow

hashtagPré-requisitos

hashtagProcesso de Publicação

hashtagPós-Publicação

hashtagEstratégia de Rollback

hashtagDeprecate um flow

hashtagQuando Depreciar

hashtagComportamento da Depreciação

hashtagExpiração da Sessão

hashtagRecuperação

hashtagAtualizar um flow

hashtagPropriedades Atualizáveis

hashtagAtualização do JSON do Flow

hashtagRestrições Importantes

hashtagGestão de Versões

hashtagObter definição JSON do flow

hashtagVisão Geral da Estrutura JSON

hashtagComponentes de Tela

hashtagTroca de Dados

hashtagCasos de Uso

hashtagEnviar chave pública de criptografia

hashtagArquitetura de Segurança

hashtagRequisitos da Chave

hashtagExemplo de Geração de Chaves

hashtagRotação de Chaves

hashtagObter chave pública atual

hashtagCampos da Resposta

hashtagSolução de Problemas

hashtagVerificação de Segurança

Listar todos os flows

O que são WhatsApp Flows?

Status dos Flows

Categorias de Flow

Criar um novo flow

Criação do Flow

Estrutura JSON do Flow

Endpoint URI

Boas Práticas

Excluir um flow

Considerações Importantes

Fluxo Recomendado

Obter detalhes do flow

Campos Disponíveis

Erros de Validação

URLs de Visualização

Publicar um flow

Pré-requisitos

Processo de Publicação

Pós-Publicação

Estratégia de Rollback

Deprecate um flow

Quando Depreciar

Comportamento da Depreciação

Expiração da Sessão

Recuperação

Atualizar um flow

Propriedades Atualizáveis

Atualização do JSON do Flow

Restrições Importantes

Gestão de Versões

Obter definição JSON do flow

Visão Geral da Estrutura JSON

Componentes de Tela

Troca de Dados

Casos de Uso

Enviar chave pública de criptografia

Arquitetura de Segurança

Requisitos da Chave

Exemplo de Geração de Chaves

Rotação de Chaves

Obter chave pública atual

Campos da Resposta

Solução de Problemas

Verificação de Segurança