WhatsApp: fluxos do bot

O bot de WhatsApp da loja segue roteiros chamados fluxos. Quando um cliente escreve, a plataforma escolhe um fluxo (por palavra-chave ou pelo fluxo padrão), abre uma sessão para ele e anda de bloco em bloco: manda uma mensagem, mostra um menu, pergunta um dado, consulta o catálogo, passa para um atendente. Esta seção documenta como ler, montar, testar e instalar esses fluxos.

Como funciona

1. Crie o fluxo

   POST /flows com name e, se quiser disparo por palavra, trigger_type: "keyword" e trigger_keywords.

2. Monte os blocos e as ligações

   POST /flows/{id}/blocks para cada passo e POST /flows/{id}/connections para cada seta.

3. Defina o bloco inicial

   PATCH /flows/{id} com start_block_id.

4. Confira e teste

   GET /flows/{id}/validate e POST /flows/{id}/simulate.

5. Ative

   PATCH /flows/{id} com status: "active". Depois use GET /inbound-probe para ver o resultado com um telefone real.

Estados do fluxo:

Estados da sessão do cliente: active (em andamento), completed (terminou), abandoned (venceu ou foi trocada) e errored (um bloco falhou).

Conceitos-chave

Gatilho: como um fluxo é escolhido

Cada fluxo tem um trigger_type. keyword: dispara quando a mensagem casa com uma das trigger_keywords (comparação exact, starts_with, contains ou regex; vence a maior trigger_priority). inbound_default: atende quem escreve sem casar com nenhuma palavra e sem sessão em andamento. manual: nunca dispara sozinho. Se uma sessão do cliente já está em andamento, a mensagem continua nela.

Sessão

Guarda o bloco atual e as variáveis (session_data). Uma sessão parada além de expires_at é abandonada e a próxima mensagem abre outra, do bloco inicial.

Seller e loja

Fluxos podem ser da loja toda (sem vendor_id) ou de um seller (lojista). Administrador restrito a um seller só vê e altera os fluxos dele; um superadministrador da loja vê todos.

Estado em letra ou palavra

O estado do fluxo pode voltar como letra (A) ou palavra (active), conforme a loja. Ao escrever, mande sempre a palavra.

Endpoints

Erros comuns

• Ativar um fluxo sem start_block_id: ele não responde. Rode /validate primeiro.
• Deixar o trigger_type em manual e esperar que o fluxo dispare sozinho.
• Criar um gatilho keyword sem palavras: a plataforma recusa com 400.
• Enviar só uma chave no config ao alterar um bloco: o objeto inteiro é substituído.
• Mandar start_block_id: null para limpar o bloco inicial: null é ignorado, use "".
• Apagar o bloco inicial: o fluxo continua apontando para ele.
• Usar test-run na sessão de um cliente real: ela avança de verdade. Teste com /simulate.
• Instalar o mesmo pacote duas vezes: cria fluxos duplicados.
• Passar um id que não é UUID: várias rotas respondem 500 em vez de 400.

Próximos passos