Timeline Items

What are Timeline Items?

Timeline items are the building blocks of conversations. Instead of only supporting messages, Cossistant uses a flexible timeline architecture that supports multiple item types.

This design enables rich, auditable conversation histories with:

• Messages: Text and media from visitors or agents
• Events: System activities and state changes
• Future expansion: AI tool calls, interactive UI, custom actions

Why Timeline Items?

Traditional chat systems only handle messages. Cossistant's timeline architecture provides:

• Complete audit trail: See when agents joined, when status changed, who resolved the conversation
• Rich context: System events provide context between messages
• Extensibility: New item types can be added without breaking existing conversations
• Flexibility: Mix messages, events, and future interactive elements in one timeline

Current Item Types

Message Items

Text and media content from visitors, agents, or AI.

Structure:

Copy{
  type: "message",
  parts: [
    { type: "text", text: "How do I reset my password?" },
    { type: "image", url: "...", mediaType: "image/png" }
  ],
  visitorId: "vis_123",        // If from visitor
  userId: null,                 // If from human agent
  aiAgentId: null,              // If from AI agent
  visibility: "public",         // or "private" for internal notes
  createdAt: "2024-01-15T10:30:00Z"
}

Message Parts:

• text: Plain text content
• image: Image attachments with URL and metadata
• file: File attachments with URL, name, size

Messages can have multiple parts (e.g., text + image).

Event Items

System-generated activities tracking conversation state changes.

Event Types:

• assigned: Agent assigned to conversation
• unassigned: Agent removed from conversation
• participant_joined: Agent joined the conversation
• participant_left: Agent left the conversation
• status_changed: Conversation status updated (open ↔ resolved)
• priority_changed: Priority level adjusted
• tag_added: Tag applied to conversation
• tag_removed: Tag removed from conversation
• resolved: Conversation marked as resolved
• reopened: Resolved conversation reopened
• visitor_blocked: Visitor blocked from support
• visitor_unblocked: Visitor unblocked

Structure:

Copy{
  type: "event",
  parts: [
    {
      type: "event",
      eventType: "participant_joined",
      actorUserId: "user_456",
      targetUserId: null,
      message: "Sarah joined the conversation"
    }
  ],
  visibility: "public",
  createdAt: "2024-01-15T10:32:00Z"
}

Events capture who did what and when, creating a transparent history.

Future Item Types

The timeline architecture is designed to support upcoming features:

AI Tool Calls

Copy{
  type: "ai_tool_call",
  parts: [
    {
      type: "tool_call",
      tool: "lookup_order",
      arguments: { orderId: "ord_789" },
      result: { status: "shipped", tracking: "1Z..." }
    }
  ]
}

Interactive UI

Copy{
  type: "ui_element",
  parts: [
    {
      type: "action_buttons",
      options: ["Resolve", "Escalate", "Request More Info"]
    }
  ]
}

Custom Actions

Copy{
  type: "custom_action",
  parts: [
    {
      type: "refund_processed",
      amount: 99,
      orderId: "ord_789"
    }
  ]
}

Timeline Item Properties

All timeline items share common fields:

• id: Unique identifier
• type: Item type (message, event, etc.)
• parts: Array of content parts
• conversationId: Parent conversation
• visibility: public or private (internal agent notes)
• createdAt: Timestamp
• updatedAt: Last modification timestamp

Actor fields (who created the item):

• visitorId: If created by visitor
• userId: If created by human agent
• aiAgentId: If created by AI agent

Visibility Control

Timeline items can be:

• public: Visible to visitors and agents (default)
• private: Internal agent notes, hidden from visitors

This enables agents to:

• Add context for other team members
• Document resolutions internally
• Share insights without visitor visibility

Timeline Ordering

Items are ordered chronologically by createdAt timestamp, providing a linear conversation history.

The most recent item (lastTimelineItem) is cached on the conversation for:

• Sorting conversations by activity
• Displaying conversation previews
• Determining unread status

Learn More

• Conversations: Chat threads containing timeline items
• Visitors: Anonymous users who create timeline items
• Contacts: Identified users with persistent timelines