Wait for the participant
flow_awaitWait for ONDC flow events and return them the moment they occur. Target one flow or the full session, and pass after_seq to see only new events without polling.
Instructions
Block until something happens, then report it. Two scopes: Name a flow_id (or transaction_id) and it waits on that one run, returning as soon as the participant calls back — pass the seq from your last call as after_seq so nothing is seen twice. When the participant sends the flow's first action this is where you learn the transaction_id, because it was theirs to choose. Name neither and it waits on the whole session: any callback on any run, a step auto-advance sent, a refused call, a form submitted. That is the one to use when you have nothing to do — it needs no seq bookkeeping, and it comes back with runs telling you where every flow stands. Narrow what wakes it with kinds / flow_ids; anything filtered out is still reported, it just does not end the wait. timed_out: true means nothing happened yet — call again. Always prefer this over polling flow_get_status.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kinds | No | Session scope only. Wake only for these kinds. Everything else that happens is still reported in `events` — it just does not end the wait, so nothing is ever lost by filtering. | |
| flow_id | No | The flow started with flow_start. Works before the transaction id exists, so prefer it. | |
| flow_ids | No | Session scope only. Wake only for these flows. Same rule as `kinds`: other flows' events are delivered, they just do not end the wait. | |
| after_seq | No | Run scope only. Only report events newer than this — use the `seq` from the last flow_get_status or flow_await so nothing is seen twice. Ignored in session scope, which tracks delivery for you. | |
| session_id | Yes | Session returned by session_create. | |
| timeout_ms | No | How long to block. Capped server-side; defaults to the cap. | |
| transaction_id | No | A specific transaction. Only known once the flow's first action has crossed the wire. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seq | Yes | Run scope: the run's latest event number, to pass back as after_seq. Session scope: the journal seq delivered through, which is tracked for you and needs passing nowhere. | |
| next | No | What the loop needs now the wait is over. Run scope only — a session wait covers several runs, so it answers with `runs` instead. | |
| runs | No | Session scope only: where every run in this session stands, so you can pick which to drive next. | |
| event | No | ||
| scope | Yes | 'run' — you named a flow or transaction, and this reports that one. 'session' — you named neither, and this reports the whole session. | |
| events | No | What has happened in this session since your last call — the participant's callbacks, steps sent automatically, refusals, form submissions. Attached to every session-scoped result and delivered exactly once, so read it here instead of polling. Absent when nothing happened. `more` above zero means call record_get_events for the rest. | |
| timed_out | Yes | True when nothing arrived. Call again to keep waiting. | |
| transaction_id | Yes | The run's transaction id. When the participant sent the flow's first action, this wait is where you learn it — it was theirs to choose. Always null in session scope, which names no single run. |