GoQQBot

切换主题

读取图片、表情、卡片与转发 ​

通过 ctx.Message() 可以读取正文、附件、卡片和转发内容。无论事件来自 WebSocket 还是 Webhook，业务代码都使用同一套消息结构。

配置事件订阅 ​

使用 WebSocket ​

将所需条目合并到 config.yaml 现有的 connection.websocket.intents 列表，保留其他业务订阅。保存后重启机器人。

yaml
connection:
  mode: websocket
  websocket:
    intents:
      - GROUP_AND_C2C_EVENT

全部 Intent 与下属事件

使用 Webhook ​

在 QQ 机器人运营与管理后台选择 开发设置 → 事件订阅与回调。将接入方式设为 Webhook。在 接收事件配置 选择 部分接收，按事件标识勾选C2C_MESSAGE_CREATE 和 GROUP_AT_MESSAGE_CREATE，按需要接收的消息场景勾选。保存设置。已选 全部接收 时，无需逐项勾选。

QQ 机器人运营与管理后台 · 配置 HTTPS 回调

将完整消息交给业务服务 ​

下面的注册函数同时支持群聊中 @机器人的消息和单聊消息。回调只接收标准库的 context.Context 和消息数据，不依赖 SDK 的事件上下文或传输协议。

go
package guide

import (
	"context"

	"github.com/ProgramCX/GoQQBot/pkg/goqqrobot"
	"github.com/ProgramCX/GoQQBot/pkg/message"
	"github.com/ProgramCX/GoQQBot/shared/types"
)

func RegisterRichReceiver(bot *goqqrobot.Bot, consume func(context.Context, *message.Received) error) {
	handler := func(ctx *types.Context) error {
		m, err := ctx.Message()
		if err != nil {
			return err
		}
		return consume(ctx.RequestContext(), m)
	}
	bot.OnMessage(message.C2C_MESSAGE_CREATE, handler)
	bot.OnMessage(message.GROUP_AT_MESSAGE_CREATE, handler)
}

业务服务可以把消息转换为自己的结构再保存。ctx.Message() 返回的切片和解析结果都是独立数据，修改后不会影响 SDK 保存的原始事件。

选择数据入口 ​

内容入口可读数据
原始文字、Unicode 表情或平台文本标签m.Content原样保留，不自动把标签转成图片
当前消息附件m.Attachments平台下发的 URL、文件名、MIME、字节数、宽高等
所有层级附件m.AllAttachments()先列出当前消息的附件，再按顺序展开嵌套条目
所有层级图片m.Images()按 MIME 筛选
语音结果附件的 VoiceWAVURL、ASRReferText平台提供的语音字段
卡片、小程序、位置等m.ARK开放的 JSON 字段
引用、并列或转发条目m.MsgElements保留各层的作者、消息索引、正文、附件和 ARK
场景扩展m.MessageScene.Lookup(key)按 key=value 提取，保留值里的等号
尚未建模的字段m.Raw、条目的 Raw原始 JSON

message.MessageAttachment 和 message.MessageScene 是对应接收模型的兼容别名。SDK 仍保留旧的原始字段 ArkData、Elements。新代码可通过 ARK 和 MsgElements 直接读取结构化数据。

读取可选卡片字段 ​

下面的函数只读数据，不联网。示例读取 jump_url。可用字段以实际收到的卡片数据为准。

go
package guide

import "github.com/ProgramCX/GoQQBot/pkg/message"

func CardJumpURL(m *message.Received) (string, bool, error) {
	if m == nil || m.ARK == nil {
		return "", false, nil
	}
	var target string
	present, err := m.ARK.Field("jump_url", &target)
	return target, present, err
}

对象或数组应解码到相应的业务结构。发送用的 ARK 模板另有独立结构。

图片表情与引用的限制 ​

需要保留作者和层级归属时，遍历 MsgElements。

注意事项 ​

  • SDK 不自动下载附件、追踪网页、上传素材或补造字段。
  • 展开后的附件列表不标明每个附件属于哪条消息。Images() 不从文件名或 URL 推测图片类型。
  • 语音字段仅在平台提供时可用。卡片不保证含跳转或图片 URL。
  • 字段缺失时返回 false, nil。实际 JSON 类型与目标类型不符时返回解码错误。
  • 原始 JSON 可能含敏感授权数据。
  • 图片表情包只有随图片附件下发时才可用 Images() 读取。内置表情、小程序或转发缺少链接时，SDK 无法生成真实图片地址。
  • 合并转发只下发文字摘要时，SDK 无法恢复原消息节点。
  • msg_idx/ref_msg_idx 是展示引用上下文。临时值或不稳定关联无法保证可靠溯源。这两个索引也不用于撤回。

另请参阅 ​

接收单聊 · 接收群聊 · 引用与撤回 · 官方单聊接收模型 · 官方群聊接收模型