qqbotsdk/docs/api/v2.md

群聊与单聊 API（v2）

from qqbotsdk.api import BotApi。经 handler 参数注入（api: BotApi）或 bot.api 使用；未封装的接口走 bot.call_api(method, path, **kwargs)。

消息规则（被动回复时限、msg_seq、富媒体流程）见收发消息。

群聊（群 openid）

方法	端点	说明
post_group_message(group_openid, content="", msg_id=None, msg_seq=1, media=None, event_id=None, markdown=None, keyboard=None, **extra)	POST /v2/groups/{group_openid}/messages	msg_id/event_id 二选一即被动回复（event_id 支持 GROUP_ADD_ROBOT / INTERACTION_CREATE 等事件）；media 传上传返回的 {"file_info": …}（自动 msg_type=7）；markdown 为字符串或完整 dict（自动 msg_type=2，与 content 互斥）；keyboard 为内嵌键盘 {"content": {"rows": [...]}} 或 {"id": …}；其余字段经 extra 透传
upload_group_file(group_openid, file_type, url, srv_send_msg=False)	POST /v2/groups/{group_openid}/files	富媒体上传，返回含 file_info；srv_send_msg=True 上传即发送
withdraw_group_message(group_openid, message_id)	DELETE /v2/groups/{group_openid}/messages/{message_id}	发出 2 分钟内可撤回
mute_group_members(group_openid, members)	POST /v2/groups/{group_openid}/restrict_chat_setting	批量禁言/解禁；members 每项为 {"op": "add"/"update"/"del", "member_openid": …, "mute_expire_at": …}（RFC3339）：add 新增禁言、update 更新到期时间、del 解禁（expire 可传空串）。单次最多 20 人、最长禁言 30 天、仅可操作普通成员（群主/管理员/机器人不可）；需群管理员身份，60 QPM
mute_group_member(group_openid, member_openid, mute_expire_at)	同上	单人禁言封装（op=add）
unmute_group_member(group_openid, member_openid)	同上	单人解禁封装（op=del）
prepare_group_upload(group_openid, file_type, file_size, file_name, md5, sha1, md5_10m)	POST /v2/groups/{group_openid}/upload_prepare	大文件分片预上传，返回 upload_id/block_size/各分片预签名 parts；逐片 PUT 后调 finish_group_upload_part，全部完成后携 upload_id 调 upload_group_file 合并；md5_10m 为文件前约 10MB 的 MD5
finish_group_upload_part(group_openid, upload_id, part_index, block_size=None, md5=None)	POST …/upload_part_finish	每个分片 PUT 成功后调用确认

单聊（用户 openid）

方法	端点	说明
post_c2c_message(openid, content="", msg_id=None, msg_seq=1, media=None, event_id=None, markdown=None, keyboard=None, **extra)	POST /v2/users/{openid}/messages	同 post_group_message
upload_c2c_file(openid, file_type, url, srv_send_msg=False)	POST /v2/users/{openid}/files	同 upload_group_file
withdraw_c2c_message(openid, message_id)	DELETE /v2/users/{openid}/messages/{message_id}	2 分钟内可撤回
post_c2c_stream_message(openid, content_raw="", *, stream_msg_id=None, index=0, input_state=STREAM_GENERATING, input_mode=None, content_type=STREAM_CONTENT_MARKDOWN, msg_id=None, event_id=None, msg_seq=None, is_wakeup=None)	POST /v2/users/{openid}/stream_messages	流式分批发送，见下节
prepare_c2c_upload(openid, …) / finish_c2c_upload_part(openid, …)	POST /v2/users/{openid}/upload_prepare · upload_part_finish	单聊分片上传，用法同群聊

流式消息

把一条回复拆成多片依次下发（LLM 逐段输出的标准玩法）：

• 首片不传 stream_msg_id，响应 id 即后续分片要携带的值；index 从 0 递增；
• 以 input_state=STREAM_FINISHED 收尾；
• input_mode="replace" 时 content_raw 须以上游已下发前缀开头；
• is_wakeup=True 为召回消息，不校验被动回复有效期。

通用方法与常量

方法	说明
me()	机器人自身信息（GET /users/@me）
generate_url_link(callback_data=None)	生成机器人分享链接（POST /v2/generate_url_link），返回 {"data": {"url": …}}；用户经链接添加时 callback_data（≤32 字符）透传给开发者
respond_interaction(interaction_id, code=0)	回应互动事件（PUT /interactions/{id}）；按钮点击收到后必须回应，否则客户端持续 loading，同一 id 仅可回应一次

常量：MSG_TYPE_TEXT=0、MSG_TYPE_MARKDOWN=2、MSG_TYPE_MEDIA=7；FILE_TYPE_IMAGE=1、FILE_TYPE_VIDEO=2、FILE_TYPE_VOICE=3、FILE_TYPE_FILE=4；流式 STREAM_INPUT_APPEND/STREAM_INPUT_REPLACE、STREAM_GENERATING=1/STREAM_FINISHED=10、STREAM_CONTENT_TEXT/STREAM_CONTENT_MARKDOWN；禁言 MUTE_OP_ADD/MUTE_OP_UPDATE/MUTE_OP_DEL。

按钮构造：button(label, data, *, type=1, permission=2, style=1) 生成单个按钮 dict，keyboard(*rows) 组装为 keyboard= 参数（单按钮独占一行，按钮列表同行并排）。点击回调经 INTERACTION_CREATE 事件处理，见收发消息。