Message & Event Flow

Relevant source files

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

• architecture.html
• README.en.md
• CONTRIBUTING.md
• architecture-diagrams.md
• AGENTS.md
• protocols/milky-v1/protocol/src/types.ts
• tests/PROTOCOL_AUTH_HEARTBEAT.md

OneBots operates as a multi-platform and multi-protocol IM bot gateway. It normalizes diverse platform events into a unified internal model before exporting them through standard wire protocols like OneBot (v11/v12), Satori, or Milky. The system maintains a decoupled architecture where the Adapter handles platform-specific details, the Account manages identity and distribution, and the Protocol handles client-facing communication.

Sources: README.en.md:8-13, AGENTS.md:12-16

1. System Architecture Overview

The message flow is divided into three primary layers that handle data transformation and routing. The core abstraction, CommonEvent, serves as the bridge between platform-specific raw data and protocol-standardized outputs.

The architecture separates platform-specific ingestion from standard protocol export.
Sources: README.en.md:27-40, architecture.html:92-114

2. Upstream Flow (Platform to Client)

The upstream flow, or ingress, processes events originating from IM platforms. The system transforms these into a standard format and pushes them to connected downstream clients.

2.1 Event Processing Steps

1. Ingestion: The Adapter receives raw events from platform SDKs or Webhooks.
2. Normalization: extractEvent() or toCommonEvent() converts raw data into a CommonEvent structure.
3. Dispatching: The Account receives the normalized event and distributes it to all enabled Protocol instances associated with that account.
4. Transformation: Each Protocol instance uses format() to convert the CommonEvent into a protocol-specific format (e.g., OneBot v11 JSON).
5. Delivery: The protocol instance pushes the event to clients via WebSocket, HTTP POST (Reverse), or SSE.

Sources: architecture.html:147-159, architecture-diagrams.md:112-138

2.2 Ingress Sequence

Platform events flow through the Adapter and Account layers before being formatted by individual Protocol instances for downstream clients.
Sources: architecture.html:260-297, architecture-diagrams.md:112-138

3. Downstream Flow (Client to Platform)

The downstream flow, or egress, handles API calls initiated by downstream clients. Clients request actions which the gateway translates and executes on the IM platforms.

3.1 Action Execution Steps

1. Request: A client sends a request (e.g., send_private_msg) to the Protocol's HTTP or WebSocket endpoint.
2. Validation: The protocol layer validates the access_token and request parameters.
3. Application: The Protocol's apply() method translates protocol-specific parameters into platform-compatible values.
4. Execution: The Adapter's sendMessage() or executeAction() method calls the platform's SDK or API.
5. Response: The result returns through the layers and is formatted as a protocol-standard JSON response.

Sources: architecture.html:160-168, architecture.html:301-340, architecture-diagrams.md:144-178

3.2 Egress Sequence

Downstream requests are validated by the Protocol layer and converted by the Adapter to match platform-specific requirements.
Sources: architecture.html:301-340, architecture-diagrams.md:144-178

4. Communication & Lifecycle Management

4.1 Transport Methods

The gateway supports multiple communication modes depending on the protocol and configuration.

Protocol	HTTP Mode	WebSocket Mode	Other
OneBot v11	HTTP Server / Reverse	WS Server / Reverse	Heartbeat Meta-Events
OneBot v12	HTTP Server / Webhook	WS Server / Reverse	Version.Impl headers
Satori v1	HTTP Server	WS Server	Webhook support
Milky v1	HTTP Server	WS Server	SSE (Server-Sent Events)

Sources: architecture-diagrams.md:275-325, tests/PROTOCOL_AUTH_HEARTBEAT.md:12-98

4.2 Lifecycle Events

The Account status transitions drive the availability of message flows.

• Pending: The account is initializing.
• Online: Events are actively dispatched; API calls are accepted.
• Offline: Event flow stops; API calls generally return implementation-specific errors.

Sources: CONTRIBUTING.md:464-470, architecture-diagrams.md:225-235

5. Event Transformation Example (Milky)

The Milky protocol defines specific event types and data structures for message processing.

Event Type	Field	Description
message_receive	message_scene	Indicates if the scene is friend, group, or temp.
message_receive	segments	An array of Segment objects (text, image, face, etc.).
bot_offline	reason	A string explaining why the bot disconnected.

Sources: protocols/milky-v1/protocol/src/types.ts:68-80, protocols/milky-v1/protocol/src/types.ts:114-122

5.1 Message Transformation Path

Transformation ensures that downstream clients receive data in their preferred protocol format regardless of the originating platform.
Sources: architecture-diagrams.md:239-271

The OneBots framework facilitates consistent message and event handling by abstracting platform complexities. By routing all traffic through a normalized CommonEvent layer, it allows developers to interact with multiple IM platforms using a single unified protocol interface.