State Machine

Each conversation instance follows a defined set of state transitions. States ensure predictable behavior and full observability.

States

Transitions

Normal Flow

CREATED → ACTIVE → WAITING_FOR_REPLY → WAITING_FOR_AGENT → ACTIVE → ...

The conversation cycles between ACTIVE, WAITING_FOR_REPLY, and WAITING_FOR_AGENT until the agent calls end_conversation().

• ACTIVE → WAITING_FOR_REPLY — agent sends a message (message_sent)
• WAITING_FOR_REPLY → WAITING_FOR_AGENT — contact replies (contact_replies)
• WAITING_FOR_AGENT → ACTIVE — agent finishes processing (agent_processes_reply)
• WAITING_FOR_AGENT → WAITING_FOR_REPLY — agent sends another message before finishing (message_sent)
• ACTIVE → WAITING_FOR_AGENT — contact replies while agent is active (contact_replies)

Heartbeat Flow

WAITING_FOR_REPLY → HEARTBEAT_SCHEDULED → WAITING_FOR_REPLY

When a contact does not respond within the configured interval, the heartbeat fires. If max follow-ups are exceeded:

HEARTBEAT_SCHEDULED → ABANDONED

Queuing

Only one active instance per contact. Additional instances enter QUEUED:

QUEUED → CREATED  (when prior instance reaches terminal state)

Pause / Resume

Any non-terminal state can be paused. The previous state is recorded for resumption:

ACTIVE → PAUSED → ACTIVE
WAITING_FOR_REPLY → PAUSED → WAITING_FOR_REPLY

Human Intervention

The agent can flag a conversation for human review:

ACTIVE → NEEDS_HUMAN_INTERVENTION → ACTIVE  (via relay resume or relay send)

Error Handling

Unrecoverable errors transition to FAILED:

ACTIVE → FAILED  (unrecoverable_error)

Cancellation

Any non-terminal state can be cancelled:

(any non-terminal) → FAILED  (reason: "cancelled")

Complete Transition Table

Terminal States

These states are final. No further transitions are possible:

• COMPLETED — conversation ended successfully
• ABANDONED — contact unresponsive after max follow-ups
• FAILED — error or manual cancellation