VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp Platform

Flows globais

Cria, lista, consulta, atualiza e apaga os Flows do WhatsApp compartilhados por todas as lojas, com a validação do JSON no formato da Meta.

Um Flow é um formulário nativo do WhatsApp: telas com textos, campos, listas e botões que abrem dentro da conversa, em vez de o cliente digitar tudo em mensagens. O Flow é descrito por um JSON no formato da Meta (flow_json). A Venddor guarda o JSON, valida e, quando você manda, publica na Meta (veja Publicar, pré-visualizar e usar com IA).

Os Flows desta página são globais: ficam no banco mestre e valem para toda loja com o módulo WhatsApp Commerce. Uma loja pode criar um Flow próprio com a mesma flow_key, e o da loja prevalece sobre o global. Um Flow só passa a ser usado pela IA de atendimento quando está published. Exigem root_admin com o privilégio manage_whatsapp_platform.

Pontos-chave
  • A flow_key é o identificador estável do Flow (até 120 caracteres, única). Depois de criado ela não muda.
  • O id do Flow é um inteiro (não UUID).
  • Salvar já valida o flow_json. Erros voltam como 422 com a lista de problemas.
  • Cada atualização soma 1 em version.
  • Apagar aqui não apaga o Flow na Meta.

O objeto Flow

Campos do Flow

idinteger
Id do Flow.
flow_keystring
Identificador único, definido na criação. Imutável.
namestring
Nome para humanos. É também o nome do Flow criado na Meta; se vazio, a Meta recebe a flow_key.
scopestring
storeglobal
Sempre global nestas rotas.
flow_jsonobject
O JSON do Flow no formato da Meta.
ai_when_to_usestring
Frase que explica à IA de atendimento quando enviar este Flow (por exemplo, "cliente quer cadastrar endereço de entrega").
ai_paramsobject
JSON Schema dos parâmetros que a IA pode preencher ao acionar o Flow. {} quando não há.
statusstring
draftpublished
draft até ser publicado. Só published é oferecido à IA. O servidor não restringe o valor enviado: use apenas esses dois.
versioninteger
Começa em 1 e sobe 1 a cada atualização.
meta_flow_idstring
Id do Flow na Meta. Vazio até o primeiro publish.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria exigida pela Meta. Valor desconhecido ou vazio vira OTHER, sem aviso.
created_atstring
Criação, RFC 3339 (UTC).
updated_atstring
Última alteração, RFC 3339 (UTC).

Regras de validação do flow_json

A plataforma recusa o JSON ao salvar, publicar e gerar quando alguma destas regras falha:

RegraDetalhe
versionObrigatório (texto, por exemplo "7.3")
screensDe 1 a 20 telas, cada uma com id não vazio e único
Layoutlayout.type deve ser SingleColumnLayout, com pelo menos 1 componente
Componentes aceitosTextHeading, TextSubheading, TextBody, TextCaption, RichText, TextInput, TextArea, Dropdown, RadioButtonsGroup, CheckboxGroup, ChipsSelector, DatePicker, CalendarPicker, PhotoPicker, DocumentPicker, OptIn, EmbeddedLink, Image, ImageCarousel, NavigationList, Footer. Os contêineres Form, If e Switch são aceitos e seus filhos também são validados
Propriedades obrigatóriasTexto (text) nos de texto e EmbeddedLink; name e label nos campos de entrada e seleção; label no Footer; src no Image; images no ImageCarousel; list-items no NavigationList
Ações (on-click-action.name)navigate, data_exchange, complete ou update_data
Limites por componenteDropdown: até 200 itens; RadioButtonsGroup, CheckboxGroup, ChipsSelector: até 20; ImageCarousel: até 10 imagens
Limites por telaAté 2 NavigationList, e ele não combina com outros componentes; até 1 DocumentPicker, que não coexiste com PhotoPicker; até 1 Form; até 1 Footer, que deve ser o último; If aninhado até 3 níveis
OutrasForm e ImageCarousel não ficam dentro de If; error-message não é permitido; on-unselect-action deve ser update_data

As mensagens de erro são devolvidas em português pelo servidor.

Listar Flows

GET/api/v1/admin/whatsapp-platform/flowsAdmin

Listar os Flows globais

Devolve todos os Flows globais, do alterado há menos tempo para o mais antigo, sem paginação, e a lista de tipos de componente aceitos (útil para montar uma paleta de edição).

200Flows listados
json
{
  "flows": [
    {
      "id": 3,
      "flow_key": "cadastro_endereco",
      "name": "Cadastro de endereço",
      "scope": "global",
      "flow_json": { "version": "7.3", "screens": [] },
      "ai_when_to_use": "Cliente quer informar ou trocar o endereço de entrega.",
      "ai_params": {},
      "status": "draft",
      "version": 2,
      "meta_flow_id": "",
      "category": "OTHER",
      "created_at": "2026-10-06T14:21:09.317Z",
      "updated_at": "2026-10-07T09:02:44.100Z"
    }
  ],
  "components": ["TextHeading", "TextBody", "TextInput", "Footer"]
}

Campos da resposta

flowsarray
Objetos Flow (veja acima). O flow_json do exemplo foi encurtado.
componentsarray
Nomes dos componentes aceitos. A ordem não é estável entre chamadas.

Criar um Flow

POST/api/v1/admin/whatsapp-platform/flowsAdmin

Criar um Flow global

Valida o flow_json e grava o Flow como draft (versão 1). Criar não publica nada na Meta.

Corpo da requisição

flow_keystringobrigatório
Identificador único, até 120 caracteres. Use letras minúsculas, números e _. Uma chave repetida falha (veja Erros).
namestring
Nome para humanos.
flow_jsonobjectobrigatório
JSON do Flow, segundo as regras acima.
ai_when_to_usestring
Quando a IA deve enviar este Flow.
ai_paramsobject
JSON Schema dos parâmetros da IA. Omitido grava {}.
statusstringpadrão: draft
draftpublished
Status inicial. Mantenha draft: published aqui só marca o registro, não publica na Meta.
categorystringpadrão: OTHER
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_key": "contato_rapido",
    "name": "Contato rápido",
    "category": "CONTACT_US",
    "ai_when_to_use": "Cliente quer deixar um recado para a loja.",
    "flow_json": {
      "version": "7.3",
      "screens": [{
        "id": "CONTATO",
        "terminal": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            { "type": "TextHeading", "text": "Fale com a gente" },
            { "type": "TextInput", "name": "mensagem", "label": "Mensagem" },
            { "type": "Footer", "label": "Enviar",
              "on-click-action": { "name": "complete", "payload": {} } }
          ]
        }
      }]
    }
  }'
200Flow criado
json
{
  "id": 4,
  "flow_key": "contato_rapido",
  "name": "Contato rápido",
  "scope": "global",
  "flow_json": { "version": "7.3", "screens": [ { "id": "CONTATO", "terminal": true, "layout": { "type": "SingleColumnLayout", "children": [] } } ] },
  "ai_when_to_use": "Cliente quer deixar um recado para a loja.",
  "ai_params": {},
  "status": "draft",
  "version": 1,
  "meta_flow_id": "",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

A criação devolve 200 (não 201) com o Flow completo.

Consultar um Flow

GET/api/v1/admin/whatsapp-platform/flows/{id}Admin

Consultar um Flow pelo id

Devolve um Flow, com o flow_json completo.

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

A resposta 200 é o objeto Flow descrito acima.

Atualizar um Flow

PUT/api/v1/admin/whatsapp-platform/flows/{id}Admin

Atualizar um Flow global

Substitui o conteúdo do Flow, valida o flow_json e soma 1 em version. É uma substituição completa: o que você não enviar é apagado ou volta ao padrão. A flow_key e o meta_flow_id não mudam. Atualizar não reenvia nada à Meta; para isso use publish de novo.

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Corpo da requisição

namestring
Nome. Omitido, o nome fica vazio.
flow_jsonobjectobrigatório
JSON do Flow completo.
ai_when_to_usestring
Omitido, fica vazio.
ai_paramsobject
Omitido, volta a {}.
statusstringpadrão: draft
draftpublished
Omitido, o Flow volta a draft, mesmo que estivesse publicado.
categorystringpadrão: OTHER
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Omitido, volta a OTHER.
flow_keystring
Ignorado: a chave não pode ser alterada.

A resposta 200 é o Flow atualizado, com version incrementada.

Apagar um Flow

DELETE/api/v1/admin/whatsapp-platform/flows/{id}Admin

Apagar um Flow global

Remove o registro da plataforma. Se o Flow já foi publicado, ele continua existindo na Meta; só deixa de estar disponível aqui. Apagar um id que não existe também devolve sucesso.

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.
200Flow apagado
json
{ "success": true }

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido{"error":"Invalid request body"}
400{id} que não é inteiro{"error":"Invalid id"}
400flow_key vazia (POST){"error":"flow_key é obrigatório"}
400flow_key já existe (POST){"error":"..."} (mensagem do banco)
400PUT em um id que não existe{"error":"flow não encontrado"}
404GET em um id que não existe{"error":"flow não encontrado"}
422flow_json inválido (POST, PUT){"error":"Flow JSON inválido","errors":["screens vazio"]}
401 / 403Sem token / sem ser root_admin com manage_whatsapp_platform{"error":"insufficient permissions"}
500Falha de banco (listar, apagar){"error":"..."}

Os textos de errors são montados em português pelo servidor, um item por problema encontrado (por exemplo, screen CONTATO comp TextInput: prop obrigatória ausente "label").

Editar um Flow publicado o devolve para rascunho

O PUT sem status grava draft. Como a IA só oferece Flows published, um Flow ativo some do atendimento até você reenviar "status": "published" (ou publicar de novo). Para só ajustar o texto, leia o Flow com GET, altere o que precisa e envie o objeto inteiro de volta, status incluído.

Valide antes de publicar

A mesma validação roda no POST, no PUT e no publish. Salvar com sucesso quer dizer que a estrutura é válida para a plataforma, mas a Meta tem regras próprias e pode recusar na publicação.

Veja também

  • Publicar, pré-visualizar e usar com IA
  • Credenciais da plataforma
  • Visão geral do WhatsApp Platform
Anterior
Chave mestra e URL padrão das rotas
Próxima
Publicar, pré-visualizar e usar com IA
Nesta página
  • O objeto Flow
  • Regras de validação do flowjson
  • Listar Flows
  • Criar um Flow
  • Exemplo de requisição
  • Consultar um Flow
  • Atualizar um Flow
  • Apagar um Flow
  • Erros
  • Veja também