Trigger a flow

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.<path>}} — nested data included ({{trigger.customer.name}}, {{trigger.items[0].name}}), with formatting such as :money and :date. 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.