From 8e7cf943060a06f8efc6b9ebd0158c0cda2e4fd0 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Wed, 4 Feb 2026 19:13:38 +0100 Subject: [PATCH 1/5] Update index.mdx --- docs/features/plugin/tools/index.mdx | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 0e08e4390..7ad37607f 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -180,11 +180,11 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | | `fetch_url` | Visits a URL and extracts text content via the Web Loader. | | **Knowledge Base** | *Requires per-model "Knowledge Base" category enabled (default: on).* | -| `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. | -| `query_knowledge_bases` | Search knowledge bases by semantic similarity to query. Finds KBs whose name/description match the meaning of your query. Use this to discover relevant knowledge bases before querying their files. | -| `search_knowledge_bases` | Search knowledge bases by name and description. | -| `query_knowledge_files` | Search knowledge base files using simple vector search. **Note:** Does not use hybrid search or reranking—for full RAG pipeline with reranking, use File Context instead by attaching files via `#` or assigning knowledge bases. | -| `search_knowledge_files` | Search files across accessible knowledge bases by filename. | +| `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. **Use this first** to discover what knowledge is available. | +| `query_knowledge_bases` | Search KB *names and descriptions* by semantic similarity. Use to find which KB is relevant when you don't know which one to query. | +| `search_knowledge_bases` | Search knowledge bases by name/description (text match). | +| `query_knowledge_files` | Search *file contents* inside KBs using vector search. **This is your main tool for finding information.** When a KB is attached to the model, searches are automatically scoped to that KB. | +| `search_knowledge_files` | Search files across accessible knowledge bases by filename (not content). | | `view_knowledge_file` | Get the full content of a file from a knowledge base. | | **Image Gen** | *Requires image generation enabled (per-tool).* | | `generate_image` | Generates a new image based on a prompt. Requires `ENABLE_IMAGE_GENERATION`. | @@ -252,6 +252,15 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo Open WebUI automatically detects and stores your timezone when you log in. This allows time-related tools and features to provide accurate local times without any manual configuration. Your timezone is determined from your browser settings. ::: +:::info Recommended KB Tool Workflow +**When an attached KB is returning empty results:** +1. First call `list_knowledge_bases` to confirm the model can see the attached KB +2. Then use `query_knowledge_files` (without specifying `knowledge_ids` — it auto-scopes to attached KBs) +3. If still empty, the files may not be embedded yet, or you may have **Full Context mode enabled** which bypasses the vector store + +**Do NOT use Full Context mode with knowledge tools** — Full Context injects file content directly and doesn't store embeddings, so `query_knowledge_files` will return empty. Use Focused Retrieval (default) for tool-based access. +::: + :::tip Knowledge Base Tools vs RAG Pipeline The native `query_knowledge_files` tool uses **simple vector search** with a default of 5 results. It does **not** use: - Hybrid search (BM25 + vector) From 7f1279916f4ff0846d70f3d20143744c69a93616 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 5 Feb 2026 21:44:00 +0100 Subject: [PATCH 2/5] NEW FEAT message queue and analytics --- docs/features/analytics/index.mdx | 71 ++++++++++- docs/features/chat-features/message-queue.mdx | 111 ++++++++++++++++++ docs/features/index.mdx | 2 + 3 files changed, 181 insertions(+), 3 deletions(-) create mode 100644 docs/features/chat-features/message-queue.mdx diff --git a/docs/features/analytics/index.mdx b/docs/features/analytics/index.mdx index b9fbe81e6..3a23fad9f 100644 --- a/docs/features/analytics/index.mdx +++ b/docs/features/analytics/index.mdx @@ -44,7 +44,22 @@ At the top right of the Analytics dashboard, you can filter all data by time per - **Last 90 days** - Quarterly trends - **All time** - Complete historical data -All metrics on the page update automatically when you change the time period. +Your selected time period is **automatically saved** and persists across browser sessions. + +### Group Filtering + +If you have [user groups](/features/rbac/groups) configured, the Analytics dashboard allows filtering by group: + +- Use the **group dropdown** next to the time period selector +- Select a specific group to view analytics **only for users in that group** +- Choose "All Users" to see instance-wide analytics + +This is useful for: +- **Department-level reporting** - Track usage for specific teams +- **Cost allocation** - Attribute token consumption to business units +- **Pilot programs** - Monitor adoption within test groups + +All metrics on the page update automatically when you change the time period or group filter. ### Summary Statistics @@ -90,6 +105,7 @@ A detailed breakdown of how each model is being used: - **Sortable columns** - Click column headers to sort by name or message count - **Model icons** - Visual identification with profile images - **Token tracking** - See which models consume the most resources +- **Clickable rows** - Click any model to open the [Model Details Modal](#model-details-modal) **Use cases:** - Identify your most popular models @@ -97,6 +113,42 @@ A detailed breakdown of how each model is being used: - Decide which models to keep or remove - Plan infrastructure upgrades based on usage +### Model Details Modal + +Clicking on any model row opens a detailed modal with two tabs: + +#### Overview Tab + +The Overview tab provides: + +- **Feedback Activity Chart** - Visual history of user feedback (thumbs up/down) over time + - Toggle between **30 days**, **1 year**, or **All time** views + - Weekly aggregation for longer time ranges +- **Tags** - Most common chat tags associated with this model (top 10) + +This helps you understand: +- How users perceive model quality over time +- Which topics/use cases the model is handling +- Trends in user satisfaction + +#### Chats Tab + +:::info Admin Chat Access Required +The Chats tab is only visible when **Admin Chat Access** is enabled in your instance settings. +::: + +The Chats tab shows conversations that used this model: + +- **User info** - Who started each chat +- **Preview** - First message of each conversation +- **Timestamp** - When the chat was last updated +- **Click to open** - Navigate directly to the shared chat view + +This is useful for: +- Understanding how users interact with specific models +- Auditing model usage for quality assurance +- Finding example conversations for training or documentation + ### User Activity Table Track user engagement and token consumption per user: @@ -248,6 +300,7 @@ The following indexes optimize analytics queries: For advanced users and integrations, Analytics provides REST API endpoints: +**Dashboard Endpoints:** ``` GET /api/v1/analytics/summary GET /api/v1/analytics/models @@ -257,13 +310,25 @@ GET /api/v1/analytics/daily GET /api/v1/analytics/tokens ``` -All endpoints support `start_date` and `end_date` parameters (Unix timestamps) for time-range filtering. +**Model Detail Endpoints:** +``` +GET /api/v1/analytics/models/{model_id}/chats # Get chats using this model +GET /api/v1/analytics/models/{model_id}/overview # Get feedback history and tags +``` + +**Common Query Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `start_date` | int | Unix timestamp (epoch seconds) - start of range | +| `end_date` | int | Unix timestamp (epoch seconds) - end of range | +| `group_id` | string | Filter to a specific user group (optional) | :::tip API Access All Analytics endpoints require admin authentication. Include your admin bearer token: ```bash curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \ - https://your-instance.com/api/v1/analytics/summary + "https://your-instance.com/api/v1/analytics/summary?group_id=abc123" ``` ::: diff --git a/docs/features/chat-features/message-queue.mdx b/docs/features/chat-features/message-queue.mdx new file mode 100644 index 000000000..93e9e356c --- /dev/null +++ b/docs/features/chat-features/message-queue.mdx @@ -0,0 +1,111 @@ +--- +sidebar_position: 10 +title: "Message Queue" +--- + +# Message Queue + +The **Message Queue** feature allows you to continue composing and sending messages while the AI is still generating a response. Instead of blocking your input until the current response completes, your messages are queued and automatically sent in sequence. + +--- + +## How It Works + +When you send a message while the AI is generating a response: + +1. **Your message is queued** - It appears in a compact queue area just above the input box +2. **You can continue working** - Add more messages, edit queued messages, or delete them +3. **Automatic processing** - Once the current response finishes, all queued messages are combined and sent together + +This creates a seamless workflow where you can capture thoughts as they come without waiting for the AI to finish. + +--- + +## Queue Management + +Each queued message shows three action buttons: + +| Action | Icon | Description | +|--------|------|-------------| +| **Send Now** | ↑ | Interrupts the current generation and sends this message immediately | +| **Edit** | ✏️ | Removes the message from the queue and puts it back in the input field | +| **Delete** | 🗑️ | Removes the message from the queue without sending | + +### Combining Messages + +When the AI finishes generating, all queued messages are **combined into a single prompt** (separated by blank lines) and sent together. This means: + +- Multiple quick thoughts become one coherent message +- Context flows naturally between your queued inputs +- The AI receives everything at once for better understanding + +--- + +## Persistence + +The message queue is preserved when you navigate between chats within the same browser session: + +- **Leaving a chat** - Queue is saved to session storage +- **Returning to the chat** - Queue is restored and processed +- **Closing the browser** - Queue is cleared (session storage only) + +This means you can start a thought, switch to another chat to check something, and return to find your queued messages waiting. + +--- + +## Settings + +You can disable the Message Queue feature if you prefer the traditional behavior: + +1. Go to **Settings** → **Interface** +2. Find **Enable Message Queue** under the Chat section +3. Toggle it off + +When disabled, sending a message while the AI is generating will: +- **Interrupt** the current generation +- **Send** your new message immediately + +:::tip Default Behavior +Message Queue is **enabled by default**. The toggle allows you to choose between: +- **Queue mode** (default) - Messages queue up until generation completes +- **Interrupt mode** - New messages stop current generation immediately +::: + +--- + +## Use Cases + +### 1. Stream of Consciousness + +You're reading an AI response and have follow-up questions. Instead of waiting: +- Queue your first follow-up +- Queue a clarification +- Queue another thought + +All are sent together when the AI finishes. + +### 2. Adding Context + +The AI is working on a complex response, but you remember additional context: +- Queue the extra information +- The AI receives it as part of the next message + +### 3. Multitasking + +You're in a long conversation and need to capture quick notes: +- Queue messages as reminders +- Edit or delete before they're sent +- Use "Send Now" for urgent interruptions + +--- + +## Summary + +| Feature | Behavior | +|---------|----------| +| **Enabled** | Messages queue during generation, sent together when complete | +| **Disabled** | New messages interrupt current generation immediately | +| **Persistence** | Queue survives navigation within session | +| **Actions** | Send Now, Edit, Delete for each queued item | + +The Message Queue helps you maintain your flow of thought without the friction of waiting for AI responses to complete. diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 9fbc8a058..b7f44d149 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -168,6 +168,8 @@ import { TopBanners } from "@site/src/components/TopBanners"; - 🔔 **Chat Completion Notifications**: Stay updated with instant in-UI notifications when a chat finishes in a non-active tab, ensuring you never miss a completed response. +- 📝 **Message Queue**: Continue composing messages while the AI is generating a response. Your messages are queued and automatically sent together when the current response completes. Edit, delete, or send queued messages immediately. [Learn about Message Queue](/features/chat-features/message-queue). + - 🌐 **Notification Webhook Integration**: Receive timely updates for long-running chats or external integration needs with configurable webhook notifications, even when your tab is closed. [Learn more about Webhooks](/features/interface/webhooks). - 📚 **Channels (Beta)**: Explore real-time collaboration between users and AIs with Discord/Slack-style chat rooms, build bots for channels, and unlock asynchronous communication for proactive multi-agent workflows. [See Channels](/features/channels). From b2897f492b6a0e9e9b0ad21b0b3facd3816e48a6 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Fri, 6 Feb 2026 00:02:19 +0100 Subject: [PATCH 3/5] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index a3dacb7c3..0ea27e680 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1358,6 +1358,41 @@ If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Role` - `X-OpenWebUI-Chat-Id` +#### `FORWARD_USER_INFO_HEADER_NAME` + +- Type: `str` +- Default: `X-OpenWebUI-User-Name` +- Description: Customizes the header name used to forward the user's display name. Change this if your infrastructure requires a specific header prefix. + +#### `FORWARD_USER_INFO_HEADER_ID` + +- Type: `str` +- Default: `X-OpenWebUI-User-Id` +- Description: Customizes the header name used to forward the user's ID. + +#### `FORWARD_USER_INFO_HEADER_EMAIL` + +- Type: `str` +- Default: `X-OpenWebUI-User-Email` +- Description: Customizes the header name used to forward the user's email address. + +#### `FORWARD_USER_INFO_HEADER_ROLE` + +- Type: `str` +- Default: `X-OpenWebUI-User-Role` +- Description: Customizes the header name used to forward the user's role. + +:::tip Custom Header Prefix +Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`: + +```bash +FORWARD_USER_INFO_HEADER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name +FORWARD_USER_INFO_HEADER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id +FORWARD_USER_INFO_HEADER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email +FORWARD_USER_INFO_HEADER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role +``` +::: + #### `ENABLE_WEB_LOADER_SSL_VERIFICATION` - Type: `bool` From 1dbd80c0cdd0795a9f6cc76cd358b4b738642f23 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Fri, 6 Feb 2026 00:32:39 +0100 Subject: [PATCH 4/5] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 27 ++++++++++++++-------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 0ea27e680..8f0c47fb2 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1350,7 +1350,7 @@ If you have already deployed with `JWT_EXPIRES_IN=-1`, you can rotate or change - type: `bool` - Default: `False` -- Description: Forwards user information (name, ID, email, role and chat-id) as X-headers to OpenAI API and Ollama API. +- Description: Forwards user and session information as HTTP headers to OpenAI API, Ollama API, MCP servers, and Tool servers. If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Name` - `X-OpenWebUI-User-Id` @@ -1358,38 +1358,47 @@ If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Role` - `X-OpenWebUI-Chat-Id` -#### `FORWARD_USER_INFO_HEADER_NAME` +This enables per-user authorization, auditing, rate limiting, and request tracing on external services. + +#### `FORWARD_USER_INFO_HEADER_USER_NAME` - Type: `str` - Default: `X-OpenWebUI-User-Name` - Description: Customizes the header name used to forward the user's display name. Change this if your infrastructure requires a specific header prefix. -#### `FORWARD_USER_INFO_HEADER_ID` +#### `FORWARD_USER_INFO_HEADER_USER_ID` - Type: `str` - Default: `X-OpenWebUI-User-Id` - Description: Customizes the header name used to forward the user's ID. -#### `FORWARD_USER_INFO_HEADER_EMAIL` +#### `FORWARD_USER_INFO_HEADER_USER_EMAIL` - Type: `str` - Default: `X-OpenWebUI-User-Email` - Description: Customizes the header name used to forward the user's email address. -#### `FORWARD_USER_INFO_HEADER_ROLE` +#### `FORWARD_USER_INFO_HEADER_USER_ROLE` - Type: `str` - Default: `X-OpenWebUI-User-Role` - Description: Customizes the header name used to forward the user's role. +#### `FORWARD_SESSION_INFO_HEADER_CHAT_ID` + +- Type: `str` +- Default: `X-OpenWebUI-Chat-Id` +- Description: Customizes the header name used to forward the current chat/session ID. + :::tip Custom Header Prefix Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`: ```bash -FORWARD_USER_INFO_HEADER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name -FORWARD_USER_INFO_HEADER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id -FORWARD_USER_INFO_HEADER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email -FORWARD_USER_INFO_HEADER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role +FORWARD_USER_INFO_HEADER_USER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name +FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id +FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email +FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role +FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id ``` ::: From a9720eb2e8c71ca50cd4f7b97345a64c246a76cb Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Fri, 6 Feb 2026 12:24:13 +0100 Subject: [PATCH 5/5] TOOLS --- docs/features/plugin/development/events.mdx | 136 +++++++++++++++++++- 1 file changed, 129 insertions(+), 7 deletions(-) diff --git a/docs/features/plugin/development/events.mdx b/docs/features/plugin/development/events.mdx index 53ccdf6fc..31b141e9a 100644 --- a/docs/features/plugin/development/events.mdx +++ b/docs/features/plugin/development/events.mdx @@ -24,15 +24,26 @@ Think of Events like push notifications and modal dialogs that your plugin can t ## 🏁 Availability -:::important -Events are **only available for native Python Tools and Functions** defined directly in Open WebUI. +### Native Python Tools & Functions -Events are **NOT supported** for: -- **OpenAPI tool servers** (external REST APIs) -- **MCP tool servers** (Model Context Protocol) +Events are **fully available** for native Python Tools and Functions defined directly in Open WebUI using the `__event_emitter__` and `__event_call__` helpers. -These external tools communicate via HTTP request/response and cannot emit real-time UI events. -::: +### External Tools (OpenAPI & MCP) + +External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests: + +| Header | Description | +|--------|-------------| +| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | +| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | + +Your external tool can use these headers to emit events back to the UI via: + +``` +POST /api/v1/chats/{chat_id}/messages/{message_id}/event +``` + +See [External Tool Events](#-external-tool-events) below for details. --- @@ -452,6 +463,117 @@ Yes—emit `"chat:message:delta"` events in a loop, then finish with `"chat:mess --- +## 🌐 External Tool Events + +External tools (OpenAPI and MCP servers) can emit events to the Open WebUI UI via a REST endpoint. This enables features like status updates, notifications, and streaming content from tools running on external servers. + +### Headers Provided by Open WebUI + +When Open WebUI calls your external tool, it includes these headers: + +| Header | Description | +|--------|-------------| +| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | +| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | + +### Event Endpoint + +**Endpoint:** `POST /api/v1/chats/{chat_id}/messages/{message_id}/event` + +**Authentication:** Requires a valid Open WebUI API key or session token. + +**Request Body:** + +```json +{ + "type": "status", + "data": { + "description": "Processing your request...", + "done": false + } +} +``` + +### Supported Event Types + +External tools can emit the same event types as native tools: +- `status` – Show progress/status updates +- `notification` – Display toast notifications +- `chat:message:delta` / `message` – Append content to the message +- `chat:message` / `replace` – Replace message content +- `files` / `chat:message:files` – Attach files +- `source` / `citation` – Add citations + +:::note +Interactive events (`input`, `confirmation`, `execute`) require `__event_call__` and are **not supported** for external tools as they need bidirectional WebSocket communication. +::: + +### Example: Python External Tool + +```python +import httpx + +def my_tool_handler(request): + # Extract headers from incoming request + chat_id = request.headers.get("X-Open-WebUI-Chat-Id") + message_id = request.headers.get("X-Open-WebUI-Message-Id") + api_key = "your-open-webui-api-key" + + # Emit a status event + httpx.post( + f"http://your-open-webui-host/api/v1/chats/{chat_id}/messages/{message_id}/event", + headers={"Authorization": f"Bearer {api_key}"}, + json={ + "type": "status", + "data": {"description": "Working on it...", "done": False} + } + ) + + # ... do work ... + + # Emit completion status + httpx.post( + f"http://your-open-webui-host/api/v1/chats/{chat_id}/messages/{message_id}/event", + headers={"Authorization": f"Bearer {api_key}"}, + json={ + "type": "status", + "data": {"description": "Complete!", "done": True} + } + ) + + return {"result": "success"} +``` + +### Example: JavaScript/Node.js External Tool + +```javascript +async function myToolHandler(req) { + const chatId = req.headers['x-open-webui-chat-id']; + const messageId = req.headers['x-open-webui-message-id']; + const apiKey = 'your-open-webui-api-key'; + + // Emit a notification + await fetch( + `http://your-open-webui-host/api/v1/chats/${chatId}/messages/${messageId}/event`, + { + method: 'POST', + headers: { + 'Authorization': `Bearer ${apiKey}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + type: 'notification', + data: { type: 'info', content: 'Tool is processing...' } + }) + } + ); + + return { result: 'success' }; +} +``` + +--- + ## 📝 Conclusion **Events** give you real-time, interactive superpowers inside Open WebUI. They let your code update content, trigger notifications, request user input, stream results, handle code, and much more—seamlessly plugging your backend intelligence into the chat UI.