Chatflow sessions
How active WhatsApp conversations are tracked and managed as sessions.
A Chatflow session is a record of one user's in-progress or completed conversation with a Chatflow. EzFlow creates a session the moment the CHATFLOW node fires inside a parent Workflow and keeps it alive until the conversation reaches an Exit node or times out.
What a session tracks
| Field | Description |
|---|---|
chatflowId | Which Chatflow definition is running |
channel | WHATSAPP or SLACK |
recipientPhone | The user's phone number (WhatsApp sessions) |
currentNodeId | The node the bot is currently waiting at |
variables | Key-value map of data collected during the conversation |
messageHistory | Ordered list of sent and received messages with timestamps |
status | Current state of the session (see below) |
retryCount | Number of timeout retries sent so far |
maxRetries | Maximum retries before the session is abandoned (default: 3) |
nodeTimeout | Seconds to wait for a user reply before retrying (default: 120) |
Session status
| Status | Meaning |
|---|---|
ACTIVE | The conversation is in progress; the session is waiting for the user or executing a node |
COMPLETED | The conversation reached an Exit node; variables are available to the parent Workflow |
FAILED | The session encountered an unrecoverable error |
TIMEOUT | The user did not reply within the allowed retries and the session was abandoned |
How inbound messages are routed
When EzFlow receives an inbound WhatsApp message, it looks up an ACTIVE session matching the WhatsApp integration ID and the sender's phone number. If a matching session exists, the message text is appended to messageHistory and execution resumes from currentNodeId. If no active session exists, the message is ignored by the Chatflow engine (it may still be processed by other parts of the platform).
Slack conversations work the same way, matched by Slack channel and user ID.
Timeouts and retries
EzFlow checks active sessions every 5 seconds. If a session has not received a reply within nodeTimeout seconds since the last activity:
- The retry count increments.
- A configurable timeout message is sent to the user.
- Steps 1–2 repeat until
retryCountreachesmaxRetries. - When
maxRetriesis exhausted, the session moves toTIMEOUTand the parent Workflow resumes withchatflowCompleted: false.
The default nodeTimeout is 120 seconds and the default maxRetries is 3, giving a maximum wait time of about 8 minutes before a session times out.
Session completion
When execution reaches an Exit node, EzFlow marks the session COMPLETED, writes the final variables map, and emits a completion event that resumes the parent Workflow. The parent Workflow receives the collected variables and can use them in downstream nodes — for example, to look up a record or send a follow-up message.
Session logs
Every state change — node transitions, sent messages, received messages, retries, and completion — is recorded in a ChatflowSessionLog entry attached to the session. Logs include the node ID, a timestamp, and any variables captured at that point.
Related
- Node types — which nodes wait for user input and which run without pausing
- WAIT_FOR_USER_RESPONSE — the internal orchestrator node that pauses execution until a reply arrives
- CHATFLOW node — the Workflow node that starts a session and receives the completed variables
- Chatflows overview — the difference between Chatflows and Workflows