Conversations
Manage conversation lifecycle, history, and agent handoffs
Conversation Lifecycle
Conversations follow a defined lifecycle with clear status transitions.
| Status | Description | Transitions to |
|---|---|---|
| Active | Conversation is in progress with active message exchange | Waiting, Resolved |
| Waiting | Conversation is paused, awaiting user response or human intervention | Active, Resolved |
| Resolved | Conversation has been completed and resolved | Active (reopened), Archived |
| Archived | Conversation has been archived for long-term storage | None (final state) |
Message History
Every message in a conversation is stored with full metadata, enabling search, analysis, and compliance auditing.
- User messages Messages sent by the end user or contact
- Agent messages Messages generated by the AI agent
- System events Internal system events such as handoffs, status changes, and tool executions
- Tool calls Tool call requests and their results, including parameters and execution time
Search across all conversations using keywords, date ranges, channels, or agent assignments.
Agent Handoff
Agents can transfer conversations to other agents or human operators when they encounter situations outside their scope.
Handoff Triggers
- Explicit rule — Routing rule matches a specific keyword or intent
- Low confidence — Agent is uncertain about the correct response
- User escalation — User explicitly requests human assistance
- Timeout — Agent cannot resolve within the configured time limit
Handoff Process
- The agent determines that a handoff is needed based on the trigger condition.
- The conversation context and full history are transferred to the receiving agent or operator.
- The user is notified that they are being connected to a different agent or a human representative.
- The receiving party reviews the context and continues the conversation seamlessly.
Conversation Context
Each conversation carries contextual information that agents use to provide relevant responses.
- Channel The channel through which the conversation is taking place (Slack, Teams, Widget, etc.)
- User The end user or contact interacting with the agent, including prior conversation history
- Session Session metadata including start time, message count, and tokens consumed
- Agent The active agent handling the conversation, including model and configuration
Conversation Metadata
Each conversation stores metadata that provides insights into usage and performance.
| Field | Description |
|---|---|
| Started At | Timestamp when the conversation was initiated |
| Resolved At | Timestamp when the conversation was resolved (null if still active) |
| Message Count | Total number of messages exchanged in the conversation |
| Tokens Used | Total input and output tokens consumed during the conversation |
| Satisfaction Score | User satisfaction rating on a 1–5 scale (if feedback was provided) |
Conversation Audit Trail
Every conversation maintains a complete audit trail for compliance and debugging purposes.
Audit events are immutable and retained according to your data retention policy. They can be exported via the API for external compliance systems.
- Tool invocations with parameters and results
- Knowledge base queries and matched articles
- Agent-to-agent and agent-to-human handoffs
- Model switches during the conversation
- Tool approval requests and outcomes