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
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:
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
| Gatilho | Quando começa |
|---|---|
keyword | A mensagem recebida combina com uma das palavras-chave. |
message | Qualquer mensagem recebida pelos números do fluxo. |
campaign_reply | O contato responde a uma campanha. |
webhook | Um sistema seu chama o webhook de entrada. |
manual | Você 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
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"}}'{"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 é
429rate_limited. Espere e repita, sem laço. - Contato com opt-out ou já numa execução ativa do fluxo responde
202comrunId: nulle oreason. - Token errado ou girado responde
404. Fluxo pausado responde409flow_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
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
429flow_rate_limited. - O ritmo de envio do fluxo (
ratePerMinute) é limitado pelo plano.