Supported Protocols

Relevant source files

The following files were used as context for generating this wiki page:

• README.en.md
• tests/PROTOCOL_AUTH_HEARTBEAT.md
• CONTRIBUTING.md
• AGENTS.md
• architecture.html
• architecture-diagrams.md
• tests/README.md
• packages/imhelper/CHANGELOG.md

OneBots serves as a multi-protocol IM bot gateway that normalizes various IM platform events into a unified CommonEvent model. The protocol layer then converts these internal events into standard wire formats, allowing downstream consumers to interact with multiple platforms using a single protocol implementation. OneBots supports export to OneBot v11, OneBot v12, Satori v1, and Milky v1.

Sources: README.en.md:5-24, AGENTS.md:12-25

Protocol Architecture and Data Flow

The system employs a layered architecture where the Protocol Layer handles inbound API calls and outbound event pushing. It sits between the Account Layer (which manages identity and ID mapping) and the Consumer Layer (downstream clients).

System Data Flow

The following diagram illustrates how events flow from IM platforms through OneBots to consumers, and how API calls return.

The diagram shows the transformation of platform-specific events into standard protocols and the routing of downstream API requests.
Sources: README.en.md:33-46, architecture.html:112-140

Protocol Implementation Details

Each supported protocol implements specific authentication, communication, and heartbeat mechanisms according to their respective standards.

OneBot v11 (OB11)

OneBot v11 is a widely used protocol in the bot ecosystem. OneBots implements its core communication methods including HTTP, Forward WebSocket, and Reverse WebSocket.

• Authentication: If access_token is configured, requests must include it in the Authorization header as Bearer <token> or as a URL query parameter access_token.
• Heartbeats: OneBots sends meta-events where post_type === 'meta_event' and meta_event_type === 'heartbeat'. These events must contain the interval (in milliseconds) and a status object.
• WebHook: Supports HMAC signatures via the X-Signature header.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:10-27, architecture-diagrams.md:195-212

OneBot v12 (OB12)

OneBot v12 provides a modernized standard with stricter header requirements and support for multiple platforms.

• Authentication: The protocol mandates checking the Authorization header first. If missing or invalid, it checks the access_token query parameter. Failure results in a 401 Unauthorized response.
• Communication Headers: Reverses WebSocket connections must set Sec-WebSocket-Protocol (e.g., 12.onebots). Webhooks must set X-OneBot-Version: 12.
• Heartbeats: Represented as a meta-event with type === 'meta' and detail_type === 'heartbeat', containing the interval in milliseconds.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:31-60, architecture.html:142-160

Satori v1

Satori is a cross-platform protocol that provides a unified API for multiple message types and resources.

• Communication: OneBots supports Satori via HTTP API and WebSocket events.
• Authentication: Typically uses Bearer Tokens in the Authorization header.
• Structure: API responses follow the format { data: any } for success and { message: string } for errors.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:83-100, packages/imhelper/CHANGELOG.md:35-50

Milky v1

Milky is a specialized protocol focused on enhanced feature support for specific platforms like QQ.

• Authentication: Uses Authorization: Bearer {access_token}. It also supports query parameters for environments where headers cannot be set.
• Error Handling: Returns 415 for unsupported Content-Types and 401 for authentication failures.
• Communication: Supports GET /event for SSE/WebSocket streams and POST /api/{action} for actions.

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:64-81, packages/imhelper/CHANGELOG.md:18-25

Comparison of Protocol Features

The following table summarizes the implementation differences between the supported protocols within OneBots.

Feature	OneBot v11	OneBot v12	Satori v1	Milky v1
Auth Header	Authorization: Bearer	Authorization: Bearer (Priority)	Authorization: Bearer	Authorization: Bearer
Query Auth	access_token	access_token (Fallback)	N/A	access_token
Heartbeat Field	interval, status	interval	Defined by standard	interval, status
Default Port	6727 (Shared)	6727 (Shared)	6727 (Shared)	6727 (Shared)
Event Push	WS / Webhook	WS / Webhook	WS / Webhook	WS / SSE / Webhook

Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:10-100, architecture.html:170-190

Protocol Registration and Lifecycle

Protocol implementations are managed by the ProtocolRegistry. Each protocol is an instance of a class inheriting from the Protocol base class.

1. Instantiation: The Account instance creates protocol instances based on the configuration in config.yaml.
2. Startup: Each protocol instance starts its own HTTP routes and WebSocket handlers via the shared App router.
3. Dispatching: When an Adapter receives a platform event, it is sent to the Account, which then iterates through all enabled Protocol instances and calls protocol.dispatch(event).
4. Action Execution: When a client calls an API, the Protocol calls protocol.apply(action, params), which routes the request back to the Adapter.

Sources: CONTRIBUTING.md:255-285, architecture.html:200-220

The sequence diagram demonstrates the bidirectional nature of the protocol layer, handling both event pushing and API request execution.
Sources: architecture-diagrams.md:150-185, architecture.html:245-280

OneBots provides a unified gateway that simplifies bot development by abstracting platform complexities into four major open protocols, allowing developers to choose the standard that best fits their existing toolchain.

Sources: README.en.md:75-85, AGENTS.md:120-130