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

Gerenciar fluxos

Lista, consulta, cria, altera e exclui fluxos conversacionais do WhatsApp Commerce.

Um fluxo é um roteiro de conversa do atendimento por WhatsApp: blocos (mensagem, pergunta, menu...) ligados por conexões, que começam a rodar quando o cliente manda uma mensagem que casa com o gatilho. Estas rotas gerenciam o fluxo em si (nome, gatilho, estado). Os blocos e as conexões do desenho têm rotas próprias, em /api/v1/admin/whatsapp/flows/{id}/blocks e .../connections. Todas as rotas desta página exigem o módulo whatsapp-commerce ativo e o privilégio manage_settings.

Listar fluxos

GET/api/v1/admin/flowsAdmin

Lista os fluxos

Parâmetros de consulta

statusstring
draftactiveinactivearchived
Filtra por estado. Aceita a palavra ou a letra.
channelstring
Filtra por canal.
vendor_iduuid
Filtra por seller. Um administrador que também é seller só vê os fluxos do próprio seller, qualquer que seja este parâmetro.
searchstring
Texto no nome ou na descrição, sem diferenciar maiúsculas.
limitintegerpadrão: 50
Itens a devolver.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição

Resposta

200Fluxos

Campos da resposta

flowsarray
Os fluxos da página. Sem contagem total: peça páginas até vir menos itens que limit.
limit / offsetinteger
Os valores usados.
flows[].iduuid
Id do fluxo.
flows[].vendor_iduuid
Seller dono do fluxo. Ausente em fluxos da loja inteira.
flows[].namestring
Nome.
flows[].descriptionstring
Descrição. Ausente se vazia.
flows[].start_block_iduuid
Bloco em que a conversa começa. Ausente enquanto não definido.
flows[].statusstring
RAPH
Estado do fluxo, devolvido como letra: R rascunho, A ativo, P inativo, H arquivado. Veja a nota abaixo.
flows[].channelstring
Canal. Padrão whatsapp.
flows[].modestring
Modo do fluxo, texto livre. Ausente se vazio.
flows[].metadataobject
Dados livres do editor visual.
flows[].trigger_typestring
manualkeywordinbound_default
O que inicia o fluxo.
flows[].trigger_keywordsarray
Palavras-chave (para keyword).
flows[].trigger_match_modestring
exactstarts_withcontainsregex
Como comparar a mensagem com as palavras-chave.
flows[].trigger_case_sensitiveboolean
Se true, maiúsculas e minúsculas diferem. Não tem efeito em regex.
flows[].trigger_priorityinteger
Em empate, vence a maior prioridade.
flows[].created_at / updated_atstring
Datas (RFC 3339, UTC).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}
403O módulo whatsapp-commerce não está ativo nesta loja.{"error":"module_disabled","module":"whatsapp-commerce"}
500Falha ao listar.{"error":"Failed to list flows: ..."}
Estado em escrita e leitura

Para escrever (status no corpo, ou no filtro) use as palavras draft, active, inactive, archived. As respostas trazem a letra (R, A, P, H) em lojas atualizadas; lojas antigas podem ainda devolver a palavra em fluxos mais velhos. Aceite os dois.

Consultar um fluxo

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

Um fluxo pelo id

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição

Resposta

200Fluxo

Campos da resposta

iduuid
Id do fluxo.
vendor_iduuid
Seller dono do fluxo. Ausente em fluxos da loja inteira.
namestring
Nome.
descriptionstring
Descrição. Ausente se vazia.
start_block_iduuid
Bloco em que a conversa começa. Ausente enquanto não definido.
statusstring
RAPH
Estado do fluxo, devolvido como letra: R rascunho, A ativo, P inativo, H arquivado. Veja a nota abaixo.
channelstring
Canal. Padrão whatsapp.
modestring
Modo do fluxo, texto livre. Ausente se vazio.
metadataobject
Dados livres do editor visual.
trigger_typestring
manualkeywordinbound_default
O que inicia o fluxo.
trigger_keywordsarray
Palavras-chave (para keyword).
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar a mensagem com as palavras-chave.
trigger_case_sensitiveboolean
Se true, maiúsculas e minúsculas diferem. Não tem efeito em regex.
trigger_priorityinteger
Em empate, vence a maior prioridade.
created_at / updated_atstring
Datas (RFC 3339, UTC).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}
403O módulo whatsapp-commerce não está ativo nesta loja.{"error":"module_disabled","module":"whatsapp-commerce"}
404Fluxo não existe (ou foi excluído).{"error":"Flow not found"}
500id não é um UUID válido (a mensagem vem do banco, em inglês).{"error":"Failed to load flow: ..."}

Criar fluxo

POST/api/v1/admin/flowsAdmin

Cria um fluxo

Corpo da requisição

namestringobrigatório
Nome. Obrigatório.
descriptionstring
Descrição.
statusstringpadrão: draft
draftactiveinactivearchived
Estado inicial.
channelstringpadrão: whatsapp
Canal.
modestring
Modo, texto livre.
metadataobject
Dados livres do editor.
vendor_iduuid
Seller dono do fluxo. Omitido: fluxo da loja inteira. Ignorado para administrador que é seller (vale o dele).
trigger_typestring
manualkeywordinbound_default
O que inicia o fluxo. manual (padrão): só é iniciado manualmente; keyword: quando a mensagem do cliente casa com trigger_keywords; inbound_default: fluxo padrão quando nenhum outro casa e o cliente não está em um fluxo.
trigger_keywordsarray
Lista de textos. Obrigatória (ao menos um não vazio) quando trigger_type é keyword.
trigger_match_modestring
exactstarts_withcontainsregex
Comparação. exact: texto igual; starts_with: começa com; contains (padrão): contém; regex: expressão regular.
trigger_case_sensitivebooleanpadrão: false
Diferencia maiúsculas de minúsculas. Padrão false.
trigger_priorityintegerpadrão: 0
Prioridade em caso de vários fluxos casando: o maior número vence. Padrão 0.

Exemplo de requisição

Resposta

201Fluxo criado

Campos da resposta

campos-
Os mesmos de Consultar um fluxo.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}
403O módulo whatsapp-commerce não está ativo nesta loja.{"error":"module_disabled","module":"whatsapp-commerce"}
400JSON inválido, name vazio, trigger_type ou trigger_match_mode fora da lista, ou keyword sem palavras-chave. A mensagem vem no campo error.{"error":"whatsapp/flows: trigger_type=keyword requires at least one non-empty trigger_keywords entry"}
Um fluxo novo ainda não conversa

Para entrar em ação, o fluxo precisa estar active, ter start_block_id e um gatilho que case. Monte os blocos e defina o bloco inicial antes de ativar, e confira com Validar.

Alterar fluxo

PATCH/api/v1/admin/flows/{id}Admin

Altera um fluxo (parcial)

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

namestring
Novo nome.
descriptionstring
Nova descrição.
statusstring
draftactiveinactivearchived
Novo estado. active liga o fluxo; inactive desliga. Palavra desconhecida vira inactive, nunca active.
channelstring
Novo canal.
modestring
Novo modo.
start_block_iduuid
Bloco inicial. Omitido: não muda. Texto vazio ("") remove o bloco inicial.
metadataobject
Dados do editor.
trigger_typestring
manualkeywordinbound_default
O que inicia o fluxo. manual (padrão): só é iniciado manualmente; keyword: quando a mensagem do cliente casa com trigger_keywords; inbound_default: fluxo padrão quando nenhum outro casa e o cliente não está em um fluxo.
trigger_keywordsarray
Lista de textos. Obrigatória (ao menos um não vazio) quando trigger_type é keyword.
trigger_match_modestring
exactstarts_withcontainsregex
Comparação. exact: texto igual; starts_with: começa com; contains (padrão): contém; regex: expressão regular.
trigger_case_sensitiveboolean
Diferencia maiúsculas de minúsculas. Padrão false.
trigger_priorityinteger
Prioridade em caso de vários fluxos casando: o maior número vence. Padrão 0.

Exemplo de requisição

Resposta

200Fluxo atualizado

Campos da resposta

campos-
O fluxo completo, depois da alteração.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}
403O módulo whatsapp-commerce não está ativo nesta loja.{"error":"module_disabled","module":"whatsapp-commerce"}
400JSON inválido ou valor recusado (mesmas regras de criar).{"error":"whatsapp/flows: invalid trigger_type \"zzz\" (want manual|keyword|inbound_default)"}
404Fluxo não existe (ou foi excluído).{"error":"Flow not found"}
Só o que você envia muda

Os campos de gatilho seguem o mesmo princípio: para limpar a lista de palavras-chave envie trigger_keywords: []; omitir mantém.

Excluir fluxo

DELETE/api/v1/admin/flows/{id}Admin

Exclui um fluxo (soft delete)

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição

Resposta

200Excluído

Campos da resposta

statusstring
Sempre deleted.
iduuid
Id do fluxo.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}
403O módulo whatsapp-commerce não está ativo nesta loja.{"error":"module_disabled","module":"whatsapp-commerce"}
500id inválido ou falha ao excluir.{"error":"Failed to delete flow: ..."}
Soft delete e id inexistente

O fluxo é marcado como excluído e deixa de aparecer, de casar com mensagens e de ser consultável. A chamada com um id inexistente (UUID válido) também responde 200.

Veja também

  • Duplicar e validar
  • Erros da API
Anterior
Fluxos de WhatsApp
Próxima
Duplicar e validar
Nesta página
  • Listar fluxos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/flows?status=active&limit=50" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/flows/4b8801c7-d1cf-4adc-807f-1aeb6f9687db" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Consulta de pedido", "description": "Cumprimenta e pede o número do pedido", "trigger_type": "keyword", "trigger_keywords": ["pedido", "order"], "trigger_match_mode": "starts_with", "trigger_priority": 5}'
bash
curl -X PATCH "$BASE_URL/api/v1/admin/flows/4b8801c7-d1cf-4adc-807f-1aeb6f9687db" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/flows/4b8801c7-d1cf-4adc-807f-1aeb6f9687db" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "flows": [
    {
      "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db",
      "name": "Consulta de pedido",
      "description": "Cumprimenta e pede o número do pedido",
      "status": "R",
      "channel": "whatsapp",
      "metadata": {},
      "trigger_type": "keyword",
      "trigger_keywords": [
        "pedido",
        "order"
      ],
      "trigger_match_mode": "starts_with",
      "trigger_case_sensitive": false,
      "trigger_priority": 5,
      "created_at": "2026-10-11T21:05:32.24225Z",
      "updated_at": "2026-10-11T21:05:32.24225Z"
    }
  ],
  "limit": 50,
  "offset": 0
}
json
{
  "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db",
  "name": "Consulta de pedido",
  "description": "Cumprimenta e pede o número do pedido",
  "status": "R",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "keyword",
  "trigger_keywords": [
    "pedido",
    "order"
  ],
  "trigger_match_mode": "starts_with",
  "trigger_case_sensitive": false,
  "trigger_priority": 5,
  "created_at": "2026-10-11T21:05:32.24225Z",
  "updated_at": "2026-10-11T21:05:32.24225Z"
}
json
{
  "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db",
  "name": "Consulta de pedido",
  "description": "Cumprimenta e pede o número do pedido",
  "status": "R",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "keyword",
  "trigger_keywords": [
    "pedido",
    "order"
  ],
  "trigger_match_mode": "starts_with",
  "trigger_case_sensitive": false,
  "trigger_priority": 5,
  "created_at": "2026-10-11T21:05:32.24225Z",
  "updated_at": "2026-10-11T21:05:32.24225Z"
}
json
{
  "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db",
  "name": "Consulta de pedido",
  "description": "Cumprimenta e pede o número do pedido",
  "status": "A",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "keyword",
  "trigger_keywords": [
    "pedido",
    "order"
  ],
  "trigger_match_mode": "starts_with",
  "trigger_case_sensitive": false,
  "trigger_priority": 5,
  "created_at": "2026-10-11T21:05:32.24225Z",
  "updated_at": "2026-10-11T21:05:32.313655Z"
}
json
{
  "status": "deleted",
  "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db"
}