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

Ler fluxos

Lista os fluxos de conversa do bot de WhatsApp, lê um fluxo e confere a estrutura dele.

Um fluxo é um roteiro de conversa: o bot recebe a mensagem do cliente, segue de bloco em bloco e responde. Estas rotas leem os fluxos da loja e conferem se a estrutura está certa.

Listar fluxos

Devolve os fluxos da loja, do mais novo ao mais antigo. Fluxos apagados não aparecem.

GET/api/v1/admin/whatsapp/flowsAdmin

Lista os fluxos de conversa do bot

Parâmetros de consulta

vendor_iduuid
Filtra por seller.
statusstring
draftactiveinactivearchived
Filtra por estado. Aceita a palavra ou a letra.
channelstring
Filtra por canal.
searchstring
Trecho a procurar no nome e na descrição.
limitintegerpadrão: 50
Itens por página. Sem teto máximo.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição (Listar fluxos)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flows?status=active&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar fluxos)

200Fluxos devolvidos
json
{
  "flows": [
    {
      "id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "name": "Boas-vindas",
      "description": "Recebe o cliente novo e mostra o menu.",
      "start_block_id": "5cf73b43-5e23-480c-8037-7a7385251a22",
      "status": "A",
      "channel": "whatsapp",
      "metadata": {},
      "trigger_type": "keyword",
      "trigger_keywords": [
        "oi"
      ],
      "trigger_match_mode": "contains",
      "trigger_case_sensitive": false,
      "trigger_priority": 0,
      "created_at": "2026-05-07T06:53:05.104529Z",
      "updated_at": "2026-07-21T15:42:56.298575Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Campos da resposta

flowsarray

Fluxos da página.

iduuid
Identificador do fluxo.
vendor_iduuid
Seller dono do fluxo. Ausente quando o fluxo é da loja toda.
namestring
Nome do fluxo.
descriptionstring
Descrição livre. Ausente quando vazia.
start_block_iduuid
Bloco por onde o fluxo começa. Ausente enquanto não definido: sem ele o fluxo não roda.
statusstring
draftactiveinactivearchived
Estado do fluxo, como está gravado: pode vir como letra (A ativo, P inativo, R rascunho, H arquivado) ou como palavra (active, inactive, draft, archived), conforme a loja. Ao escrever, envie sempre a palavra.
channelstring
Canal. Hoje sempre whatsapp.
modestring
Texto livre opcional guardado com o fluxo. Ausente quando vazio.
metadataobject
Objeto JSON livre para uso do integrador. {} quando vazio.
trigger_typestring
manualkeywordinbound_default
O que dispara o fluxo.
trigger_keywordsarray
Palavras-chave do gatilho keyword. Lista vazia quando não há.
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar a mensagem com as palavras-chave.
trigger_case_sensitiveboolean
true distingue maiúsculas de minúsculas (não vale para regex).
trigger_priorityinteger
Desempate entre fluxos que casam: o maior valor vence.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
limitinteger
Limite aplicado.
offsetinteger
Deslocamento aplicado.

Erros (Listar fluxos)

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":"Failed to list flows: ..."}
Sem total

A resposta não traz o total de fluxos. Continue pedindo páginas até receber uma lista menor que limit.

Ver um fluxo

Devolve só os dados do fluxo. Os blocos e as ligações têm rotas próprias.

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

Lê um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição (Ver um fluxo)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver um fluxo)

200Fluxo devolvido
json
{
  "id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "name": "Boas-vindas",
  "description": "Recebe o cliente novo e mostra o menu.",
  "start_block_id": "5cf73b43-5e23-480c-8037-7a7385251a22",
  "status": "A",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "keyword",
  "trigger_keywords": [
    "oi"
  ],
  "trigger_match_mode": "contains",
  "trigger_case_sensitive": false,
  "trigger_priority": 0,
  "created_at": "2026-05-07T06:53:05.104529Z",
  "updated_at": "2026-07-21T15:42:56.298575Z"
}

Campos da resposta

iduuid
Identificador do fluxo.
vendor_iduuid
Seller dono do fluxo. Ausente quando o fluxo é da loja toda.
namestring
Nome do fluxo.
descriptionstring
Descrição livre. Ausente quando vazia.
start_block_iduuid
Bloco por onde o fluxo começa. Ausente enquanto não definido: sem ele o fluxo não roda.
statusstring
draftactiveinactivearchived
Estado do fluxo, como está gravado: pode vir como letra (A ativo, P inativo, R rascunho, H arquivado) ou como palavra (active, inactive, draft, archived), conforme a loja. Ao escrever, envie sempre a palavra.
channelstring
Canal. Hoje sempre whatsapp.
modestring
Texto livre opcional guardado com o fluxo. Ausente quando vazio.
metadataobject
Objeto JSON livre para uso do integrador. {} quando vazio.
trigger_typestring
manualkeywordinbound_default
O que dispara o fluxo.
trigger_keywordsarray
Palavras-chave do gatilho keyword. Lista vazia quando não há.
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar a mensagem com as palavras-chave.
trigger_case_sensitiveboolean
true distingue maiúsculas de minúsculas (não vale para regex).
trigger_priorityinteger
Desempate entre fluxos que casam: o maior valor vence.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Ver um fluxo)

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"}
404Fluxo não encontrado (ou de outro seller, para administrador restrito a um seller).{"error":"Flow not found"}
500O id não é um UUID válido (a plataforma devolve 500 em vez de 400).{"error":"Failed to load flow: whatsapp/flows: query flow: pq: invalid input syntax for type uuid: \"xyz\" (22P02)"}

Conferir um fluxo

Percorre o grafo do fluxo e aponta erros de forma (sem entrada, bloco solto, ligação duplicada). Não altera nada. Rode antes de ativar.

GET/api/v1/admin/whatsapp/flows/{id}/validateAdmin

Confere a estrutura de um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição (Conferir um fluxo)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa/validate" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Conferir um fluxo)

200Com problemas
json
{
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "issues": [
    {
      "code": "no_entry",
      "message": "flow has blocks but no start_block_id is set"
    },
    {
      "code": "orphan_block",
      "block_id": "b8c1057a-d5b6-448f-af73-31734882b110",
      "message": "block has no inbound connections and is not the entry block"
    }
  ],
  "valid": false
}
200Sem problemas
json
{
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "issues": [],
  "valid": true
}

Campos da resposta

flow_iduuid
O fluxo conferido.
validboolean
true quando issues está vazia.
issuesarray

Problemas achados.

codestring
no_entrystart_block_not_in_floworphan_blockdangling_outboundduplicate_edgeself_loopunknown_block_ref
Tipo do problema.
block_iduuid
Bloco envolvido, quando há.
edge_iduuid
Ligação envolvida, quando há.
messagestring
Explicação em inglês.

Erros (Conferir um fluxo)

StatusQuandoCorpo
400Outra falha ao conferir (inclusive id que não é UUID).{"error":"whatsapp/flows: ..."}
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"}
404Fluxo não encontrado.{"error":"flow not found"}
Códigos de problema

no_entry: há blocos, mas start_block_id não está definido. start_block_not_in_flow: o bloco inicial não pertence ao fluxo. orphan_block: o bloco não recebe nenhuma ligação e não é o inicial. dangling_outbound: uma ligação aponta para um bloco que não existe no fluxo. unknown_block_ref: uma ligação sai de um bloco que não existe no fluxo. duplicate_edge: duas ligações saem do mesmo bloco com o mesmo connection_type. self_loop: uma ligação liga o bloco a ele mesmo.

Valida a forma, não o conteúdo

A conferência não olha o config de cada bloco nem se o start_block_id é do tipo trigger. Teste o comportamento com a simulação.

Veja também

  • Criar e alterar fluxos
  • Blocos
  • Visão geral
Anterior
WhatsApp: fluxos do bot
Próxima
Criar e alterar fluxos
Nesta página
  • Listar fluxos
  • Exemplo de requisição (Listar fluxos)
  • Resposta (Listar fluxos)
  • Erros (Listar fluxos)
  • Ver um fluxo
  • Exemplo de requisição (Ver um fluxo)
  • Resposta (Ver um fluxo)
  • Erros (Ver um fluxo)
  • Conferir um fluxo
  • Exemplo de requisição (Conferir um fluxo)
  • Resposta (Conferir um fluxo)
  • Erros (Conferir um fluxo)
  • Veja também