go-cqhttp

https://docs.go-cqhttp.org/
Admin
go-cqhttp is a lightweight, native, high-concurrency, and cross-platform OneBot Golang...
Tokens:18,322
Snippets:186
Trust Score:7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Skip 5-Second Delay - Windows

Source: https://docs.go-cqhttp.org/guide/quick_start

Use the `faststart` command-line argument to bypass the initial 5-second delay when starting go-cqhttp on Windows.

```bash
.\go-cqhttp.exe -faststart

```

--------------------------------

### Skip 5-Second Delay - Linux

Source: https://docs.go-cqhttp.org/guide/quick_start

Use the `faststart` command-line argument to bypass the initial 5-second delay when starting go-cqhttp on Linux.

```bash
./go-cqhttp -faststart

```

--------------------------------

### Install ffmpeg - Ubuntu/Debian

Source: https://docs.go-cqhttp.org/guide/quick_start

Install ffmpeg on Ubuntu or Debian-based Linux distributions using the apt package manager.

```bash
apt install -y ffmpeg

```

--------------------------------

### Run go-cqhttp Docker Container

Source: https://docs.go-cqhttp.org/guide/docker.html

Starts a go-cqhttp container, mapping local configuration and device files, exposing the HTTP port, and running in detached mode.

```bash
docker run \
  -v /path/to/config.yml:/data/config.yml \
  -v /path/to/device.json:/data/device.json \
  -p 2333:8080 \
  -d \
  --name cqhttp \
  ghcr.io/mrs4s/go-cqhttp:master

```

--------------------------------

### Forward HTTP GET Request Example

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

Use GET requests to send parameters to an API endpoint for active operations. Parameters are appended to the URL.

```http
GET /终结点?参数1=参数值&参数2=参数值 HTTP/1.1


```

--------------------------------

### Reverse HTTP Event Reporting Example (Private Message)

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

go-cqhttp sends event reports via POST requests to a configured URL. This example shows the format for a private message event.

```http
POST / HTTP/1.1

{
    "time": 1515204254,
    "self_id": 10001000,
    "post_type": "message",
    "message_type": "private",
    "sub_type": "friend",
    "message_id": 12,
    "user_id": 12345678,
    "message": "你好～",
    "raw_message": "你好～",
    "font": 456,
    "sender": {
        "nickname": "小不点",
        "sex": "male",
        "age": 18
    }
}



```

--------------------------------

### Custom Server IP Configuration

Source: https://docs.go-cqhttp.org/guide/config.html

This example shows how to specify custom server IP addresses and ports for go-cqhttp to connect to. Each IP:PORT pair should be on a new line.

```text
1.1.1.1:53
1.1.2.2:8899

```

--------------------------------

### Install ffmpeg - CentOS 7 and earlier

Source: https://docs.go-cqhttp.org/guide/quick_start

Install ffmpeg on CentOS 7 and earlier versions using the yum package manager.

```bash
yum install ffmpeg ffmpeg-devel

```

--------------------------------

### Install ffmpeg - CentOS 8 and later

Source: https://docs.go-cqhttp.org/guide/quick_start

Install ffmpeg on CentOS 8 and later versions using the dnf package manager.

```bash
dnf install ffmpeg ffmpeg-devel

```

--------------------------------

### Array Message Example: At and Text

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

An example of an array-based message format combining an '@' mention and a text message.

```json
[
    {
        "type": "at",
        "data": {
            "qq": 123456
        }
    },
    {
        "type": "text",
        "data": {
            "text": "早上好啊"
        }
    }
]
```

--------------------------------

### Run go-cqhttp Docker Container with Container ID

Source: https://docs.go-cqhttp.org/guide/docker.html

Starts a go-cqhttp container and displays the container ID upon successful execution. This ID can be used to manage the container.

```bash
docker run \
    -v /path/to/config.yml:/data/config.yml \
    -v /path/to/device.json:/data/device.json \
    -p 2333:8080 \
    -d \
    --name cqhttp \
    ghcr.io/mrs4s/go-cqhttp:master
aa89d8943600a653b7e06a9d404fd6396b33c5c4e3b37d28c27df2437b3df033 # 这个就是容器的识别码

```

--------------------------------

### CQ Code Example with Mention and Text

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

A valid CQ message string can combine different elements, such as a mention and plain text. This example shows how to mention a user and append text.

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

--------------------------------

### Verify HMAC SHA1 Signature in Go (Gin Framework)

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

This Go example, designed as a Gin middleware, shows how to read the request body, compute the HMAC SHA1 signature using a secret key, and validate it against the 'X-Signature' header.

```go
package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha1"
	"encoding/hex"
	"io"
	"net/http"
	"github.com/gin-gonic/gin"
)

// CqhttpAuth 当X-Signature存在时，校验签名
// 该方法配置为 gin middleware，可根据需要修改
// secert 配置的密钥
func CqhttpAuth(secret string) gin.HandlerFunc {
	return func(c *gin.Context) {
		hSignature := c.GetHeader("X-Signature")
		if hSignature != "" {
			if secret == "" {
				c.AbortWithStatus(http.StatusUnauthorized)
				return
			}
			// 读取 request body
			body, err := io.ReadAll(c.Request.Body)
			if err != nil {
				c.AbortWithStatus(http.StatusInternalServerError)
				return
			}
			// gin框架中request body只能读取一次，需要复写 request body
			c.Request.Body = io.NopCloser(bytes.NewBuffer(body))
			// 使用密钥计算request body的 hmac码
			mac := hmac.New(sha1.New, []byte(secret))
			if _, err := mac.Write(body); err != nil {
				c.AbortWithStatus(http.StatusInternalServerError)
				return
			}
			// 校验hmac签名
			if "sha1="+hex.EncodeToString(mac.Sum(nil)) != hSignature {
				c.AbortWithStatus(http.StatusUnauthorized)
				return
			}
		}
		c.Next()
	}

}

```

--------------------------------

### Verify HMAC SHA1 Signature in C#

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

This C# example demonstrates how to initialize HMACSHA1 with a secret key and verify if a given signature matches the computed hash of the data.

```csharp
using System.Security.Cryptography;
using System.Text;

// HMACSHA1 的初始化
byte[] tokenBin = Encoding.UTF8.GetBytes(secret);    // 获取二进制数据
HMACSHA1 sha1 = new HMACSHA1(tokenBin);              // 初始化 HMACSHA1

// 验证签名与数据是否匹配
private bool Verify(string? signature, byte[] data)
{
    if (signature == null)
        return sha1 == null;
    if (sha1 == null)
        return false;

    if (signature.StartsWith("sha1="))
        signature = signature.Substring(5);

    byte[] hash = sha1.ComputeHash(data);
    string realSignature = string.Join(null, hash.Select(bt => Convert.ToString(bt, 16).PadLeft(2, '0')));
    return signature == realSignature;
}

```

--------------------------------

### WebSocket Event Reporting Example (Message)

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

When connected via WebSocket, event reports are received in the same format as reverse HTTP POST requests. This example shows a message event.

```json
{
    "time": 1515204254,
    "self_id": 10001000,
    "post_type": "message",
    "message_type": "private",
    "sub_type": "friend",
    "message_id": 12,
    "user_id": 12345678,
    "message": "你好～",
    "raw_message": "你好～",
    "font": 456,
    "sender": {
        "nickname": "小不点",
        "sex": "male",
        "age": 18
    }
}


```

--------------------------------

### Pull go-cqhttp Docker Image

Source: https://docs.go-cqhttp.org/guide/docker.html

Pulls the latest go-cqhttp Docker image from GitHub Container Registry. Ensure Docker is installed and running before executing.

```bash
docker pull ghcr.io/mrs4s/go-cqhttp:master

```

--------------------------------

### Forward HTTP POST Request Example (Action in Body)

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

Send POST requests where the action and its parameters are specified within the JSON request body. This allows for dynamic action calls.

```http
POST / HTTP/1.1

{
    "action": "终结点名称, 例如 'send_group_msg'",
    "params": {
        "参数名": "参数值",
        "参数名2": "参数值"
    }
}


```

--------------------------------

### Quick Operation: Reply in Private Message

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

Example of a JSON response for a quick operation, specifically replying to a private message. Only fields present in the response trigger an action.

```json
{
    "reply": "嗨～"
}
```

--------------------------------

### Forward HTTP - Sending Actions

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

This section describes how to send requests to go-cqhttp using Forward HTTP. It supports GET requests with query parameters, POST requests with parameters in the request body, and POST requests with the action and params specified in the body. It also mentions the possibility of using form data.

```APIDOC
## Forward HTTP - Sending Actions

### Description
Use Forward HTTP to send requests to go-cqhttp by sending requests to `/API_Endpoint`. Parameters can be sent using GET or POST requests. The specific method for requests is detailed in the API section.

### Method
GET or POST

### Endpoint
`/API_Endpoint` or `/` (when specifying action in body)

### Parameters
#### Query Parameters (for GET requests)
- **param1** (type) - Description
- **param2** (type) - Description

#### Request Body (for POST requests)
- **param_name** (type) - Description
- **param_name2** (type) - Description

#### Request Body (for POST requests with action specified)
- **action** (string) - The name of the endpoint to call, e.g., 'send_group_msg'.
- **params** (object) - An object containing the parameters for the action.
  - **param_name** (type) - Description
  - **param_name2** (type) - Description

### Request Example (GET)
```http
GET /API_Endpoint?param1=value1&param2=value2 HTTP/1.1
```

### Request Example (POST with parameters in body)
```http
POST /API_Endpoint HTTP/1.1
Content-Type: application/json

{
    "param_name": "value",
    "param_name2": "value2"
}
```

### Request Example (POST with action in body)
```http
POST / HTTP/1.1
Content-Type: application/json

{
    "action": "send_group_msg",
    "params": {
        "param_name": "value",
        "param_name2": "value2"
    }
}
```

### Request Example (POST with form data)
```http
POST /API_Endpoint HTTP/1.1
Content-Type: application/x-www-form-urlencoded

[form data]
```
```

--------------------------------

### Forward HTTP POST Request Example (Form Data)

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

Use POST requests with form data to send parameters to an API endpoint. This is another method for active operations.

```http
POST /终结点 HTTP/1.1


```

--------------------------------

### Filter Messages Starting with '!!'

Source: https://docs.go-cqhttp.org/guide/eventfilter.html

This filter allows only messages that begin with '!!' to be reported. It uses a regular expression to match the start of the raw message.

```json
{
    "raw_message": {
        ".regex": "^!!"
    }
}
```

--------------------------------

### String Message Format with CQ Codes

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

An example of a message string using CQ codes to embed special content like QQ emoticons and images.

```cqcode
[CQ:face,id=178]看看我刚拍的照片[CQ:image,file=123.jpg]
```

--------------------------------

### WebSocket Action Request Example

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

Send a JSON payload to a WebSocket endpoint to perform actions. The 'echo' field can be used to correlate requests and responses.

```json
{
    "action": "终结点名称, 例如 'send_group_msg'",
    "params": {
        "参数名": "参数值",
        "参数名2": "参数值"
    },
    "echo": "'回声', 如果指定了 echo 字段, 那么响应包也会同时包含一个 echo 字段, 它们会有相同的值"
}


```

--------------------------------

### Get Guild Roles

Source: https://docs.go-cqhttp.org/api/guild.html

Retrieves a list of all roles within a specified guild. Includes details about each role's properties and membership.

```APIDOC
## GET /get_guild_roles

### Description
Retrieves a list of all roles within a specified guild. This endpoint provides details for each role, including its ID, name, color, and membership information.

### Method
GET

### Endpoint
`/get_guild_roles`

### Parameters
#### Query Parameters
- **guild_id** (string) - Required - The ID of the guild for which to retrieve roles.

### Response
#### Success Response (200) (Array)
- **argb_color** (int64) - The ARGB color value of the role (e.g., 4294927682).
- **disabled** (bool) - Indicates if the role is disabled.
- **independent** (bool) - Unknown property.
- **max_count** (int32) - The maximum number of members that can have this role.
- **member_count** (int32) - The current number of members who have this role.
- **owned** (bool) - Unknown property.
- **role_id** (string) - The unique identifier for the role.
- **role_name** (string) - The name of the role.
```

--------------------------------

### WebSocket Action Response Example

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

The format of a response received via WebSocket after sending an action request. It includes status, return code, and optional error messages or data.

```json
{
    "status": "状态, 表示 API 是否调用成功, 如果成功, 则是 OK, 其他的在下面会说明",
    "retcode": 0,
    "msg": "错误消息, 仅在 API 调用失败时有该字段",
    "wording": "对错误的详细解释(中文), 仅在 API 调用失败时有该字段",
    "data": {
        "响应数据名": "数据值",
        "响应数据名2": "数据值",
    },
    "echo": "'回声', 如果请求时指定了 echo, 那么响应也会包含 echo"
}


```

--------------------------------

### Forward HTTP POST Request Example (JSON Body)

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

Use POST requests with a JSON body to send parameters to an API endpoint. This method is suitable for sending messages and other active operations.

```http
POST /终结点 HTTP/1.1

{
    "参数名": "参数值",
    "参数名2": "参数值"
}


```

--------------------------------

### Reverse HTTP - Receiving Events

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

This section explains how go-cqhttp uses Reverse HTTP to actively send 'reports' to the client via POST requests. It details the request headers and provides an example of a message event report.

```APIDOC
## Reverse HTTP - Receiving Events

### Description
When using Reverse HTTP, go-cqhttp will actively send 'reports' to the client via POST requests. The detailed content of the request body is explained in the Event section.

### Method
POST

### Endpoint
The configured report URL (e.g., `http://127.0.0.1:8080/`)

### Headers
- **X-Self-ID** (string) - The logged-in QQ number.
- **X-Signature** (string) - Optional signature.

### Request Example (Private Message Event)
```http
POST / HTTP/1.1
Host: 127.0.0.1:8080
X-Self-ID: 10001000

{
    "time": 1515204254,
    "self_id": 10001000,
    "post_type": "message",
    "message_type": "private",
    "sub_type": "friend",
    "message_id": 12,
    "user_id": 12345678,
    "message": "Hello~",
    "raw_message": "Hello~",
    "font": 456,
    "sender": {
        "nickname": "Little Dot",
        "sex": "male",
        "age": 18
    }
}
```
```

--------------------------------

### Build go-cqhttp from Source

Source: https://docs.go-cqhttp.org/guide/quick_start

Compile go-cqhttp from source code using the Go build command. This command includes optimizations for smaller binary size and static linking.

```bash
go build -ldflags "-s -w -extldflags '-static'"

```

--------------------------------

### Add ffmpeg to PATH - Windows

Source: https://docs.go-cqhttp.org/guide/quick_start

Set the ffmpeg bin directory to the system's PATH environment variable on Windows using the `setx` command. This is necessary for go-cqhttp to support arbitrary audio formats.

```cmd
setx /M PATH "C:\Program Files\ffmpeg\bin;%PATH%"

```

--------------------------------

### Update go-cqhttp - Windows with Mirror

Source: https://docs.go-cqhttp.org/guide/quick_start

Update go-cqhttp on Windows using a mirror URL to potentially speed up downloads from GitHub.

```bash
go-cqhttp.exe update https://hub.fgit.ml

```

--------------------------------

### Update go-cqhttp - Windows

Source: https://docs.go-cqhttp.org/guide/quick_start

Update go-cqhttp on Windows by running the `update` command. This will download the latest version from the release page.

```bash
go-cqhttp.exe update

```

--------------------------------

### Get Guild Message

Source: https://docs.go-cqhttp.org/api/guild.html

Retrieves a specific message from a guild channel. Supports caching options for faster responses.

```APIDOC
## GET /get_guild_msg

### Description
Retrieves a specific message from a guild channel using its message ID. The `no_cache` parameter can be used to bypass the cache for more up-to-date information at the cost of slower response times.

### Method
GET

### Endpoint
`/get_guild_msg`

### Parameters
#### Query Parameters
- **message_id** (string) - Required - The ID of the guild message to retrieve.
- **no_cache** (bool) - Optional - If true, bypasses the cache. Defaults to false.

### Response
#### Success Response (200)
- **channel_id** (string) - The ID of the sub-channel.
- **guild_id** (string) - The ID of the guild.
- **message** (string) - The content of the message.
- **message_id** (string) - The ID of the message.
- **message_seq** (int64) - The sequence number of the message within the channel.
- **message_source** (string) - The source of the message (e.g., 'channel', 'direct').
- **sender** (object) - Information about the message sender.
  - **nickname** (string) - The sender's nickname.
  - **tiny_id** (string) - The sender's tiny ID.
  - **user_id** (int64) - The sender's user ID.
- **reactions** (array) - Currently always empty.
- **time** (int64) - The timestamp when the message was sent (10-digit Unix timestamp).
```

--------------------------------

### Default go-cqhttp Configuration (config.yml)

Source: https://docs.go-cqhttp.org/guide/config.html

This is the default configuration file for go-cqhttp. It covers account settings, message handling, output logging, and database options. Adjust these settings to customize your bot's behavior.

```yaml
# go-cqhttp 默认配置文件

account: # 账号相关
  uin: 1233456 # QQ账号
  password: '' # 密码为空时使用扫码登录
  encrypt: false  # 是否开启密码加密
  status: 0      # 在线状态 请参考 https://docs.go-cqhttp.org/guide/config.html#在线状态
  relogin: # 重连设置
    delay: 3   # 首次重连延迟, 单位秒
    interval: 3   # 重连间隔
    max-times: 0  # 最大重连次数, 0为无限制

  # 是否使用服务器下发的新地址进行重连
  # 注意, 此设置可能导致在海外服务器上连接情况更差
  use-sso-address: true
  # 是否允许发送临时会话消息
  allow-temp-session: false

  # 数据包的签名服务器列表，第一个作为主签名服务器，后续作为备用
  # 兼容 https://github.com/fuqiuluo/unidbg-fetch-qsign
  # 如果遇到 登录 45 错误, 或者发送信息风控的话需要填入一个或多个服务器
  # 不建议设置过多，设置主备各一个即可，超过 5 个只会取前五个
  # 示例:
  # sign-servers: 
  #   - url: 'http://127.0.0.1:8080' # 本地签名服务器
  #     key: "114514"  # 相应 key
  #     authorization: "-"   # authorization 内容, 依服务端设置
  #   - url: 'https://signserver.example.com' # 线上签名服务器
  #     key: "114514"  
  #     authorization: "-"   
  #   ... 
  # 
  # 服务器可使用docker在本地搭建或者使用他人开放的服务
  sign-servers: 
    - url: '-'  # 主签名服务器地址， 必填
      key: '114514'  # 签名服务器所需要的apikey, 如果签名服务器的版本在1.1.0及以下则此项无效
      authorization: '-'   # authorization 内容, 依服务端设置，如 'Bearer xxxx'
    - url: '-'  # 备用
      key: '114514'  
      authorization: '-' 

  # 判断签名服务不可用（需要切换）的额外规则
  # 0: 不设置 （此时仅在请求无法返回结果时判定为不可用）
  # 1: 在获取到的 sign 为空 （若选此建议关闭 auto-register，一般为实例未注册但是请求签名的情况）
  # 2: 在获取到的 sign 或 token 为空（若选此建议关闭 auto-refresh-token ）
  rule-change-sign-server: 1

  # 连续寻找可用签名服务器最大尝试次数
  # 为 0 时会在连续 3 次没有找到可用签名服务器后保持使用主签名服务器，不再尝试进行切换备用
  # 否则会在达到指定次数后 **退出** 主程序
  max-check-count: 0
  # 签名服务请求超时时间(s)
  sign-server-timeout: 60
  # 如果签名服务器的版本在1.1.0及以下, 请将下面的参数改成true
  # 建议使用 1.1.6 以上版本，低版本普遍半个月冻结一次
  is-below-110: false
  # 在实例可能丢失（获取到的签名为空）时是否尝试重新注册
  # 为 true 时，在签名服务不可用时可能每次发消息都会尝试重新注册并签名。
  # 为 false 时，将不会自动注册实例，在签名服务器重启或实例被销毁后需要重启 go-cqhttp 以获取实例
  # 否则后续消息将不会正常签名。关闭此项后可以考虑开启签名服务器端 auto_register 避免需要重启
  # 由于实现问题，当前建议关闭此项，推荐开启签名服务器的自动注册实例
  auto-register: false
  # 是否在 token 过期后立即自动刷新签名 token（在需要签名时才会检测到，主要防止 token 意外丢失）
  # 独立于定时刷新
  auto-refresh-token: false
  # 定时刷新 token 间隔时间，单位为分钟, 建议 30~40 分钟, 不可超过 60 分钟
  # 目前丢失token也不会有太大影响，可设置为 0 以关闭，推荐开启
  refresh-interval: 40

heartbeat:
  # 心跳频率, 单位秒
  # -1 为关闭心跳
  interval: 5

message:
  # 上报数据类型
  # 可选: string,array
  post-format: string
  # 是否忽略无效的CQ码, 如果为假将原样发送
  ignore-invalid-cqcode: false
  # 是否强制分片发送消息
  # 分片发送将会带来更快的速度
  # 但是兼容性会有些问题
  force-fragment: false
  # 是否将url分片发送
  fix-url: false
  # 下载图片等请求网络代理
  proxy-rewrite: ''
  # 是否上报自身消息
  report-self-message: false
  # 移除服务端的Reply附带的At
  remove-reply-at: false
  # 为Reply附加更多信息
  extra-reply-data: false
  # 跳过 Mime 扫描, 忽略错误数据
  skip-mime-scan: false
  # 是否自动转换 WebP 图片
  convert-webp-image: false
  # download 超时时间(s)
  http-timeout: 15

output:
  # 日志等级 trace,debug,info,warn,error
  log-level: warn
  # 日志时效 单位天. 超过这个时间之前的日志将会被自动删除. 设置为 0 表示永久保留.
  log-aging: 15
  # 是否在每次启动时强制创建全新的文件储存日志. 为 false 的情况下将会在上次启动时创建的日志文件续写
  log-force-new: true
  # 是否启用日志颜色
  log-colorful: true
  # 是否启用 DEBUG
  debug: false # 开启调试模式

# 默认中间件锚点
default-middlewares: &default
  # 访问密钥, 强烈推荐在公网的服务器设置
  access-token: ''
  # 事件过滤器文件目录
  filter: ''
  # API限速设置
  # 该设置为全局生效
  # 原 cqhttp 虽然启用了 rate_limit 后缀, 但是基本没插件适配
  # 目前该限速设置为令牌桶算法, 请参考:
  # https://baike.baidu.com/item/%E4%BB%A4%E7%89%8C%E6%A1%B6%E7%AE%97%E6%B3%95/6597000?fr=aladdin
  rate-limit:
    enabled: false # 是否启用限速
    frequency: 1  # 令牌回复频率, 单位秒
    bucket: 1     # 令牌桶大小

database: # 数据库相关设置
  leveldb:
    # 是否启用内置leveldb数据库
    # 启用将会增加10-20MB的内存占用和一定的磁盘空间
    # 关闭将无法使用 撤回 回复 get_msg 等上下文相关功能
    enable: true
  sqlite3:
    # 是否启用内置sqlite3数据库
    # 启用将会增加一定的内存占用和一定的磁盘空间
    # 关闭将无法使用 撤回 回复 get_msg 等上下文相关功能
    enable: false
    cachettl: 3600000000000 # 1h

# 连接服务列表
servers:
  # 添加方式，同一连接方式可添加多个，具体配置说明请查看文档
  #- http: # http 通信
  #- ws:   # 正向 Websocket
  #- ws-reverse: # 反向 Websocket
  #- pprof: #性能分析服务器

```

--------------------------------

### Windows Initial Run Output

Source: https://docs.go-cqhttp.org/guide/quick_start

This output indicates that the configuration file was not found and a default one has been generated. You need to edit this file before restarting the program.

```text
[WARNING]: 尝试加载配置文件 config.yml 失败: 文件不存在
[INFO]: 默认配置文件已生成,请编辑 config.yml 后重启程序.

```

--------------------------------

### go-cqhttp Default Directory Structure

Source: https://docs.go-cqhttp.org/guide/file.html

This snippet shows the default file and directory layout generated by go-cqhttp. It includes the main executable, configuration files, log directory, and data directories for images and databases.

```bash
.
├── go-cqhttp
├── config.yml
├── device.json
├── logs
│   └── xx-xx-xx.log
└── data
    ├── images
    │   └── xxxx.image
    └── db

```

--------------------------------

### View go-cqhttp Container Logs

Source: https://docs.go-cqhttp.org/guide/docker.html

Retrieves the logs for the 'cqhttp' container. This is essential for verifying login status and checking for any errors during operation.

```bash
docker container logs cqhttp

```

--------------------------------

### Update go-cqhttp - Linux

Source: https://docs.go-cqhttp.org/guide/quick_start

Update go-cqhttp on Linux by running the `update` command. This will download the latest version from the release page.

```bash
./go-cqhttp update

```

--------------------------------

### Windows Successful Login Output

Source: https://docs.go-cqhttp.org/guide/quick_start

This output signifies a successful login and indicates that the bot is ready for use.

```text
[INFO]: 登录成功 欢迎使用: balabala

```

--------------------------------

### Implemented APIs

Source: https://docs.go-cqhttp.org/guide/achieve.html

This section lists the APIs that are implemented in Go-CQHTTP, categorized by their adherence to the OneBot standard.

```APIDOC
## Implemented APIs

### OneBot Standard APIs

API| Function
---|---
/send_private_msg| Send private message
/send_group_msg| Send group message
/send_msg| Send message
/delete_msg| Delete message
/set_group_kick| Kick group member
/set_group_ban| Ban group member
/set_group_whole_ban| Ban all group members
/set_group_admin| Set group admin
/set_group_card| Set group card (remark)
/set_group_name| Set group name
/set_group_leave| Leave group
/set_group_special_title| Set group special title
/set_friend_add_request| Handle friend add request
/set_group_add_request| Handle group add request/invitation
/get_login_info| Get login account info
/get_stranger_info| Get stranger info
/get_friend_list| Get friend list
/get_group_info| Get group info
/get_group_list| Get group list
/get_group_member_info| Get group member info
/get_group_member_list| Get group member list
/get_group_honor_info| Get group honor info
/can_send_image| Check if image can be sent
/can_send_record| Check if record can be sent
/get_version_info| Get version info
/set_restart| Restart go-cqhttp
/.handle_quick_operation| Perform quick operation on event

### Extended APIs

API| Function
---|---
/set_group_portrait| Set group portrait
/get_image| Get image info
/get_msg| Get message
/get_forward_msg| Get forward message content
/send_group_forward_msg| Send forward message (group)
/.get_word_slices| Get Chinese word slices
/.ocr_image| Image OCR
/get_group_system_msg| Get group system messages
/get_group_file_system_info| Get group file system info
/get_group_root_files| Get group root directory file list
/get_group_files_by_folder| Get group subdirectory file list
/get_group_file_url| Get group file resource URL
/get_status| Get status
```

--------------------------------

### Complex Event Filtering Example

Source: https://docs.go-cqhttp.org/guide/eventfilter.html

A complex filter combining multiple conditions using 'or' and nested checks. It filters private messages not from specific users (11111, 22222, 33333) and not from user 44444, OR messages from group/discuss types where the group ID is 12345 or the raw message contains '通知'.

```json
{
    ".or": [
        {
            "message_type": "private",
            "user_id": {
                ".not": {
                    ".in": [11111, 22222, 33333]
                },
                ".neq": 44444
            }
        },
        {
            "message_type": {
                ".regex": "group|discuss"
            },
            ".or": [
                {
                    "group_id": 12345
                },
                {
                    "raw_message": {
                        ".contains": "通知"
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### Default Device Information JSON

Source: https://docs.go-cqhttp.org/guide/config.html

This JSON structure defines the default virtual device information for go-cqhttp. It includes various hardware and software identifiers required for device emulation.

```json
{
  "protocol": 0,
  "display": "xxx",
  "product": "xxx",
  "device": "xxx",
  "board": "xxx",
  "model": "xxx",
  "finger_print": "xxx",
  "boot_id": "xxx",
  "proc_version": "xxx",
  "imei": "xxx",
  "brand": "xxx",
  "bootloader": "xxx",
  "base_band": "",
  "version": {
    "incremental": "xxx",
    "release": "xxx",
    "codename": "xxx",
    "sdk": 0 // 随机
  },
  "sim_info": "xxx",
  "os_type": "xxx",
  "mac_address": "xxx",
  "ip_address": [
    // ...
  ],
  "wifi_bssid": "xxx",
  "wifi_ssid": "xxx",
  "imsi_md5": "xxx",
  "android_id": "xxx",
  "apn": "xxx",
  "vendor_name": "xxx",
  "vendor_os_name": "xxx"
}

```

--------------------------------

### Custom Music Share (JSON)

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

Use this JSON format to share custom music. Specify the URL, audio source, and title.

```json
{
    "type": "music",
    "data": {
        "type": "custom",
        "url": "http://baidu.com",
        "audio": "http://baidu.com/1.mp3",
        "title": "音乐标题"
    }
}
```

--------------------------------

### Short Video Cache File Structure

Source: https://docs.go-cqhttp.org/guide/file.html

Describes the structure of short video cache files, similar to image cache files. It includes metadata for the video source MD5 hash, video cover MD5 hash, video file size, video cover size, original filename, and a UUID.

```text
Offset| Type| Description
---|---|---
0x00| [16]byte| Video source file MD5 HASH
0x10| [16]byte| Video cover MD5 HASH
0x20| uint32| Video source file size
0x24| uint32| Video cover size
0x28| string| Original filename (QQ internal ID)
0x28 + Original name length| [16]byte| UUID

```

--------------------------------

### Custom Music Share (CQ Code)

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

Use this CQ code format for custom music sharing. It includes URL, audio source, and title.

```plaintext
[CQ:music,type=custom,url=http://baidu.com,audio=http://baidu.com/1.mp3,title=音乐标题]
```

--------------------------------

### Image Cache File Structure

Source: https://docs.go-cqhttp.org/guide/file.html

Details the structure of image cache files (.image) used by go-cqhttp for performance. It specifies the offset, type, and description of metadata including MD5 hash, file size, original filename, and download link.

```text
Offset| Type| Description
---|---|---
0x00| [16]byte| Image source file MD5 HASH
0x10| uint32| Image source file size
0x14| string| Original filename (QQ internal ID)
0x14 + Original name length| string| Image download link

```

--------------------------------

### WebSocket - Sending Actions and Receiving Events

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

This section covers WebSocket communication, which is full-duplex. It explains the format for sending actions and the expected response format for actions. It also notes that receiving an event report via WebSocket is the same format as Reverse HTTP.

```APIDOC
## WebSocket Communication

### Description
WebSocket communication is full-duplex, allowing for both sending messages and receiving events. The data format for actions and events is detailed below. Different WebSocket endpoints are available to separate Action and Event functionalities.

### Sending Actions via WebSocket
Send a JSON object with `action`, `params`, and an optional `echo` field.

#### Request Format
```json
{
    "action": "action_name",
    "params": {
        "param_name": "value",
        "param_name2": "value2"
    },
    "echo": "echo_string"
}
```

### Action Response Format
Responses to actions will include `status`, `retcode`, `msg`, `wording` (if error), `data`, and an optional `echo` field.

#### Response Format
```json
{
    "status": "OK",
    "retcode": 0,
    "msg": "Error message (if any)",
    "wording": "Detailed error explanation (if any)",
    "data": {
        "response_data_name": "data_value",
        "response_data_name2": "data_value2"
    },
    "echo": "echo_string"
}
```

### Receiving Events via WebSocket
Event reports received via WebSocket have the same format as Reverse HTTP.

#### Event Report Format (Example: Private Message)
```json
{
    "time": 1515204254,
    "self_id": 10001000,
    "post_type": "message",
    "message_type": "private",
    "sub_type": "friend",
    "message_id": 12,
    "user_id": 12345678,
    "message": "Hello~",
    "raw_message": "Hello~",
    "font": 456,
    "sender": {
        "nickname": "Little Dot",
        "sex": "male",
        "age": 18
    }
}
```

### WebSocket Endpoints
- **`/`**: Handles Actions, Post events, and results.
- **`/api`**: Handles Actions only (sending and receiving results).
- **`/event`**: Handles Post events only.
```

--------------------------------

### Custom Reply Message

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

Create a custom reply with specified text, QQ, time, and sequence.

```plaintext
[CQ:reply,text=Hello World,qq=10086,time=3376656000,seq=5123]
```

--------------------------------

### Implemented CQ Codes

Source: https://docs.go-cqhttp.org/guide/achieve.html

This section lists the CQ Codes implemented in Go-CQHTTP, categorized by their adherence to the OneBot standard.

```APIDOC
## Implemented CQ Codes

### OneBot Standard CQ Codes

CQ Code| Function
---|---
[CQ:face]| QQ Face
[CQ:record]| Voice
[CQ:video]| Short Video
[CQ:at]| @ Someone
[CQ:share]| Link Share
[CQ:music]| Music Share
[CQ:reply]| Reply
[CQ:forward]| Merged Forward
[CQ:xml]| XML Message
[CQ:json]| JSON Message

### Extended CQ Codes

CQ Code| Function
---|---
[CQ:image]| Image
[CQ:redbag]| Red Packet
[CQ:poke]| Poke
[CQ:gift]| Gift
[CQ:node]| Merged Forward Message Node
[CQ:cardimage]| XML Image Message (Show off big picture)
[CQ:tts]| Text to Speech
```

--------------------------------

### Create Guild Role

Source: https://docs.go-cqhttp.org/api/guild.html

Creates a new role within a specified guild. Allows setting initial properties like name and color.

```APIDOC
## POST /create_guild_role

### Description
Creates a new role within a specified guild. You can define the role's name, color, and whether it's independent.

### Method
POST

### Endpoint
`/create_guild_role`

### Parameters
#### Request Body
- **guild_id** (string) - Required - The ID of the guild.
- **color** (string) - Required - The color for the new role.
- **name** (string) - Required - The name for the new role.
- **independent** (bool) - Optional - Unknown property. Defaults to false.
- **initial_users** (array of string) - Optional - A list of user IDs to initially assign this role to.

### Response
#### Success Response (200) (Array)
- **role_id** (int64) - The ID of the newly created role.
```

--------------------------------

### Custom Message Node Forwarding

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

Create custom message nodes for forwarding, specifying sender name, QQ, and content. Content can be text or other message types.

```json
[
	{
		"type": "node",
		"data": {
			"name": "消息发送者A",
			"uin": "10086",
			"content": [
				{
					"type": "text",
					"data": {
						"text": "测试消息1"
					}
				}
			]
		}
	},
	{
		"type": "node",
		"data": {
			"name": "消息发送者B",
			"uin": "10087",
			"content": "[CQ:image,file=xxxxx]测试消息2"
		}
	}
]
```

--------------------------------

### JSON Representation of Mention

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

This JSON object represents a mention, specifying the target QQ number or 'all' for everyone.

```json
{
    "type": "at",
    "data": {
        "qq": "10001000",
        "name": "此栏无效，此人在群里"
    }
}

```

--------------------------------

### CQ Code for Short Video

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

This CQ Code is used to send a short video, specifying the video file URL and optionally a cover image.

```text
[CQ:video,file=http://baidu.com/1.mp4]
```

--------------------------------

### CQ Code for Music Share

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

This CQ Code is used to share music, specifying the platform (e.g., 163 for NetEase Cloud Music) and the song ID.

```text
[CQ:music,type=163,id=28949129]
```

--------------------------------

### HTTP Request with Access Token

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

When an Access Token is configured, it must be included in the 'Authorization' header for HTTP requests.

```http
GET /api HTTP/1.1
Host: localhost:6006
Authorization: Bearer 114514


```

--------------------------------

### CQ Code for Shake

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

This CQ Code is a shortcut for the basic 'shake' (poke) action. Note: This CQ code is not yet supported by go-cqhttp.

```text
[CQ:shake]
```

--------------------------------

### CQ Code Basic Syntax

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

The fundamental structure of a CQ Code is defined by square brackets, with parameters separated by commas. Ensure no extra spaces around commas.

```text
[CQ:类型,参数=值,参数=值]
```

--------------------------------

### Mixed Custom and Direct Message Node Forwarding

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

Combine custom message nodes with direct message node references for forwarding. This allows for a mix of custom sender information and existing message IDs.

```json
[
    {
        "type": "node",
        "data": {
            "name": "自定义发送者",
            "uin": "10086",
            "content": "我是自定义消息",
            "seq": "5123",
            "time": "3376656000"
        }
    },
    {
        "type": "node",
        "data": {
            "id": "123"
        }
    }
]
```

--------------------------------

### Accessing Array Elements by Index

Source: https://docs.go-cqhttp.org/guide/eventfilter.html

Shows how to filter based on elements within an array using numerical indices. This allows targeting specific items in a list.

```json
{
  "message.0.type": "text"
}
```

--------------------------------

### CQ Code for Contact Recommendation

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

This CQ Code is used to recommend a QQ contact or group. Note: This CQ code is not yet supported by go-cqhttp.

```text
[CQ:contact,type=qq,id=10001000]
[CQ:contact,type=group,id=100100]
```

--------------------------------

### Reverse WebSocket Request with Access Token

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

For reverse WebSocket connections, go-cqhttp includes the Access Token in the request header when connecting to your application.

```http
GET /ws HTTP/1.1
Host: localhost:6006
Authorization: Bearer 114514
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIH
Sec-WebSocket-Version: 13


```

--------------------------------

### CQ Code for QQ Face

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

This CQ Code format is used to send a QQ face, specifying the face ID.

```text
[CQ:face,id=123]
```

--------------------------------

### Filter All Events

Source: https://docs.go-cqhttp.org/guide/eventfilter.html

This configuration will filter out all incoming events. Use with caution.

```json
{
    ".not": {}
}
```

--------------------------------

### Image Share with URL

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

Send an image using its network URL. Supports specifying image type and effect ID.

```plaintext
[CQ:image,file=http://baidu.com/1.jpg,type=show,id=40004]
```

--------------------------------

### CQ Code for Link Share

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

This CQ Code is used to share a link, specifying the URL and title, with optional content and image.

```text
[CQ:share,url=http://baidu.com,title=百度]
```
Tokens:
Raw