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

Criar e alterar fluxos

Cria, altera, apaga e duplica fluxos de conversa do bot de WhatsApp.

Estas rotas escrevem nos fluxos. Lembre da ordem de montagem: criar o fluxo, criar os blocos, criar as ligações, definir o bloco inicial e só então ativar.

Criar um fluxo

Cria um fluxo vazio. Depois de criar, adicione os blocos, ligue-os e defina start_block_id com PATCH. Um fluxo novo nasce como rascunho e com gatilho manual, ou seja, não responde a ninguém até você configurar o gatilho e ativar.

POST/api/v1/admin/whatsapp/flowsAdmin

Cria um fluxo de conversa

Corpo da requisição

namestringobrigatório
Nome. Obrigatório, não pode ser vazio.
vendor_iduuid
Seller dono do fluxo. Omitido, o fluxo é da loja toda. Administrador restrito a um seller tem este campo ignorado e forçado para o seu seller.
descriptionstring
Descrição livre.
statusstringpadrão: draft
draftactiveinactivearchived
Estado inicial. Uma palavra não reconhecida não é recusada: é gravada como inactive (disabled vale como apelido de inactive).
channelstringpadrão: whatsapp
Canal.
modestring
Texto livre opcional.
metadataobjectpadrão: {}
Objeto JSON livre.
trigger_typestring
manualkeywordinbound_default
O que dispara o fluxo. manual não dispara sozinho (só pelos testes); keyword dispara quando a mensagem casa com trigger_keywords; inbound_default atende quem escreve e não casou com nenhum outro fluxo.
trigger_keywordsarray
Palavras-chave. Obrigatória (com ao menos uma não vazia) quando trigger_type é keyword.
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar. Padrão contains.
trigger_case_sensitivebooleanpadrão: false
Distingue maiúsculas de minúsculas.
trigger_priorityintegerpadrão: 0
Desempate: o maior vence.

Exemplo de requisição (Criar um fluxo)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Boas-vindas",
    "description": "Recebe o cliente novo e mostra o menu.",
    "trigger_type": "keyword",
    "trigger_keywords": [
      "oi",
      "olá"
    ],
    "trigger_match_mode": "contains"
  }'

Resposta (Criar um fluxo)

201Fluxo criado
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.",
  "status": "draft",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "keyword",
  "trigger_keywords": [
    "oi",
    "olá"
  ],
  "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 (Criar um fluxo)

StatusQuandoCorpo
400Corpo que não é JSON, nome vazio, trigger_type ou trigger_match_mode inválidos, ou gatilho keyword sem palavras.{"error":"whatsapp/flows: name is required"} ou {"error":"whatsapp/flows: invalid trigger_type \"x\" (want manual|keyword|inbound_default)"} ou {"error":"whatsapp/flows: trigger_type=keyword requires at least one non-empty trigger_keywords entry"}
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"}
Criar não ativa

Mesmo com trigger_type configurado, o fluxo só atende clientes quando está ativo e tem start_block_id. Rode GET /flows/{id}/validate antes de ativar.

Alterar um fluxo

Altera só os campos enviados. É por aqui que você define o bloco inicial e ativa ou desativa o fluxo.

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

Altera um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

namestring
Novo nome.
descriptionstring
Nova descrição.
statusstring
draftactiveinactivearchived
Novo estado. Uma palavra não reconhecida não é recusada: é gravada como inactive.
channelstring
Novo canal.
modestring
Novo texto livre.
start_block_iduuid
Bloco inicial. Envie "" (texto vazio) para limpar. null é ignorado: não limpa.
metadataobject
Novo objeto de metadados, que substitui o atual. null volta para {}.
trigger_typestring
manualkeywordinbound_default
O que dispara o fluxo. manual não dispara sozinho (só pelos testes); keyword dispara quando a mensagem casa com trigger_keywords; inbound_default atende quem escreve e não casou com nenhum outro fluxo.
trigger_keywordsarray
Palavras-chave. Obrigatória (com ao menos uma não vazia) quando trigger_type é keyword.
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar. Padrão contains.
trigger_case_sensitiveboolean
Distingue maiúsculas de minúsculas.
trigger_priorityinteger
Desempate: o maior vence.

Exemplo de requisição (Alterar um fluxo)

bash
curl -X PATCH "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_block_id": "5cf73b43-5e23-480c-8037-7a7385251a22",
    "status": "active"
  }'

Resposta (Alterar um fluxo)

200Fluxo atualizado
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 (Alterar um fluxo)

StatusQuandoCorpo
400Corpo que não é JSON, valor de gatilho inválido, ou trigger_keywords vazia com gatilho keyword.{"error":"Invalid JSON body"} ou {"error":"whatsapp/flows: invalid trigger_match_mode \"x\" (want exact|starts_with|contains|regex)"}
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"}
Ativar de forma segura

A ordem recomendada é: criar o fluxo, criar os blocos, criar as ligações, definir start_block_id, conferir com /validate, testar com /simulate e só então enviar status: "active".

Um só fluxo padrão por seller

Se mais de um fluxo inbound_default estiver ativo para o mesmo seller, vale o de maior trigger_priority. Desative o antigo ao ativar o novo.

Apagar um fluxo

Apaga o fluxo (remoção lógica): ele some das listagens e deixa de atender clientes.

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

Apaga um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição (Apagar um fluxo)

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

Resposta (Apagar um fluxo)

200Fluxo apagado
json
{
  "status": "deleted",
  "id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa"
}

Campos da resposta

statusstring
deleted
Sempre deleted.
iduuid
O id enviado.

Erros (Apagar 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"}
500O id não é um UUID válido, ou falha ao apagar.{"error":"Failed to delete flow: ..."}
200 mesmo se não existir

A rota responde deleted também para um id que não existe, já foi apagado ou pertence a outro seller. Confira com GET se precisar ter certeza. Não há rota para restaurar.

Duplicar um fluxo

Copia o fluxo com todos os blocos e ligações, para você editar a cópia sem mexer no original. A cópia nasce como rascunho e com gatilho manual; as palavras-chave, o modo e a prioridade são copiados.

POST/api/v1/admin/whatsapp/flows/{id}/cloneAdmin

Duplica um fluxo com blocos e ligações

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

new_namestring
Nome da cópia. Omitido, usa o nome original seguido de (copy).

Exemplo de requisição (Duplicar um fluxo)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa/clone" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_name": "Boas-vindas (versão 2)"
  }'

Resposta (Duplicar um fluxo)

201Cópia criada
json
{
  "id": "d4e5f6a7-1b2c-4d3e-8f90-a1b2c3d4e5f6",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "name": "Boas-vindas (versão 2)",
  "description": "Recebe o cliente novo e mostra o menu.",
  "start_block_id": "e1f2a3b4-5c6d-4e7f-8091-a2b3c4d5e6f7",
  "status": "draft",
  "channel": "whatsapp",
  "metadata": {},
  "trigger_type": "manual",
  "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 (Duplicar um fluxo)

StatusQuandoCorpo
400Fluxo de origem não existe, ou falha ao copiar.{"error":"whatsapp/flows: source flow not found"}
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"}
Ids novos

A cópia tem ids novos para o fluxo, os blocos e as ligações. O start_block_id da cópia já aponta para o bloco equivalente.

Veja também

  • Ler fluxos
  • Blocos
  • Ligações
Anterior
Ler fluxos
Próxima
Blocos
Nesta página
  • Criar um fluxo
  • Exemplo de requisição (Criar um fluxo)
  • Resposta (Criar um fluxo)
  • Erros (Criar um fluxo)
  • Alterar um fluxo
  • Exemplo de requisição (Alterar um fluxo)
  • Resposta (Alterar um fluxo)
  • Erros (Alterar um fluxo)
  • Apagar um fluxo
  • Exemplo de requisição (Apagar um fluxo)
  • Resposta (Apagar um fluxo)
  • Erros (Apagar um fluxo)
  • Duplicar um fluxo
  • Exemplo de requisição (Duplicar um fluxo)
  • Resposta (Duplicar um fluxo)
  • Erros (Duplicar um fluxo)
  • Veja também