ChatReceive — Input & Output

Execution Timeline

When a workflow reaches a ChatReceive node, the following sequence occurs:

The node registers a listener with the chat platform (channel, user, and keyword filters applied).
The waiting port fires immediately — any nodes connected to waiting execute now.
The workflow execution suspends. No compute resources are consumed during the wait.
When a matching message arrives: the workflow resumes and the success port fires with the message payload.
If TimeoutMinutes elapses before a message arrives: the error port fires.

waiting Port Output

The waiting port fires synchronously on node entry. It carries minimal state — primarily the context needed to send a prompt to the user:

Field	Type	Description
`listening_on_channel`	string	The channel ID the node is listening on (from `FromChannel`, or empty if not set).
`listening_for_user`	string	The user ID the node will accept messages from (from `FromUser`, or empty if not set).
`keyword_filter`	string	The keyword filter in effect (from `KeywordFilter`, or empty if not set).
`timeout_at`	string (ISO 8601)	Timestamp when the timeout will fire (if `TimeoutMinutes` was set). Empty string if no timeout is configured.
`conversation_id`	string	Unique ID for this ChatReceive instance within the workflow run. Use this to correlate the waiting/success/error events in logs.

{
  "listening_on_channel": "CH-support-tier2",
  "listening_for_user": "",
  "keyword_filter": "",
  "timeout_at": "2026-05-23T16:00:00.000Z",
  "conversation_id": "cr_7f3a9b2c-1d4e-4f80-a123-789012345678"
}

success Port Output

Fires when a matching chat message is received. Contains the full message payload:

Field	Type	Description
`message_text`	string	Full text content of the received message.
`from_user`	string	User ID of the person who sent the message.
`from_channel`	string	Channel ID where the message was received.
`received_at`	string (ISO 8601)	Timestamp when the message was received.
`conversation_id`	string	The same conversation ID issued in the waiting port — use for correlating the full conversation lifecycle.
`raw_message`	object	The raw message event object from the chat platform (structure varies by platform).

{
  "message_text": "Yes, approved. Please proceed.",
  "from_user": "U-manager-007",
  "from_channel": "CH-approvals",
  "received_at": "2026-05-23T14:47:32.000Z",
  "conversation_id": "cr_7f3a9b2c-1d4e-4f80-a123-789012345678",
  "raw_message": { "type": "message", "text": "Yes, approved. Please proceed.", "ts": "1748000852.000100" }
}

error Port Output — Timeout and Filter Failure

Field	Type	Description
`errorCode`	string	Either `"timeout"` (TimeoutMinutes elapsed) or `"filter_mismatch"` (message received but keyword did not match after max wait).
`message`	string	Human-readable description of what happened.
`conversation_id`	string	Same conversation ID from the waiting port for correlation.
`waited_minutes`	integer	Actual number of minutes the node waited before the error fired.

// Timeout scenario:
{
  "errorCode": "timeout",
  "message": "No matching message received within 60 minutes.",
  "conversation_id": "cr_7f3a9b2c-1d4e-4f80-a123-789012345678",
  "waited_minutes": 60
}

Design tip: Always connect the error port to a cleanup handler. Typical cleanup includes: sending an escalation message to a supervisor channel, marking the workflow record as "timed out" in your database, and optionally restarting the ChatReceive listener with an extended timeout.