tuitui-bot

推推机器人异步 Python SDK，移植自 npm 包 @qihoo/tuitui-bot-sdk。支持 Python 3.10 及以上版本。

安装

pip install tuitui-bot

推推机器人 SDK 迭代较快，可能包含不兼容变更。建议固定到明确版本，不要使用 >=、~= 等自动升级范围；升级前先完成兼容性验证。

发送消息

import asyncio

from tuitui_bot import TuituiBotClient


async def main() -> None:
    client = TuituiBotClient("your-app-id", "your-app-secret")
    try:
        response = await client.im.send_text(
            to=client.to.account("user-account"),
            text="你好，来自 `python` SDK",
        )
        print("消息发送成功", response)
    except Exception as error:
        print("消息发送失败", error)


asyncio.run(main())

SDK 使用 client.to.account()、uid()、group()、accounts() 和 uids() 创建单聊或群聊目标， 频道和帖子能力位于 client.teams。

消息、团队、文件和机器人属性等 API 调用失败时都会抛出异常，使用方应捕获并记录完整错误。接口错误 会抛出 TuituiApiError，异常文本包含底层网络错误。错误详情中的 trans_id 是本次 API 调用的上下文 ID；遇到难以定位的问题时，可将该 ID 和错误消息提交给推推技术支持团队。

事件订阅（收消息）

事件订阅通过 WebSocket 持续接收单聊、群聊、团队帖子和交互回调。只发送消息时不需要订阅；完整代码 见 samples/receive.py，消息结构见 SDK 导出的 TuituiMessageData。

SDK 自动确认事件、过滤心跳并去重。连接异常时会自动重连；如需感知错误，通过 on_error 记录日志， 不需要自行重连。调用 await subscription.unsubscribe() 后会关闭连接并停止重连。

发送交互式卡片

SDK 接收推推原生交互卡片结构，业务可以定义自己的模板。具体字段请参考 SDK 导出的 TuituiOutboundInteractiveMessage 类型以及推推 API 文档，完整代码请参考 samples/send_interactive.py。

最佳实践

需要提前开启事件订阅（收消息）。发送交互式卡片后，用户点击同意、拒绝等按钮时，会收到一条类型为 interactive 的消息。处理完业务逻辑后，应调用 client.im.modify_interactive() 原地更新卡片，删除 操作按钮并显示“已同意”或“已拒绝”等最终状态文案，不应继续保留可点击按钮，给用户操作反馈同时 避免用户重复操作。

Agent 执行中间步骤上报

client.agent 提供 Agent 执行中间步骤的类型化、保序上报能力。具体调用示例请查看 samples/agent_report.py。

API

• client.im：发送单聊、群聊消息（文本、图片、图文、页面、链接、文件和交互卡片）、编辑消息、表情回复和拉取聊天记录。
• client.teams：团队、频道、帖子 API。
• client.file：底层公共文件 API，可用于消息、帖子等场景。
• client.file_space：文件空间，目前仅用于团队模块，包含文件、目录的新增、列表和删除。
• client.group：建群、群成员管理及群信息查询。
• client.property：机器人自身属性查询与修改（名称、账号、头像、Webhook、可交互式消息回调地址和快捷指令）。
• client.event：通过 WebSocket 订阅推推事件，用于实时收消息等场景。
• client.agent：上报 Agent 执行中间步骤（模型调用、工具调用），供推推客户端展示。
• client.request()：调用尚未封装的原始 Bot API。

消息、帖子的内容支持 Markdown 格式（可交互式消息除外）。

示例

包含收、发消息示例，用法详见 samples/README.md。