0 Fork 0

mirror of https://github.com/snowy-yang/qqbotsdk.git synced 2026-10-21 14:26:17 +00:00

Files

T

snowy-yang bcd69099b6 docs: 文档模块化重构（guide/api 多页），文档站迁移 GitHub Pages Actions 部署

GUIDE/API 拆为 docs/guide/ 五页与 docs/api/ 七页，侧边栏分组折叠，
旧链接 alias 映射；安装改为 pip install qqbotsdk-py，README 加徽章；
删除 docs 分支同步工作流，pages.yml 直部署（自定义域名 CNAME 随产物带上）。

2026-10-03 19:12:11 +08:00

4.5 KiB

Raw Blame History

群聊与单聊 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_member(group_openid, mute_expire_at)`	POST /v2/groups/{group_openid}/restrict_chat_setting	`mute_expire_at` 为 RFC3339 到期时间；传早于当前的时间即解禁
`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。

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

4.5 KiB Raw Blame History Unescape Escape