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

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

Resposta

200Fluxos
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
}

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

bash
curl "$BASE_URL/api/v1/admin/flows/4b8801c7-d1cf-4adc-807f-1aeb6f9687db" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxo
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"
}

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

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}'

Resposta

201Fluxo criado
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"
}

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

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"}'

Resposta

200Fluxo atualizado
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"
}

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

bash
curl -X DELETE "$BASE_URL/api/v1/admin/flows/4b8801c7-d1cf-4adc-807f-1aeb6f9687db" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído
json
{
  "status": "deleted",
  "id": "4b8801c7-d1cf-4adc-807f-1aeb6f9687db"
}

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