Session Status

SessionStatus

The SessionStatus type represents the current lifecycle state of a ChatSession. Subscribe via session.on('status_changed', ...) or read useChatSession().status.

Value	Meaning	Can Send?
`idle`	Session created but not yet started.	No
`authenticating`	Acquiring or refreshing an auth token.	No
`connecting`	Establishing transport connection.	No
`ready`	Connected and accepting messages.	Yes
`submitted`	User message sent, awaiting response stream.	No
`streaming`	Agent response is actively streaming.	No
`waiting_for_tool`	Agent requested a tool call; waiting for result.	No
`uploading`	File upload in progress.	No
`handoff_requested`	Live-agent handoff was requested.	No
`handoff_queued`	User is in the handoff queue.	No
`handoff_connected`	Connected to a live agent.	Yes
`ended`	Session ended normally.	No
`expired`	Session expired server-side.	No
`disconnected`	Transport connection lost.	No
`recovering`	Recovery policy is attempting reconnection.	No
`error`	Unrecoverable error.	No
`shutdown`	Client or session was shut down.	No

HandoffStatus

Tracks the live-agent handoff lifecycle within a session. Read via useChatSession().handoffStatus or the AgentTransferPart.status field.

Value	Meaning
`none`	No handoff in progress.
`requested`	Handoff requested by the agent.
`queued`	Waiting in the agent queue.
`connecting`	Connecting to the live agent.
`ringing`	Agent desktop is being alerted.
`connected`	Live agent is active.
`on_hold`	Live agent has placed the customer on hold.
`ended`	Handoff leg ended without a resolution signal.
`failed`	Handoff failed.
`cancelled`	Handoff was cancelled.
`completed`	Handoff was successfully resolved.

State Transition Notes

The session starts at idle and moves through authenticating and connecting to ready.
Sending a message transitions from ready to submitted, then to streaming as the response arrives.
If the agent calls a tool, the session enters waiting_for_tool until the result is returned, then resumes streaming.
A transport disconnect moves the session to disconnected, then recovering while the recovery policy retries. On success, the session returns to streaming or ready. On failure, it moves to error.
ended, expired, error, and shutdown are terminal states. Create a new session to continue.

Source: docs/reference/session-status.md