Metadata-Version: 2.5
Name: oibot
Version: 2026.11.17
Summary: a lightweight bot framework
Requires-Python: >=3.14
Requires-Dist: aiohttp
Requires-Dist: cryptography
Description-Content-Type: text/markdown

# OiBot

OiBot is a lightweight, fully asynchronous QQ bot framework built on
[aiohttp](https://github.com/aio-libs/aiohttp). It wraps event delivery, plugin
dispatch, message construction, dependency injection, and the QQ Bot HTTP APIs
in a small, typed interface.

## Table of contents

- [Highlights](#highlights)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
  - [Start the bot](#start-the-bot)
  - [Write the smallest useful plugin](#write-the-smallest-useful-plugin)
- [WebSocket transport](#websocket-transport)
- [Framework design](#framework-design)
  - [Modules are plugins](#modules-are-plugins)
  - [Type annotations are event subscriptions](#type-annotations-are-event-subscriptions)
  - [Matchers can return context](#matchers-can-return-context)
  - [Matcher chains pass context in order](#matcher-chains-pass-context-in-order)
  - [Lifecycle hooks share the aiohttp application](#lifecycle-hooks-share-the-aiohttp-application)
- [Dependency injection](#dependency-injection)
  - [Lazy dependencies: acquire only when needed](#lazy-dependencies-acquire-only-when-needed)
- [Messages and conversations](#messages-and-conversations)
  - [Turn event handling into a conversation](#turn-event-handling-into-a-conversation)
- [Calling APIs directly](#calling-apis-directly)
- [API reference](#api-reference)
  - [`OiBot`](#oibot-1)
  - [Plugin, matcher, and dependency APIs](#plugin-matcher-and-dependency-apis)
  - [Message builders](#message-builders)
  - [Sending and streaming messages](#sending-and-streaming-messages)
  - [Rich media uploads](#rich-media-uploads)
  - [Markdown image materials](#markdown-image-materials)
  - [Message recall and interactions](#message-recall-and-interactions)
  - [Group management](#group-management)
  - [Group join approval strategies](#group-join-approval-strategies)
  - [Bot information and guilds](#bot-information-and-guilds)
  - [Menus](#menus)
  - [Panels](#panels)
  - [Access tokens and raw requests](#access-tokens-and-raw-requests)
  - [Events](#events)
- [Troubleshooting](#troubleshooting)

## Highlights

- Webhook and WebSocket transports share one `aiohttp` application and API
  client, with signature verification and connection recovery built in.
- Ordinary Python modules are discovered as plugins, with lifecycle hooks and
  concurrent handler dispatch.
- Handler annotations select event types and unions; matcher results supply
  named handler arguments.
- Synchronous and asynchronous rules compose with `&`, `|`, and `~` for logical
  checks, or `>>` and `<<` for ordered context passing and short-circuiting.
- Eager and lazy dependencies support functions, generators, and context
  managers, with reuse within each handler invocation and automatic cleanup.
- The shared application holds resources for the bot's lifetime; dependency
  providers manage resources for individual handler invocations.
- Message builders cover text, Markdown, keyboards, cards, rich media, and
  streaming. Images can also be managed as reusable Markdown materials.
- `reply(...)` targets the originating conversation, with quoting for group
  messages; `chat(...)` waits for message or button responses.
- Typed QQ Bot APIs cover messaging, interactions, group management, menus,
  and panels, with access-token refresh and scoped request throttling.

## Requirements

- Python 3.14 or later, as declared in `pyproject.toml`.
- A QQ Bot application ID and application secret.

## Installation

Install the latest stable release from PyPI:

```sh
python -m pip install --upgrade oibot
```

For a project managed by uv:

```sh
uv add oibot --frozen
```

Install the latest development version from GitHub:

```sh
python -m pip install --upgrade 'oibot @ git+https://github.com/OrganRemoved/oibot.git'
```

Alternatively, install the branch archive:

```sh
python -m pip install --upgrade https://github.com/OrganRemoved/oibot/archive/refs/heads/main.zip
```

## Quick start

Create an importable plugin package next to the bot entry point:

```text
awesome_oibot/
├── bot.py
└── plugins/
    ├── __init__.py
    └── ping.py
```

### Start the bot

```python
import logging
from os import environ

from oibot.bot import OiBot


logging.basicConfig(
    level=logging.INFO,
    format="[%(asctime)s][%(levelname)s][%(module)s:%(funcName)s:%(lineno)d] %(message)s",
)


if __name__ == "__main__":
    OiBot(
        plugins="plugins",
        app_id=environ["OIBOT_APP_ID"],
        app_secret=environ["OIBOT_APP_SECRET"],
    ).webhook(
        path="/callback",
        host=environ.get("OIBOT_HOST", "0.0.0.0"),
        port=int(environ.get("OIBOT_PORT", "8080")),
    )
```

Configure the platform callback URL to point to the public HTTPS URL ending in
`/callback`, then run `python bot.py` from `awesome_oibot`. OiBot handles the
callback-validation request with the configured application secret and rejects
event deliveries whose Ed25519 request signature is missing or invalid.

### Write the smallest useful plugin

A plugin is a Python module containing typed event handlers:

```python
from oibot.event.group_at_message_create import GroupAtMessageCreateEvent
from oibot.event.group_message_create import GroupMessageCreateEvent
from oibot.plugin import on


@on(lambda event: event.content.strip() == "/ping")
async def ping(event: GroupAtMessageCreateEvent | GroupMessageCreateEvent) -> None:
    await event.reply("pong")
```

The annotation subscribes to both event types. The rule selects messages, and
`reply(...)` sends a response using the event's context. OiBot discovers the
handler when it imports the plugin module.

## WebSocket transport

For WebSocket event delivery, import `Intents` from its concrete module and
combine the required flags with `|`:

```python
from os import environ

from oibot.bot import OiBot
from oibot.transport.websocket import Intents


if __name__ == "__main__":
    OiBot(
        plugins="plugins",
        app_id=environ["OIBOT_APP_ID"],
        app_secret=environ["OIBOT_APP_SECRET"],
    ).websocket(intents=Intents.GROUP_AND_C2C_EVENT | Intents.INTERACTION)
```

`GROUP_AND_C2C_EVENT` is the default. Add `INTERACTION` for callback buttons.
Add `GROUP_MEMBER_EVENT` for group-member joins, departures, and join requests.
Join-request events require the bot to be a group administrator.
Other flags include `GUILDS`, `GUILD_MEMBERS`, `GUILD_MESSAGES`,
`GUILD_MESSAGE_REACTIONS`, `DIRECT_MESSAGE`, `OPEN_FORUMS_EVENT`,
`AUDIO_OR_LIVE_CHANNEL_MEMBER`, `MESSAGE_AUDIT`, `FORUMS_EVENT`, `AUDIO_ACTION`,
and `PUBLIC_GUILD_MESSAGES`.

Both `webhook(...)` and `websocket(...)` are blocking entry points that own the
bot HTTP-client lifecycle. Inside a running handler, use `event.bot` for API
calls.

## Framework design

The event path is deliberately short and explicit:

```text
Webhook / WebSocket
        ↓
typed Event + reply/session context
        ↓
PluginManager
        ↓
type annotation → matcher → dependency graph
        ↓
async handler
```

This keeps transport concerns outside business plugins while preserving the
original event and bot instance all the way to the handler.

### Modules are plugins

`OiBot(plugins=...)` accepts one path or an iterable of paths. Directories are
scanned recursively and Python files beginning with `_` are ignored. An
imported module becomes a plugin when it exposes at least one `@on(...)`
handler or an `init(app)` lifecycle hook.

Plugins remain ordinary Python modules. Handlers from all loaded plugins run
concurrently; their execution order is not guaranteed.

### Type annotations are event subscriptions

`@on(...)` inspects the handler signature. An event parameter annotated with a
concrete `Event` subclass selects that event, and a union selects several event
types. Annotating with the base `Event` creates a catch-all handler.

Import event classes from their concrete modules, for example
`oibot.event.friend_add`. The `oibot.event` package itself defines the base
`Event` and `EventType`.

This design provides three benefits at once:

- dispatch metadata lives next to the parameter that consumes the event;
- editors and type checkers know the exact event interface inside the handler;
- the framework can inject the matching event without string-based event names.

A handler must have at least one event-typed parameter. Without one, it has no
event subscription and will not run.

### Matchers can return context

A rule may be synchronous or asynchronous. `await matcher.match(...)`
normalizes its result into a context dictionary:

| Rule result | Match context |
| --- | --- |
| Non-empty dictionary | The dictionary itself. Values may be falsy, as in `{"text": ""}` or `{"value": None}`. |
| Other truthy value | `{"_": result}`, including `{"_": True}` for `True`. |
| Falsy value, including `False`, `None`, or `{}` | `{}`; the handler is skipped. |

Only keys matching named handler parameters are injected. A handler with
`**kwargs` receives the complete matcher context. Event and dependency
parameters are supplied by the framework and take precedence over matching
context keys.

Use `&`, `|`, and `~` for logical composition, with `Matcher.all(...)` and
`Matcher.any(...)` as named equivalents for `&` and `|`:

- `&` requires every branch to match and merges their contexts. A failed
  branch stops the match.
- `|` accepts the first successful branch and returns its context.
- `~` returns the boolean inverse of a rule's success, without retaining its
  context. Applying `~` twice restores the truth value, not the original data.

Within `&` and `|`, branches receive the same input; results are not passed
between them. Synchronous branches run first. If still needed, asynchronous
branches run concurrently and their results are processed in completion order.
For `&`, later results overwrite duplicate keys; for `|`, the first successful
completion wins. Unfinished branches are cancelled once the outcome is known.
Use a chain when execution order or context passing matters.

### Matcher chains pass context in order

`left >> right` runs left before right; `left << right` runs right before left.
Synchronous and asynchronous rules can be mixed. Every stage receives the same
event and the accumulated keyword context. Each stage must accept all incoming
keywords; use named parameters for the values it needs and `**kwargs` for the
rest. The chain passes context separately from the event.

Dictionary results update that context, with later values replacing earlier
values of the same name. A failed match stops the chain and skips the handler.

```python
from typing import Any

from oibot.event.group_at_message_create import GroupAtMessageCreateEvent
from oibot.event.group_message_create import GroupMessageCreateEvent
from oibot.matcher import Matcher
from oibot.plugin import on


MessageEvent = GroupAtMessageCreateEvent | GroupMessageCreateEvent


def echo_input(event: MessageEvent) -> dict[str, str] | None:
    command, _, text = event.content.strip().partition(" ")
    if command in {"echo", "/echo"}:
        return {"text": text}


def nonempty_text(
    event: MessageEvent, *, text: str, **kwargs: Any
) -> dict[str, str] | None:
    if text := text.strip():
        return {"text": text}


parse_echo = Matcher(echo_input)
normalize_text = Matcher(nonempty_text)


@on(parse_echo >> normalize_text)
async def echo(event: MessageEvent, *, text: str) -> None:
    await event.reply(text)
```

`/echo   hello` produces `{"text": "  hello"}`, then `{"text": "hello"}`.
The handler receives the normalized text. `/echo` stops at the second rule;
unrelated messages stop at the first. `normalize_text << parse_echo` gives the
same order and result.

Chains retain fields from earlier stages unless a later result replaces them.
Each result follows the same truthiness and context rules described above.

Use `await matcher.match(event)` to run a matcher directly. Chains are always
asynchronous. A chain's parameter signature follows its first executed rule:
the left operand of `>>` or the right operand of `<<`. Parenthesize mixed
compositions, such as `parse_input >> (check_a | check_b)`.

### Lifecycle hooks share the aiohttp application

A plugin may define `init(app)`. Use an asynchronous generator when a resource
needs deterministic setup and cleanup:

```python
from collections.abc import AsyncIterator

from aiohttp import ClientSession, web


async def init(app: web.Application) -> AsyncIterator[None]:
    async with ClientSession(base_url="https://example.com") as client:
        app["upstream_client"] = client
        yield
```

Synchronous and asynchronous generators finish setup up to `yield` before
startup continues, and resume for cleanup during shutdown. Ordinary sync or
async `init(app)` callables run as background tasks; startup does not wait for
them to finish. Use a generator for resources that must be ready before events
are handled.

The same `aiohttp.web.Application` is available as `bot.app`, allowing the
entry point and plugins to share routes, schedulers, connection pools, and
other resources for that bot's lifetime.

## Dependency injection

Dependencies are parameter defaults declared with
`Dependency.from_provider(...)`. The provider may be a synchronous function,
coroutine function, generator, async generator, context-manager class, or
async-context-manager class.

The smallest resource dependency needs no wrapper function:

```python
from aiohttp import ClientSession

from oibot.event.group_at_message_create import GroupAtMessageCreateEvent
from oibot.event.group_message_create import GroupMessageCreateEvent
from oibot.plugin import Dependency, on


@on(lambda event: event.content.strip() == "status")
async def status(
    event: GroupAtMessageCreateEvent | GroupMessageCreateEvent,
    *,
    session: ClientSession = Dependency.from_provider(ClientSession),
) -> None:
    async with session.get("https://example.com/health") as response:
        await event.reply(await response.text())
```

The framework enters `ClientSession` as an async context manager and closes it
after the handler finishes. The same lifecycle applies to custom generators
and context managers.

Providers may depend on other providers and request the current event through
a type annotation. Matcher context is injected into the handler, not into
provider parameters. Dependencies are resolved after the matcher succeeds.
For each matched handler:

- independent eager dependencies are resolved concurrently;
- the same provider callable used several times in one handler invocation is
  resolved once and cached;
- generator and context-manager cleanup runs in reverse acquisition order; and
- `eager=False` injects a zero-argument async resolver, so an expensive browser,
  HTTP client, or other resource is created only when the handler actually
  awaits that resolver.

This keeps resource ownership local to a handler while retaining explicit
types and deterministic cleanup. Resources shared across handlers can instead
live in `bot.app` and be managed by a plugin's `init(app)` hook.

### Lazy dependencies: acquire only when needed

A lookup command can return usage text before it ever needs an HTTP client:

```python
from collections.abc import Awaitable, Callable

from aiohttp import ClientSession

from oibot.event.group_at_message_create import GroupAtMessageCreateEvent
from oibot.event.group_message_create import GroupMessageCreateEvent
from oibot.matcher import Matcher
from oibot.plugin import Dependency, on


MessageEvent = GroupAtMessageCreateEvent | GroupMessageCreateEvent


def lookup_input(event: MessageEvent) -> dict[str, str] | None:
    command, _, keyword = event.content.strip().partition(" ")
    if command == "/lookup":
        return {"keyword": keyword.strip()}


@on(Matcher(lookup_input))
async def lookup(
    event: MessageEvent,
    *,
    keyword: str,
    get_session: Callable[[], Awaitable[ClientSession]] = Dependency.from_provider(
        ClientSession, eager=False
    ),
) -> None:
    if not keyword:
        await event.reply("Usage: /lookup <keyword>")
        return

    session = await get_session()
    async with session.get(
        "https://api.example.com/search", params={"q": keyword}
    ) as response:
        response.raise_for_status()
        await event.reply(await response.text())
```

`/lookup` returns the usage hint without creating a session. `/lookup example`
creates one at `await get_session()`. OiBot reuses it within that handler
invocation and closes it when the handler exits, including on exceptions.

The URL above is a placeholder for your own API.

## Messages and conversations

Common message events expose `reply(...)`. A string is converted to a plain
text message, while the builders in `oibot.api.message` cover Markdown,
keyboards, rich media, references, and input notifications.

`GroupAtMessageCreateEvent` and `GroupMessageCreateEvent` support
`await event.reply("pong", quote=True)` to reference the incoming message,
using its `message_scene.ext["msg_idx"]`. Their `chat(...)` methods accept the
same option. C2C and interaction helpers do not accept `quote`; retain the
original group-message event when a later button response should quote it.

```python
from oibot.api.message import Button, Buttons, Keyboard, Markdown, Media, Message


await event.reply(
    Message.markdown(
        Markdown(Markdown.h2("OiBot"), "Choose an action:"),
        keyboard=Keyboard(
            Buttons(
                Button.callback(
                    id="confirm",
                    label="Confirm",
                    visited_label="Confirmed",
                    data={"confirmed": True},
                ),
                Button.jump(
                    id="project",
                    label="Project",
                    data="https://github.com/OrganRemoved/oibot",
                ),
            )
        ),
    )
)


await event.reply(
    Message.media(Media.image(url="https://example.com/image.png"), content="An image")
)
```

`Media.image(...)`, `Media.video(...)`, `Media.voice(...)`, and
`Media.file(...)` accept a URL or bytes through `data=...`. The high-level
`send_user_message(...)` and `send_group_message(...)` methods prepare and
upload byte content automatically using the platform's multipart protocol.
Byte uploads require `file_name`, for example
`Media.image(data=image_bytes, file_name="image.png")`. URL uploads can omit it.

For images embedded in Markdown, use
[`upload_media_image(...)`](#markdown-image-materials) and pass its returned
`url` to `Markdown.image(...)`. `Message.media(Media.image(...))` uses the
rich-media upload and send APIs; `Message.markdown(...)` sends the Markdown
image reference.

### Turn event handling into a conversation

`chat(...)` sends a message and suspends the current handler. Without a
keyboard, it waits for the same user's next message. A Markdown or card message
with a keyboard waits for a button callback instead; the button's permission
controls who may respond. `timeout` accepts seconds, a `timedelta`, or `None`.

```python
from oibot.api.message import (
    Button,
    ButtonActionPermission,
    Buttons,
    Keyboard,
    Markdown,
    Message,
)


try:
    interaction = await event.chat(
        Message.markdown(
            Markdown("Continue?"),
            keyboard=Keyboard(
                Buttons(
                    Button.callback(
                        id="continue",
                        label="Continue",
                        data={"continue": True},
                        permission=ButtonActionPermission.specify_user_ids(
                            event.author.member_openid
                        ),
                    )
                )
            ),
        ),
        timeout=30,
    )
except TimeoutError:
    await event.reply("Timed out.")
else:
    if interaction.button_data["continue"]:
        await interaction.reply("Continuing.")
```

This group-message example limits the button to the initiating member.
OiBot suffixes outgoing button IDs with the originating event ID on a copy of
the message. The session manager routes a matching response to the waiting
handler instead of dispatching it to plugins. Text waits are keyed by user;
button waits are keyed by button ID. Keep one active wait per key.

The transport also records recent incoming message or event identifiers in a
bounded quota pool. The sending layer uses an available entry to supply reply
identifiers and sequence numbers; if no entry is available, it leaves the
message fields as supplied. This reply context is separate from the visible
message reference added by `quote=True`.

## Calling APIs directly

During event handling, the complete API client is available as `event.bot`:

```python
from oibot.api.message import Message


await event.bot.send_group_message(
    group_openid=event.group_openid, message=Message.content("A proactive message")
)

await event.bot.delete_group_message(
    group_openid=event.group_openid, message_id="MESSAGE_ID"
)
```

For a one-off API call outside a running transport, use `OiBot` as an async
context manager so its HTTP client is opened and closed correctly:

```python
import asyncio
from os import environ

from oibot.bot import OiBot


async def main() -> None:
    async with OiBot(
        app_id=environ["OIBOT_APP_ID"], app_secret=environ["OIBOT_APP_SECRET"]
    ) as bot:
        information = await bot.get_bot_information()
        print(information)


asyncio.run(main())
```

Access tokens are cached until shortly before expiry and fetched again on
demand. The API methods also use local sliding-window limiters keyed by
application and, where appropriate, by user or group. This provides
backpressure without forcing every plugin to implement its own limiter.

## API reference

The methods below are available directly on an `OiBot` instance. API methods
are asynchronous unless stated otherwise. Parameters following `*` are
keyword-only.

The package root deliberately does not re-export the public types. Import each
name from its concrete module:

```python
from oibot.api.interaction import Code
from oibot.api.message import (
    Button,
    ButtonActionPermission,
    ButtonRenderDataStyle,
    Buttons,
    Keyboard,
    Markdown,
    Media,
    Message,
    MessageReference,
    MsgType,
    StreamInputState,
    at,
    channel,
    media,
)
from oibot.api.rich_media import FileType
from oibot.bot import OiBot
from oibot.matcher import Matcher
from oibot.plugin import Dependency, on
from oibot.transport.websocket import Intents
```

Request and response models are ordinary dictionaries at runtime, with
`TypedDict` definitions providing editor and type-checker support. Optional
arguments whose value is `None` are omitted from request payloads where the API
uses `CompactDict`.

### `OiBot`

```text
OiBot(
    plugins: str | Iterable[str] | None = None,
    *,
    app_id: str | None = None,
    app_secret: str | None = None,
    **application_options,
)
```

`plugins` accepts a Python file, a directory, or an iterable containing either.
Additional constructor options are forwarded to `aiohttp.web.Application`.

| Member | Behavior |
| --- | --- |
| `app` | Shared `aiohttp.web.Application`. It also stores `app["bot"]` and the credential context variables and is passed to plugin lifecycle hooks. |
| `app_id` / `app_secret` | Credentials for the current context. API calls use them to obtain an access token. |
| `async with bot` | Opens and closes the shared `aiohttp.ClientSession` with QQ API authentication middleware. Use this form for one-off API calls outside a transport. |
| `webhook(path="/", host="0.0.0.0", port=8080, **route_options)` | Blocking Webhook entry point. Registers the POST route, validates callbacks and signatures, starts the HTTP server, and owns shutdown. |
| `websocket(intents=Intents.GROUP_AND_C2C_EVENT, shard=(0, 1), properties={}, host="0.0.0.0", port=8080, **connect_options)` | Blocking WebSocket entry point. `Intents` flags combine with `\|`; extra options go to `aiohttp`'s WebSocket connection. An HTTP site is also started when plugins added application routes. |
| `await bot(method, url, **request_options)` | Low-level request interface used by API mixins. It returns decoded JSON or `None` for an empty body; authentication follows the host rules described below. |

The blocking transport methods run the application lifecycle hooks as well as
the client session. A bare `async with OiBot(...)` opens only the API client; it
does not start event delivery or the `aiohttp` application runner.

### Plugin, matcher, and dependency APIs

| API | Behavior |
| --- | --- |
| `@on(matcher=None)` | Declares an async handler. One or more parameters must be annotated with `Event` subclasses; a union subscribes to every member type. |
| `Matcher(rule)` | Wraps a synchronous or asynchronous rule. A truthy result matches; a non-empty dictionary also becomes injectable handler context. `{}` means no match. |
| `left & right` / `Matcher.all(...)` | Requires every rule to match and merges contexts. Synchronous branches run first, then asynchronous branches run concurrently; results do not flow between branches. |
| `left \| right` / `Matcher.any(...)` | Returns the first successful context: synchronous branches first, then asynchronous branches in completion order. |
| `~matcher` | Inverts the wrapped rule's truth value and discards its context. A successful inversion normalizes to `{"_": True}`. |
| `left >> right` | Runs left, then right, passing the accumulated keyword context between stages. Returns the final context, or `{}` on the first failed match. Always asynchronous. |
| `left << right` | Runs right, then left, with the same context passing and failure behavior as `>>`. Always asynchronous. |
| `await matcher.match(...)` | Normalizes a successful result to a dictionary and a failed result to `{}`. |
| `Dependency.from_provider(provider, eager=True)` | Declares a parameter dependency. Set `eager=False` to inject an async zero-argument resolver instead of the resolved value. |
| `init(app)` | Optional module lifecycle hook. Sync/async generators provide awaited setup and shutdown cleanup; ordinary callables run as background tasks. |

Dependency providers may themselves declare event parameters and dependencies.
Within one matched handler graph, each provider callable is resolved once.
Independent eager providers run concurrently, while generators and context
managers are released automatically in reverse acquisition order.

### Message builders

The builders in [`oibot.api.message`](src/oibot/api/message.py) are dictionary
subclasses, so they can be passed directly to the API while retaining typed
constructors.

#### `Message`, `Media`, and `Card`

| Builder | Result |
| --- | --- |
| `Message.content(text, ...)` | Plain-text message. |
| `Message.markdown(markdown=None, *, keyboard=None, ...)` | Markdown message, optionally with an inline keyboard. |
| `Message.media(media, *, content=None, ...)` | Image, video, voice, or file message with optional accompanying text. |
| `Message.card(card, *, keyboard=None, ...)` | Image-and-text card message for C2C or group chats, optionally with an inline keyboard. |
| `Message.input_notify(input_second, ...)` | C2C input-status notification. Group sends do not accept this message type. |
| `Media.image(data=..., file_name=...)` / `image(url=...)` | Image descriptor. Byte uploads require a file name; URL uploads can omit it. |
| `Media.video(...)` / `voice(...)` / `file(...)` | Other rich-media descriptors. Supply bytes and `file_name`, or a remote `url=...`. |
| `Card.tuwen(*, title, description, url, pic_url)` | Card descriptor containing a title, description, destination URL, and image URL. |
| `MessageReference(message_id=...)` | Adds a reference to another message. |

Media builders create descriptors; sending methods perform the upload. Supply
`file_name` with byte content. A remote `url` can be used without a file name.

Every `Message` constructor also accepts the applicable `msg_id`, `event_id`,
`msg_seq`, `message_reference`, and `is_wakeup` fields. Normally
`event.reply(...)` or the quota pool supplies reply context automatically; set
these fields when explicit protocol control is required.

```python
from oibot.api.message import Card, Message


await event.reply(
    Message.card(
        Card.tuwen(
            title="Update available",
            description="Read the latest changes.",
            url="https://example.com/update",
            pic_url="https://example.com/cover.png",
        )
    )
)
```

The platform requires card titles of 1–50 characters, descriptions of 1–200
characters, and HTTPS URLs of at most 1024 characters for both `url` and
`pic_url`. Like the other builders, `Card.tuwen(...)` constructs the payload;
the platform validates these limits. With a keyboard, `Message.card(...)`
returns `Message[Keyboard]`, and `chat(...)` waits for a button interaction.

#### `Markdown`

`Markdown(*elements, separator="\n", indent=False,
force_verify_image_resource=None)` joins fragments and stores the final
`content`. `str(markdown)` returns that content.

| Helpers | Purpose |
| --- | --- |
| `h1` through `h6` | Headings |
| `emphasis`, `strong_emphasis`, `strikethrough` | Inline emphasis |
| `code_span`, `fenced_code_block`, `inline_latex` | Code and formula formatting |
| `link`, `autolink` | Links |
| `image(*, text, url, width, height)` | Image markup using a public URL or a `qqbot-media://` reference; this builder only constructs the Markdown. |
| `block_quote`, `bullet_list`, `ordered_list`, `task_list` | Block and list layouts, including nested `Markdown` fragments |
| `table(header=..., rows=..., alignments=...)` | Table with optional `left`, `center`, or `right` alignment per column |
| `thematic_break` | Horizontal separator |
| `cmd_enter`, `cmd_input` | QQ Bot command-entry and command-input tags |

#### Keyboards and mentions

```python
keyboard = Keyboard(
    Buttons(
        Button.callback(
            id="refresh",
            label="Refresh",
            data={"action": "refresh"},
            permission=ButtonActionPermission.all(),
        ),
        Button.instruction(id="search", label="Search", data="/search ", enter=False),
    ),
    Buttons(Button.jump(id="docs", label="Documentation", data="https://example.com")),
)
```

| Builder | Behavior |
| --- | --- |
| `Keyboard(*rows)` | Builds an inline keyboard; each positional row is a `Buttons(...)` instance. |
| `Button.jump(...)` | Opens the URL or target supplied in `data`. |
| `Button.callback(...)` | Emits an interaction. Dictionary `data` is compact JSON-encoded automatically; the default permission is everyone. |
| `Button.instruction(...)` | Inserts or sends command text, controlled by `reply`, `enter`, and `anchor`. |
| `ButtonActionPermission.all()` / `admin()` | Allows everyone or group administrators. |
| `ButtonActionPermission.specify_user_ids(...)` / `specify_role_ids(...)` | Limits an action to selected users or roles. |
| `ButtonRenderDataStyle` | `GRAY`, `BLUE`, `WHITE`, and `BLUE_BACKGROUND` render styles. |
| `at(id)` | Returns an at-user tag; `at("all")` returns the at-everyone tag. |
| `channel(channel_id)` | Returns a channel mention. |
| `media(token)` | Returns `qqbot-media://image/v1/<token>` from a platform-issued token. |

`ButtonRenderData`, `ButtonAction`, `Buttons`, `Rows`, `Keyboard`,
`MessageReference`, and `InputNotify` remain available for callers that need to
construct lower-level payloads directly.

### Sending and streaming messages

The high-level `send_*` methods accept a `Message` builder and are the preferred
entry points. The lower-level `*_message` methods expose the wire fields
directly. Use `MsgType.PLAINTEXT`, `MARKDOWN`, `INPUT_NOTIFY`, `MEDIA`, or `CARD`
instead of their numeric wire values.

| Method | Behavior and return value |
| --- | --- |
| `send_user_message(*, openid, message)` | Sends a C2C `Message`. URL media is registered automatically; byte media is prepared, uploaded in server-directed concurrent parts, finalized, and then sent. Returns `MessageResponse`. |
| `send_group_message(*, group_openid, message)` | Group counterpart to `send_user_message`. Returns `MessageResponse`. |
| `send_raw_user_message(*, openid, msg_type, content=None, markdown=None, keyboard=None, media=None, card=None, message_reference=None, input_notify=None, event_id=None, msg_id=None, is_wakeup=None, msg_seq=None)` | Low-level C2C send. `media` is a finalized `MediaInfo` rather than a `Media` builder. |
| `send_raw_group_message(*, group_openid, msg_type, content=None, markdown=None, keyboard=None, media=None, card=None, message_reference=None, event_id=None, msg_id=None, is_wakeup=None, msg_seq=None)` | Low-level group send. |
| `stream_user_message(*, openid, input_state, index, content_type, content_raw, input_mode="append", event_id=None, msg_id=None, stream_msg_id=None, msg_seq=None, is_wakeup=None)` | Sends or updates a C2C stream. `content_type` is `"text"` or `"markdown"` and `input_mode` is `"append"` or `"replace"`. |

`StreamInputState.GENERATING` marks an in-progress stream and
`StreamInputState.FINISHED` completes it. `MessageResponse` contains `id`,
`timestamp`, and `ext_info.ref_idx`; `StreamMessageResponse` may additionally
contain `remain_msg_len`.

The high-level media path deep-copies the message before replacing its media
descriptor, so a builder can be reused safely. Recent supported incoming
events populate a bounded quota pool. When `send_raw_user_message(...)` or
`send_raw_group_message(...)` receives no `msg_id` or `event_id`, it can acquire
a valid identifier and sequence number from that pool. Local limiters apply
application-, user-, and group-scoped backpressure; platform-side limits and
errors still remain authoritative.

### Rich media uploads

[`oibot.api.rich_media`](src/oibot/api/rich_media.py) exposes the upload
protocol used by `send_user_message(...)` and `send_group_message(...)`.
`FileType` has `IMAGE`, `VIDEO`, `VOICE`, and `FILE` members.

| Method | Behavior |
| --- | --- |
| `upload_user_file(*, openid, file_type, url=None, srv_send_msg=False, file_name=None, upload_id=None)` | Registers URL media or a completed upload for a user and returns `RichMediaUploadResponse`. |
| `upload_group_file(*, group_openid, file_type, url=None, srv_send_msg=False, file_name=None, upload_id=None)` | Registers URL media or a completed upload for a group and returns `RichMediaUploadResponse`. |
| `prepare_user_upload(*, openid, file_name, file_type=None, file_size=None, md5=None, sha1=None, md5_10m=None)` | Starts a multipart user upload. |
| `prepare_group_upload(*, group_openid, file_name, file_type=None, file_size=None, md5=None, sha1=None, md5_10m=None)` | Starts a multipart group upload. |
| `upload_user_part(*, openid, upload_id, data, block_size, part, retry_timeout=300, retry_delay=1)` | Uploads one prepared user part and reports its digest. |
| `upload_group_part(*, group_openid, upload_id, data, block_size, part, retry_timeout=300, retry_delay=1)` | Uploads one prepared group part and reports its digest. |
| `finish_user_upload_part(*, openid, upload_id=None, part_index=None, block_size=None, md5=None)` | Marks one user-upload part complete. |
| `finish_group_upload_part(*, group_openid, upload_id=None, part_index=None, block_size=None, md5=None)` | Marks one group-upload part complete. |

`RichMediaUploadPrepareResponse` supplies `upload_id`, `block_size`, the
presigned `parts`, and an `upload_config` containing concurrency and retry
settings. `RichMediaUploadResponse` supplies `file_uuid`, `file_info`, `ttl`,
and optional `id` and `raw_url`. Application code normally needs these
low-level methods only when implementing a custom upload pipeline.

`file_size` and `block_size` in this multipart protocol are decimal strings.
The prepare methods require `file_name`.
When completing a multipart upload with `upload_id`, `upload_user_file(...)`
and `upload_group_file(...)` also require `file_name` in the request. Their
Python signatures keep it optional because URL uploads may omit it. These
mixins forward parameters without adding runtime validation.

### Markdown image materials

[`oibot.api.material`](src/oibot/api/material.py) provides `MaterialMixin`,
included in `OiBot`, for the platform's
[image material APIs](https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/material-management.html).

| Method | Behavior |
| --- | --- |
| `prepare_media_image_upload(*, file_name, file_size, content_type, md5, sha1)` | Returns `MediaImageUploadPrepareResponse` with `upload_id`, `presigned_url`, and `expires_in`. `file_size` is an integer. |
| `complete_media_image_upload(*, upload_id, md5)` | Completes the upload using the PUT response's unquoted ETag. Returns `MediaImageUploadResponse` with `image_id`, `url`, `ttl`, and `preview_url`. |
| `upload_media_image(*, data, file_name, content_type)` | Runs the full upload flow and returns `MediaImageUploadResponse`. All three arguments are required; `data` is bytes. |
| `get_media_images(*, cursor=None)` | Returns `MediaImageListResponse` with `images`, `next_cursor`, and `total`. An empty next cursor marks the last page. |
| `delete_media_image(*, image_id)` | Deletes the material, releases its quota, and returns `None`. |

`upload_media_image(...)` performs these steps:

1. Compute the byte length, MD5, and SHA1, then call prepare.
2. PUT the original bytes to `presigned_url` using the declared Content-Type.
3. Remove the quotes from the response ETag and pass it to complete with
   `upload_id`.

Given PNG bytes in `image_bytes`, upload and send the returned reference from
a running handler:

```python
from oibot.api.message import Markdown, Message


image = await event.bot.upload_media_image(
    data=image_bytes, file_name="image.png", content_type="image/png"
)
await event.reply(
    Message.markdown(
        Markdown.image(text="Image", url=image["url"], width=800, height=400)
    )
)
```

The returned `url` can be reused in later Markdown messages sent by the same
bot. `image_id` identifies the material for deletion; `ttl` is its sliding
lifetime in seconds. `preview_url` is a temporary preview link.

The `media(token)` helper in `oibot.api.message` constructs
`qqbot-media://image/v1/<token>` from an existing platform-issued token, alongside
the `at(...)` and `channel(...)` helpers. Pass only the token component to
`media(...)`. Upload responses already contain the complete reference in `url`,
which can be used directly. Keep `image_id` for management operations.

List all pages of materials:

```python
page = await event.bot.get_media_images()
images = page["images"]

while cursor := page["next_cursor"]:
    page = await event.bot.get_media_images(cursor=cursor)
    images.extend(page["images"])
```

Each image record includes `image_id`, `url`, `file_name`, `preview_url`,
`created_at`, and `expires_at`; the timestamps are Unix seconds. Delete a
material when it is no longer needed:

```python
await event.bot.delete_media_image(image_id=image["image_id"])
```

Platform limits apply to these methods:

- Images may be at most 10 MB, with `content_type` set to `image/png`,
  `image/jpeg`, `image/gif`, or `image/webp`. The file-name extension must match.
- Each bot can retain up to 100 images. References expire after 90 days without
  use; a successful message reference renews that window.
- Upload tasks last 4 hours; presigned URL lifetime is given by `expires_in`.
  Deleting a material invalidates future references while existing messages
  retain their images.

### Message recall and interactions

| Method | Behavior |
| --- | --- |
| `delete_user_message(*, openid, message_id)` | Recalls a C2C message. |
| `delete_group_message(*, group_openid, message_id)` | Recalls a group message. |
| `delete_channel_message(*, channel_id, message_id, hide_tip=False)` | Recalls a channel message, optionally hiding the recall notice. |
| `delete_dm_message(*, guild_id, message_id, hide_tip=False)` | Recalls a direct message in a guild context. |
| `acknowledge_interaction(*, interaction_id, code)` | Acknowledges an interaction result and returns `None`. |

Use the `Code` enum for interaction acknowledgement:
`SUCCESS`, `FAILURE`, `RATE_LIMIT_EXCEEDED`, `DUPLICATE_OPERATION`,
`PERMISSION_DENIED`, or `REQUIRES_ADMIN_PRIVILEGES`. An
`InteractionCreateEvent` also exposes `await event.acknowledge(code)`, which
returns `None`.

### Group management

| Method | Behavior and return value |
| --- | --- |
| `get_group_info(*, group_openid)` | Returns `GroupInformation` with the open ID, name, memo, class, tags, and member count. |
| `get_group_bot_state(*, group_openid)` | Returns `BotState` with the bot member ID, join time, proactive-message permission, receive setting, and member role. |
| `get_group_members(*, group_openid, cursor=None)` | Returns up to 30 `GroupMember` records and the next pagination cursor. |
| `get_group_member(*, group_openid, member_openid)` | Returns one `GroupMember` with its role, join time, bot flag, and optional union open ID. |
| `remove_group_members(*, group_openid, member_openids, add_to_member_blacklist=False)` | Removes up to 20 members and optionally adds them to the group blacklist. |
| `get_group_join_requests(*, group_openid, cursor=None, limit=None)` | Returns a cursor-based `JoinRequestListResponse`. |
| `review_group_join_request(*, group_openid, member_openid, op, join_request_id=None, reject_reason=None, add_to_member_blacklist=False)` | Approves or declines one request. `op` is `"approve"` or `"decline"`. |
| `get_group_member_blacklist(*, group_openid, cursor=None, limit=None)` | Lists blacklisted users and returns the next cursor; `limit` defaults to 20 and cannot exceed 100. |
| `update_group_member_blacklist(*, group_openid, op, member_openids)` | Adds or removes up to 20 users with `op="add"` or `"del"` and returns any failed open IDs. |
| `get_group_restrict_chat_setting(*, group_openid)` | Returns the global mute rule and current member mute states. |
| `set_group_restrict_chat_setting(*, group_openid, members=None)` | Applies member mute operations. Each `SetMemberMuteState` uses `op="add"`, `"update"`, or `"del"` plus `member_openid` and optional `mute_expire_at`. |

A group member includes its open ID, username, role, bot flag, join time, and an
optional union open ID. The QQ Bot platform currently exposes the five member
listing, lookup, removal, and blacklist methods above only to invited
applications.

A join request includes its request and member IDs, username, source and apply
time, risk information, optional inviter, bot flag, and optional verification
message or question-and-answer list. The corresponding
`GroupJoinRequestEvent` provides `approve()` and `decline(...)` shortcuts.

### Group join approval strategies

| Method | Behavior and return value |
| --- | --- |
| `get_group_join_approval_strategies(*, cursor=None, limit=None)` | Lists strategies and returns the next cursor. |
| `create_group_join_approval_strategy(*, group_openids=None, group_ids=None, is_enable=None, expire_at=None, remark=None)` | Creates a strategy and returns its ID, state, and expiry. |
| `update_group_join_approval_strategy(*, strategy_id, is_enable=None, expire_at=None, group_action=None, remark=None)` | Updates state, expiry, remark, or group assignments. |
| `delete_group_join_approval_strategy(*, strategy_id)` | Deletes a strategy. |
| `execute_group_join_approval_strategy(*, strategy_id)` | Executes a strategy immediately. |
| `update_group_join_approval_strategy_whitelist_users(*, strategy_id, op, whitelist_users)` | Adds or removes whitelist users and returns the new whitelist count. |

`group_action` is a `GroupJoinApprovalStrategyGroupAction` dictionary with
`op="add"` or `"del"` and optional `group_openids` or numeric `group_ids`.
Strategy state uses `"on"` or `"off"`.

### Bot information and guilds

| Method | Behavior and return value |
| --- | --- |
| `get_bot_information()` | Returns `BotInformation`: ID, username, avatar, bot flag, and optional union IDs, share URL, and welcome message. |
| `get_bot_guilds(*, before=None, after=None, limit=None)` | Returns guild records with ownership, membership, capacity, description, and join-time data. Use `before` or `after` for pagination. |
| `generate_url_link(*, callback_data=None)` | Returns `URLLinkResponse` with the generated share link in `response["data"]["url"]`. Optional `callback_data` supports up to 32 characters. |

```python
response = await bot.generate_url_link(callback_data="invite")
share_url = response["data"]["url"]
```

### Menus

| Method | Behavior and return value |
| --- | --- |
| `get_global_menu()` | Returns the current menu `version` and optional `menu`. |
| `update_global_menu(*, menu=None)` | Updates the global menu and returns its new `version`. |

A `Menu` contains an `items` list. Each item has a `name` and a `type` of
`"switch"`, `"send_message"`, `"link"`, or `"menu"`, plus the matching
`switch`, `send_message`, `link`, or `sub_menu_items` field. Top-level items may
also choose `align="left"` or `"right"`.

```python
from oibot.api.menu import Menu


menu: Menu = {
    "items": [
        {"name": "Help", "type": "send_message", "send_message": "/help"},
        {"name": "Project", "type": "link", "link": "https://example.com"},
    ]
}
await bot.update_global_menu(menu=menu)
```

### Panels

| Method | Behavior and return value |
| --- | --- |
| `get_panels(*, scope, cursor=None, limit=None)` | Lists panels in `"c2c"`, `"group"`, `"channel"`, or `"dm"` scope. |
| `create_panel(*, scope, panel, target_type=None, user_openids=None, group_openids=None)` | Creates a global or specifically targeted panel and returns `panel_id`. |
| `get_panel(*, panel_id)` | Returns panel details and any user or group targets. |
| `update_panel(*, panel_id, panel)` | Replaces panel content and returns the new `version`. |
| `delete_panel(*, panel_id)` | Deletes a panel. |
| `update_panel_target(*, panel_id, op, user_openids=None, group_openids=None)` | Adds or deletes specific targets with `op="add"` or `"del"`. |

A `Panel` contains `items` and optional `remark` and `version`. Each
`PanelItem` has a `name`, `type="command"` or `"link"`, and optional `desc`,
`only_admin`, and `link` fields. List responses contain `records`,
`next_cursor`, and `is_end`; each record includes scope, target type, timestamps,
and version.

### Access tokens and raw requests

| Method | Behavior |
| --- | --- |
| `get_app_access_token(app_id, app_secret)` | Calls the unauthenticated token endpoint and returns `{"access_token": str, "expires_in": str}`. |
| `get_access_token(app_id, app_secret)` | Returns the cached token or coalesces concurrent refreshes. The cache entry is removed 60 seconds before server-reported expiry. |
| `await bot(method, url, **request_options)` | Executes a request through the shared client. The middleware adds `Authorization: QQBot ...` when the URL host is `api.bot.qq.com`, except for `/app/getAppAccessToken`. |

COS uploads use the authorization embedded in their presigned URLs. The
middleware does not add the QQ Bot access token to those requests. Both rich
media and Markdown material uploads use this shared client behavior.

The client is configured with `raise_for_status=True`, so HTTP failures surface
as `aiohttp` exceptions. OiBot does not silently retry ordinary API calls.
Multipart part upload has timeout-bounded retries; WebSocket connection and
session recovery are managed separately by the transport.

### Events

`Event(bot, ctx)` dispatches an incoming payload to a registered structured
subclass. Every event exposes:

| Member | Behavior |
| --- | --- |
| `event.bot` | The owning `OiBot` and its complete API surface. |
| `event.ctx` | Original delivery envelope, including `d`, `id`, `op`, `s`, and `t`. |
| `event["id"]` and other envelope keys | Dictionary-style access to top-level delivery fields. |
| `event.some_payload_field` | Falls back to `ctx["d"]["some_payload_field"]` when no typed property exists. |
| `Event.dispatch(ctx)` | Returns the registered class for `ctx["t"]`, or base `Event` when the type is unknown. |

Import `Event` and `EventType` from `oibot.event`. Structured classes live in
their concrete modules:

| Event | Typed data and convenience operations |
| --- | --- |
| [`C2CMessageCreateEvent`](src/oibot/event/c2c_message_create.py) | `id`, `content`, `timestamp`, `author`, `attachments`, `message_scene`, `message_type`, and optional `ark_data`; supports `reply(str \| Message)` and `chat(...)`. |
| [`GroupAtMessageCreateEvent`](src/oibot/event/group_at_message_create.py) | At-mention message with `group_openid`, author, mentions, attachments, scene, type, optional Ark data, and recursively parsed `msg_elements`; supports `reply(...)` and `chat(...)`, including `quote=True`. |
| [`GroupMessageCreateEvent`](src/oibot/event/group_message_create.py) | Full group-message counterpart to `GroupAtMessageCreateEvent`, including nested message elements and the same conversation helpers. |
| [`InteractionCreateEvent`](src/oibot/event/interaction_create.py) | Typed interaction `type`, `scene`, `chat_type`, `timestamp`, and resolved data. `button_data` decodes callback JSON, `button_id` exposes its ID, and `acknowledge(code)` acknowledges the result. |
| `C2CInteractionCreateEvent` | Adds `user_openid` plus C2C `reply(...)` and `chat(...)`. |
| `GroupInteractionCreateEvent` | Adds `group_openid` and `group_member_openid` plus group `reply(...)` and `chat(...)`, without a `quote` parameter. |
| `GuildInteractionCreateEvent` | Adds `guild_id` and `channel_id` for guild-scene interactions. |
| [`GroupJoinRequestEvent`](src/oibot/event/group_join_request.py) | Request, group and member IDs, source, apply time, optional risk, inviter, verification, and automatic-strategy data; supports `approve()` and `decline(...)`. |
| [`FriendAddEvent`](src/oibot/event/friend_add.py) / [`FriendDelEvent`](src/oibot/event/friend_del.py) | Friend open ID, typed author and timestamp; add events can `reply(Message)`. |
| [`C2CMsgReceiveEvent`](src/oibot/event/c2c_msg_receive.py) / [`C2CMsgRejectEvent`](src/oibot/event/c2c_msg_reject.py) | C2C proactive-message permission state with open ID and timestamp; receive events can `reply(Message)`. |
| [`GroupAddRobotEvent`](src/oibot/event/group_add_robot.py) / [`GroupDelRobotEvent`](src/oibot/event/group_del_robot.py) | Group robot lifecycle, group and operator IDs, and timestamp; add events can `reply(Message)`. |
| [`GroupMemberAddEvent`](src/oibot/event/group_member_add.py) / [`GroupMemberRemoveEvent`](src/oibot/event/group_member_remove.py) | Group and member IDs plus timestamp; both can `reply(Message)`. |
| [`GroupMsgReceiveEvent`](src/oibot/event/group_msg_receive.py) / [`GroupMsgRejectEvent`](src/oibot/event/group_msg_reject.py) | Group proactive-message permission state, operator ID, and timestamp; both expose `reply(Message)`. |

Message-event authors, attachments, mentions, message scenes, Ark payloads, and
nested message elements are immutable dataclasses returned by cached
properties. `ArkData.ark_type` supports `"tuwen"`, `"feed"`, `"miniapp"`, `"map"`,
`"contact_card"`, `"video_share"`, `"music_together"`, and `"picture"` for C2C,
at-mention, and full-group-message events, including nested group message
elements. Interaction payloads use the same pattern. Lifecycle-event
`reply(...)` methods accept a built `Message`, while message and interaction
events additionally accept a plain string.

`EventType` names the wider QQ Bot event vocabulary. Event types without a
registered structured class deliberately remain base `Event` instances, so a
catch-all handler can observe protocol additions without breaking dispatch.

## Troubleshooting

- **A plugin is not loaded:** start the process from the directory containing
  the plugin package, keep `plugins/__init__.py`, do not prefix the module name
  with `_`, and make sure the module contains `@on(...)` or `init(app)`.
- **A handler never runs:** annotate its event parameter, import the concrete
  event class, and enable the matching event or WebSocket intent in the QQ Bot
  configuration.
- **A callback button never arrives over WebSocket:** include
  `Intents.INTERACTION`.
- **An API method has no client session:** call it from a running transport or
  inside `async with OiBot(...)`.
- **A dependency is not resolved:** declare it as a parameter default with
  `Dependency.from_provider(...)` and keep an event-typed parameter on the
  handler. Providers may additionally request the event by annotation.

Keep application credentials in environment variables or a secret manager; do
not commit them to source control. In production, expose Webhook endpoints over
HTTPS, normally through a reverse proxy. Never place the application secret in
the callback URL or its query parameters.
