Disparar um fluxo
POST/flows/:id/trigger
Inicia uma execução do fluxo para um contato. O fluxo precisa estar ativo e publicado, e a versão publicada precisa ter um gatilho do tipo API.
Identifique o contato por contact.id ou por contact.phone — com o telefone, um
contato que não existe é criado. O que vier em data fica disponível no fluxo como
{{trigger.<chave>}}. O número que envia é phoneNumberId, ou o configurado no
gatilho, ou o número ativo mais antigo da conta.
A resposta é 202 com o runId; as mensagens saem em seguida, fora da requisição.
runId pode vir null sem ser erro: o gatilho não leva a nenhum passo, ou o mesmo
contato começou este fluxo há pouco (o intervalo mínimo entre execuções). Começar uma
execução cancela as outras em andamento do mesmo contato naquele número.
Idempotência. Com Idempotency-Key, repetir a chamada em até 24 horas devolve
200 com o mesmo runId e replayed: true, sem iniciar outra execução. Diferente de
POST /messages: aqui o corpo não é comparado, e uma chamada que falhou não guarda a
chave — a repetição tenta de novo.
Request
Responses
- 200
- 202
- 401
- 402
- 403
- 404
- 409
- 422
- 429
Repetição com a mesma Idempotency-Key.
Execução iniciada.
Token ausente, malformado, desconhecido ou revogado (authentication), ou
conta suspensa (tenant_inactive).
Sem direito de uso (payment_required). O corpo traz o motivo em reason e a saída
em action: o que fazer (kind) e a página do painel onde se faz (url).
A credencial não pode usar o número: fora do escopo da chave, de outra conta, ou a conta não tem número ativo.
Fluxo inexistente (not_found) ou contact.id desconhecido (contact_not_found).
O fluxo não está ativo ou não foi publicado (flow_not_active).
Corpo inválido (invalid_request), a versão publicada não tem gatilho de API (flow_no_api_trigger) ou o telefone não é válido (contact_invalid_phone).
Limite de requisições excedido (rate_limit).
Response Headers
Segundos a aguardar antes de tentar de novo.
Categoria do limite aplicada — send, media ou default.
Qual balde os outros headers descrevem — key (a API key), session (o painel) ou account (o teto da conta).
Teto de requisições da categoria na janela atual.
Requisições restantes na janela atual.