### Install Project Dependencies

Source: https://github.com/kagangtuya-star/sealchat/blob/master/ui/README.md

Run this command to install all necessary packages for the project.

```sh
npm install
```

--------------------------------

### Register a New User with curl

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Use this endpoint to create a new user account. The first user gets admin privileges. Ensure the 'invitationCode' is provided if required by your setup.

```bash
# Register a new user
curl -s -X POST http://localhost:3212/api/v1/user-signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "secret123",
    "nickname": "Alice",
    "invitationCode": ""
  }'
```

```json
# Response
{
  "message": "注册成功",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Start SealChat with Docker Compose

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Pulls the latest SealChat Docker image and starts the service in detached mode using Docker Compose. Assumes `config.yaml` is present or copied from an example.

```bash
# Pull and start
docker pull ghcr.io/kagangtuya-star/sealchat:latest
cp config.docker.yaml.example config.yaml
docker compose up -d
```

--------------------------------

### Enter a Channel

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Joins a specified channel to start receiving messages and updates.

```APIDOC
## channel.enter (WebSocket API)

### Description
Joins a channel and starts receiving messages from it. Sets the connection's active channel context for typing indicators and presence.

### API Call
`channel.enter`

### Data Payload
- **channel_id** (string) - Required - The unique identifier of the channel to enter.

### Request Example
```javascript
ws.send(JSON.stringify({
  api: "channel.enter",
  echo: "req-1", // Unique identifier for the request
  data: { channel_id: "ch_abc123" }
}));
// Server broadcasts channel-presence-updated to all channel members
```
```

--------------------------------

### User Sign-up

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new user account. The first user gets administrator privileges. Supports optional captcha modes.

```APIDOC
## POST /api/v1/user-signup

### Description
Creates a new account. The first registered user automatically receives `sys-admin` privileges and a default world is created on their behalf. Supports optional captcha modes (local image captcha, Cloudflare Turnstile, or Cap).

### Method
POST

### Endpoint
/api/v1/user-signup

### Request Body
- **username** (string) - Required - The desired username.
- **password** (string) - Required - The user's password.
- **nickname** (string) - Required - The user's display name.
- **invitationCode** (string) - Optional - An invitation code if required.

### Request Example
```json
{
  "username": "alice",
  "password": "secret123",
  "nickname": "Alice",
  "invitationCode": ""
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **token** (string) - Authentication token for the newly created user.
```

--------------------------------

### Get Current Configuration

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Fetches the current server configuration. Sensitive fields are masked for non-administrator users.

```bash
# Get current config (sensitive fields masked for non-admins)
curl -s http://localhost:3212/api/v1/config \
  -H "Authorization: $ADMIN_TOKEN"
```

--------------------------------

### Docker Deployment for SealChat

Source: https://github.com/kagangtuya-star/sealchat/blob/master/README.md

Instructions for deploying SealChat using Docker. It includes pulling the latest image, creating a configuration file, and starting the service with Docker Compose. The first registered account becomes the administrator.

```bash
docker pull ghcr.io/kagangtuya-star/sealchat:latest

cp config.docker.yaml.example config.yaml

docker compose up -d

# Access http://localhost:3212/, the first registered account will become the administrator
```

--------------------------------

### S3 Storage Configuration Example

Source: https://github.com/kagangtuya-star/sealchat/blob/master/deploy_zh.md

Configure SealChat to use S3 for storing attachments and audio. Ensure S3 is enabled and specify bucket details, endpoint, and region. Consider using environment variables for sensitive keys.

```yaml
storage:
  mode: s3
  local:
    uploadDir: ./sealchat-data/upload
    audioDir: ./sealchat-data/static/audio
    tempDir: ./sealchat-data/temp
  s3:
    enabled: true
    attachmentsEnabled: true
    audioEnabled: true
    endpoint: https://s3.example.com
    region: ""
    bucket: your-bucket-name
    accessKey: ""       # 建议留空，改用环境变量
    secret: ""          # 建议留空，改用环境变量
    sessionToken: ""
    pathStyle: false
    publicBaseUrl: https://cdn.example.com
    useSSL: true
```

--------------------------------

### Get Public World Keywords

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves keywords for a specified world from a public endpoint. No authorization is required.

```bash
# Public endpoint (no auth required)
curl -s "http://localhost:3212/api/v1/public/worlds/world_abc/keywords"
```

--------------------------------

### Get Attachment and Thumbnail

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves an attachment by its ID or its thumbnail. The output is saved to a file.

```bash
curl -s "http://localhost:3212/api/v1/attachment/att_abc123" \
  -H "Authorization: $TOKEN" \
  --output image.png
```

```bash
# Get thumbnail
curl -s "http://localhost:3212/api/v1/attachment/att_abc123/thumb" \
  -H "Authorization: $TOKEN" \
  --output thumb.jpg
```

--------------------------------

### Get Login Info via OneBot v11 HTTP

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Fetch the bot's login information, including user ID and nickname, using the OneBot v11 HTTP API. Requires a bot token.

```bash
curl -s -X POST http://localhost:3212/onebot/http \
  -H "Authorization: Bearer <bot-token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_login_info", "params": {}}'
```

--------------------------------

### Build and Run SealChat from Source

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Builds the SealChat server from source code using Go. Includes steps for downloading dependencies, building the UI, compiling the backend, and running the server. Also provides commands for running backend tests.

```bash
go mod download
cd ui && npm install && npm run build
go build -o sealchat_server ./
./sealchat_server          # starts on :3212
go test ./...              # run backend tests
```

--------------------------------

### Build for Production

Source: https://github.com/kagangtuya-star/sealchat/blob/master/ui/README.md

Execute this command to type-check, compile, and minify the project for production deployment.

```sh
npm run build
```

--------------------------------

### Get Attachment

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves an attachment by its ID. Also provides an option to get a thumbnail version of the attachment.

```APIDOC
## GET /api/v1/attachment/:id

### Description
Retrieves a specific attachment using its unique ID. You can also request a thumbnail version of the attachment.

### Method
GET

### Endpoint
/api/v1/attachment/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the attachment.

### Request Example
```bash
curl -s "http://localhost:3212/api/v1/attachment/att_abc123" \
  -H "Authorization: $TOKEN" \
  --output image.png

# Get thumbnail
curl -s "http://localhost:3212/api/v1/attachment/att_abc123/thumb" \
  -H "Authorization: $TOKEN" \
  --output thumb.jpg
```
```

--------------------------------

### Execute Database Backup

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Initiates a database backup. Requires an administrator token for authorization. The response includes the backup filename and size.

```bash
curl -s -X POST http://localhost:3212/api/v1/admin/backup/execute \
  -H "Authorization: $ADMIN_TOKEN"
# Response: { "filename": "chat_backup_20251201.db", "size": 10485760 }
```

--------------------------------

### Run Development Server

Source: https://github.com/kagangtuya-star/sealchat/blob/master/ui/README.md

Use this command to compile and hot-reload the application for development.

```sh
npm run dev
```

--------------------------------

### Create a User via Admin API

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Create a new user account with a username, password, and nickname. Requires an admin token.

```bash
curl -s -X POST http://localhost:3212/api/v1/admin/user-create \
  -H "Authorization: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "pass123", "nickname": "Bob"}'
```

--------------------------------

### List Database Backups

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves a list of available database backups. Requires an administrator token for authorization.

```bash
curl -s "http://localhost:3212/api/v1/admin/backup/list" \
  -H "Authorization: $ADMIN_TOKEN"
```

--------------------------------

### Get Character Card via WebSocket

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves a character card for a specific user within a channel. Used for synchronizing game sheet data between SealChat and SealDice bots.

```javascript
ws.send(JSON.stringify({
  api: "character.get",
  echo: "char-1",
  data: { userId: "user_001", channelId: "ch_abc123" }
}));
```

--------------------------------

### Manage Configuration Versions via CLI

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Provides command-line interface for managing configuration versions, including listing, showing, rolling back, and exporting configurations. Also includes user secret management for resetting passwords and listing admin users.

```bash
# List saved config versions
./sealchat_server --config-list
```

```bash
# Show version 3 (secrets masked)
./sealchat_server --config-show 3
```

```bash
# Roll back to version 2
./sealchat_server --config-rollback 2
```

```bash
# Export to file
./sealchat_server --config-export 1 --output config.backup.yaml
```

```bash
# Reset a user's password to 123456
./sealchat_server --user-secret reset --username alice
```

```bash
# List admin users
./sealchat_server --user-secret list
```

--------------------------------

### Get Group List via OneBot v11 HTTP

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieve a list of groups the bot is a part of using the OneBot v11 HTTP API. Requires a bot token.

```bash
curl -s -X POST http://localhost:3212/onebot/http \
  -H "Authorization: Bearer <bot-token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_group_list", "params": {}}'
```

--------------------------------

### Create World

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new world. Requires authentication token and a JSON payload with world details like name, public status, and description.

```bash
curl -s -X POST http://localhost:3212/api/v1/worlds \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My RPG World",
    "isPublic": false,
    "description": "A dark fantasy setting"
  }'
# Response: { "world": { "id": "world_abc", "name": "My RPG World", ... } }
```

--------------------------------

### List All Users via Admin API

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieve a paginated list of all users in the system. Requires an admin token.

```bash
curl -s "http://localhost:3212/api/v1/admin/user-list?page=1&pageSize=20" \
  -H "Authorization: $ADMIN_TOKEN"
```

--------------------------------

### Batch Create Users from CSV via Admin API

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Upload a CSV file to batch create multiple user accounts. Requires an admin token and the `file` part of the request should contain the CSV data.

```bash
curl -s -X POST http://localhost:3212/api/v1/admin/user-batch-create \
  -H "Authorization: $ADMIN_TOKEN" \
  -F "file=@users.csv"
```

--------------------------------

### Database Backup

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Execute a database backup and retrieve a list of available backups.

```APIDOC
## POST /api/v1/admin/backup/execute

### Description
Executes a database backup.

### Method
POST

### Endpoint
/api/v1/admin/backup/execute

### Response
#### Success Response (200)
- **filename** (string) - The name of the generated backup file.
- **size** (integer) - The size of the backup file in bytes.

### Request Example
```bash
curl -s -X POST http://localhost:3212/api/v1/admin/backup/execute \
  -H "Authorization: $ADMIN_TOKEN"
```

### Response Example
```json
{ "filename": "chat_backup_20251201.db", "size": 10485760 }
```

## GET /api/v1/admin/backup/list

### Description
Retrieves a list of available database backups.

### Method
GET

### Endpoint
/api/v1/admin/backup/list

### Request Example
```bash
curl -s "http://localhost:3212/api/v1/admin/backup/list" \
  -H "Authorization: $ADMIN_TOKEN"
```
```

--------------------------------

### Bulk Import World Keywords

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Imports keywords in bulk from a CSV file into a specified world. Requires authorization and the file to be sent as form data.

```bash
# Bulk import keywords
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/keywords/import" \
  -H "Authorization: $TOKEN" \
  -F "file=@keywords.csv"
```

--------------------------------

### WebSocket Connection and Identify

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Establishes a WebSocket connection and authenticates the client using a token.

```APIDOC
## GET /ws/seal

### Description
All real-time operations happen over a single WebSocket endpoint. After connecting, the client must send an `Identify` opcode within 10 seconds or the connection is dropped. Bots use a 32-character token; regular users use a JWT bearer token. Empty token creates a guest session with read-only access.

### Method
GET

### Endpoint
/ws/seal

### WebSocket Opcodes

| Opcode | Name          | Direction        | Purpose                            |
|--------|---------------|------------------|------------------------------------|
| 0      | Event         | Server → Client  | Broadcast events (messages, etc.)  |
| 1      | Ping          | Client → Server  | Heartbeat with focus state         |
| 2      | Pong          | Server → Client  | Heartbeat acknowledgement          |
| 3      | Identify      | Client → Server  | Authentication with token          |
| 4      | Ready         | Server → Client  | Auth result (user info or error)   |
| 5      | LatencyProbe  | Client → Server  | Round-trip latency measurement     |
| 6      | LatencyResult | Server → Client  | Latency probe response             |

### Request Example (Identify Opcode)
```javascript
const ws = new WebSocket("ws://localhost:3212/ws/seal");

ws.onopen = () => {
  // Opcode 3 = Identify
  ws.send(JSON.stringify({
    op: 3,
    body: { token: "abc123..." } // User JWT or Bot Token
  }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // op 4 = Ready
  if (msg.op === 4 && !msg.body.errorMsg) {
    console.log("Connected as", msg.body.user.nick);
  }
  // op 0 = Event
  if (msg.op === 0) {
    console.log("Event:", msg.body.type, msg.body.message?.content);
  }
};

// Keep-alive (op 1 = Ping)
setInterval(() => ws.send(JSON.stringify({ op: 1, body: { focused: true } })), 30000);
```
```

--------------------------------

### Create a Channel

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new channel within a world.

```APIDOC
## Create a Channel (WebSocket) — `channel.create`

```javascript
ws.send(JSON.stringify({
  api: "channel.create",
  echo: "chan-1",
  data: {
    world_id: "world_abc",
    name: "tavern",
    parent_id: "",          // optional category channel
    perm_type: "public"     // "public" | "private"
  }
}));
```
```

--------------------------------

### Register a Bot Token via Admin API

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Create a new API token for a bot user. This action requires the `sys-admin` role and returns the generated token and bot user ID.

```bash
curl -s -X POST http://localhost:3212/api/v1/admin/bot-token-add \
  -H "Authorization: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dice Bot",
    "kind": "manual"
  }'
```

--------------------------------

### Config Management (REST)

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieve and update server configuration settings.

```APIDOC
## GET /api/v1/config

### Description
Retrieves the current server configuration. Sensitive fields are masked for non-admin users.

### Method
GET

### Endpoint
/api/v1/config

### Request Example
```bash
curl -s http://localhost:3212/api/v1/config \
  -H "Authorization: $ADMIN_TOKEN"
```

## PUT /api/v1/config

### Description
Updates the server configuration.

### Method
PUT

### Endpoint
/api/v1/config

### Request Body
- **registerOpen** (boolean) - Whether user registration is open.
- **pageTitle** (string) - The title displayed on the page.
- **imageSizeLimit** (integer) - The maximum allowed size for images in bytes.

### Request Example
```bash
curl -s -X PUT http://localhost:3212/api/v1/config \
  -H "Authorization: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"registerOpen": true, "pageTitle": "My SealChat", "imageSizeLimit": 8192}'
```
```

--------------------------------

### Join World

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Allows a user to join a specified world. Requires the world ID and an Authorization token.

```bash
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/join" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Create a World

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new world with specified properties.

```APIDOC
## Create a World — `POST /api/v1/worlds`

```bash
curl -s -X POST http://localhost:3212/api/v1/worlds \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My RPG World",
    "isPublic": false,
    "description": "A dark fantasy setting"
  }'
# Response: { "world": { "id": "world_abc", "name": "My RPG World", ... } }
```
```

--------------------------------

### Register a Bot Token

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates an API token for a bot user. Requires `sys-admin` role.

```APIDOC
## POST /api/v1/admin/bot-token-add

### Description
Creates an API token for a bot user. Requires `sys-admin` role.

### Method
POST

### Endpoint
`/api/v1/admin/bot-token-add`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the bot.
- **kind** (string) - Required - The kind of bot (e.g., "manual").

### Request Example
```json
{
  "name": "My Dice Bot",
  "kind": "manual"
}
```

### Response
#### Success Response (200)
- **token** (string) - The generated API token for the bot.
- **botUserId** (string) - The ID of the newly created bot user.
```

--------------------------------

### Setting Database Connection via Environment Variable

Source: https://github.com/kagangtuya-star/sealchat/blob/master/deploy_zh.md

Configure the SealChat CLI to connect to a PostgreSQL database using an environment variable. This method takes precedence over the configuration file.

```bash
export SEALCHAT_DSN="postgresql://user:pass@localhost:5432/sealchat"
./sealchat-server --config-list
```

--------------------------------

### Join / Leave World

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Allows a user to join or leave a specific world.

```APIDOC
## Join / Leave World — `POST /api/v1/worlds/:worldId/join`

```bash
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/join" \
  -H "Authorization: $TOKEN"

curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/leave" \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### Audio Asset Management

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Manages ambient audio assets for scenes, including listing, uploading, and streaming. Requires ffmpeg and ffprobe.

```bash
# List assets
curl -s http://localhost:3212/api/v1/audio/assets \
  -H "Authorization: $TOKEN"
```

```bash
# Upload new audio asset (workbench admin required)
curl -s -X POST http://localhost:3212/api/v1/audio/assets/upload \
  -H "Authorization: $TOKEN" \
  -F "file=@battle-drums.mp3" \
  -F "name=Battle Drums" \
  -F "folderId=folder_001"
```

```bash
# Stream audio
curl -s "http://localhost:3212/api/v1/audio/stream/asset_001" \
  -H "Authorization: $TOKEN" \
  --output stream.mp3
```

--------------------------------

### CLI Commands for Configuration Management

Source: https://github.com/kagangtuya-star/sealchat/blob/master/deploy_zh.md

Manage SealChat's configuration versions using CLI commands. These commands allow listing history, viewing specific versions, rolling back, and exporting configurations.

```bash
# 列出所有配置历史版本
./sealchat-server --config-list
```

```bash
# 查看指定版本的配置详情（敏感字段显示为 ******）
./sealchat-server --config-show 3
```

```bash
# 回滚到指定版本（会创建新版本记录）
./sealchat-server --config-rollback 2
```

```bash
# 导出指定版本为 YAML 文件
./sealchat-server --config-export 1 --output config.backup.yaml
```

--------------------------------

### Create World Keyword

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new keyword within a specified world. Requires authorization and a JSON payload containing the word, definition, and category ID.

```bash
# Create a keyword
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/keywords" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "word": "Elven Steel",
    "definition": "A rare alloy forged only in the ancient elven forges.",
    "categoryId": "cat_materials"
  }'
```

--------------------------------

### Asset Management

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Manages an ambient audio library for scenes, supporting listing, uploading, and streaming audio assets. Requires ffmpeg and ffprobe.

```APIDOC
## Audio Asset Management

### List Assets

#### Method
GET

#### Endpoint
/api/v1/audio/assets

### Upload Asset

#### Method
POST

#### Endpoint
/api/v1/audio/assets/upload

#### Form Data
- **file** (file) - Required - The audio file to upload.
- **name** (string) - Required - The name of the audio asset.
- **folderId** (string) - Optional - The ID of the folder to place the asset in.

### Stream Audio

#### Method
GET

#### Endpoint
/api/v1/audio/stream/asset_001

#### Parameters
#### Path Parameters
- **asset_001** (string) - Required - The ID of the audio asset to stream.
```

--------------------------------

### User Sign-in

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Authenticates a user with their credentials and returns a bearer token for subsequent requests.

```APIDOC
## POST /api/v1/user-signin

### Description
Authenticates with username/email + password and returns a bearer token. The token is passed as `Authorization: <token>` on all subsequent authenticated requests.

### Method
POST

### Endpoint
/api/v1/user-signin

### Request Body
- **username** (string) - Required - The user's username or email.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "alice",
  "password": "secret123"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **token** (string) - Bearer token for authentication.
```

--------------------------------

### List Worlds

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves a list of worlds accessible to the authenticated user. Requires an Authorization token.

```bash
curl -s http://localhost:3212/api/v1/worlds \
  -H "Authorization: $TOKEN"
# Response: { "items": [{ "id", "name", "memberCount", ... }], "total": 3 }
```

--------------------------------

### User Sign-in with curl

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Authenticate with your username and password to obtain a bearer token. This token is required for all subsequent authenticated API requests.

```bash
curl -s -X POST http://localhost:3212/api/v1/user-signin \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secret123"}'
```

```json
# Response
{"message": "登录成功", "token": "abc123..."}
```

```bash
# All subsequent calls
curl -s http://localhost:3212/api/v1/user-info \
  -H "Authorization: abc123..."
```

--------------------------------

### Configure S3 Storage and Email Notifications

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

This YAML configuration sets up S3 for attachments and audio, specifying the endpoint, bucket, and region. It also configures email notifications with SMTP details. Environment variables are preferred for sensitive credentials.

```yaml
storage:
  s3:
    attachmentsEnabled: true
    audioEnabled: true
    endpoint: "https://cos.ap-guangzhou.myqcloud.com"
    bucket: "my-sealchat-bucket"
    region: "ap-guangzhou"
    # Prefer env vars over config file for secrets:
    # SEALCHAT_S3_ACCESS_KEY, SEALCHAT_S3_SECRET_KEY
emailNotification:
  enabled: true
  smtp:
    host: "smtp.example.com"
    port: 587
    username: "noreply@example.com"
    password: "smtp-password"
emailAuth:
  enabled: true
```

--------------------------------

### Gallery Management

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Manages gallery collections and items, including creation and uploading. Also supports searching gallery items.

```bash
# Create a collection
curl -s -X POST http://localhost:3212/api/v1/gallery/collections \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Character Art", "worldId": "world_abc"}'
```

```bash
# Upload an item to the gallery
curl -s -X POST http://localhost:3212/api/v1/gallery/items/upload \
  -H "Authorization: $TOKEN" \
  -F "file=@art.png" \
  -F "collectionId=coll_001"
```

```bash
# Search gallery
curl -s "http://localhost:3212/api/v1/gallery/search?q=goblin&collectionId=coll_001" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### User Management

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

APIs for managing users within the system.

```APIDOC
## GET /api/v1/admin/user-list

### Description
Lists all users in the system.

### Method
GET

### Endpoint
`/api/v1/admin/user-list`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **pageSize** (integer) - Optional - The number of users per page.

## POST /api/v1/admin/user-create

### Description
Creates a new user.

### Method
POST

### Endpoint
`/api/v1/admin/user-create`

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new user.
- **password** (string) - Required - The password for the new user.
- **nickname** (string) - Optional - The nickname for the new user.

## POST /api/v1/admin/user-batch-create

### Description
Creates multiple users from a CSV file.

### Method
POST

### Endpoint
`/api/v1/admin/user-batch-create`

### Parameters
#### Form Data
- **file** (file) - Required - The CSV file containing user data.

## POST /api/v1/admin/user-password-reset

### Description
Resets a user's password.

### Method
POST

### Endpoint
`/api/v1/admin/user-password-reset`

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user whose password to reset.
- **newPassword** (string) - Required - The new password for the user.
```

--------------------------------

### Quick Upload Attachment

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Uploads an attachment with hash-based deduplication. Skips upload if the file already exists.

```bash
curl -s -X POST http://localhost:3212/api/v1/attachment-upload-quick \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha256": "abcdef...", "filename": "image.png", "size": 102400}'
```

--------------------------------

### Run SealChat with docker run

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Runs SealChat as a Docker container with specified port mappings, volume mounts for data persistence, and environment variables. Ensures the container restarts automatically unless stopped.

```bash
docker run -d --name sealchat --restart unless-stopped \
  -u 0:0 \
  -p 3212:3212 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/sealchat-data:/app/sealchat-data \
  -v $(pwd)/static:/app/static \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -e TZ=Asia/Shanghai \
  ghcr.io/kagangtuya-star/sealchat:latest
```

--------------------------------

### Export World Keywords

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Exports all keywords from a specified world to a CSV file. Requires authorization.

```bash
# Export keywords
curl -s "http://localhost:3212/api/v1/worlds/world_abc/keywords/export" \
  -H "Authorization: $TOKEN" \
  --output keywords.csv
```

--------------------------------

### Typing Indicator

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Broadcasts real-time typing state including optional content preview for IC roleplay.

```APIDOC
## Typing Indicator — `message.typing`

Broadcasts real-time typing state including optional content preview for IC roleplay.

```javascript
ws.send(JSON.stringify({
  api: "message.typing",
  echo: "type-1",
  data: {
    channel_id: "ch_abc123",
    state: "content",       // "indicator" | "content" | "silent"
    content: "I walk into",  // preview text (optional)
    ic_mode: "ic"
  }
}));
// Others receive: { type: "typing-preview", typing: { state, content, icMode } }
```
```

--------------------------------

### Connect to OneBot WebSocket

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Establish a WebSocket connection to the OneBot v11 endpoint for event-driven messaging. Authorization can be provided via query parameter or header.

```javascript
const ws = new WebSocket("ws://localhost:3212/onebot/ws");
// Authorization via query param or header: ?access_token=<32-char-bot-token>

ws.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (event.post_type === "message" && event.message_type === "group") {
    console.log(`[Group ${event.group_id}] ${event.sender.nickname}: ${event.message}`);
    // Echo reply
    ws.send(JSON.stringify({
      action: "send_group_msg",
      params: { group_id: event.group_id, message: `You said: ${event.message}` },
      echo: `reply-${event.message_id}`
    }));
  }
};
```

--------------------------------

### Leave World

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Allows a user to leave a specified world. Requires the world ID and an Authorization token.

```bash
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/leave" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Configure Digest Push

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Configures time-window-based activity digests. Supports active push to an external URL or passive polling. Includes options for push headers and signature verification.

```bash
# Enable active push (SealChat → your server)
curl -s -X POST "http://localhost:3212/api/v1/channels/ch_abc123/digest-push" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "window": "1h",
    "thresholdMode": "channel_member_count",
    "pushMode": "active",
    "pushUrl": "https://your-bot.example.com/digest",
    "pushMethod": "POST",
    "pushHeaders": "{\"X-Env\": \"prod\"}",
    "signSecret": "hmac-secret-key"
  }'
```

```bash
# Poll latest digest (passive mode)
curl -s "http://localhost:3212/api/v1/webhook/channels/ch_abc123/digests/latest?token=whk_token_here"
# Response: { "channelId": "ch_abc123", "items": [{ "messageCount": 5, "speakerNames": ["Alice"], ... }] }
```

```bash
# Verify incoming push signature (HMAC-SHA256)
# signature = HMAC_SHA256(secret, X-SealChat-Timestamp + "." + rawBody)
# Header: X-SealChat-Signature: sha256=<hex>
```

--------------------------------

### Create Channel

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a new channel within a world. Specify the world ID, channel name, and permissions type ('public' or 'private'). An optional parent channel ID can be provided for categorization.

```javascript
ws.send(JSON.stringify({
  api: "channel.create",
  echo: "chan-1",
  data: {
    world_id: "world_abc",
    name: "tavern",
    parent_id: "",          // optional category channel
    perm_type: "public"     // "public" | "private"
  }
}));
```

--------------------------------

### Update Server Configuration

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Updates the server configuration. Requires an administrator token and specifies the content type as JSON. The request body should contain the configuration parameters to be updated.

```bash
# Update config
curl -s -X PUT http://localhost:3212/api/v1/config \
  -H "Authorization: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"registerOpen": true, "pageTitle": "My SealChat", "imageSizeLimit": 8192}'
```

--------------------------------

### OneBot v11 HTTP Endpoint

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Exposes a OneBot v11-compatible HTTP API for bots written for QQ clients.

```APIDOC
## POST /onebot/http

### Description
SealChat exposes a OneBot v11-compatible HTTP API so bots written for QQ (e.g., SealDice, go-cqhttp clients) can interact via standard OneBot actions.

### Method
POST

### Endpoint
`/onebot/http`

### Parameters
#### Request Body
- **action** (string) - Required - The OneBot action to perform (e.g., "send_group_msg", "get_group_list").
- **params** (object) - Required - Parameters for the action.
- **echo** (string) - Optional - An identifier to echo back in the response.

### Request Example
```json
{
  "action": "send_group_msg",
  "params": { "group_id": 123456789, "message": "Hello from OneBot!" },
  "echo": "req-001"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the operation (e.g., "ok").
- **retcode** (integer) - The return code of the operation.
- **data** (object) - Data returned by the action.
- **echo** (string) - Echoed from the request.
```

--------------------------------

### Quick Upload Attachment

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Uploads an attachment using its SHA256 hash for deduplication. If the file already exists, it skips the upload.

```APIDOC
## POST /api/v1/attachment-upload-quick

### Description
Quickly uploads an attachment by first checking if a file with the same SHA256 hash already exists. If it does, the upload is skipped.

### Method
POST

### Endpoint
/api/v1/attachment-upload-quick

### Request Body
- **sha256** (string) - Required - The SHA256 hash of the file.
- **filename** (string) - Required - The name of the file.
- **size** (integer) - Required - The size of the file in bytes.
```

--------------------------------

### List Worlds

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Retrieves a list of worlds accessible to the user.

```APIDOC
## List Worlds — `GET /api/v1/worlds`

```bash
curl -s http://localhost:3212/api/v1/worlds \
  -H "Authorization: $TOKEN"
# Response: { "items": [{ "id", "name", "memberCount", ... }], "total": 3 }
```
```

--------------------------------

### WebSocket Connection and Identification

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Establish a WebSocket connection for real-time events. The client must send an 'Identify' opcode (3) with a valid token within 10 seconds to authenticate. Bots use a 32-character token, users use JWT, and an empty token creates a guest session.

```javascript
const ws = new WebSocket("ws://localhost:3212/ws/seal");

ws.onopen = () => {
  // Opcode 3 = Identify
  ws.send(JSON.stringify({
    op: 3,
    body: { token: "abc123..." }
  }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // op 4 = Ready
  if (msg.op === 4 && !msg.body.errorMsg) {
    console.log("Connected as", msg.body.user.nick);
  }
  // op 0 = Event
  if (msg.op === 0) {
    console.log("Event:", msg.body.type, msg.body.message?.content);
  }
};

// Keep-alive (op 1 = Ping)
setInterval(() => ws.send(JSON.stringify({ op: 1, body: { focused: true } })), 30000);
```

--------------------------------

### Enter a Channel via WebSocket

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Join a specific channel to receive messages and set presence. The 'echo' field can be used for client-side request tracking.

```javascript
ws.send(JSON.stringify({
  api: "channel.enter",
  echo: "req-1",
  data: { channel_id: "ch_abc123" }
}));
// Server broadcasts channel-presence-updated to all channel members
```

--------------------------------

### Configure Digest Push

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Configures time-window-based activity digests for channels. Supports enabling active push to an external endpoint or passive polling.

```APIDOC
## POST /api/v1/channels/:channelId/digest-push

### Description
Configures digest push settings for a channel. This allows for time-window-based activity digests to be pushed to an external HTTP endpoint or polled via a token. It also includes details on how to verify incoming push signatures.

### Method
POST

### Endpoint
/api/v1/channels/:channelId/digest-push

### Request Body
- **enabled** (boolean) - Required - Whether digest push is enabled.
- **window** (string) - Required - The time window for digests (e.g., "1h").
- **thresholdMode** (string) - Required - The mode for triggering digests (e.g., "channel_member_count").
- **pushMode** (string) - Required - The mode for receiving digests ('active' or 'passive').
- **pushUrl** (string) - Optional - The URL to push digests to (required if pushMode is 'active').
- **pushMethod** (string) - Optional - The HTTP method for push requests (e.g., "POST").
- **pushHeaders** (string) - Optional - Custom headers for push requests (JSON string).
- **signSecret** (string) - Optional - Secret key for signing push requests (HMAC-SHA256).

### Poll Latest Digest (Passive Mode)

#### Method
GET

#### Endpoint
/api/v1/webhook/channels/:channelId/digests/latest

#### Query Parameters
- **token** (string) - Required - The token for polling digests.
```

--------------------------------

### Manage World Keywords (REST)

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

APIs for managing world-scoped keywords and glossary entries.

```APIDOC
## POST /api/v1/worlds/:worldId/keywords

### Description
Creates a new keyword within a specific world.

### Method
POST

### Endpoint
/api/v1/worlds/:worldId/keywords

### Parameters
#### Path Parameters
- **worldId** (string) - Required - The ID of the world to add the keyword to.

#### Request Body
- **word** (string) - Required - The keyword itself.
- **definition** (string) - Required - The definition of the keyword.
- **categoryId** (string) - Optional - The ID of the category the keyword belongs to.

### Request Example
```bash
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/keywords" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "word": "Elven Steel",
    "definition": "A rare alloy forged only in the ancient elven forges.",
    "categoryId": "cat_materials"
  }'
```

## POST /api/v1/worlds/:worldId/keywords/import

### Description
Bulk imports keywords into a world from a CSV file.

### Method
POST

### Endpoint
/api/v1/worlds/:worldId/keywords/import

### Parameters
#### Path Parameters
- **worldId** (string) - Required - The ID of the world to import keywords into.

#### Request Body
- **file** (file) - Required - The CSV file containing keywords.

### Request Example
```bash
curl -s -X POST "http://localhost:3212/api/v1/worlds/world_abc/keywords/import" \
  -H "Authorization: $TOKEN" \
  -F "file=@keywords.csv"
```

## GET /api/v1/worlds/:worldId/keywords/export

### Description
Exports all keywords from a specific world to a CSV file.

### Method
GET

### Endpoint
/api/v1/worlds/:worldId/keywords/export

### Parameters
#### Path Parameters
- **worldId** (string) - Required - The ID of the world to export keywords from.

### Request Example
```bash
curl -s "http://localhost:3212/api/v1/worlds/world_abc/keywords/export" \
  -H "Authorization: $TOKEN" \
  --output keywords.csv
```

## GET /api/v1/public/worlds/:worldId/keywords

### Description
Retrieves a list of public keywords for a specific world. No authentication is required.

### Method
GET

### Endpoint
/api/v1/public/worlds/:worldId/keywords

### Parameters
#### Path Parameters
- **worldId** (string) - Required - The ID of the world to retrieve keywords from.

### Request Example
```bash
curl -s "http://localhost:3212/api/v1/public/worlds/world_abc/keywords"
```
```

--------------------------------

### Password Reset Request and Confirmation

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Initiate an email-based password reset. Ensure SMTP is configured in 'config.yaml'. The process involves requesting a code and then confirming the reset with that code.

```bash
# 1. Request reset code
curl -s -X POST http://localhost:3212/api/v1/password-reset/request \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'
```

```bash
# 2. Confirm with code from email
curl -s -X POST http://localhost:3212/api/v1/password-reset/confirm \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "code": "123456", "newPassword": "newpass123"}'
```

--------------------------------

### List Messages

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Fetches a paginated history of messages in the active channel. Use `before` for pagination to retrieve messages before a specific message ID.

```javascript
ws.send(JSON.stringify({
  api: "message.list",
  echo: "list-1",
  data: {
    channel_id: "ch_abc123",
    before: "msg_oldid",  // cursor for pagination
    limit: 50
  }
}));
// Response: { echo: "list-1", data: { items: [...], total: 120 } }
```

--------------------------------

### Create a Channel Identity

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Creates a channel identity (persona) for a user, allowing custom display names, colors, and avatars.

```APIDOC
## Create a Channel Identity — `POST /api/v1/channel-identities`

Channel identities allow users to post as named characters with custom avatars and colors, enabling immersive roleplay personas.

```bash
curl -s -X POST http://localhost:3212/api/v1/channel-identities \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Goblin Warrior",
    "color": "#22c55e",
    "avatarAttachmentId": "att_abc123"
  }'
# Response: { "identity": { "id": "ident_xyz", "displayName": "Goblin Warrior", ... } }
```
```

--------------------------------

### Set Audio Playback State

Source: https://context7.com/kagangtuya-star/sealchat/llms.txt

Broadcasts synchronized audio playback state to all channel members. The server then broadcasts an 'audio-state-updated' event.

```bash
curl -s -X POST http://localhost:3212/api/v1/audio/state \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ch_abc123",
    "tracks": [{
      "type": "bgm",
      "assetId": "asset_001",
      "volume": 0.8,
      "isPlaying": true,
      "loopEnabled": true,
      "fadeIn": 2000
    }],
    "isPlaying": true
  }'
# Server broadcasts "audio-state-updated" event to channel
```