OneBot11 Platform Feature Documentation
OneBot11Adapter is an adapter built based on the OneBot V11 protocol.
Document Information
- Corresponding Module Version: 4.6.2
- Maintainer: ErisPulse
- Last Updated: 2026-11-10
Basic Information
- Platform Overview: OneBot is a standard for chatbot application interfaces
- Adapter Name: OneBotAdapter
- Supported Protocol/API Version: OneBot V11
- Multi-Account Support: Default multi-account architecture, supports simultaneous configuration and operation of multiple OneBot accounts
- Configuration Key Name:
OneBotAdapter
v5 Paradigm Update (from 4.3.0)
This adapter has completed alignment with the v5 paradigm (incremental upgrade, API compatible):
- BaseConverter Inheritance: Common fields of converters (id/time/platform/self/raw) are built by the framework build_base_event, and are overridden by OB11 field names (echo/time/self_id)
- spawn_background Task Ownership: Client mode connection tasks are changed to use Runtime.spawn_background (owner ownership, automatic shutdown recovery)
- Framework Soft Dependency: Installing the adapter no longer declares a hard dependency on ErisPulse, avoiding pip parsing to adjust the framework version; runtime detection of ErisPulse>=2.7.1 and logging a warning when the version is too low
- Startup Version Log: Outputs OneBotAdapter vX.Y.Z loaded during initialization
Existing capabilities (supported since 4.2.0): Multi-account, standard action mapping of Api DSL (get_self_info→get_login_info, etc.), Request DSL (friend/group request approval: event.approve() / event.reject()), EventMixin, i18n.
Since 4.3.1, request event handling is implemented according to the specification, see the following Standardization Alignment section.
Standard API Actions (Api DSL)
The adapter automatically maps OneBot12 standard action names to OB11 action names, allowing modules to call them uniformly across platforms:
| OB12 Standard Action | OB11 Action | Description |
|---|---|---|
| get_self_info | get_login_info | Standardized fields: user_id/user_name/user_displayname |
| get_user_info | get_stranger_info | Standardized fields |
| delete_message | delete_msg | Recall message |
| leave_group | set_group_leave | Leave group |
| get_friend_list | get_friend_list | Action name consistent, default pass-through |
| get_group_info | get_group_info | Action name consistent, default pass-through |
| upload_file | upload_group_file / upload_private_file | Extended group_id/user_id optional parameters, filetype automatically detects type routing |
Basic Usage
from ErisPulse import sdk
onebot = sdk.adapter.get("onebot11")
# Get bot information
result = await onebot.Api.get_self_info()
print(result["data"]["user_id"], result["data"]["user_name"])
# Recall message
await onebot.Api.delete_message(message_id=123456)
# Upload group file (filetype automatically detects type routing to upload_group_file)
result = await onebot.Api.upload_file(group_id=123456, file="/path/to/file.zip")
# Specify account (multi-account)
result = await onebot.Api.Using("main").get_self_info()
# Unmapped OB11 actions are called via the call() escape hatch (NapCat/Lagrange common extensions)
result = await onebot.Api.call("send_poke", group_id=123, user_id=456)
OB11 Protocol Extensions (NapCat/go-cqhttp/SnowLuma Common)
Frequently used extension actions have been encapsulated into typed methods (OB11ExtensionApi mixin), supporting IDE completion:
await onebot.Api.send_poke(user_id=789, group_id=123456)
await onebot.Api.set_msg_emoji_like(message_id=123, emoji_id="76")
await onebot.Api.mark_msg_as_read(group_id=123456)
result = await onebot.Api.get_group_msg_history(group_id=123456, count=20)
await onebot.Api.set_essence_msg(message_id=123)
result = await onebot.Api.ocr_image(image="https://example.com/img.png")
Extension actions use OB11 action names directly, without platform prefixes. Actions that are not encapsulated are called using
Api.call("action_name", ...).
Send Query Methods (Deprecated)
The following Send methods are still available but marked as deprecated, it is recommended to use Api DSL instead:
| Send Method (Deprecated) | Api DSL Alternative |
|---|---|
Send.GetLoginInfo() |
Api.get_self_info() |
Send.GetFriendList() |
Api.get_friend_list() |
Send.GetGroupInfo() |
Api.get_group_info(group_id) |
Send.GetGroupList() |
Api.get_group_list() |
Send.GetGroupMemberInfo(uid) |
Api.get_group_member_info(gid, uid) |
Send.GetGroupMemberList() |
Api.get_group_member_list(gid) |
Send.GetMsg(mid) |
Api.call("get_msg", message_id=mid) |
Send.GetForwardMsg(id) |
Api.call("get_forward_msg", id=id) |
Standardization Alignment
This section explains the adapter's alignment with ErisPulse standardization specifications. For specification details, refer to the SDK documentation "Request Operation Specification" (docs/en/standards/request-action-spec.md) and "API Response Specification" (docs/en/standards/api-response.md).
Request Event Handling (from 4.3.1)
The adapter implements request event handling according to the request operation specification:
- Context Retention: The event entry maps
request_idto{request_type, sub_type, group_id, account, ts}and caches it (TTL 3600 seconds, maximum 512 entries, cleared after successful request processing), for subsequentaccept()/reject()routing - Endpoint Routing Priority:
accept()/reject()kwargs explicitly passed parameters (request_type/sub_type/group_idas reserved names) > event retained context > fallback friend endpoint (set_friend_add_request) and outputs WARNING - Group Invitation/Join Request: When
request_type == "group", correctly routes toset_group_add_request(add groupsub_type="add", invitesub_type="invite") - Deprecation Notice: The method of specifying request type via private parameter
_request_typebefore 4.3.1 is deprecated and will be ignored if passed
call_api Error Handling
- When the account is not connected or the connection is closed,
call_apino longer throwsConnectionError, but returns a standard failure response (status="failed",retcode=33001) - API call timeout also returns a standard failure response (
retcode=33001)
Account Field Dual Compatibility
call_apiaccepts both standard fieldaccount_idand old field name_account_id(standard name takes precedence); framework ApiDSL automatically adapts, module code is recommended to useaccount_id- Send DSL all methods read
send_context: automatically uses the current event source account within the event chain, explicitly specifiedUsing()account takes precedence
Error Code Specification
| retcode | Meaning | Triggered Scenario |
|---|---|---|
| 0 | Success | Action executed successfully |
| 33001 | Network Error | Account not connected, connection closed, API call timeout |
| 10002 | Unsupported Action | Called an unimplemented action |
| 10003 | Parameter Error | Missing required parameters |
Platform raw response data is retained in the
onebot11_rawfield.
Supported Message Sending Types
All send methods are implemented through chain syntax, for example:
from ErisPulse.Core import adapter
onebot = adapter.get("onebot11")
# Send using the default account
await onebot.Send.To("group", group_id).Text("Hello World!")
# Send using a specific account
await onebot.Send.Using("main").To("group", group_id).Text("Message from main account")
# Chain modifiers: @user + reply
await onebot.Send.To("group", group_id).At(123456).Reply(msg_id).Text("Reply message")
# @all members
await onebot.Send.To("group", group_id).AtAll().Text("Announcement message")
Basic Send Methods
.Text(text: str): Send plain text message..Image(file: Union[str, bytes], filename: str = "image.png"): Send image (supports URL, Base64, or bytes)..Voice(file: Union[str, bytes], filename: str = "voice.amr"): Send voice message..Video(file: Union[str, bytes], filename: str = "video.mp4"): Send video message..Face(id: Union[str, int]): Send QQ emoticon..File(file: Union[str, bytes], filename: str = "file.dat"): Send file (auto-detects type)..Raw_ob12(message: List[Dict], **kwargs): Send OneBot12 formatted message (auto-converts to OB11)..Recall(message_id: Union[str, int]): Recall message.
Group Operation Methods
The following methods must specify the target group via To("group", group_id) and execute operations within the group context:
.Kick(user_id, reject_add_request=False): Kick group member..Ban(user_id, duration=1800): Mute group member (in seconds), 0 means unmute..WholeBan(enable=True): Enable/disable group-wide mute..SetAdmin(user_id, enable=True): Set/unset group admin..SetCard(user_id, card=""): Set group nickname..SetGroupName(name): Modify group name..Leave(is_dismiss=False): Leave group (group owner can dismiss)..SetTitle(user_id, title=""): Set group title..SetPortrait(file): Set group portrait.
Query Methods
.GetMsg(message_id): Get message content..GetForwardMsg(id): Get forwarded message..GetLoginInfo(): Get current login account information..GetFriendList(): Get friend list..GetGroupInfo(): Get group information (requiresTo("group", group_id))..GetGroupList(): Get group list..GetGroupMemberInfo(user_id): Get group member information (requiresTo("group", group_id))..GetGroupMemberList(): Get group member list (requiresTo("group", group_id)).
Friend Operation Methods
.Like(user_id, times=1): Send friend like (maximum 10 times).
Chain Modifier Methods (can be combined)
Chain modifier methods return self, supporting chained calls, must be called before the final send method:
.At(user_id: Union[str, int], name: str = None): @ specified user (can be called multiple times)..AtAll(): @ all members..Reply(message_id: Union[str, int]): Reply to specified message.
Chained Call Examples
# Basic send
await onebot.Send.To("group", 123456).Text("Hello")
# @ single user
await onebot.Send.To("group", 123456).At(789012).Text("Hello")
# @ multiple users
await onebot.Send.To("group", 123456).At(111).At(222).At(333).Text("Hello everyone")
# Send OneBot12 formatted message
ob12_msg = [{"type": "text", "data": {"text": "Hello"}}]
await onebot.Send.To("group", 123456).Raw_ob12(ob12_msg)
# Like
await onebot.Send.Like(123456, times=10)
# Mute group member
await onebot.Send.To("group", 123456).Ban(789012, duration=3600)
# Unmute
await onebot.Send.To("group", 123456).Ban(789012, duration=0)
# Kick member
await onebot.Send.To("group", 123456).Kick(789012)
# Set group admin
await onebot.Send.To("group", 123456).SetAdmin(789012)
# Modify group name
await onebot.Send.To("group", 123456).SetGroupName("New group name")
# Get group info
result = await onebot.Send.To("group", 123456).GetGroupInfo()
# Specify account operation
await onebot.Send.Using("main").To("group", 123456).Ban(789012)
Handling Unsupported Types
If an undefined send method is called, the adapter returns a text prompt:
# Call an undefined method
await onebot.Send.To("group", 123456).SomeUnsupportedMethod(arg1, arg2)
# Actually sends: "[Unsupported send type] Method name: SomeUnsupportedMethod, Parameters: [...]"
Request Operations (Request DSL)
The adapter provides a request operation DSL for handling friend and group requests (add group/invite) approval/rejection operations.
Event Shortcut Methods
Request events support event.approve() and event.reject() shortcut methods, which internally automatically call the Request DSL:
from ErisPulse.Core.Event import request
@request.on_friend_request()
async def handle_friend_request(event):
comment = event.get("comment", "")
if comment == "passphrase":
await event.approve()
else:
await event.reject()
@request.on_group_request()
async def handle_group_request(event):
group_id = event.get("group_id")
await event.approve()
Manually Calling Request DSL
# Approve request
await onebot.Request("flag_string").accept()
# Reject request
await onebot.Request("flag_string").reject()
# Specify account operation
await onebot.Request("flag_string").Using("main").accept()
Complete Example
from ErisPulse.Core.Event import request
@request.on_friend_request()
async def handle_friend_request(event):
comment = event.get("comment", "")
# Method 1: Use Event shortcut method
if comment == "passphrase":
await event.approve()
else:
await event.reject()
# Method 2: Use Request DSL
flag = event.get("flag")
if comment == "passphrase":
await onebot.Request(flag).accept()
else:
await onebot.Request(flag).reject()
Request Operation Return Value
{
"status": "ok",
"retcode": 0,
"data": {...},
"message_id": "",
"message": ""
}
Event Type Mapping
Standard OB12 Mapping
| OB11 Original Type | Converted detail_type | Description |
|---|---|---|
| message_type: private | private |
Private chat message |
| message_type: group | group |
Group chat message |
| request_type: friend | friend |
Friend request |
| request_type: group | group |
Group request |
| meta_event_type: heartbeat | heartbeat |
Heartbeat |
| notice_type: group_upload | group_file_upload |
Group file upload |
| notice_type: group_admin | group_admin_change |
Group admin change |
| notice_type: group_increase | group_member_increase |
Group member increase |
| notice_type: group_decrease | group_member_decrease |
Group member decrease |
| notice_type: group_ban | group_ban |
Group mute |
| notice_type: friend_add | friend_increase |
Friend add |
| notice_type: friend_delete | friend_decrease |
Friend delete |
| notice_type: group_recall / friend_recall | message_recall |
Message recall |
Platform-Specific Events (onebot11_ prefix)
| OB11 Original Type | Converted detail_type | Description |
|---|---|---|
| meta_event_type: lifecycle | onebot11_lifecycle |
OneBot implementation lifecycle |
| notify + sub_type: honor | onebot11_honor |
Group honor change |
| notify + sub_type: poke | onebot11_poke |
Poke |
| notify + sub_type: lucky_king | onebot11_lucky_king |
Group red envelope lucky king |
| CQ code unknown type | Message segment onebot11_{type} |
Unrecognized CQ code |
Event Examples
// Friend request
{
"type": "request",
"detail_type": "friend",
"user_id": "789012",
"comment": "Please add friend",
"request_id": "flag_abc123",
"flag": "flag_abc123"
}
// Heartbeat
{
"type": "meta_event",
"detail_type": "heartbeat",
"interval": 5000,
"status": {...}
}
// Lifecycle (platform-specific)
{
"type": "meta_event",
"detail_type": "onebot11_lifecycle",
"sub_type": "enable"
}
// Poke (platform-specific)
{
"type": "notice",
"detail_type": "onebot11_poke",
"group_id": "123456",
"user_id": "789012",
"target_id": "345678"
}
// Group red envelope lucky king (platform-specific)
{
"type": "notice",
"detail_type": "onebot11_lucky_king",
"group_id": "123456",
"user_id": "789012",
"target_id": "345678"
}
// Honor change (platform-specific)
{
"type": "notice",
"detail_type": "onebot11_honor",
"group_id": "123456",
"user_id": "789012",
"honor_type": "talkative"
}
// CQ code extension message segment
{
"type": "message",
"message": [
{"type": "onebot11_shake", "data": {}}
]
}
Extension Field Explanation
- All specific fields are prefixed with
onebot11_ - Original event data is retained in the
onebot11_rawfield - Original event type is retained in the
onebot11_raw_typefield - Message content CQ codes are converted to corresponding message segments (standard types without prefix, unknown types with
onebot11_prefix) - Reply messages add
replytype message segments - @ messages add
mentiontype message segments
Event Extension Methods
The OneBot11 adapter registers the following platform-specific methods for event objects, which can be directly called in event handlers:
from ErisPulse.Core.Event import message
@message.on_message()
async def handle_message(event):
raw_event = event.get_raw_event()
raw_self_id = event.get_raw_self_id()
sender_info = event.get_sender_info()
sender_role = event.get_sender_role()
Method List
| Method | Return Type | Description |
|---|---|---|
get_raw_event() |
dict |
Get complete raw OneBot11 event data |
get_raw_self_id() |
str |
Get original self_id (Bot's QQ number) |
get_sender_info() |
dict |
Get complete sender information (including nickname, role, level, etc.) |
get_sender_role() |
str |
Get sender's role in the group (owner/admin/member) |
get_sender_level() |
int |
Get sender's level |
get_sender_title() |
str |
Get sender's group title |
is_system_message() |
bool |
Determine if it is a system message (sub_type == "system") |
Usage Example
from ErisPulse.Core.Event import message, command
@message.on_group_message()
async def handle_group(event):
role = event.get_sender_role()
if role == "admin" or role == "owner":
await event.reply("Hello admin!")
title = event.get_sender_title()
if title:
await event.reply(f"Your title is: {title}")
@command("whoami")
async def whoami(event):
info = event.get_sender_info()
nickname = info.get("nickname", "unknown")
level = event.get_sender_level()
await event.reply(f"Nickname: {nickname}, Level: {level}")
Configuration Options
The OneBot11 adapter uses a multi-account architecture, with each account configured independently. The configuration key name is OneBotAdapter.
Account Configuration Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
bot_id |
str |
Yes | "" |
Bot's QQ number, used to identify the account |
mode |
str |
No | "server" |
Operation mode: "server" (passive listening) or "client" (active connection) |
url |
str |
No | "ws://127.0.0.1:3001" |
WebSocket address for Client mode |
token |
str |
No | "" |
Authentication token (Client mode connection token / Server mode verification token) |
server_path |
str |
No | "/" |
WebSocket path for Server mode |
enabled |
bool |
No | true |
Whether to enable this account |
name |
str |
No | "" |
Account comment name |
Built-in Default Values
- Reconnection interval: 30 seconds
- API call timeout: 30 seconds
Configuration Example
[OneBotAdapter.accounts.main]
bot_id = "123456789"
mode = "server"
server_path = "/onebot-main"
token = "main_token"
enabled = true
[OneBotAdapter.accounts.backup]
bot_id = "987654321"
mode = "client"
url = "ws://127.0.0.1:3002"
token = "backup_token"
enabled = true
[OneBotAdapter.accounts.test]
bot_id = "111222333"
mode = "client"
url = "ws://127.0.0.1:3003"
enabled = false
Default Configuration
If no accounts are configured, the adapter will automatically create:
[OneBotAdapter.accounts.default]
bot_id = ""
mode = "server"
server_path = "/"
enabled = true
Send Method Return Values
All send methods return a Task object, which can be awaited to get the send result. The return result follows the ErisPulse adapter standardization return specification:
{
"status": "ok",
"retcode": 0,
"data": {...},
"message_id": "123456",
"message": "",
"onebot11_raw": {...}
}
Multi-Account Send Syntax
# Account selection methods
await onebot.Send.Using("main").To("group", 123456).Text("Main account message")
await onebot.Send.Using("backup").To("group", 123456).Image("http://example.com/image.jpg")
# API call method
await onebot.call_api("send_msg", account_id="main", group_id=123456, message="Hello")
Account Resolution Priority
The resolution priority of account_id parameters in call_api and Using():
- Exact match account name
- Match
bot_idfield - Match any
strtype field of the account - Fall back to the first enabled account
Asynchronous Processing Mechanism
The OneBot11 adapter uses an asynchronous non-blocking design, ensuring:
- Message sending does not block the event handling loop
- Multiple concurrent send operations can proceed simultaneously
- API responses are handled in a timely manner
- WebSocket connections remain active
- Multi-account concurrent processing, with each account running independently
Error Handling
The adapter provides a comprehensive error handling mechanism:
- Network connection exceptions automatically reconnect (supports independent reconnection for each account, interval 30 seconds)
- API call timeout handling (fixed 30-second timeout, timeout returns
retcode=33001standard failure response) - When the account is not connected or the connection is closed,
call_apireturnsretcode=33001standard failure response, no longer throwsConnectionError - Automatically retries connection failures at the interval
Enhanced Event Handling
In multi-account mode, all events automatically add account information:
{
"type": "message",
"detail_type": "private",
"self": {"user_id": "123456789", "platform": "onebot11"},
"platform": "onebot11",
// ... other event fields
}
The adapter automatically maintains the self_id → account_name mapping, allowing event.reply() to correctly route to the source account without manually specifying the account.
Management Interface
# Get all account information
accounts = onebot.accounts
# Check account connection status
connection_status = {
account_id: connection is not None and not connection.closed
for account_id, connection in onebot.connections.items()
}
# Dynamically enable/disable accounts (requires adapter restart)
onebot.accounts["test"].enabled = False
self_id Automatic Mapping
The adapter automatically establishes a mapping between OneBot self_id (QQ number) and account_name, used for event routing back:
# Adapter automatically completes
# When receiving an event, the self.user_id field is filled with bot_id
# The adapter automatically records: self_id("123456789") → account_name("main")
# Therefore, event.reply() can automatically find the correct account to send messages
@message.on_message()
async def handler(event):
await event.reply("Automatically routed to the correct account")