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

Flows da loja

Lista, cria, lê, altera e apaga os Flows (telas de formulário do WhatsApp) da loja.

Um Flow da Meta é um conjunto de telas (formulários, listas, seletores) que abre dentro do WhatsApp. Estas rotas guardam, no painel da loja, o desenho dos seus Flows. Elas não falam com a Meta: para isso veja a página de publicação.

Listar os Flows

Devolve os Flows da loja, do alterado mais recentemente ao mais antigo, e a lista de componentes de tela que a plataforma aceita.

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

Lista os Flows da loja

Exemplo de requisição (Listar os Flows)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/meta-flows" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar os Flows)

200Flows devolvidos
json
{
  "components": [
    "Dropdown",
    "RadioButtonsGroup",
    "DatePicker",
    "Image",
    "TextCaption",
    "CalendarPicker",
    "NavigationList",
    "CheckboxGroup",
    "OptIn",
    "RichText",
    "ChipsSelector",
    "DocumentPicker",
    "TextHeading",
    "TextBody",
    "TextInput",
    "TextArea",
    "Footer",
    "EmbeddedLink",
    "TextSubheading",
    "PhotoPicker",
    "ImageCarousel"
  ],
  "flows": [
    {
      "id": 2,
      "flow_key": "contato-rapido",
      "name": "Contato rápido",
      "scope": "store",
      "flow_json": {
        "version": "6.2",
        "screens": [
          {
            "id": "CONTACT",
            "title": "Contato",
            "terminal": true,
            "success": true,
            "layout": {
              "type": "SingleColumnLayout",
              "children": [
                {
                  "type": "TextHeading",
                  "text": "Fale com a gente"
                },
                {
                  "type": "Form",
                  "name": "form",
                  "children": [
                    {
                      "type": "TextInput",
                      "name": "nome",
                      "label": "Seu nome",
                      "input-type": "text",
                      "required": true
                    },
                    {
                      "type": "Footer",
                      "label": "Enviar",
                      "on-click-action": {
                        "name": "complete",
                        "payload": {
                          "nome": "${form.nome}"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        ]
      },
      "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
      "ai_params": {},
      "status": "draft",
      "version": 1,
      "meta_flow_id": "",
      "category": "CONTACT_US",
      "created_at": "2026-10-11T23:55:12.229890Z",
      "updated_at": "2026-10-11T23:55:12.229890Z"
    }
  ]
}

Campos da resposta

flowsarray

Flows da loja. Sem paginação.

idinteger
Identificador numérico do Flow na loja. Não é UUID.
flow_keystring
Chave única e estável do Flow na loja (até 120 caracteres). Não muda depois de criado.
namestring
Nome mostrado no painel e usado como nome do Flow na Meta.
scopestring
storeglobal
Onde o Flow vive. Nestas rotas é sempre store.
flow_jsonobject
O desenho das telas, no formato JSON de Flows da Meta.
ai_when_to_usestring
Texto que explica ao assistente quando enviar este Flow.
ai_paramsobject
Objeto JSON livre guardado junto ao Flow. {} quando vazio.
statusstring
draftpublished
draft até ser publicado na Meta; published depois.
versioninteger
Começa em 1 e sobe a cada PUT.
meta_flow_idstring
Id do Flow na Meta, preenchido na publicação. Texto vazio antes disso.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
componentsarray
Nomes dos 21 tipos de componente aceitos em flow_json.

Erros (Listar os Flows)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao consultar.{"error":"..."}

Criar um Flow

Guarda um Flow novo na loja, ainda só no painel: ele não existe na Meta até ser publicado. O flow_json é validado antes de gravar.

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

Cria um Flow da loja

Corpo da requisição

flow_keystringobrigatório
Chave única do Flow na loja. Obrigatória, até 120 caracteres.
namestring
Nome do Flow.
flow_jsonobjectobrigatório
Desenho das telas no formato de Flows da Meta. Obrigatório e validado (veja as regras na visão geral).
ai_when_to_usestring
Quando o assistente deve enviar este Flow.
ai_paramsobject
Objeto JSON livre. Omitido, vira {}.
statusstringpadrão: draft
draftpublished
Estado a gravar. Omitido, vira draft.
categorystringpadrão: OTHER
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta. Valor fora da lista vira OTHER.

Exemplo de requisição (Criar um Flow)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-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": "Quando o cliente pedir para ser chamado de volta.",
    "flow_json": {
      "version": "6.2",
      "screens": [
        {
          "id": "CONTACT",
          "title": "Contato",
          "terminal": true,
          "success": true,
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              {
                "type": "TextHeading",
                "text": "Fale com a gente"
              },
              {
                "type": "Form",
                "name": "form",
                "children": [
                  {
                    "type": "TextInput",
                    "name": "nome",
                    "label": "Seu nome",
                    "input-type": "text",
                    "required": true
                  },
                  {
                    "type": "Footer",
                    "label": "Enviar",
                    "on-click-action": {
                      "name": "complete",
                      "payload": {
                        "nome": "${form.nome}"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }'

Resposta (Criar um Flow)

200Flow criado
json
{
  "id": 2,
  "flow_key": "contato-rapido",
  "name": "Contato rápido",
  "scope": "store",
  "flow_json": {
    "version": "6.2",
    "screens": [
      {
        "id": "CONTACT",
        "title": "Contato",
        "terminal": true,
        "success": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            {
              "type": "TextHeading",
              "text": "Fale com a gente"
            },
            {
              "type": "Form",
              "name": "form",
              "children": [
                {
                  "type": "TextInput",
                  "name": "nome",
                  "label": "Seu nome",
                  "input-type": "text",
                  "required": true
                },
                {
                  "type": "Footer",
                  "label": "Enviar",
                  "on-click-action": {
                    "name": "complete",
                    "payload": {
                      "nome": "${form.nome}"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "ai_params": {},
  "status": "draft",
  "version": 1,
  "meta_flow_id": "",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T23:55:12.229890Z",
  "updated_at": "2026-10-11T23:55:12.229890Z"
}

Campos da resposta

idinteger
Identificador numérico do Flow na loja. Não é UUID.
flow_keystring
Chave única e estável do Flow na loja (até 120 caracteres). Não muda depois de criado.
namestring
Nome mostrado no painel e usado como nome do Flow na Meta.
scopestring
storeglobal
Onde o Flow vive. Nestas rotas é sempre store.
flow_jsonobject
O desenho das telas, no formato JSON de Flows da Meta.
ai_when_to_usestring
Texto que explica ao assistente quando enviar este Flow.
ai_paramsobject
Objeto JSON livre guardado junto ao Flow. {} quando vazio.
statusstring
draftpublished
draft até ser publicado na Meta; published depois.
versioninteger
Começa em 1 e sobe a cada PUT.
meta_flow_idstring
Id do Flow na Meta, preenchido na publicação. Texto vazio antes disso.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Criar um Flow)

StatusQuandoCorpo
400Corpo que não é JSON, flow_key ausente, ou chave já usada (a mensagem é a do banco de dados).{"error":"flow_key é obrigatório"} ou {"error":"pq: duplicate key value violates unique constraint \"whatsapp_meta_flows_flow_key_key\" (23505)"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
422O flow_json não passa na validação. A lista errors diz o que corrigir.{"error":"Flow JSON inválido","errors":["version ausente","screens vazio"]}
Status 200, não 201

Esta rota responde 200 ao criar.

Valide sem publicar

O flow_json passa pela mesma validação que a publicação usa. Se a criação aceitar, a publicação não vai recusar por estrutura (ela ainda pode falhar na Meta).

Ver um Flow

Devolve um Flow pelo id, com o flow_json completo.

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

Lê um Flow da loja

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Exemplo de requisição (Ver um Flow)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver um Flow)

200Flow devolvido
json
{
  "id": 2,
  "flow_key": "contato-rapido",
  "name": "Contato rápido",
  "scope": "store",
  "flow_json": {
    "version": "6.2",
    "screens": [
      {
        "id": "CONTACT",
        "title": "Contato",
        "terminal": true,
        "success": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            {
              "type": "TextHeading",
              "text": "Fale com a gente"
            },
            {
              "type": "Form",
              "name": "form",
              "children": [
                {
                  "type": "TextInput",
                  "name": "nome",
                  "label": "Seu nome",
                  "input-type": "text",
                  "required": true
                },
                {
                  "type": "Footer",
                  "label": "Enviar",
                  "on-click-action": {
                    "name": "complete",
                    "payload": {
                      "nome": "${form.nome}"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "ai_params": {},
  "status": "draft",
  "version": 1,
  "meta_flow_id": "",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T23:55:12.229890Z",
  "updated_at": "2026-10-11T23:55:12.229890Z"
}

Campos da resposta

idinteger
Identificador numérico do Flow na loja. Não é UUID.
flow_keystring
Chave única e estável do Flow na loja (até 120 caracteres). Não muda depois de criado.
namestring
Nome mostrado no painel e usado como nome do Flow na Meta.
scopestring
storeglobal
Onde o Flow vive. Nestas rotas é sempre store.
flow_jsonobject
O desenho das telas, no formato JSON de Flows da Meta.
ai_when_to_usestring
Texto que explica ao assistente quando enviar este Flow.
ai_paramsobject
Objeto JSON livre guardado junto ao Flow. {} quando vazio.
statusstring
draftpublished
draft até ser publicado na Meta; published depois.
versioninteger
Começa em 1 e sobe a cada PUT.
meta_flow_idstring
Id do Flow na Meta, preenchido na publicação. Texto vazio antes disso.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Ver um Flow)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Flow não encontrado.{"error":"flow não encontrado"}

Alterar um Flow

Substitui o Flow inteiro: nome, desenho, textos para o assistente, estado e categoria. O flow_key não muda. A version sobe em 1.

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

Substitui um Flow da loja

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Corpo da requisição

namestring
Nome do Flow.
flow_jsonobjectobrigatório
Desenho das telas no formato de Flows da Meta. Obrigatório e validado (veja as regras na visão geral).
ai_when_to_usestring
Quando o assistente deve enviar este Flow.
ai_paramsobject
Objeto JSON livre. Omitido, vira {}.
statusstringpadrão: draft
draftpublished
Estado a gravar. Omitido, vira draft.
categorystringpadrão: OTHER
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta. Valor fora da lista vira OTHER.

Exemplo de requisição (Alterar um Flow)

bash
curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contato rápido v2",
    "category": "CONTACT_US",
    "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
    "flow_json": {
      "version": "6.2",
      "screens": [
        {
          "id": "CONTACT",
          "title": "Contato",
          "terminal": true,
          "success": true,
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              {
                "type": "TextHeading",
                "text": "Fale com a gente"
              },
              {
                "type": "Form",
                "name": "form",
                "children": [
                  {
                    "type": "TextInput",
                    "name": "nome",
                    "label": "Seu nome",
                    "input-type": "text",
                    "required": true
                  },
                  {
                    "type": "Footer",
                    "label": "Enviar",
                    "on-click-action": {
                      "name": "complete",
                      "payload": {
                        "nome": "${form.nome}"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }'

Resposta (Alterar um Flow)

200Flow atualizado
json
{
  "id": 2,
  "flow_key": "contato-rapido",
  "name": "Contato rápido v2",
  "scope": "store",
  "flow_json": {
    "version": "6.2",
    "screens": [
      {
        "id": "CONTACT",
        "title": "Contato",
        "terminal": true,
        "success": true,
        "layout": {
          "type": "SingleColumnLayout",
          "children": [
            {
              "type": "TextHeading",
              "text": "Fale com a gente"
            },
            {
              "type": "Form",
              "name": "form",
              "children": [
                {
                  "type": "TextInput",
                  "name": "nome",
                  "label": "Seu nome",
                  "input-type": "text",
                  "required": true
                },
                {
                  "type": "Footer",
                  "label": "Enviar",
                  "on-click-action": {
                    "name": "complete",
                    "payload": {
                      "nome": "${form.nome}"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "ai_params": {},
  "status": "draft",
  "version": 2,
  "meta_flow_id": "",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T23:55:12.229890Z",
  "updated_at": "2026-10-11T23:55:12.229890Z"
}

Campos da resposta

idinteger
Identificador numérico do Flow na loja. Não é UUID.
flow_keystring
Chave única e estável do Flow na loja (até 120 caracteres). Não muda depois de criado.
namestring
Nome mostrado no painel e usado como nome do Flow na Meta.
scopestring
storeglobal
Onde o Flow vive. Nestas rotas é sempre store.
flow_jsonobject
O desenho das telas, no formato JSON de Flows da Meta.
ai_when_to_usestring
Texto que explica ao assistente quando enviar este Flow.
ai_paramsobject
Objeto JSON livre guardado junto ao Flow. {} quando vazio.
statusstring
draftpublished
draft até ser publicado na Meta; published depois.
versioninteger
Começa em 1 e sobe a cada PUT.
meta_flow_idstring
Id do Flow na Meta, preenchido na publicação. Texto vazio antes disso.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Alterar um Flow)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
400Corpo que não é JSON, ou Flow inexistente (esta rota responde 400, não 404).{"error":"flow não encontrado"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
422O flow_json não passa na validação. A lista errors diz o que corrigir.{"error":"Flow JSON inválido","errors":["version ausente","screens vazio"]}
Volta para rascunho

Se você não enviar status, o Flow volta a draft mesmo que estivesse published. O meta_flow_id é mantido, mas a versão na Meta só muda quando você publicar de novo.

É PUT de verdade

Todos os campos são regravados. Reenvie flow_json e ai_when_to_use mesmo que só queira mudar o nome.

Apagar um Flow

Remove o Flow do painel.

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

Apaga um Flow da loja

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Exemplo de requisição (Apagar um Flow)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar um Flow)

200Flow apagado
json
{
  "success": true
}

Campos da resposta

successboolean
Sempre true.

Erros (Apagar um Flow)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao apagar.{"error":"..."}
A cópia na Meta continua

A rota apaga só o registro da loja, de forma definitiva. Um Flow já publicado continua existindo na conta da Meta. A rota também responde success para um id que não existe.

Veja também

  • Publicar e enviar
  • Visão geral
Anterior
WhatsApp: Flows da Meta
Próxima
Publicar e enviar
Nesta página
  • Listar os Flows
  • Exemplo de requisição (Listar os Flows)
  • Resposta (Listar os Flows)
  • Erros (Listar os Flows)
  • Criar um Flow
  • Exemplo de requisição (Criar um Flow)
  • Resposta (Criar um Flow)
  • Erros (Criar um Flow)
  • Ver um Flow
  • Exemplo de requisição (Ver um Flow)
  • Resposta (Ver um Flow)
  • Erros (Ver um Flow)
  • Alterar um Flow
  • Exemplo de requisição (Alterar um Flow)
  • Resposta (Alterar um Flow)
  • Erros (Alterar um Flow)
  • Apagar um Flow
  • Exemplo de requisição (Apagar um Flow)
  • Resposta (Apagar um Flow)
  • Erros (Apagar um Flow)
  • Veja também