Conversation History

Zubo records every message exchanged across all channels — Telegram, Discord, Slack, WhatsApp, Signal, Email, and Web Chat — into a unified conversation history backed by SQLite. Every conversation is tagged with its source channel, user identifier, and timestamp, making it possible to search, browse, and analyze your entire interaction history from a single place.

Copy-Paste Task Cards

Secure API Access

Enable API auth and create a key before exposing ports beyond localhost.

zubo config set auth.enabled true
zubo auth create-key my-app

Set Local Model Fallback

Keep responses available during provider outages or API quota issues.

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

401 Unauthorized / Missing Bearer token

If auth.enabled is true, all /api/* calls require Authorization: Bearer <key>. Create a new key if needed.

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status

Provider Timeout / Upstream unavailable

Use failover and switch temporarily to a responsive provider or smaller model. Check logs for repeated timeout patterns.

zubo model openai/gpt-4o-mini
zubo logs --follow

Missing local model (Ollama/LM Studio)

If local providers fail, ensure the runtime is running and a model is installed.

ollama serve
ollama pull llama3.3

Cross-Channel History

Unlike siloed chat logs, Zubo's conversation history is channel-agnostic. A conversation that starts on Telegram and continues on Discord is linked by user identity and stored in the same database. This means:

Unified timeline — every message from every channel appears in a single chronological view. You can see the full picture of your interactions regardless of where they happened.
Channel metadata — each message is tagged with its source channel (telegram, discord, slack, whatsapp, signal, email, webchat) so you can filter by channel when needed.
User identity — messages are associated with user identifiers (Telegram user ID, Discord user ID, email address, etc.), enabling per-user history views.
Conversation grouping — messages are grouped into conversations by session. Each conversation has a unique ID, a title (auto-generated or user-set), and metadata including message count and time range.

Conversation data is stored in the zubo.db SQLite database in WAL mode, allowing concurrent reads from the dashboard while the agent writes new messages.

Full-Text Search

Zubo indexes all conversation messages using SQLite FTS5, the same full-text search engine used for memory retrieval. This gives you instant keyword search across your entire conversation history with BM25 relevance ranking.

BM25 ranking — results are ranked by relevance using the BM25 algorithm, which considers term frequency, document length, and corpus statistics. The most relevant messages appear first.
Prefix matching — search for deploy* to match "deploy", "deployed", "deploying", "deployment".
Phrase search — wrap terms in double quotes for exact phrase matching: "error handling".
Boolean operators — combine terms with AND, OR, and NOT for precise filtering.
Channel filtering — combine FTS search with channel filters to search only within a specific channel.

Search Examples

# Simple keyword search
GET /api/conversations/search?q=deployment

# Phrase search
GET /api/conversations/search?q="kubernetes cluster"

# Channel-scoped search
GET /api/conversations/search?q=budget&channel=telegram

# Date-range search
GET /api/conversations/search?q=error&from=2026-02-01&to=2026-02-14

Dashboard History Panel

The web dashboard includes a dedicated History panel for browsing and searching conversations visually. Access it by clicking History in the dashboard sidebar.

Conversation list — all conversations are listed in reverse chronological order, showing the title, channel, message count, and last activity time. Click any conversation to expand it and view the full message thread.
Search bar — type keywords into the search bar at the top to perform a full-text search across all conversations. Results update in real time as you type, with matching terms highlighted in context.
Channel filter — use the channel dropdown to filter conversations by source channel. Select "All Channels" to see everything, or a specific channel to narrow down.
Statistics view — the History panel shows aggregate statistics at the top: total conversations, total messages, messages per channel, and a timeline chart of conversation activity over the last 30 days.
Export — export any conversation as Markdown or JSON using the export button on each conversation card.

API Endpoints

All conversation endpoints are under /api/conversations and require authentication when auth.enabled is true.

List Conversations

GET /api/conversations?limit=20&offset=0&channel=telegram

Returns a paginated list of conversations, ordered by most recent activity.

Query parameters:

Parameter	Default	Description
`limit`	20	Number of conversations to return. Maximum 100.
`offset`	0	Number of conversations to skip for pagination.
`channel`	—	Filter by source channel (e.g., `telegram`, `discord`, `webchat`).

Response:

{
  "conversations": [
    {
      "id": "conv_abc123",
      "title": "Deployment discussion",
      "channel": "telegram",
      "messageCount": 24,
      "firstMessageAt": "2026-02-10T09:15:00Z",
      "lastMessageAt": "2026-02-10T11:30:00Z"
    }
  ],
  "total": 156,
  "limit": 20,
  "offset": 0
}

Search Conversations

GET /api/conversations/search?q=kubernetes&channel=slack&limit=20

Search across all conversation messages using FTS5. Returns conversations containing matching messages, ranked by relevance.

Query parameters:

Parameter	Default	Description
`q`	—	Search query string. Supports FTS5 syntax: phrases (`"exact match"`), prefix (`deploy*`), boolean (`error AND production`).
`channel`	—	Filter results to a specific channel.
`from`	—	Start date filter (ISO 8601 format).
`to`	—	End date filter (ISO 8601 format).
`limit`	20	Maximum results to return.

Response:

{
  "results": [
    {
      "conversationId": "conv_abc123",
      "title": "Kubernetes setup",
      "channel": "slack",
      "matchCount": 3,
      "snippet": "...deployed the kubernetes cluster to production...",
      "lastMessageAt": "2026-02-12T14:20:00Z"
    }
  ],
  "total": 8,
  "query": "kubernetes"
}

Conversation Statistics

GET /api/conversations/stats

Returns aggregate statistics about conversation history.

Response:

{
  "totalConversations": 156,
  "totalMessages": 4280,
  "byChannel": {
    "webchat": 2100,
    "telegram": 1200,
    "discord": 680,
    "slack": 200,
    "email": 100
  },
  "last30Days": [
    { "date": "2026-02-14", "conversations": 5, "messages": 87 },
    { "date": "2026-02-13", "conversations": 3, "messages": 42 }
  ]
}

Get Conversation Messages

GET /api/conversations/:id/messages?limit=100

Returns the messages in a specific conversation, ordered chronologically.

Query parameters:

Parameter	Default	Description
`limit`	100	Maximum messages to return. Maximum 500.
`offset`	0	Number of messages to skip for pagination.

Response:

{
  "conversationId": "conv_abc123",
  "title": "Deployment discussion",
  "channel": "telegram",
  "messages": [
    {
      "role": "user",
      "content": "Can you check the deployment status?",
      "timestamp": "2026-02-10T09:15:00Z"
    },
    {
      "role": "assistant",
      "content": "The deployment to production completed successfully at 9:12 AM. All health checks are passing.",
      "timestamp": "2026-02-10T09:15:04Z"
    }
  ],
  "total": 24
}

Previous← Channel Setup NextWebhooks →