How flow runs work
A run is one contact's trip through a flow, from the entry node to wherever it ends. Every run is scoped to a single contact on a single WhatsApp number: a contact can only have one active run per flow-eligible number at a time. If a trigger matches while a run is already active for that contact and number, Relay ignores it until the existing run finishes.
Moving from node to node
The engine walks the graph one node at a time, starting at the entry node. Most node types send something (or do something) and immediately continue to their configured next node. Three node types pause the run and wait for the contact to reply:
- Send buttons — waits for a button tap. Typing a button's title doesn't count; it's an unrecognized reply.
- Send list — waits for a row selection.
- Collect input — waits for any non-empty reply and saves it to a variable.
Everything else — Send message, Send media, If/else, Tag contact — runs straight through with no pause.
Unrecognized replies
When a run is paused and the contact's reply doesn't match anything the node expects (a button title that doesn't exist, or a reply that arrives from an entirely different context), Relay re-prompts: it resends the same node's message and waits again. This isn't configurable per flow — every flow uses the same fixed policy:
- Up to 2 re-prompts.
- After the 2nd unrecognized reply, the run ends in a handoff — the conversation moves to the shared inbox, unassigned, so a human can pick it up.
Timeouts
If a paused run gets no reply at all — recognized or not — for 24 hours, a background sweep ends it with a Timed out status. The contact can start a new run afterward the normal way (typing a keyword, or on their next first-ever message for a First-inbound-message trigger).
Paused by agent
If a human agent sends a message into the conversation from the shared inbox while a run is active, Relay treats that as the agent taking over and ends the run with status Paused by agent — the flow won't send anything further into that conversation. This is a one-way handback: the flow doesn't resume where it left off; the contact would need to trigger a new run to go through the flow again.
Automations while a run is active
While a contact has an active run on a number, Relay suppresses two automation triggers for that contact's messages on that number so the flow doesn't get talked over by an unrelated automation replying at the same time:
- New Message automations
- Keyword Match automations
Two other triggers are unaffected and still fire normally, because they're about the contact's lifecycle rather than the message itself:
- First Message from Contact
- New Contact Created
See Flows vs Automations for how the two systems relate more generally.
Run statuses
| Status | Meaning |
|---|---|
| Active | Currently in progress — either mid-node or paused waiting for a reply. |
| Completed | Reached an End node normally. |
| Handed off | Reached a Handoff to agent node, or exhausted its re-prompts. |
| Timed out | No reply for 24 hours while paused. |
| Paused by agent | An agent replied from the inbox while the run was active. |
| Failed | The engine hit an unexpected error partway through (rare — usually a sign of a malformed node config that slipped past validation). |
Only Active is ongoing; the other five are all final. See Monitoring runs for how to inspect a run in detail.