Disparar um fluxo pela API

Um fluxo é uma automação montada no editor visual do painel: mensagens, perguntas, condições, esperas. O gatilho API deixa o seu sistema iniciar esse fluxo para um contato no momento certo — um pedido pago, um lead que chegou do site, um boleto que venceu — sem você montar cada mensagem no código.

Preparar o fluxo

No editor, adicione o gatilho API e ligue-o ao primeiro passo.
Opcionalmente, escolha no gatilho o número que vai enviar.
Publique e ative o fluxo. O disparo usa sempre a versão publicada — um gatilho que só existe no rascunho responde 422 flow_no_api_trigger.

O id do fluxo aparece no editor e em GET /flows.

Disparar

curl -X POST https://api.joinotify.com/flows/cm1fl0w000001/trigger \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1042-pago' \
  -d '{
    "contact": { "phone": "+5541987111527" },
    "data": { "pedido": "1042", "valor": "R$ 189,90" }
  }'

202 Accepted
{ "data": { "runId": "cm1run0000001", "replayed": false } }

O contato vem por contact.id ou contact.phone. Com o telefone, um contato que não existe é criado — e dispara contact.created.
Os dados de data ficam disponíveis no fluxo como {{trigger.pedido}}, com valor padrão opcional: {{trigger.cupom|sem cupom}}.
O número que envia é phoneNumberId, se você mandar; senão, o configurado no gatilho; senão, o número ativo mais antigo da conta.

A resposta chega antes das mensagens: o fluxo roda em seguida, fora da requisição.

runId: null não é erro

Acontece quando o gatilho não está ligado a nenhum passo, ou quando o mesmo contato começou este fluxo há poucos instantes — há um intervalo mínimo entre execuções, para que um evento duplicado no seu sistema não mande tudo duas vezes.

Começar uma execução cancela as outras em andamento do mesmo contato naquele número, em qualquer fluxo. Um contato conversa com um fluxo de cada vez.

Repetir sem duplicar

Com Idempotency-Key, repetir o disparo em até 24 horas devolve 200 com o mesmo runId e replayed: true, sem começar outra execução. Duas diferenças para o POST /messages:

o corpo não é comparado — a mesma chave devolve a mesma execução, mesmo com outro data;
uma chamada que falhou (fluxo inativo, número inválido) não guarda a chave, e a repetição tenta de novo.

O que é conferido depois

O disparo aceita o pedido; as regras de envio valem quando cada mensagem sai:

um template de marketing para um contato em opt-out ou na lista de supressão encerra a execução com o motivo contact_opted_out;
uma mensagem livre com a janela de 24 horas fechada encerra com window_closed, a menos que o passo tenha um template reserva configurado;
se a conta perder o direito de uso no meio do caminho, a execução para com billing.

Acompanhar o resultado

Assine dois eventos no seu endpoint de webhooks:

Evento	O que traz
`flow.answer.captured`	Cada resposta que um passo de Pergunta ou Aguardar resposta guardou
`flow.run.completed`	O fim da execução, com todas as variáveis do fluxo

Os dados que você mandou em data não voltam no evento — guarde o runId para casar as duas pontas. Execuções que falham ou são canceladas não geram flow.run.completed. Os payloads estão no catálogo de eventos.

Limites e escopo

Cada disparo gasta uma requisição do limite de envio da sua chave. As mensagens que o fluxo manda depois não gastam.
Uma API key restrita a alguns números pode disparar, mas só com números do escopo dela. Listar e consultar fluxos exige uma chave sem restrição.

Preparar o fluxo​

Disparar​

Repetir sem duplicar​

O que é conferido depois​

Acompanhar o resultado​

Limites e escopo​