跳转到正文
消息类

发送群聊消息

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_iduint64_t是在线 Bot QQ 号,不能为 0
platformconst char *是所属平台 PLATFORM_*
group_iduint64_t是群号,不能为 0
messageconst char *是非空 Segment[] 消息段 UTF-8 JSON 数组

复用媒体限制

  • 已有群视频:数组必须只含一条群聊 video 段,作为独立消息发送,不会上传文件。
  • 已有群语音:数组必须只含一条群聊 voice 段(取自收到的群消息或 upload_group_voice 返回的 message)。

返回值 SendResult

用完必须调用 free_send_result(result) 交还;客户端未提供接口时返回 NULL。需要撤回时,请先复制成功结果中的关联值,再交还结构体。

字段类型说明
codeint32_t0 表示成功;服务器拒绝时原样保留服务端结果码,本地失败为 RESULT_LOCAL_ERROR(-1)
msg_sequint64_t消息序号(仅成功时有效,撤回时使用)
msg_randomuint64_t消息随机数(仅成功时有效,撤回时使用)
client_sequint64_t客户端序号(仅成功时有效,好友消息撤回时使用)
msg_timeuint64_t发送时间,Unix 秒(仅成功时有效,好友消息撤回时使用)
errorconst char *失败原因,非 NULL,无内容时为 ""

消息段 Segment

message 参数及消息回调的 message 字段均为 UTF-8 JSON 数组(不是纯文本字符串),数组顺序即消息内容顺序。发送时数组不能为空,非负整数字段支持 JSON 数字或数字字符串;接收时应容忍未知类型和字段,不要用浮点数保存 64 位整数。

字段类型说明
typestring消息段类型,见下表
dataSegmentData与 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(可选,0 AMR / 1 SILK / 2 MP3 / 3 AAC)、wave_amplitudes(可选,0–255 整数数组)。
  • 必须作为消息数组中的唯一消息段单独发送。

合并转发 forward

  • 接收字段:service_id、res_id(为空时省略)、user_id(可选)、title、summary、preview、count(可选)、messages(仅接收时可能出现)。
  • 发送时必须原样传入 upload_forward_message 返回的 result->message(同一账号、平台和目标);发送不接受 messages 字段,且 res_id 为必填字符串。

本页目录