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

Fluxo

Lê o fluxo de conversa do seller, altera nome, status e gatilho, e confere se o desenho está coerente.

Estas quatro rotas tratam do fluxo como um todo, sem mexer nos blocos. Veja o vocabulário (fluxo, bloco, conexão, gatilho) no resumo da seção. Todas exigem um usuário seller com o módulo whatsapp-commerce e o privilégio vendor_manage_whatsapp.

Fluxo ativo

GET/api/v1/vendor/whatsapp/flows/activeSeller

Devolve o fluxo ativo do seller

É o ponto de entrada do editor. Procura o fluxo ativo do seller, de preferência o de boas-vindas (inbound_default). Se o seller ainda não tem um fluxo próprio, mas existe um da loja, a plataforma cria uma cópia editável para o seller e a devolve. Ou seja, esta chamada de leitura pode criar dados.

Exemplo de requisição

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

Resposta

200Fluxo do seller
json
{
  "flow": {
    "id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "name": "Welcome Retail",
    "description": "Boas-vindas, menu, catálogo, carrinho e pedidos.",
    "start_block_id": "b1a2c3d4-0000-4000-8000-000000000001",
    "status": "active",
    "channel": "whatsapp",
    "metadata": {},
    "trigger_type": "inbound_default",
    "trigger_keywords": [],
    "trigger_match_mode": "contains",
    "trigger_case_sensitive": false,
    "trigger_priority": 0,
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-09T18:30:00Z"
  },
  "owned": true
}
200Seller sem nenhum fluxo
json
{ "flow": null }

Campos da resposta

flowobject
O fluxo, ou null se não existe nenhum fluxo ativo para o seller nem para a loja.
flow.iduuid
Id do fluxo.
flow.vendor_iduuid
Seller dono. Ausente em fluxo da loja.
flow.namestring
Nome.
flow.descriptionstring
Descrição. Pode estar ausente.
flow.start_block_iduuid
Bloco em que a conversa começa. Ausente enquanto não definido.
flow.statusstring
draft, active, inactive ou archived (ou a letra correspondente, veja o resumo).
flow.channelstring
Sempre whatsapp nos fluxos criados por aqui.
flow.modestring
Modo do fluxo, quando definido.
flow.metadataobject
Dados livres anexados ao fluxo.
flow.trigger_typestring
manualkeywordinbound_default
Quando o fluxo dispara.
flow.trigger_keywordsarray
Palavras-chave, quando trigger_type é keyword.
flow.trigger_match_modestring
exactstarts_withcontainsregex
Como comparar a mensagem com as palavras-chave.
flow.trigger_case_sensitiveboolean
Se a comparação diferencia maiúsculas.
flow.trigger_priorityinteger
Desempate entre fluxos que combinam: o maior vence.
flow.created_atstring
RFC 3339.
flow.updated_atstring
RFC 3339.
ownedboolean
true quando o fluxo pertence ao seller. false significa fluxo da loja, somente leitura. Ausente quando flow é null.

Erros

StatusQuandoCorpo
401Sem token{"error":"authentication required"}
403Token que não é de seller{"error":"insufficient permissions"}
403Módulo desligado{"error":"module_disabled","module":"whatsapp-commerce"}
403Falta o privilégio{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}
404Usuário sem cadastro de seller{"error":"vendor profile not found","code":"vendor_profile_not_found"}
500Falha ao ler{"error":"..."}

Ler um fluxo

GET/api/v1/vendor/whatsapp/flows/{id}Seller

Lê um fluxo do seller

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição

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

Resposta

200Fluxo
json
{
  "id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Welcome Retail",
  "start_block_id": "b1a2c3d4-0000-4000-8000-000000000001",
  "status": "active",
  "channel": "whatsapp",
  "trigger_type": "inbound_default",
  "trigger_keywords": [],
  "trigger_match_mode": "contains",
  "trigger_case_sensitive": false,
  "trigger_priority": 0,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-09T18:30:00Z"
}

Os campos são os de flow em "Fluxo ativo". Os blocos e conexões ficam em rotas próprias: Blocos e Conexões.

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja acima
404Fluxo inexistente, da loja ou de outro seller{"error":"flow not found or not owned by this seller"}

Alterar um fluxo

PATCH/api/v1/vendor/whatsapp/flows/{id}Seller

Altera nome, status, gatilho e bloco inicial do fluxo

Atualização parcial: só os campos enviados mudam. Um corpo sem campos conhecidos não faz nada e devolve o fluxo como está. Devolve o fluxo atualizado.

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

namestring
Nome do fluxo.
descriptionstring
Descrição. String vazia limpa o texto.
statusstring
draftactiveinactivearchived
Estado do fluxo. disabled é aceito como sinônimo de inactive.
channelstring
Canal. Mantenha whatsapp.
modestring
Modo do fluxo. String vazia limpa.
start_block_iduuid
Bloco em que a conversa começa. String vazia remove o bloco inicial.
metadataobject
Dados livres. Substitui o objeto inteiro.
trigger_typestring
manualkeywordinbound_default
Quando o fluxo dispara.
trigger_keywordsarray
Palavras-chave. São aparadas e normalizadas. Com trigger_type keyword, precisa ter ao menos uma não vazia.
trigger_match_modestring
exactstarts_withcontainsregex
Como comparar. Uma expressão regular inválida faz o fluxo ser ignorado na hora de combinar, sem aviso.
trigger_case_sensitiveboolean
Diferenciar maiúsculas. Não vale em regex.
trigger_priorityinteger
Prioridade. O maior vence entre fluxos que combinam.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/vendor/whatsapp/flows/$FLOW_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active",
  "trigger_type": "keyword",
  "trigger_keywords": [
    "promo",
    "oferta"
  ],
  "trigger_match_mode": "contains"
}'

Resposta

200Fluxo atualizado
json
{
  "id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Promoções",
  "status": "active",
  "channel": "whatsapp",
  "trigger_type": "keyword",
  "trigger_keywords": ["promo", "oferta"],
  "trigger_match_mode": "contains",
  "trigger_case_sensitive": false,
  "trigger_priority": 0,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400trigger_type inválido{"error":"whatsapp/flows: invalid trigger_type \"x\" (want manual|keyword|inbound_default)"}
400trigger_match_mode inválido{"error":"whatsapp/flows: invalid trigger_match_mode \"x\" (want exact|starts_with|contains|regex)"}
400keyword sem palavras{"error":"whatsapp/flows: trigger_type=keyword requires at least one non-empty trigger_keywords entry"}
401 / 403Autenticação, módulo ou privilégioveja acima
404Fluxo inexistente, da loja ou de outro seller{"error":"flow not found or not owned by this seller"}
Ativar não desliga o fluxo anterior

Mudar um fluxo para active não desativa outro fluxo inbound_default do mesmo seller. Se dois combinam, vale o de maior trigger_priority. Para trocar de verdade, desative o antigo ou use a instalação de modelo pronto com substituição.

Validar o desenho

GET/api/v1/vendor/whatsapp/flows/{id}/validateSeller

Aponta problemas de desenho no fluxo

Somente leitura. Percorre os blocos e conexões e devolve a lista de problemas. Rode depois de editar e antes de ativar.

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp/flows/$FLOW_ID/validate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resultado da validação
json
{
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "valid": false,
  "issues": [
    {
      "code": "orphan_block",
      "block_id": "b1a2c3d4-0000-4000-8000-000000000009",
      "message": "block has no inbound connections and is not the entry block"
    }
  ]
}

Campos da resposta

flow_iduuid
Fluxo conferido.
validboolean
true quando issues está vazio.
issuesarray
Problemas encontrados. Sempre um array.
issues[].codestring
no_entrystart_block_not_in_flowself_loopunknown_block_refdangling_outboundduplicate_edgeorphan_block
no_entry: há blocos mas falta o bloco inicial. start_block_not_in_flow: o bloco inicial não é deste fluxo. self_loop: uma conexão sai e chega no mesmo bloco. unknown_block_ref: a origem da conexão não é deste fluxo. dangling_outbound: o destino da conexão não é deste fluxo. duplicate_edge: duas conexões do mesmo bloco com o mesmo tipo. orphan_block: bloco que nenhuma conexão alcança e que não é o inicial.
issues[].block_iduuid
Bloco envolvido, quando há.
issues[].edge_iduuid
Conexão envolvida, quando há.
issues[].messagestring
Descrição em inglês do problema.

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja acima
404Fluxo inexistente, da loja ou de outro seller{"error":"flow not found or not owned by this seller"}
400Falha ao ler o desenho{"error":"..."}
Validar não impede ativar

A API não bloqueia a ativação de um fluxo inválido. Um bloco solto (orphan_block) é inofensivo, mas dangling_outbound ou unknown_block_ref fazem a conversa quebrar no meio. Trate valid: false como impedimento no seu fluxo de publicação.

Veja também

  • Blocos
  • Conexões
  • Modelos prontos
Anterior
Fluxos e experiência do WhatsApp
Próxima
Blocos
Nesta página
  • Fluxo ativo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler um fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Validar o desenho
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também