Skip to main content

OiBot

OiBot is a lightweight, fully asynchronous QQ bot framework built on 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

  • 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:

python -m pip install --upgrade oibot

For a project managed by uv:

uv add oibot --frozen

Install the latest development version from GitHub:

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

Alternatively, install the branch archive:

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:

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

Start the bot

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:

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 |:

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:

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.

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:

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:

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:

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.

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(...) 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.

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:

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:

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:

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

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 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.

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

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 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 provides MaterialMixin, included in OiBot, for the platform's image material APIs.

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:

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:

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:

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.
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".

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 id, content, timestamp, author, attachments, message_scene, message_type, and optional ark_data; supports reply(str | Message) and chat(...).
GroupAtMessageCreateEvent 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 Full group-message counterpart to GroupAtMessageCreateEvent, including nested message elements and the same conversation helpers.
InteractionCreateEvent 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 Request, group and member IDs, source, apply time, optional risk, inviter, verification, and automatic-strategy data; supports approve() and decline(...).
FriendAddEvent / FriendDelEvent Friend open ID, typed author and timestamp; add events can reply(Message).
C2CMsgReceiveEvent / C2CMsgRejectEvent C2C proactive-message permission state with open ID and timestamp; receive events can reply(Message).
GroupAddRobotEvent / GroupDelRobotEvent Group robot lifecycle, group and operator IDs, and timestamp; add events can reply(Message).
GroupMemberAddEvent / GroupMemberRemoveEvent Group and member IDs plus timestamp; both can reply(Message).
GroupMsgReceiveEvent / GroupMsgRejectEvent 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.

Metadata

Release files for oibot 2026.11.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oibot 2026.11.17
File Size Uploaded Provenance Actions
oibot-2026.11.17.tar.gz 59.9 kB Without provenance Details for oibot-2026.11.17.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oibot 2026.11.17
File Interpreter ABI Platform Actions
oibot-2026.11.17-py3-none-any.whl Python 3 none any Details for oibot-2026.11.17-py3-none-any.whl

Total release size: 121.8 kB

Release files / oibot-2026.11.17.tar.gz

Download URL oibot-2026.11.17.tar.gz
Size 59.9 kB
Tags Source
SHA-256 checksum
How to use checksums
184f9196571ab6cab187b4f7f878ed2f6085ebfda56f1c1777d18a55ce571f1a
BLAKE2b-256 checksum
How to use checksums
b27989f2db6c2525f94f6f2ac11fb91e711c5ad77dc426d643f600901b5dfa51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / oibot-2026.11.17-py3-none-any.whl

Download URL oibot-2026.11.17-py3-none-any.whl
Size 61.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
735a99d13ed3e6ecad1cf50de3150deceb2bcec101402203ed6e7eecd94c7f38
BLAKE2b-256 checksum
How to use checksums
d869139880c2a55c32d5f980ed9f6241430bcbccddab9b64b5c8f2e645dff16f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for oibot 2026.11.17

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page