mirror of
https://github.com/open-webui/docs
synced 2025-06-16 11:28:36 +00:00
doc: events
This commit is contained in:
Timothy Jaeryang Baek
parent
0fcd28d3d1
commit
e8b2de229e
302
docs/features/plugin/events/index.mdx
Normal file
302
docs/features/plugin/events/index.mdx
Normal file
@ -0,0 +1,302 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "⛑️ Events"
|
||||
---
|
||||
|
||||
# ⛑️ Events: Using `__event_emitter__` and `__event_call__` in Open WebUI
|
||||
|
||||
Open WebUI's plugin architecture is not just about processing input and producing output—**it's about real-time, interactive communication with the UI and users**. To make your Tools, Functions, and Pipes more dynamic, Open WebUI provides a built-in event system via the `__event_emitter__` and `__event_call__` helpers.
|
||||
|
||||
This guide explains **what events are**, **how you can trigger them** from your code, and **the full catalog of event types** you can use (including much more than just `"input"`).
|
||||
|
||||
---
|
||||
|
||||
## 🌊 What Are Events?
|
||||
|
||||
**Events** are real-time notifications or interactive requests sent from your backend code (Tool, or Function) to the web UI. They allow you to update the chat, display notifications, request confirmation, run UI flows, and more.
|
||||
|
||||
- Events are sent using the `__event_emitter__` helper for one-way updates, or `__event_call__` when you need user input or a response (e.g., confirmation, input, etc.).
|
||||
|
||||
**Metaphor:**
|
||||
Think of Events like push notifications and modal dialogs that your plugin can trigger, making the chat experience richer and more interactive.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Basic Usage
|
||||
|
||||
### Sending an Event
|
||||
|
||||
You can trigger an event anywhere inside your Tool, or Function by calling:
|
||||
|
||||
```python
|
||||
await __event_emitter__(
|
||||
{
|
||||
"type": "status", # See the event types list below
|
||||
"data": {
|
||||
"description": "Processing started!",
|
||||
"done": False,
|
||||
"hidden": False,
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
You **do not** need to manually add fields like `chat_id` or `message_id`—these are handled automatically by Open WebUI.
|
||||
|
||||
### Interactive Events
|
||||
|
||||
When you need to pause execution until the user responds (e.g., confirm/cancel dialogs, code execution, or input), use `__event_call__`:
|
||||
|
||||
```python
|
||||
result = await __event_call__(
|
||||
{
|
||||
"type": "input", # Or "confirmation", "execute"
|
||||
"data": {
|
||||
"title": "Please enter your password",
|
||||
"message": "Password is required for this action",
|
||||
"placeholder": "Your password here",
|
||||
},
|
||||
}
|
||||
)
|
||||
# result will contain the user's input value
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📜 Event Payload Structure
|
||||
|
||||
When you emit or call an event, the basic structure is:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "event_type", // See full list below
|
||||
"data": { ... } // Event-specific payload
|
||||
}
|
||||
```
|
||||
|
||||
Most of the time, you only set `"type"` and `"data"`. Open WebUI fills in the routing automatically.
|
||||
|
||||
---
|
||||
|
||||
## 🗂 Full List of Event Types
|
||||
|
||||
Below is a comprehensive table of **all supported `type` values** for events, along with their intended effect and data structure. (This is based on up-to-date analysis of Open WebUI event handling logic.)
|
||||
|
||||
| type | When to use | Data payload structure (examples) |
|
||||
|-----------------------------|-----------------------------------------------|--------------------------------------------------------------------|
|
||||
| `status` | Show a status update/history for a message | `{description: ..., done: bool, hidden: bool}` |
|
||||
| `chat:completion` | Provide a chat completion result | (Custom, see Open WebUI internals) |
|
||||
| `chat:message:delta`,<br/>`message` | Append content to the current message | `{content: "text to append"}` |
|
||||
| `chat:message`,<br/>`replace` | Replace current message content completely | `{content: "replacement text"}` |
|
||||
| `chat:message:files`,<br/>`files` | Set or overwrite message files (for uploads, output) | `{files: [...]}` |
|
||||
| `chat:title` | Set (or update) the chat conversation title | Topic string OR `{title: ...}` |
|
||||
| `chat:tags` | Update the set of tags for a chat | Tag array or object |
|
||||
| `source`,<br/>`citation` | Add a source/citation, or code execution result | For code: See [below.](#code-execution-event) |
|
||||
| `notification` | Show a notification ("toast") in the UI | `{type: "info" or "success" or "error" or "warning", content: "..."}` |
|
||||
| `confirmation` <br/>(needs `__event_call__`) | Ask for confirmation (OK/Cancel dialog) | `{title: "...", message: "..."}` |
|
||||
| `input` <br/>(needs `__event_call__`) | Request simple user input ("input box" dialog) | `{title: "...", message: "...", placeholder: "...", value: ...}` |
|
||||
| `execute` <br/>(needs `__event_call__`) | Request user-side code execution and return result | `{code: "...javascript code..."}` |
|
||||
|
||||
**Other/Advanced types:**
|
||||
|
||||
- You can define your own types and handle them at the UI layer (or use upcoming event-extension mechanisms).
|
||||
|
||||
### ❗ Details on Specific Event Types
|
||||
|
||||
#### `status`
|
||||
|
||||
Show an updating status/history block for a message (e.g., progress).
|
||||
**Data Example:**
|
||||
```python
|
||||
{
|
||||
"description": "Step 1/3: Fetching data...",
|
||||
"done": False,
|
||||
"hidden": False
|
||||
}
|
||||
```
|
||||
|
||||
#### `chat:message:delta` or `message`
|
||||
|
||||
Append text to the message in progress (streaming output).
|
||||
|
||||
```python
|
||||
{
|
||||
"content": "Partial text"
|
||||
}
|
||||
```
|
||||
|
||||
#### `chat:message` or `replace`
|
||||
|
||||
Set or replace the entire message content.
|
||||
|
||||
```python
|
||||
{
|
||||
"content": "Final complete response."
|
||||
}
|
||||
```
|
||||
|
||||
#### `files` or `chat:message:files`
|
||||
|
||||
Set or update the array of files for a message (useful for file uploads or response with files):
|
||||
|
||||
```python
|
||||
{
|
||||
"files": [
|
||||
{ "name": "file.txt", "url": "https://..." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `chat:title`
|
||||
|
||||
Update the conversation title or trigger UI to refresh titles.
|
||||
|
||||
```python
|
||||
{
|
||||
"title": "New conversation subject"
|
||||
}
|
||||
```
|
||||
|
||||
#### `chat:tags`
|
||||
|
||||
Update tags on the current chat session.
|
||||
|
||||
```python
|
||||
{
|
||||
"tags": ["work", "openai", "todo"]
|
||||
}
|
||||
```
|
||||
|
||||
#### `source` or `citation` (and code execution)
|
||||
|
||||
Append a source reference, or—if `type: code_execution` inside `data`—track code execution state for the message.
|
||||
|
||||
```python
|
||||
{
|
||||
"type": "code_execution",
|
||||
"id": "unique-id-abc",
|
||||
"status": "running" | "done" | "error",
|
||||
"output": "...",
|
||||
...
|
||||
}
|
||||
```
|
||||
If not code, ordinary reference/citation data is added to message `.sources`.
|
||||
|
||||
#### `notification`
|
||||
|
||||
Show a UI "toast" for the user.
|
||||
|
||||
```python
|
||||
{
|
||||
"type": "success", # or "error", "info", "warning"
|
||||
"content": "Successfully completed action!"
|
||||
}
|
||||
```
|
||||
|
||||
#### `confirmation` (**requires** `await __event_call__`)
|
||||
|
||||
Presents an OK/Cancel/Yes/No confirmation dialog to the user, returns user response.
|
||||
|
||||
```python
|
||||
{
|
||||
"title": "Are you sure?",
|
||||
"message": "Do you want to continue?",
|
||||
}
|
||||
```
|
||||
|
||||
#### `input` (**requires** `await __event_call__`)
|
||||
|
||||
Prompts user for simple text input (modal input box).
|
||||
|
||||
```python
|
||||
{
|
||||
"title": "Enter your email",
|
||||
"message": "We'll send you a receipt.",
|
||||
"placeholder": "user@example.com"
|
||||
}
|
||||
```
|
||||
Returns `{value: ...}`.
|
||||
|
||||
#### `execute` (**requires** `await __event_call__`)
|
||||
|
||||
Evaluates code client-side (dangerous!). Used for specialized scenarios.
|
||||
|
||||
```python
|
||||
{
|
||||
"code": "return 2 + 2;"
|
||||
}
|
||||
```
|
||||
Returns the result of evaluation.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ When & Where to Use Events
|
||||
|
||||
- **From any Tool, or Function** in Open WebUI.
|
||||
- To **stream responses**, show progress, request user data, update the UI, or display supplementary info/files.
|
||||
- `await __event_emitter__` is for one-way messages (fire and forget).
|
||||
- `await __event_call__` is for when you need a response from the user (input, execute, confirmation).
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tips & Advanced Notes
|
||||
|
||||
- **Multiple types per message:** You can emit several events of different types for one message—for example, show `status` updates, then stream with `chat:message:delta`, then complete with a `chat:message`.
|
||||
- **Custom event types:** While the above list is the standard, you may use your own types and detect/handle them in custom UI code.
|
||||
- **Extensibility:** The event system is designed to evolve—always check the [Open WebUI documentation](https://github.com/open-webui/open-webui) for the most current list and advanced usage.
|
||||
|
||||
---
|
||||
|
||||
## 🧐 FAQ
|
||||
|
||||
### Q: How do I trigger a notification for the user?
|
||||
Use `notification` type:
|
||||
```python
|
||||
await __event_emitter__({
|
||||
"type": "notification",
|
||||
"data": {"type": "success", "content": "Task complete"}
|
||||
})
|
||||
```
|
||||
|
||||
### Q: How do I prompt the user for input and get their answer?
|
||||
Use:
|
||||
```python
|
||||
response = await __event_call__({
|
||||
"type": "input",
|
||||
"data": {
|
||||
"title": "What's your name?",
|
||||
"message": "Please enter your preferred name:",
|
||||
"placeholder": "Name"
|
||||
}
|
||||
})
|
||||
# response will be: {"value": "user's answer"}
|
||||
```
|
||||
|
||||
### Q: What event types are available for `__event_call__`?
|
||||
- `"input"`: Input box dialog
|
||||
- `"confirmation"`: Yes/No, OK/Cancel dialog
|
||||
- `"execute"`: Run provided code on client and return result
|
||||
|
||||
### Q: Can I update files attached to a message?
|
||||
Yes—use the `"files"` or `"chat:message:files"` event type with a `{files: [...]}` payload.
|
||||
|
||||
### Q: Can I update the conversation title or tags?
|
||||
Absolutely: use `"chat:title"` or `"chat:tags"` accordingly.
|
||||
|
||||
### Q: Can I stream responses (partial tokens) to the user?
|
||||
Yes—emit `"chat:message:delta"` events in a loop, then finish with `"chat:message"`.
|
||||
|
||||
---
|
||||
|
||||
## 📝 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.
|
||||
|
||||
- Use `__event_emitter__` for one-way status/content updates.
|
||||
- Use `__event_call__` for interactions that require user follow-up (input, confirmation, execution).
|
||||
|
||||
Refer to this document for common event types and structures, and explore Open WebUI source code or docs for breaking updates or custom events!
|
||||
|
||||
---
|
||||
|
||||
**Happy event-driven coding in Open WebUI! 🚀**
|
||||
@ -1,9 +1,9 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "🔄 Valves & UserValves"
|
||||
title: "🔄 Valves"
|
||||
---
|
||||
|
||||
## Valves & UserValves
|
||||
## Valves
|
||||
|
||||
Valves and UserValves are used to allow users to provide dynamic details such as an API key or a configuration option. These will create a fillable field or a bool switch in the GUI menu for the given function. They are always optional, but HIGHLY encouraged.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user