DOCSEARCHbyAlgolia
Submit Docs

go-cqhttp Documentation

website·Indexed 33 days ago

https://docs.go-cqhttp.org/

Documentation for go-cqhttp, a lightweight, high-concurrency, cross-platform QQ client implementation based on Mirai and MiraiGo. It provides an API and event reporting system compatible with the OneBot standard, featuring support for CQ Code, HTTP communication, and Docker deployment.

Tokens
23.5K
Snippets
167
Records
211
Agent score
65%

What's inside go-cqhttp

  1. Overview of go-cqhttp

    go-cqhttp is a native Golang implementation of cqhttp developed using mirai and MiraiGo. It is based on the original cqhttp API with additional modifications and extensions. It is currently in development and available as beta releases.

  2. Overview of go-cqhttp configuration files

    go-cqhttp uses two primary configuration files:

    1. config.yml: Contains runtime configurations. It is automatically generated upon the first run of go-cqhttp.
    2. device.json: Contains virtual device information. It is automatically generated upon the first account login.

  3. Overview of go-cqhttp communication methods

    go-cqhttp acts as a QQ client simulator. Users interact with it via four primary communication methods to perform QQ operations:

    • Forward HTTP: Client sends requests to go-cqhttp. Used for "active operations" (e.g., sending messages). Cannot receive messages.
    • Reverse HTTP: go-cqhttp sends requests to a client-hosted HTTP server. Used for "passive operations" (e.g., receiving messages). Cannot send messages.
    • Forward WebSocket: go-cqhttp acts as the server; client connects. Full-duplex, supporting both sending and receiving messages.
    • Reverse WebSocket: Client acts as the server; go-cqhttp connects. Full-duplex, supporting both sending and receiving messages.

  4. Retrieve go-cqhttp version information

    Use the /get_version_info endpoint to retrieve detailed versioning and environment information about the running go-cqhttp instance. This API requires no parameters.
    GET /get_version_info

  5. Call go-cqhttp Actions (APIs)

    Actions (APIs) allow clients to perform operations like sending messages, recalling messages, or accepting friend requests. go-cqhttp supports the following communication formats for calling actions:

    • GET request URL parameters
    • POST request JSON body
    • POST request form data
    • WebSocket JSON messages

  6. Handle group message events in go-cqhttp

    Group message events are reported with post_type: "message" and message_type: "group". They include details about the sender, the message content, and the group context. For anonymous messages, the sub_type will be anonymous and the anonymous object will contain the user's anonymous ID, name, and flag. Note that the sender field is provided on a best-effort basis and may be inaccurate or missing, especially for anonymous messages.
    {
  "time": 123456789,
  "self_id": 12345,
  "post_type": "message",
  "message_type": "group",
  "sub_type": "normal", // normal, anonymous, or notice
  "message_id": 1001,
  "user_id": 67890,
  "message": "...",
  "raw_message": "Hello!",
  "font": 0,
  "sender": { ... },
  "group_id": 111222,
  "anonymous": { // null if not anonymous
    "id": 123,
    "name": "Anonymous User",
    "flag": "some_flag"
  }
}

  7. Retrieve group information

    The /get_group_info endpoint returns details about a specific group. If the bot is not a member of the group, fields like group_create_time, group_level, max_member_count, and member_count will return 0. Group images can be accessed via https://p.qlogo.cn/gh/{group_id}/{group_id}/100.
    // Request Parameters
{
  "group_id": "int64",
  "no_cache": "boolean (default: false)"
}

// Response
{
  "group_id": "int64",
  "group_name": "string",
  "group_memo": "string",
  "group_create_time": "uint32",
  "group_level": "uint32",
  "member_count": "int32",
  "max_member_count": "int32"
}

  8. Understand CQ Code basic syntax

    CQ Code is a text-based format used to represent special message types in go-cqhttp. The basic grammar is [CQ:type,parameter=value,parameter=value].

    Crucially, there should be no extra spaces within the CQ Code (e.g., after commas), as spaces will be treated as part of the parameter or value. A single message can consist of multiple parts, combining CQ Codes with plain text.

    [CQ:at,qq=114514]早上好啊

  9. Handle go-cqhttp Event reports

    Events (Reports) are the mechanism go-cqhttp uses to push data to the client, such as receiving messages, message recalls, or friend requests. The format of the message chain in these reports (either array or string) is determined by the go-cqhttp configuration file.

  10. Interact with go-cqhttp via SDKs

    Once go-cqhttp is running, you can communicate with it using HTTP or WebSocket protocols to build a QQ bot. It is recommended to use a dedicated SDK. Known SDKs include:

    • C# / .NET: EleCho.GoCqHttpSdk, IlyfairyLib.GoCqHttpSdk, Saladim.QBot
    • Go: leafbot, Nyabot
    • PHP: 虞灪 (MicroDreamTeam/go-cq-http-sdk)
    • Python: pycqBot, Nakuru Project

    Alternatively, any SDK implementing the OneBot standard can be used, though some go-cqhttp specific APIs may be missing.

  11. Retrieve message details by ID

    Fetch detailed information about a specific message. Note: The raw_message field was named message_raw in versions v0.9.35 to v0.9.36-fix3 and did not exist in versions prior to v0.9.35.

    POST /get_msg { "message_id": 12345 }

  12. Understand message sender data structures (Post_Message_MessageSender)

    The Post_Message_MessageSender structure provides details about the user sending a message. The available fields depend on whether the message is a private chat or a group chat.

    Common Fields (Private & Group):

    • user_id (int64): Sender's QQ number
    • nickname (string): Nickname
    • sex (string): Gender (male, female, or unknown)
    • age (int32): Age

    Private Chat Specifics:

    • If the private chat is a temporary group session, the group_id (int64) field is included to indicate the source group.

    Group Chat Specifics:

    • card (string): Group card/remark
    • area (string): Region
    • level (string): Member level
    • role (string): Role (owner, admin, or member)
    • title (string): Exclusive title