Skip to main content

​
What is OneBot 11?

OneBot 11 is a unified bot protocol standard that provides a consistent API interface for QQ bot frameworks. NapCat implements the OneBot 11 protocol, allowing you to build QQ bots using standardized actions and events.

​
Action System

Actions are the core of OneBot 11 API - they allow you to interact with QQ by sending requests and receiving responses. Each action has:
  • Action Name: The identifier for the action (e.g., send_msg, get_group_info)
  • Request Parameters: Input data required by the action
  • Response Data: Output data returned after execution
  • Return Codes: Status codes indicating success or failure

​
How to Call Actions

Actions can be called through different network adapters:

​
HTTP POST

POST /send_msg
Content-Type: application/json

{
  "message_type": "private",
  "user_id": "123456",
  "message": "Hello!"
}

​
WebSocket

{
  "action": "send_msg",
  "params": {
    "message_type": "private",
    "user_id": "123456",
    "message": "Hello!"
  },
  "echo": "optional-request-id"
}

​
Response Format

All actions return a standardized response: 
{
  "status": "ok",
  "retcode": 0,
  "data": {
    // Response data specific to the action
  },
  "message": "",
  "wording": "",
  "echo": "optional-request-id"
}
​
status
string
Response status: ok for success, failed for failure
​
retcode
number
Return code: 0 for success, non-zero for errors
​
data
object
Response data specific to each action
​
message
string
Error message (only present on failure)
​
echo
any
Echo value from request (WebSocket only)

​
Common Error Codes

​
1400
error
Request parameter error or business logic execution failed
​
1401
error
Insufficient permissions
​
1404
error
Resource not found
​
400
error
Bad request (HTTP)
​
200
error
Operation timeout or unknown error

​
Action Categories

NapCat organizes actions into several categories:

​
Message Actions

Send, delete, and retrieve messages in private chats and groups. View Message Actions →

​
Group Actions

Manage groups, members, permissions, and group settings. View Group Actions →

​
User Actions

Get user information, friend lists, and send interactions. View User Actions →

​
File Actions

Upload and download files in groups and private chats. View File Actions →

​
Extended Actions

NapCat-specific extensions for advanced features like OCR, status setting, and more. View Extended Actions →

​
Message Format

Messages in OneBot 11 can be sent in three formats:

​
String (CQ Code)

{
  "message": "[CQ:at,qq=123456] Hello!"
}

{
  "message": [
    { "type": "at", "data": { "qq": "123456" } },
    { "type": "text", "data": { "text": " Hello!" } }
  ]
}

​
Single Segment

{
  "message": { "type": "text", "data": { "text": "Hello!" } }
}

​
Action Name Variants

Each action supports three calling variants:
  • action_name - Standard synchronous call
  • action_name_async - Asynchronous execution
  • action_name_rate_limited - Rate-limited execution
Example: send_msg, send_msg_async, send_msg_rate_limited

Build docs developers (and LLMs) love

Get started for freeTalk to us