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
- Requirements
- Installation
- Quick start
- WebSocket transport
- Framework design
- Dependency injection
- Messages and conversations
- Calling APIs directly
- API reference
- Troubleshooting
Highlights
- Webhook and WebSocket transports share one
aiohttpapplication 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=Falseinjects 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:
- Compute the byte length, MD5, and SHA1, then call prepare.
- PUT the original bytes to
presigned_urlusing the declared Content-Type. - 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_typeset toimage/png,image/jpeg,image/gif, orimage/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(...)orinit(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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.