Chat History

Chat History lets you browse, search, and review all conversations between your bots and users. Every message sent and received is automatically stored, so you can look back at any conversation, check what the AI said, and trace how issues were resolved.

Why Use Chat History?

• Review past conversations — Look up what was discussed in any chat, at any time
• Debug AI responses — Trace the full message flow to understand why the AI gave a particular answer
• Filter and search — Quickly find conversations by bot name, chat type, or keyword
• Audit and compliance — Keep a persistent record of all interactions

Viewing Conversations

The Chat History page in the Web UI displays all conversations in a card-based layout. Each conversation card shows:

• Title — The conversation title (or "No Title" if unset)
• Bot name — Which bot handled the conversation
• Chat type — Whether it was a group or private chat
• Last updated — When the conversation was last active
• Message count — How many messages the conversation contains
• Preview — The first 3 non-system messages, giving you a quick glimpse of the conversation content

Click the view button (eye icon) on a conversation card to open the detail panel and see the full message history.

Detail Panel

The detail panel slides in from the right and displays:

• Conversation metadata — Bot name, chat type (group/private with icon), chat ID, and timestamps
• Full message list — All messages in chronological order, with each message showing:
  • Role — Whether the message is from the user, assistant, system, or a tool
  • Timestamp — When the message was sent
  • Content — The full message text, rendered with Markdown formatting for assistant messages

Messages are visually distinguished by role:

Role	Icon	Description
User	👤	Messages sent by the human user
Assistant	🤖	Messages generated by the AI
System	⚙️	System-level instructions or context
Tool	🔧	Output from tool calls made by the AI

Filtering Conversations

The filter toolbar at the top of the Chat History page lets you narrow down the list:

• Bot Name — Type a bot name to show only conversations handled by that bot
• Chat Type — Choose between "All", "Group", or "Private" to filter by chat type
• Keyword — Search across conversation titles and chat IDs

After setting your filters, click the Search button (or press Enter) to apply them. Click Reset to clear all filters and show every conversation.

Deleting Conversations

You can delete a conversation by clicking the delete button (trash icon) on its card. A confirmation dialog will ask you to confirm before the deletion proceeds.

警告

Deleting a conversation is permanent. It removes the conversation and all of its messages from the database.

Data Storage

Conversations and messages are stored in the shared SQLite database (ruri.db), alongside other Ruri data. This means:

• No separate database setup is needed — everything uses the same database
• Conversation data persists across Ruri restarts
• The database schema is managed centrally by Ruri's initialization process

Conversation Model

Each conversation record contains:

Field	Type	Description
id	UUID	Unique conversation identifier
bot_name	String	Name of the bot (configuration file name)
chat_type	Enum	group or private
chat_id	String	Group ID or chat partner ID
title	String	Optional conversation title
created_at	Datetime	When the conversation was created
updated_at	Datetime	When the conversation was last updated

Message Model

Each message within a conversation contains:

Field	Type	Description
id	UUID	Unique message identifier
conversation_id	UUID	Foreign key to the parent conversation
role	String	user, assistant, system, or tool
content	String	The message text
created_at	Datetime	When the message was created

Automatic Conversation Management

Ruri automatically manages conversations through the get_or_create_conversation mechanism:

• When a new chat session starts, Ruri looks for an existing conversation matching the bot name, chat type, and chat ID
• If one exists, it reuses that conversation
• If none exists, it creates a new one automatically

When a conversation is deleted, all associated messages are cascade-deleted from the database.

API Endpoints

Chat History exposes a REST API for programmatic access:

List Conversations

GET /api/conversations

Returns a list of conversations, with optional query parameters for filtering:

Parameter	Description
bot_name	Filter by bot name
chat_type	Filter by group or private
keyword	Search in title and chat ID (partial match)

Create a Conversation

POST /api/conversations

Creates a new conversation. Request body:

{
  "bot_name": "my-bot",
  "chat_type": "private",
  "chat_id": "user-123",
  "title": "Optional Title"
}

Get a Conversation

GET /api/conversations/:id

Returns a single conversation by its ID.

Delete a Conversation

DELETE /api/conversations/:id

Deletes a conversation and all of its messages. Returns 204 No Content on success.

Add a Message

POST /api/conversations/:id/messages

Adds a message to a conversation. The conversation's updated_at timestamp is automatically refreshed. Request body:

{
  "role": "user",
  "content": "Hello, how are you?"
}

Get Messages

GET /api/conversations/:id/messages

Returns all messages in a conversation, ordered by created_at ascending.

Web UI Performance

The Chat History page includes several optimizations for a smooth experience:

• LocalStorage caching — Message data is cached in the browser's LocalStorage with a 5-minute TTL. Revisiting a conversation within the TTL loads instantly from cache instead of fetching from the server.
• Batch loading — Preview messages are loaded in batches of 5 concurrent requests, so the conversation list populates quickly even with many conversations.
• Cache-first strategy — When loading preview messages, the UI checks the cache first and only makes a network request if the cache is expired or missing.
• Automatic cache pruning — Expired entries are automatically cleaned up when new data is saved, preventing stale data from accumulating.