mirror of
https://github.com/open-webui/docs.git
synced 2026-01-03 02:09:51 +07:00
421 lines
12 KiB
Plaintext
421 lines
12 KiB
Plaintext
---
|
|
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.](/docs/features/plugin/events/index.mdx#source-or-citation-and-code-execution) |
|
|
| `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 a status/progress update in the UI:
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "status",
|
|
"data": {
|
|
"description": "Step 1/3: Fetching data...",
|
|
"done": False,
|
|
"hidden": False,
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `chat:message:delta` or `message`
|
|
|
|
**Streaming output** (append text):
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "chat:message:delta", # or simply "message"
|
|
"data": {
|
|
"content": "Partial text, "
|
|
},
|
|
}
|
|
)
|
|
|
|
# Later, as you generate more:
|
|
await __event_emitter__(
|
|
{
|
|
"type": "chat:message:delta",
|
|
"data": {
|
|
"content": "next chunk of response."
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `chat:message` or `replace`
|
|
|
|
**Set (or replace) the entire message content:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "chat:message", # or "replace"
|
|
"data": {
|
|
"content": "Final, complete response."
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `files` or `chat:message:files`
|
|
|
|
**Attach or update files:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "files", # or "chat:message:files"
|
|
"data": {
|
|
"files": [
|
|
# Open WebUI File Objects
|
|
]
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `chat:title`
|
|
|
|
**Update the chat's title:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "chat:title",
|
|
"data": {
|
|
"title": "Market Analysis Bot Session"
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `chat:tags`
|
|
|
|
**Update the chat's tags:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "chat:tags",
|
|
"data": {
|
|
"tags": ["finance", "AI", "daily-report"]
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `source` or `citation` (and code execution)
|
|
|
|
**Add a reference/citation:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "source", # or "citation"
|
|
"data": {
|
|
# Open WebUI Source (Citation) Object
|
|
}
|
|
}
|
|
)
|
|
```
|
|
|
|
**For code execution (track execution state):**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "source",
|
|
"data": {
|
|
# Open WebUI Code Source (Citation) Object
|
|
}
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `notification`
|
|
|
|
**Show a toast notification:**
|
|
|
|
```python
|
|
await __event_emitter__(
|
|
{
|
|
"type": "notification",
|
|
"data": {
|
|
"type": "info", # "success", "warning", "error"
|
|
"content": "The operation completed successfully!"
|
|
}
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `confirmation` (**requires** `__event_call__`)
|
|
|
|
**Show a confirm dialog and get user response:**
|
|
|
|
```python
|
|
result = await __event_call__(
|
|
{
|
|
"type": "confirmation",
|
|
"data": {
|
|
"title": "Are you sure?",
|
|
"message": "Do you really want to proceed?"
|
|
}
|
|
}
|
|
)
|
|
|
|
if result: # or check result contents
|
|
await __event_emitter__({
|
|
"type": "notification",
|
|
"data": {"type": "success", "content": "User confirmed operation."}
|
|
})
|
|
else:
|
|
await __event_emitter__({
|
|
"type": "notification",
|
|
"data": {"type": "warning", "content": "User cancelled."}
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
### `input` (**requires** `__event_call__`)
|
|
|
|
**Prompt user for text input:**
|
|
|
|
```python
|
|
result = await __event_call__(
|
|
{
|
|
"type": "input",
|
|
"data": {
|
|
"title": "Enter your name",
|
|
"message": "We need your name to proceed.",
|
|
"placeholder": "Your full name"
|
|
}
|
|
}
|
|
)
|
|
|
|
user_input = result
|
|
await __event_emitter__(
|
|
{
|
|
"type": "notification",
|
|
"data": {"type": "info", "content": f"You entered: {user_input}"}
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### `execute` (**requires** `__event_call__`)
|
|
|
|
**Run code dynamically on the user's side:**
|
|
|
|
```python
|
|
result = await __event_call__(
|
|
{
|
|
"type": "execute",
|
|
"data": {
|
|
"code": "print(40 + 2);",
|
|
}
|
|
}
|
|
)
|
|
|
|
await __event_emitter__(
|
|
{
|
|
"type": "notification",
|
|
"data": {
|
|
"type": "info",
|
|
"content": f"Code executed, result: {result}"
|
|
}
|
|
}
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ 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! 🚀** |