QQBot Platform Features Documentation
QQBotAdapter is an adapter built on the official QQ bot (QQ OpenAPI) protocol, integrating full-scenario features such as group chat, private chat, and guilds, and providing OneBot12 standard events, standard Api actions, and request action interfaces.
Document Information
- Corresponding module version: 5.3.3
- Maintainer: ErisPulse
- Last updated: 2026-11-10
Basic Information
- Platform introduction: Official QQ bot development interface, supporting group chat, private chat, guilds, and other scenarios
- Adapter name: QQBotAdapter
- Connection method: WebSocket long connection (default) or Webhook HTTP callback (per-account configuration, Ed25519 signature verification)
- Authentication: appId + clientSecret to obtain an access_token (valid 7200s, auto-refreshed 45s in advance)
- API base URL:
https://api.bot.qq.com(the official unified domain since v5; sandbox is deprecated) - OneBot12 compatibility: full coverage of message sending/receiving, events, standard Api actions, and request actions
- Multiple accounts: supported; any account under
accountsruns in parallel (websocket/webhook modes can be mixed)
Configuration
# config.toml
[QQBot_Adapter]
intents = "[0, 9, 12, 25, 26, 27]" # Global: event intents to subscribe to (JSON array, supports event names)
[QQBot_Adapter.accounts.default]
appid = "YOUR_APPID" # QQ bot application ID (required)
secret = "YOUR_CLIENT_SECRET" # QQ bot client secret (required)
mode = "websocket" # Event receiving method: websocket / webhook
bot_id = "" # Bot ID (leave empty to fetch automatically; can be filled manually for Using() targeting)
gateway_url = "" # WebSocket gateway URL (leave empty to fetch dynamically via /gateway/bot)
api_base_url = "https://api.bot.qq.com" # API base URL (customizable for proxying)
access_token_url = "" # Custom token endpoint (leave empty to use the official endpoint)
webhook_path = "/webhook" # Webhook callback path (effective when mode=webhook)
enabled = true
v5 breaking changes:
- The
sandboxfield is deprecated: the official unified domainapi.bot.qq.comis used; sandbox in old configs is automatically migrated and ignored (with a warning printed) - Old flat configuration (appid/secret written directly under
[QQBot_Adapter]) is automatically migrated toaccounts.default - The framework is a soft dependency: installing the adapter will not pull in a framework version; at runtime
ErisPulse>=2.7.1is detected and prompted
intents description (supports bit numbers or event names):
| Bit | Event Name | Description |
|---|---|---|
| 0 | GUILDS | Guild changes |
| 1 | GUILD_MEMBERS | Guild member changes |
| 9 | GUILD_MESSAGES | Guild messages (private domain requires review) |
| 10 | GUILD_MESSAGE_REACTIONS | Guild message reactions |
| 12 | DIRECT_MESSAGE | Guild direct messages |
| 24 | GROUP_MEMBER | Group member changes (new in v5) |
| 25 | GROUP_AND_C2C_EVENT | Group @ messages and private chat messages |
| 26 | INTERACTION | Interaction events (buttons, etc.) |
| 27 | MESSAGE_AUDIT | Message audit events |
| 28 | FORUMS_EVENT | Forum events (private domain only) |
| 29 | AUDIO_ACTION | Audio operations |
| 30 | PUBLIC_GUILD_MESSAGES | Guild messages (public domain) |
# The two forms are equivalent
intents = "[0, 9, 12, 25, 26, 27]"
intents = '["GUILDS", "GUILD_MESSAGES", "DIRECT_MESSAGE", "GROUP_AND_C2C_EVENT", "INTERACTION", "MESSAGE_AUDIT"]'
Standardization Alignment
This section describes the adapter's behaviors aligned with the ErisPulse standardization specifications. For specification details, see the SDK documentation "Request Action Specification" (docs/en/standards/request-action-spec.md) and "API Response Specification" (docs/en/standards/api-response.md).
Error Code Normalization (5.3.x)
- Platform errors unified to 34100: when the official QQ API returns an error,
retcode=34100is returned, and the original response (including the officialcode/message) is preserved in theqqbot_rawfield (media upload failures also use 34100) - Timeout 33001: API call timeouts return
retcode=33001(the former 32000 is no longer used) - Missing recall context 10003:
delete_messagereturnsretcode=10003(parameter error) when the context owning the message cannot be found - Request family reserved 34001/34003:
34001is returned when a request does not exist or has expired;34003is returned when the request context lacks routing parameters
| retcode | Description |
|---|---|
| 0 | Success |
| 10001 | Missing parameters / empty endpoint |
| 10002 | Unsupported action |
| 10003 | Unable to determine send target/account, missing recall context, and other parameter errors |
| 33000 | Network/API call exception |
| 33001 | Request timeout |
| 34001 | Request does not exist or has expired (Request DSL) |
| 34003 | Request context lacks routing parameters (Request DSL) |
| 34100 | Platform business error (original response and official code preserved in qqbot_raw) |
Notification Event Naming (5.3.x)
Friend add/remove notification events are unified to standard naming:
| Official Event | Converted detail_type | Description |
|---|---|---|
| FRIEND_ADD | friend_increase |
Friend added (the former friend_add is deprecated) |
| FRIEND_DEL | friend_decrease |
Friend removed (the former friend_del is deprecated) |
Request Context Retention (since 5.3.2)
The group join request event entry maps request_id to the application context (group/applicant openid) and caches it (TTL 3600 seconds, cap of 512 entries, cleaned up after the request is processed successfully); when performing approval, it routes to POST /v2/groups/{group_openid}/approval_join_request/{member_openid}.
Extended Action Routing (5.3.x)
Guild member permission queries are provided through extended actions with the platform prefix:
result = await qqbot.Api.call("qqbot.get_channel_member_permissions", channel_id="...", member_id="...")
Stream Send Reads send_context
Streaming messages (.Stream()) read send_context: within an event chain, the account from the current event source is used automatically; an account explicitly specified via Using() takes priority.
Message Sending
Basic Sending
from ErisPulse import sdk
qqbot = sdk.adapter.get("qqbot")
# Send text
await qqbot.Send.To("user", user_openid).Text("Hello World!")
# Group @ message (automatically uses the <qqbot-at-user id="x" /> format)
await qqbot.Send.To("group", group_openid).At("member_openid").Text("@you")
await qqbot.Send.To("group", group_openid).AtAll().Text("Announcement")
# Guild channel message (@ automatically uses the <@user_id> format)
await qqbot.Send.To("channel", channel_id).Text("Guild channel message")
# Guild direct message (create the session first)
dms = await qqbot.create_dms(user_id, source_guild_id)
await qqbot.Send.To("dms", dms["data"]["guild_id"]).Text("Direct message")
# Reply to a message (passive reply, automatically carries msg_id)
await qqbot.Send.To("group", group_openid).Reply(msg_id).Text("Reply content")
# Multiple accounts (Using/Account specifies account name or bot_id)
await qqbot.Send.Using("account2").To("group", group_openid).Text("From the second bot")
Rich Media
# URL / local path / binary three-form support; automatic chunked upload for files over 5MB
await qqbot.Send.To("group", gid).Image("https://example.com/img.png")
await qqbot.Send.To("user", uid).Image("/path/to/local.png")
await qqbot.Send.To("user", uid).Voice(open("audio.mp3", "rb").read())
await qqbot.Send.To("user", uid).Video("https://example.com/v.mp4")
await qqbot.Send.To("user", uid).File(b"...", filename="doc.pdf")
# Guild channel images go through multipart direct upload (file_image)
await qqbot.Send.To("channel", cid).Image(open("img.png", "rb").read())
file_type mapping: image=1, video=2, voice=3, file=4 (determined automatically by message segment type; file segments are inferred by file extension).
Markdown / Ark / Embed / Keyboard
# Native Markdown
await qqbot.Send.To("group", gid).Markdown("# Title\n- List item")
# Template Markdown
await qqbot.Send.To("user", uid).Markdown(template_id=1, kv=[{"key": "title", "value": "Notification"}])
await qqbot.Send.To("user", uid).Markdown(custom_template_id="23456", kv=[...])
# Ark template
await qqbot.Send.To("user", uid).Ark(23, [{"key": "a", "value": "b"}])
# Embed (guild channels/guild DMs only)
await qqbot.Send.To("channel", cid).Embed({"title": "Title", "content": "Content"})
# Keyboard (automatically set to the markdown type with bot_appid attached)
keyboard = {"content": {"rows": [[{"label": "Confirm", "type": 2, "data": "ok"}]]}}
await qqbot.Send.To("group", gid).Keyboard(keyboard).Text("Please choose")
# Merged forward (the official md has no collapse syntax, rendered as a quoted list; requires native Markdown permission, automatically falls back to plain text on failure)
await qqbot.Send.To("group", gid).MergeForward(nodes)
Streaming Messages (new in v5, C2C only)
# One-shot streaming send (input_state=10 completes directly)
await qqbot.Send.To("user", openid).Stream("Answer content")
# Multi-turn append streaming
r = await qqbot.stream_message(openid, "First segment", input_state=1, msg_id=passive_msg_id)
stream_id = r["data"]["id"]
r = await qqbot.stream_message(openid, "Second segment", stream_msg_id=stream_id, index=1, input_state=1)
r = await qqbot.stream_message(openid, "Final segment", stream_msg_id=stream_id, index=2, input_state=10)
Message Recall
# Standard Api action: automatically routes to the corresponding recall endpoint based on the message source (group/private chat/guild channel/DM)
await qqbot.Api.delete_message(message_id)
The adapter automatically registers the owning target of sent/received messages, so no manual passing of group_id/channel_id is needed; retcode=10003 is returned when the context is missing.
OneBot12 Standard Api Actions (new in v5)
# Bot information
result = await qqbot.Api.get_self_info()
# Group management
result = await qqbot.Api.get_group_info(group_openid) # {group_id, group_name}
result = await qqbot.Api.get_group_member_list(group_openid) # automatic paginated aggregation
result = await qqbot.Api.get_group_member_info(group_openid, member_openid)
# Guild channels
result = await qqbot.Api.get_guild_list()
result = await qqbot.Api.get_guild_info(guild_id)
result = await qqbot.Api.get_guild_member_list(guild_id)
result = await qqbot.Api.get_channel_list(guild_id)
result = await qqbot.Api.get_channel_info(guild_id, channel_id)
await qqbot.Api.set_channel_name(guild_id, channel_id, "New name")
await qqbot.Api.leave_channel(guild_id, channel_id) # delete sub-channel
# Meta actions
result = await qqbot.Api.get_status() # {"good": bool, "bots": [...]}
result = await qqbot.Api.get_version() # {"impl": "ErisPulse-QQBotAdapter", "onebot_version": "12"}
# Multiple accounts
result = await qqbot.Api.Using("account2").get_self_info()
Supported standard actions: get_self_info / get_group_info / get_group_member_info / get_group_member_list / get_guild_info / get_guild_list / get_guild_member_info / get_guild_member_list / get_channel_info / get_channel_list / set_channel_name / leave_channel / delete_message / get_status / get_version / get_supported_actions. Unsupported actions return retcode=10002 (e.g., get_friend_list, as the official QQ API has no corresponding endpoint).
Request Actions (Request DSL, new in v5)
The GROUP_JOIN_REQUEST (group join request) event is converted into a one-to-one interactive request event, supporting standardized approval:
from ErisPulse.Core.Event import request as request_event
@request_event.on_request()
async def handle_join_request(event):
if event.get("platform") != "qqbot":
return
# Auto-approve
result = await event.approve()
# Or reject: await event.reject(comment="Does not meet the requirements")
# Or specify an account: await qqbot.Request(event["request_id"]).Using("account2").accept()
request_id= officialjoin_request_id- The adapter automatically caches the application context (group/applicant openid), routing to
POST /v2/groups/{group_openid}/approval_join_request/{member_openid}when executing - Rejection can include
reject_reason;retcode=34001is returned when the context has expired
You can also call the platform methods directly:
await qqbot.approve_group_join(group_openid, member_openid, join_request_id, approve=True)
await qqbot.approve_group_join(group_openid, member_openid, approve=False, reject_reason="Reason")
Platform Native API Method Family
The adapter exposes the full official QQ API (the first parameter is mostly the target ID; account_id optionally specifies an account):
Bot / Interaction
get_me(), reply_interaction(interaction_id, code=0)
Guild
get_guilds(), get_guild(guild_id), mute_guild_all(guild_id, mute_seconds),
get_guild_roles / create_guild_role / update_guild_role / delete_guild_role,
get_guild_api_permission, demand_guild_api_permission(guild_id, channel_id, path, method, desc)
Sub-channel (Channel)
get_channels, get_channel, create_channel(guild_id, name, type=0, ...), update_channel(channel_id, name=..., ...), delete_channel,
get_channel_pins, pin_message, unpin_message
Guild Members
get_guild_members, get_guild_member, mute_guild_members (batch/whole guild), mute_guild_member,
add_guild_member_role / remove_guild_member_role, kick_guild_member
Permissions / Announcements / Reactions
get_channel_role_permissions, update_channel_role_permissions, get_channel_member_permissions (extended action qqbot.get_channel_member_permissions), update_channel_member_permissions, create_announce,
add_reaction, delete_reaction, get_reaction_users
Schedules / Threads / Audio
get_schedules, get_schedule, create_schedule, update_schedule, delete_schedule,
get_threads, get_thread, publish_thread(channel_id, title, content, format=3), delete_thread,
control_audio(channel_id, audio_url, text, status), mic_online, mic_offline
Group Management (v2, some endpoints are only available to whitelisted bots)
await qqbot.get_group_info_raw(group_openid) # Group information
await qqbot.get_group_bot_state(group_openid) # Bot's state in the group
await qqbot.get_group_members(group_openid) # Member list (with next_cursor)
await qqbot.get_group_member(group_openid, member_openid)
await qqbot.batch_remove_group_members(group_openid, [member_openid], add_to_blacklist=False)
await qqbot.get_group_member_blacklist(group_openid)
await qqbot.update_group_member_blacklist(group_openid, "add", [member_openid])
await qqbot.get_group_join_requests(group_openid) # Group join request list
await qqbot.approve_group_join(...) # Approve group join requests
await qqbot.get_group_restrict_setting(group_openid) # Mute settings
await qqbot.set_group_restrict(group_openid, [{"op": "add", "member_openid": "...", "mute_expire_at": 123}])
# Group join approval strategies
await qqbot.get_join_approval_strategies()
await qqbot.create_join_approval_strategy(strategy_dict)
await qqbot.update_join_approval_strategy(strategy_id, **fields)
await qqbot.delete_join_approval_strategy(strategy_id)
await qqbot.execute_join_approval_strategy(strategy_id)
await qqbot.update_join_approval_strategy_whitelist(strategy_id, "add", [user_ids])
Custom Menu / Command Panel (new in v5)
# Global custom menu (effective for C2C only; up to 5 sub-menu items, non-nestable)
menu_items = [
{"type": "send_message", "content": {"label": "Help", "content": "/help"}},
{"type": "link", "content": {"label": "Official website", "content": "https://example.com"}},
]
await qqbot.update_custom_menu(menu_items)
result = await qqbot.get_custom_menu()
# Command panel (scope: c2c/group/channel/dm; up to 20 per bot)
await qqbot.create_command_panel("c2c", [
{"type": "command", "content": {"label": "Weather query", "content": "/weather"}},
{"type": "link", "content": {"label": "More", "content": "https://example.com"}},
], remark="Panel remark", target_type="all")
await qqbot.get_command_panels("c2c")
await qqbot.get_command_panel(panel_id)
await qqbot.update_command_panel(panel_id, items)
await qqbot.delete_command_panel(panel_id)
await qqbot.update_command_panel_targets(panel_id, "add", user_openids=[...])
WebSocket Connection
Connection Flow
- Obtain an access_token with appId + clientSecret (
POST https://bots.qq.com/app/getAppAccessToken) - Dynamically obtain the gateway URL via
GET /gateway/bot(used directly whengateway_urlis configured) - Receive OP_HELLO (op=10) and get the heartbeat interval
- Send OP_IDENTIFY (op=2) for authentication (intents support bitwise combination)
- Receive READY, obtain session_id and bot_id, and send the connect meta event
- Heartbeat loop (op=1) and event dispatch (op=0)
Disconnection and Reconnection
- Maximum 50 reconnect attempts with exponential backoff
min(5 * 2^n, 300)seconds - On OP_RECONNECT (op=7) the session is retained (Resume); on OP_INVALID_SESSION (op=9) re-Identify
- The reconnect counter is reset automatically when send/receive work normally
Token Management
- The access_token is valid for 7200 seconds and is auto-refreshed 45 seconds in advance (lazily checked at request time)
- Refresh failures are automatically retried 3 times (with increasing delay)
- Request headers:
Authorization: QQBot {token}+X-Union-Appid: {appid}(new in v5)
Webhook Integration (new in v5)
Set the account's mode to webhook to switch to HTTP callback for receiving events:
[QQBot_Adapter.accounts.mybot]
appid = "..."
secret = "..."
mode = "webhook"
webhook_path = "/webhook" # multiple webhook accounts automatically append the account name to avoid conflicts
- The adapter registers HTTP routes via the ErisPulse router; the startup log outputs the full callback URL
- Ed25519 signature verification: seed = the secret cyclically padded to 32 bytes; verifies the
X-Signature-Ed25519signature overX-Signature-Timestamp + body - Automatically handles the op=13 signature verification handshake (callback URL configuration validation) and op=0 event dispatch
- Depends on the
cryptographylibrary (installed together with the adapter)
Event Subscription and the openid System
- QQBot uses the openid system rather than QQ numbers; user/group identifiers are all openid strings
- Group messages are only received by default when a user @-mentions the bot (
GROUP_AT_MESSAGE_CREATE) - Receiving all group messages: the corresponding permission must be enabled in the bot management console on the QQ Open Platform (there is no API to set it); once enabled, non-@ group messages are pushed as
GROUP_MESSAGE_CREATE, and the adapter fully supports the conversion (markedqqbot_is_at_message=false; if the message contains an @-bot marker, it is automatically recognized as an @ message) - @ detection: QQ carries "being @" through the event name, and the @ marker in group messages is
<@{group openid}>(an id system different from the READY bot_id). The adapter automatically parses both marker styles and injects/normalizes the bot mention segment, ensuringon_at_message()/is_at_message()work; it also automatically learns the bot's openid in each group, so @ messages withinGROUP_MESSAGE_CREATEunder the "receive all group messages" mode can also be recognized (the original openid is preserved in the mention segment'sdata.qqbot_openid) - Passive replies: group/private chat messages must carry
msg_idorevent_id, which the adapter automatically caches and attaches event_idcannot be mixed with rich media (official limitation); the adapter handles this with automatic degradation- Sending may trigger an audit; the result is notified via the
qqbot_audit_pass/qqbot_audit_rejectevents - Call
shutdown()on program exit to release resources
Usage Examples
Handling Group Messages (@ detection)
from ErisPulse.Core.Event import message
@message.on_at_message()
async def handle_at(event):
if event.get("platform") != "qqbot":
return
text = event.get_text()
if text == "check-in":
await event.reply("Checked in")
Handling Button Interactions
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_interaction(event):
if event.get("detail_type") != "qqbot_interaction":
return
button_id = event.get("qqbot_button_id")
await qqbot.reply_interaction(event.get("qqbot_interaction_id"), code=0)
if button_id == "confirm":
await qqbot.Send.To("group", event.get("group_id")).Text("Confirmed")
Multiple Account Startup
[QQBot_Adapter.accounts.bot_a]
appid = "A_APPID"
secret = "..."
enabled = true
[QQBot_Adapter.accounts.bot_b]
appid = "B_APPID"
secret = "..."
mode = "webhook"
enabled = true
Both accounts start in parallel: bot_a uses WebSocket and bot_b uses Webhook, without affecting each other.