Timeline Items

What are Timeline Items?

Timeline items are the building blocks of conversations. Instead of treating a conversation as a flat list of messages, Cossistant stores a timeline of structured records that can represent both chat content and everything happening around it.

This design enables rich, auditable conversation histories with:

• Messages: Visitor, human agent, or AI message content
• Events: System activities and state changes
• Identification records: Visitor/contact identification activity
• Tool activity: AI and tool timeline records

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
• Flexibility: Mix messages, events, identification, and tool activity in one ordered history
• Extensibility: New item types can be added without breaking existing conversations

Current Item Types

Message Items

Message items hold the actual content exchanged in a conversation. They can come from a visitor, a human teammate, or an AI agent.

The important implementation detail is that text remains the original message body. Rich content and derived content live in parts, so one timeline item can keep the original message while also storing things like attachments, metadata, or translations.

Canonical Timeline Item Shape

Message Parts:

• text: Plain text content
• image: Image attachments with URL and metadata
• file: File attachments with URL, name, size
• translation: Stored translated text for a specific audience
• metadata: Source channel details such as widget, email, or API

Additional AI and internal parts can also appear in the same parts array, but conceptually the important rule is that parts enrich the message instead of replacing it.

Event Items

Event items are system-generated records that explain what changed around the conversation.

Common examples include:

• assigned: Agent assigned to conversation
• unassigned: Agent removed from conversation
• participant_requested: Another participant was requested
• participant_joined: Agent joined the conversation
• participant_left: Agent left the conversation
• status_changed: Conversation status updated
• 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
• visitor_identified: A visitor was linked to contact information
• ai_paused / ai_resumed: AI handling state changed

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

Identification Items

Identification items capture moments where the visitor becomes known or their identity changes in a meaningful way. They help preserve an auditable record of contact identification and related lifecycle changes inside the same conversation timeline.

Tool Items

Tool items represent AI and tool activity that is written into the timeline. Depending on visibility and tool policy, they can power customer-facing progress, internal logs, or decision traces without needing a separate storage model.

Translation Parts

Translations are stored as translation parts on the same timeline item instead of replacing the original text. That lets Cossistant keep the source message forever while resolving the best display text for each audience.

• team translations are used for dashboard-facing display
• visitor translations are used for widget or other visitor-facing display
• The dashboard can show translated text and still offer Show original
• The widget can prefer a visitor-facing translation when one exists

Translation Part Shape

Example

Copy{
  "type": "message",
  "text": "Hola, necesito ayuda con mi factura",
  "parts": [
    {
      "type": "translation",
      "text": "Hello, I need help with my invoice",
      "sourceLanguage": "es",
      "targetLanguage": "en",
      "audience": "team",
      "mode": "auto",
      "modelId": "google/gemini-2.5-flash-lite"
    }
  ]
}

Timeline Item Properties

All timeline items share common fields:

• id: Unique identifier
• conversationId: Parent conversation
• organizationId: Owning organization
• type: Item type (message, event, identification, tool)
• text: Canonical/original message text when applicable
• parts: Array of structured content parts
• visibility: public or private (internal agent notes)
• createdAt: Timestamp

Actor fields (who created the item):

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

deletedAt exists as an internal lifecycle field, but it is usually not part of the day-to-day conceptual model when reasoning about timelines.

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