Adapter Base API & Contracts

Relevant source files

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

• CONTRIBUTING.md
• README.en.md
• AGENTS.md
• architecture-diagrams.md
• architecture.html

The Adapter layer serves as the primary abstraction between disparate Instant Messaging (IM) platforms and the internal OneBots core. It normalizes platform-specific events and APIs into a unified CommonEvent model and a shared set of Adapter APIs. This architecture allows the system to support multiple platforms (e.g., QQ, WeChat, Slack) while exporting data through standardized wire protocols like OneBot, Satori, or Milky.

Sources: README.en.md:16-20, AGENTS.md:9-12

Core Architecture

The Adapter is an abstract base class defined within @onebots/core. Every platform implementation must inherit from this class to provide specific logic for event extraction and action execution.

Class Hierarchy and Relationships

The following diagram illustrates the relationship between the central App, the Adapter, and the Account instances it manages.

The Adapter manages multiple Account instances, each representing a unique identity on the target platform.
Sources: architecture-diagrams.md:150-165, architecture.html:120-140

Adapter Registry & Schemas

OneBots uses a central AdapterRegistry to handle the lifecycle and configuration of platform adapters. Developers must register their adapters and provide a configuration schema to enable the management console to display appropriate UI elements.

Registration Procedure

1. Define Schema: Provide metadata for configuration fields (e.g., access_token, server_url).
2. Register Platform: Use AdapterRegistry.register to link a platform string (e.g., 'foo') to its Adapter class.
3. Extend Types: Use TypeScript module augmentation to add the new platform configuration to the Adapter.Configs namespace.

Sources: CONTRIBUTING.md:300-310, AGENTS.md:213-220

Configuration Schema Example

Adapters define their requirements using a Schema object, which supports types, defaults, and UI hints.

Field	Type	Description
account_id	string	Stable identifier within OneBots.
access_token	string	Sensitive credential for the platform API.
receive_mode	string	Choice between 'websocket', 'webhook', or 'manual'.

Sources: adapters/adapter-mattermost/src/index.ts:50-100 (Reference context from monorepo patterns)

Data Normalization Contracts

The primary responsibility of an Adapter is data translation. This involves two directions: Uplink (Platform to OneBots) and Downlink (OneBots to Platform).

Uplink: Event Normalization

The Adapter converts raw platform JSON payloads into a CommonEvent. This ensures that downstream protocols do not need to understand platform-specific quirks.

Downlink: Action Execution

When a client calls a protocol API, the protocol translates the request into a call to the Adapter's standardized methods.

Method	Role	Requirement
sendMessage	Sends text or segments	Must return a message_id.
deleteMessage	Recalls/Removes content	Requires platform message reference.
getUserInfo	Fetches profile data	Normalizes into a standard user object.
createId	Normalizes IDs	Converts raw platform IDs to CommonTypes.Id.

Sources: architecture-diagrams.md:150-165, AGENTS.md:163-165

Implementation Guidelines

Technical constraints for developing new adapters:

• ID Mapping: You must normalize all platform IDs using this.createId(rawId). You must use resolveId when sending data back to the platform. Sources: AGENTS.md:163-166
• Logging: You must use this.logger obtained via app.getLogger(platform). You must not use console.log. Sources: CONTRIBUTING.md:105-115, AGENTS.md:168-170
• Error Handling: Wrap platform-specific errors using ErrorHandler.wrap(). Use specific categories like NetworkError or AdapterError. Sources: CONTRIBUTING.md:135-145, packages/core/ARCHITECTURE.md:15-25
• File Naming: Use adapter.ts for the implementation, bot.ts for stateful SDK wrappers, and index.ts for registration. Sources: CONTRIBUTING.md:270-280, AGENTS.md:85-88

Message Sending Sequence

The following sequence shows how a message flows from a client through the Adapter to the IM platform.

Conclusion

The Adapter Base API provides a rigid contract that ensures interoperability across the OneBots ecosystem. By enforcing CommonEvent normalization, ID mapping, and standardized error handling, the framework allows developers to add support for new IM platforms without modifying protocol or core logic. Each implementation resides in the adapters/ directory as a separate package, maintaining a clean separation of concerns within the pnpm monorepo.

Sources: README.en.md:75-80, AGENTS.md:65-75