centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-26 13:18:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update import-export.md

Browse Source
This commit is contained in:
DrMelone
2026-03-05 20:04:31 +01:00
parent f9178b0b52
commit 0037f77caf
1 changed files with 171 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
docs/features/chat-conversations/data-controls/import-export.md
View File

@@ -29,14 +29,174 @@ It's a good practice to periodically export your chats, especially before major
Click the **Import Chats** button and select a JSON file to restore conversations. Open WebUI supports importing from:
- **Open WebUI exports**: Native JSON format from previous exports
- **ChatGPT exports**: Conversations exported from OpenAI's ChatGPT
- **Other compatible formats**: JSON files following the expected structure
- **ChatGPT exports**: Conversations exported from OpenAI's ChatGPT (auto-detected and converted)
- **Custom JSON files**: Any JSON file that follows the expected structure documented below
### Import Behavior
- Imported chats are added to your existing conversations (they don't replace them)
- Duplicate detection may vary based on chat IDs
- If using ChatGPT exports, the format is automatically converted
- Each imported chat receives a new unique ID, so re-importing the same file will create duplicates
- If using ChatGPT exports, the format is automatically detected and converted
## Chat Import JSON Schema
The import file must be a **JSON array** of chat objects. There are two accepted formats: the **standard format** (used by Open WebUI exports) and a **legacy format**.
### Standard Format (Recommended)
Each object in the array should have a `chat` key containing the conversation data:
```json
[
{
"chat": {
"title": "My Conversation",
"models": ["llama3.2"],
"history": {
"currentId": "message-id-2",
"messages": {
"message-id-1": {
"id": "message-id-1",
"parentId": null,
"childrenIds": ["message-id-2"],
"role": "user",
"content": "Hello, how are you?",
"timestamp": 1700000000
},
"message-id-2": {
"id": "message-id-2",
"parentId": "message-id-1",
"childrenIds": [],
"role": "assistant",
"content": "I'm doing well, thank you!",
"model": "llama3.2",
"done": true,
"timestamp": 1700000005
}
}
}
},
"meta": {
"tags": ["greeting"]
},
"pinned": false,
"folder_id": null,
"created_at": 1700000000,
"updated_at": 1700000005
}
]
```
### Legacy Format
If the objects in the array do **not** have a `chat` key, the entire object is treated as the chat data itself (i.e. the object is wrapped in `{ "chat": <object> }` automatically):
```json
[
{
"title": "My Conversation",
"models": ["llama3.2"],
"history": {
"currentId": "message-id-2",
"messages": {
"message-id-1": {
"id": "message-id-1",
"parentId": null,
"childrenIds": ["message-id-2"],
"role": "user",
"content": "Hello!"
},
"message-id-2": {
"id": "message-id-2",
"parentId": "message-id-1",
"childrenIds": [],
"role": "assistant",
"content": "Hi there!",
"model": "llama3.2",
"done": true
}
}
}
}
]
```
### Field Reference
#### Top-Level Chat Object (Standard Format)
| Field | Type | Required | Description |
|---|---|---|---|
| `chat` | object | ✅ | The conversation data (see Chat Data below) |
| `meta` | object | ❌ | Metadata such as `tags` (array of strings). Defaults to `{}` |
| `pinned` | boolean | ❌ | Whether the chat is pinned. Defaults to `false` |
| `folder_id` | string \| null | ❌ | ID of the folder to place the chat in. Defaults to `null` |
| `created_at` | integer \| null | ❌ | Unix timestamp (seconds) for when the chat was created |
| `updated_at` | integer \| null | ❌ | Unix timestamp (seconds) for when the chat was last updated |
#### Chat Data Object
| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | ❌ | The conversation title. Defaults to `"New Chat"` |
| `models` | string[] | ❌ | List of model identifiers used in the conversation |
| `history` | object | ✅ | Contains the message tree (see History below) |
| `options` | object | ❌ | Chat-level options/parameters |
#### History Object
| Field | Type | Required | Description |
|---|---|---|---|
| `currentId` | string | ✅ | ID of the last message in the active conversation branch |
| `messages` | object | ✅ | A map of message ID → message object (see Message below) |
#### Message Object
| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | ✅ | Unique identifier for the message |
| `parentId` | string \| null | ✅ | ID of the parent message, or `null` for the first message |
| `childrenIds` | string[] | ✅ | Array of child message IDs. Empty array `[]` for the last message |
| `role` | string | ✅ | Either `"user"` or `"assistant"` |
| `content` | string | ✅ | The message text (supports Markdown) |
| `model` | string | ❌ | Model identifier (relevant for assistant messages) |
| `done` | boolean | ❌ | Whether the response is complete |
| `timestamp` | integer | ❌ | Unix timestamp (seconds) for the message |
| `context` | string \| null | ❌ | Additional context for the message |
:::info Message Tree Structure
Messages use a **tree structure** rather than a flat list. Each message references its parent via `parentId` and its children via `childrenIds`. This allows Open WebUI to support branching conversations (e.g. editing a message and getting a different response). The `history.currentId` field points to the last message in the currently active branch.
:::
### ChatGPT Export Format
ChatGPT exports are automatically detected when the first object in the array contains a `mapping` key. You don't need to manually convert ChatGPT exports—just import the file directly and Open WebUI will handle the conversion.
### Minimal Working Example
The smallest valid import file looks like this:
```json
[
{
"title": "Quick Chat",
"history": {
"currentId": "msg-1",
"messages": {
"msg-1": {
"id": "msg-1",
"parentId": null,
"childrenIds": [],
"role": "user",
"content": "Hello!"
}
}
}
}
]
```
This uses the legacy format (no `chat` wrapper) with a single user message.
## FAQ
@@ -44,7 +204,13 @@ Click the **Import Chats** button and select a JSON file to restore conversation
**A:** No. Imported chats are added alongside your existing conversations.
**Q: Can I import chats from Claude, Gemini, or other platforms?**
**A:** Currently, native import support is available for Open WebUI and ChatGPT formats. Other platforms may require manual conversion to the expected JSON structure.
**A:** There is no built-in converter for these platforms. You would need to transform your export into the JSON structure documented above. The key requirement is building the message tree with correct `parentId` / `childrenIds` relationships.
**Q: Is there a size limit for imports?**
**A:** There's no hard-coded limit, but very large files may take longer to process. The practical limit depends on your server configuration and available memory.
**Q: What happens if I import the same file twice?**
**A:** Each import creates new chats with fresh IDs, so you will end up with duplicate conversations.
**Q: What message roles are supported?**
**A:** The import supports `"user"` and `"assistant"` roles. System messages are typically set via model configurations rather than stored in the chat history.