Platform Adapter Ecosystem

Relevant source files

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

• README.en.md
• CONTRIBUTING.md
• AGENTS.md
• architecture-diagrams.md
• architecture.html
• packages/onebots/src/extension-catalog.ts
• adapters/adapter-mattermost/src/index.ts
• packages/core/ARCHITECTURE.md

The Platform Adapter Ecosystem maps diverse Instant Messaging (IM) platform events and APIs into a unified CommonEvent abstraction and shared Adapter APIs. This layer allows a single OneBots process to communicate with multiple platforms—such as QQ, WeChat, Discord, and Telegram—without rewriting glue code for each platform.

The system normalizes platform-specific behaviors into a standard format, which the Protocol layer then exports to downstream consumers using wire formats like OneBot v11/v12, Satori, or Milky.
Sources: README.en.md:16-24, AGENTS.md:12-19

Core Architecture

The adapter ecosystem functions as the interface between external IM platforms and the internal OneBots core. Every platform-specific implementation inherits from a base Adapter class and manages multiple Account instances.

Hierarchy and Relationships

The following class diagram illustrates the relationship between the application, adapters, and accounts:

The App manages multiple Adapter instances; each Adapter creates and manages Account instances representing specific logins on that platform.
Sources: architecture-diagrams.md:154-220, architecture.html:112-148

Adapter Lifecycle and Registration

Adapters are modular extensions registered via the AdapterRegistry. This registry tracks capabilities, metadata, and configuration schemas for every supported platform.

Registry Metadata

Each adapter must provide metadata during registration to be visible in the Web UI or CLI.

Field	Description
name	Technical identifier for the platform (e.g., mattermost).
displayName	Human-readable name shown in UI (e.g., Mattermost).
description	Summary of supported APIs and transport modes.
packageName	The npm package name (e.g., @onebots/adapter-mattermost).
schema	A JSON schema defining configuration fields like access_token.

Sources: packages/onebots/src/extension-catalog.ts:28-44, adapters/adapter-mattermost/src/index.ts:143-156

Implementation Requirements

To add a new platform, a developer must:

1. Extend the Adapter base class to implement mandatory methods like sendMessage.
2. Define a Schema using AdapterRegistry.registerSchema to provide Web form semantics.
3. Register the Adapter using AdapterRegistry.register.
4. Handle IDs using createId() for normalization and resolveId() for platform delivery.
   Sources: CONTRIBUTING.md:270-325, AGENTS.md:213-221

Data Flow Logic

The ecosystem handles two primary data directions: Uplink (events from platforms) and Downlink (actions from clients).

Uplink: Event Normalization

When a platform sends an event (e.g., a new message), the adapter extracts the data and projects it into a CommonEvent.

The adapter ensures that regardless of whether the source is a Discord webhook or a Telegram bot update, the internal core receives a standardized CommonEvent.
Sources: architecture-diagrams.md:83-112, architecture.html:167-184

Downlink: Action Execution

When a downstream client calls an API (e.g., send_private_msg), the Protocol layer passes the request to the Adapter.

Adapters are responsible for converting universal parameters (like user_id and message segments) back into platform-specific structures required by the IM service.
Sources: architecture-diagrams.md:118-150, architecture.html:209-242

Supported Platforms Summary

OneBots includes over 20 adapters. The following table highlights common platforms and their primary connectivity methods.

Platform	Connection Method	Key Configuration Fields
QQ Official	WebSocket	app_id, client_secret
Mattermost	REST API v4 / WebSocket	server_url, access_token
Telegram	Bot API	bot_token
Slack	Socket Mode / Events API	bot_token, app_token
Discord	WebSocket / Gateway	bot_token
Email	IMAP / SMTP	host, port, user, pass

Sources: README.en.md:58-61, packages/onebots/src/extension-catalog.ts:63-180, adapters/adapter-mattermost/src/index.ts:58-139

Conclusion

The Platform Adapter Ecosystem provides a scalable foundation for multi-platform bot development. By abstracting the complexities of 20+ IM platforms into a single CommonEvent model, it enables developers to focus on business logic while maintaining compatibility with diverse messaging ecosystems.
Sources: README.en.md:11-15, AGENTS.md:12-19