消息类
发送群聊消息
send_group_message:向指定群发送一条消息。
const SendResult *send_group_message(uint64_t self_id, const char *platform,
uint64_t group_id, const char *message);
void free_send_result(const SendResult *result);- 权限:
send_group_message - 调用要求:需要账号在线,请在工作线程中调用
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
self_id | uint64_t | 是 | 在线 Bot QQ 号,不能为 0 |
platform | const char * | 是 | 所属平台 PLATFORM_* |
group_id | uint64_t | 是 | 群号,不能为 0 |
message | const char * | 是 | 非空 Segment[] 消息段 UTF-8 JSON 数组 |
复用媒体限制
- 已有群视频:数组必须只含一条群聊
video段,作为独立消息发送,不会上传文件。 - 已有群语音:数组必须只含一条群聊
voice段(取自收到的群消息或upload_group_voice返回的message)。
返回值 SendResult
用完必须调用 free_send_result(result) 交还;客户端未提供接口时返回 NULL。需要撤回时,请先复制成功结果中的关联值,再交还结构体。
| 字段 | 类型 | 说明 |
|---|---|---|
code | int32_t | 0 表示成功;服务器拒绝时原样保留服务端结果码,本地失败为 RESULT_LOCAL_ERROR(-1) |
msg_seq | uint64_t | 消息序号(仅成功时有效,撤回时使用) |
msg_random | uint64_t | 消息随机数(仅成功时有效,撤回时使用) |
client_seq | uint64_t | 客户端序号(仅成功时有效,好友消息撤回时使用) |
msg_time | uint64_t | 发送时间,Unix 秒(仅成功时有效,好友消息撤回时使用) |
error | const char * | 失败原因,非 NULL,无内容时为 "" |
消息段 Segment
message 参数及消息回调的 message 字段均为 UTF-8 JSON 数组(不是纯文本字符串),数组顺序即消息内容顺序。发送时数组不能为空,非负整数字段支持 JSON 数字或数字字符串;接收时应容忍未知类型和字段,不要用浮点数保存 64 位整数。
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 消息段类型,见下表 |
data | SegmentData | 与 type 对应的消息段数据 |
消息段类型一览
type | 说明 | 支持场景 | 发送支持 |
|---|---|---|---|
text | 文本 | 群聊 / 好友 | 支持 |
at | @ 某人 | 群聊 | 支持 |
at_all | @ 全体成员 | 群聊 | 支持 |
face | 表情 | 群聊 / 好友 | 支持 |
image | 图片 | 群聊 / 好友 | 支持 |
flash_image | 闪照 | 好友 | 支持 |
video | 短视频 | 群聊 / 好友 | 支持(须单独作为唯一消息段) |
voice | 语音 | 群聊 / 好友 | 支持(须单独作为唯一消息段) |
forward | 合并转发 | 群聊 / 好友 | 支持 |
reply | 回复 / 引用 | 群聊 / 好友 | 仅接收 |
redpack | 红包 | 群聊 / 好友 | 仅接收 |
unknown | 未知消息段 | 群聊 / 好友 | 仅接收 |
文本 text
{ "type": "text", "data": { "text": "你好" } }text(string,必填):文本内容。
@ 某人 at
{ "type": "at", "data": { "user_id": 123456789 } }user_id(uint64,必填且不能为0):被 @ 用户的 QQ 号。
@ 全体成员 at_all
{ "type": "at_all", "data": {} }data为空对象。
表情 face
{ "type": "face", "data": { "id": 14, "big": false, "text": "/微笑" } }id(uint64,必填):表情 ID。big(bool,可选,默认false):是否为大表情 / 超级表情。text/pack_id/sticker_id(string,可选):展示文案、表情包标识、贴纸标识。
图片 image
- 字段:
file_id、name、md5、sha1、size、width、height、pic_type、original、url(发送时可为空串,不参与下载或上传)。 - 推荐直接原样传入
upload_group_image/upload_friend_image返回的result->message,或原样复用收到的新版图片消息段。
闪照 flash_image
- 字段:
name、size、type、md5、width、height、url、reference(可选)。 - 仅好友消息支持;须原样传入
upload_friend_flash_image返回的result->message并保留reference。
短视频 video
- 字段:
file_id、name、md5、sha1、size、width、height、duration、video_codec(可选,0为 H.264,1为 H.265)、thumbnail(可选封面对象,字段同正片,无 URL)。 - 必须作为消息数组中的唯一消息段单独发送。
语音 voice
- 字段:
file_id、name、md5、sha1、size、duration、audio_codec(可选,0AMR /1SILK /2MP3 /3AAC)、wave_amplitudes(可选,0–255整数数组)。 - 必须作为消息数组中的唯一消息段单独发送。
合并转发 forward
- 接收字段:
service_id、res_id(为空时省略)、user_id(可选)、title、summary、preview、count(可选)、messages(仅接收时可能出现)。 - 发送时必须原样传入
upload_forward_message返回的result->message(同一账号、平台和目标);发送不接受messages字段,且res_id为必填字符串。