Ir para o conteúdo

Fluxos

Criar e publicar um fluxo, iniciar pelo webhook de entrada e acompanhar as execuções.

Um fluxo é uma conversa automática: um gatilho começa a execução, e os blocos mandam mensagens, esperam respostas, aplicam listas e chamam outros sistemas. O editor visual fica na área do cliente, em Marketing > Fluxos.

As rotas de /api/v1/marketing/flows abrem com uma chave de API (wck_...) com o escopo Fluxos, criada em API > Chaves de API (veja Começar). A chave de um número ou de um cluster não abre essas rotas. O seu sistema também conversa com um fluxo pelo webhook de entrada, que não pede chave. Uma chave restrita a alguns números só vê os fluxos que enviam por esses números (os outros respondem 404), e salvar ou publicar um fluxo que enviaria por outro número responde 403 SENDER_NOT_ALLOWED.

O plano precisa incluir Fluxos. O limite do plano conta os fluxos ativos: rascunhos e pausados não contam.

Criar e publicar

bash
curl -X POST "$API_URL/api/v1/marketing/flows" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pedido recebido", "trigger": {"type": "webhook", "config": {}}, "sender": {"instanceIds": ["<id do número>"]}}'

A resposta 201 é o rascunho, e traz webhook.token e webhook.path. Copie o token agora: a API guarda só um hash dele, e nenhuma leitura o mostra de novo.

Monte o grafo pelo editor (ou com PATCH /flows/<id>) e publique:

bash
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/publish" \
  -H "Authorization: Bearer $API_KEY"

A publicação valida o fluxo. Com erro, a resposta é 422 flow_invalid com a lista de problemas por bloco (missing_trigger, output_unconnected, unknown_variable...), e nada muda. Publicado, o fluxo fica active. Editar depois cria um rascunho novo, e as execuções em andamento seguem a versão em que começaram.

Gatilhos

GatilhoQuando começa
keywordA mensagem recebida combina com uma das palavras-chave.
messageQualquer mensagem recebida pelos números do fluxo.
campaign_replyO contato responde a uma campanha.
webhookUm sistema seu chama o webhook de entrada.
manualVocê inicia para um contato ou uma lista.

Nos gatilhos message e campaign_reply, o mesmo contato só começa o fluxo de novo depois de um intervalo: 24 horas por padrão, ajustável em trigger.config.cooldownHours, de 0 (sem intervalo) a 720. O gatilho keyword não tem intervalo.

Webhook de entrada

bash
curl -X POST "$API_URL/api/v1/hooks/flows/fwh_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+55 81 99999-0001", "name": "Ana", "pedido": 123, "cliente": {"plano": "ouro"}}'
json
{"runId": "6f1c0000-0000-4000-8000-000000000000"}
  • Não leva Authorization: o token no caminho é a credencial. Guarde a URL como um segredo.
  • phone é obrigatório. O contato é criado se ainda não existir (e conta no limite de contatos).
  • Os campos do corpo viram variáveis do fluxo: {{webhook.pedido}}, {{webhook.cliente.plano}}.
  • Corpo de até 64 KiB. Rajada de 30 chamadas por token, e 2 por segundo depois disso; acima disso a resposta é 429 rate_limited. Espere e repita, sem laço.
  • Contato com opt-out ou já numa execução ativa do fluxo responde 202 com runId: null e o reason.
  • Token errado ou girado responde 404. Fluxo pausado responde 409 flow_not_active.

Perdeu o token? Gere outro em POST /flows/<id>/webhook/rotate (ou pelo editor). O anterior deixa de valer na hora. As chamadas recentes ficam em GET /flows/<id>/webhook/logs, sem o corpo e sem o telefone.

Início manual

bash
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/start" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag": "clientes"}'

Aceita {"contactIds": [...]} (até 1.000) ou {"tag": "..."} (até 10.000 contatos). A resposta diz quantas execuções começaram e quais contatos foram pulados (optout, already_running, not_found).

Execuções

  • GET /flows/<id>/runs: execuções do fluxo, com o status (running, waiting, completed, failed, cancelled).
  • GET /flows/runs/<runId>: o passo a passo, com o que foi enviado e respondido.
  • POST /flows/runs/<runId>/cancel: cancela uma execução.
  • GET /flows/<id>/stats: totais e a contagem por bloco.

Limites

  • Uma execução ativa por contato em cada fluxo.
  • No máximo 60 inícios automáticos por minuto por fluxo. Acima disso, o webhook responde 429 flow_rate_limited.
  • O ritmo de envio do fluxo (ratePerMinute) é limitado pelo plano.