onebots

English

简体中文

English

简体中文

Appearance

OneBot V12 Protocol ​

OneBot V12 is the next generation version of the OneBot protocol, providing a more modern and flexible robot interface standard.

Protocol Introduction ​

OneBot V12 improvements over V11:

  • More standardized message segment format (replacing CQ Code)
  • More complete type system
  • Cross-platform feature support
  • Better extensibility
  • Standardized error handling

Standard Reference ​

Documentation Navigation ​

Enable the protocol ​

Select OneBot V12 in the Web Extensions view or the TUI setup wizard. The manager installs the protocol and its required peers into a new immutable runtime generation, verifies it, and waits for explicit activation:

bash
onebots ui --data-dir /path/to/onebots-data --setup

Configuration ​

Configure OneBot V12 protocol in config.yaml:

yaml
# Global default configuration
general:
  onebot.v12:
    use_http: true        # Enable HTTP API
    use_ws: false         # Enable WebSocket
    use_ws_reverse: false # Enable reverse WebSocket

# Account configuration
wechat.my_mp:
  onebot.v12:
    use_http: true
    use_ws: true
    access_token: "your_token"

Communication Methods ​

HTTP API ​

URL Format: http://localhost:6727/{platform}/{account_id}/onebot/v12/{action}

Example:

bash
# Send message
curl -X POST http://localhost:6727/wechat/my_mp/onebot/v12/send_message \
  -H "Content-Type: application/json" \
  -d '{
    "detail_type": "private",
    "user_id": "123456",
    "message": [
      {"type": "text", "data": {"text": "Hello"}}
    ]
  }'

WebSocket ​

URL Format: ws://localhost:6727/{platform}/{account_id}/onebot/v12

Reverse WebSocket ​

yaml
wechat.my_mp:
  onebot.v12:
    use_ws_reverse: true
    ws_reverse_url: "ws://your-server:8080/ws"

Message Format ​

OneBot V12 uses a unified message segment array format:

json
[
  {
    "type": "text",
    "data": {"text": "Hello "}
  },
  {
    "type": "at",
    "data": {"user_id": "123456"}
  }
]

Client SDK Usage ​

typescript
import { createOnebot12Client } from '@imhelper/onebot-v12';

const client = createOnebot12Client({
  baseUrl: 'http://localhost:6727/qq/my-bot/onebot/v12',
  apiBaseUrl: 'http://localhost:6727/qq/my-bot/onebot/v12',
  wsUrl: 'ws://localhost:6727/qq/my-bot/onebot/v12',
  selfId: 'my-bot',
  accessToken: 'your-access-token',
  receiveMode: 'ws',
});

client.on('message.group', async message => message.reply('Received!'));
await client.start();