Conversations

What are Conversations?

Conversations are threaded chat sessions between visitors (or contacts) and your support team. Each conversation has a timeline of items—messages, events, and more.

Key Properties

Every conversation includes:

• status: open or resolved
• priority: low, medium, high, or urgent
• participants: Support agents (human or AI) involved
• tags: Labels for categorization (billing, technical, onboarding, etc.)
• timeline: Ordered list of timeline items
• lastTimelineItem: Most recent activity for sorting/preview

Conversation Lifecycle

Creation

Conversations are created when:

• A visitor sends their first message through the support widget
• A support agent initiates a conversation from the dashboard
• Your backend creates one via the API

Status Flow

open → resolved
  ↓       ↑
  └───────┘ (can be reopened)

• open: Active conversation requiring attention
• resolved: Conversation marked as complete (can be reopened)

Priority Levels

Conversations can be prioritized:

• low: General questions, non-urgent feedback
• medium: Standard support requests (default)
• high: Important issues affecting user experience
• urgent: Critical problems requiring immediate attention

Support agents can adjust priority based on conversation context.

Real-time Updates

Conversations support real-time synchronization via WebSocket:

• New messages appear instantly
• Typing indicators show when agents are composing
• Seen receipts track when messages are read
• Status changes broadcast immediately

The Cossistant SDK handles all WebSocket management automatically—no configuration needed.

Conversation Timeline

Each conversation has a timeline of items:

• Messages: Text and files from visitors or agents
• Events: System activities (assigned, resolved, participant joined)
• Future items: AI tool calls, interactive UI, custom actions

The timeline provides a complete audit trail of the conversation.

Example Timeline

1. [MESSAGE] Visitor: "How do I reset my password?"
2. [EVENT] Agent Sarah joined the conversation
3. [MESSAGE] Sarah: "I can help! Click your profile..."
4. [EVENT] Conversation marked as resolved
5. [MESSAGE] Visitor: "Thanks, that worked!"
6. [EVENT] Conversation reopened

Multi-Agent Support

Conversations can involve multiple participants:

• Human agents: Support team members
• AI agents: Automated assistants
• Mixed mode: AI handles initial triage, escalates to humans

Agents can:

• Join and leave conversations
• See full conversation history
• Add internal notes (private timeline items)

Tags and Organization

Tag conversations for filtering and reporting:

Copytags: ["billing", "urgent", "enterprise-customer"];

Tags help:

• Route conversations to specialized teams
• Generate reports and analytics
• Filter dashboard views
• Track common issue types

Seen Tracking

Cossistant tracks when participants last viewed a conversation:

• Visitors: Automatic seen updates when widget is open
• Agents: Tracked in dashboard
• Unread count: Calculated per participant

This powers unread badges in the support widget and dashboard.

Cross-Device Continuity

For identified contacts, conversations sync across devices:

• Start conversation on desktop
• Continue on mobile
• Same history, same context

Anonymous visitors have device-specific conversations.

Learn More

• Timeline Items: Building blocks of conversations
• Visitors: Anonymous users who start conversations
• Contacts: Identified users with cross-device history