Trigger a flow
POST/flows/:id/trigger
Starts a run of the flow for a contact. The flow must be active and published, and the published version must have an API trigger.
Identify the contact by contact.id or by contact.phone — with the phone, a contact
that does not exist is created. Whatever comes in data is available in the flow as
{{trigger.<key>}}. The sending number is phoneNumberId, or the one set on the
trigger, or the account's oldest active number.
The answer is 202 with the runId; the messages go out afterwards, outside the
request. runId may be null without it being an error: the trigger leads to no step,
or the same contact started this flow a moment ago (the minimum interval between runs).
Starting a run cancels the contact's other live runs on that number.
Idempotency. With Idempotency-Key, repeating the call within 24 hours returns
200 with the same runId and replayed: true, without starting another run. Unlike
POST /messages: here the body is not compared, and a call that failed does not keep
the key — the repeat tries again.
Request
Responses
- 200
- 202
- 401
- 402
- 403
- 404
- 409
- 422
- 429
A repeat with the same Idempotency-Key.
Run started.
Missing, malformed, unknown or revoked token (authentication), or a suspended
account (tenant_inactive).
No entitlement (payment_required). The body carries the reason in reason and the
way out in action: what to do (kind) and the dashboard page where it is done (url).
The credential cannot use the number: outside the key scope, from another account, or the account has no active number.
Flow does not exist (not_found) or unknown contact.id (contact_not_found).
The flow is not active or was never published (flow_not_active).
Invalid body (invalid_request), the published version has no API trigger (flow_no_api_trigger) or the phone is not valid (contact_invalid_phone).
Rate limit exceeded (rate_limit).
Response Headers
Seconds to wait before retrying.
Which rate limit category applied — send, media or default.
Which bucket the other headers describe — key (the API key), session (the dashboard) or account (the account ceiling).
Request ceiling for this category in the current window.
Requests left in the current window.