NcatBot 文档

外观

API 调用

约 624 字大约 2 分钟

2025-01-23

NcatBot 推荐使用异步 API, 但从 3.7.0 版本起, 所有 API 均已经提供同步支持.

典型反应

提示

如果你此前未了解异步, 可以先使用同步方法, 过程中逐渐学习异步.

介绍

NcatBot 提供 API 调用, 用于完成各种操作.

提供 API 的类是 BotAPI. BotClient 类的成员 api, 也就是示例代码中的 bot.api, 就是一个 BotAPI 实例.

调用 API 接口

在回调函数中, 调用 bot.api 的成员方法即可完成回复.

注意, 当使用 bot.api 中的异步方法, 调用时必须加上 await 关键字.

所有的同步方法均以 xxx_sync() 结尾, 如果一个方法的异步版本是 bot.api.xxx(), 那么异步版本的函数名是 bot.api.xxx_async(). 典例是 post_group_msg() 和 post_group_msg_sync().

注意

任何形如 bot.api.xxx() 的调用都是错误用法, 只有 await bot.api.xxx() 或者 bot.api.xxx_sync() 才是正确用法.

python
@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == '测试':
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 异步调用测试成功喵~")
        bot.api.post_private_msg_sync(msg.user_id, text="NcatBot 同步调用测试成功喵~")

bot.api 还有其它成员方法, 用于完成其它类型的操作, 例如加群审核等, 请参考 主要 API 及其使用 和 其它 API 及其使用

同步回调函数

3.7.0 版本后, 大部分回调函数可以被定义为同步回调函数, 同步回调函数中禁止调用异步 API.

API 调用返回值

所有 API 调用返回结果均为 dict。返回值可以这样获取：

result = await api.post_group_message("123456", "喵喵喵") # 异步
result = api.post_group_message_sync("123456", "喵喵喵") # 同步

提示

由于 await 符号优先级的问题，永远推荐先把返回值赋给 result 后再做进一步处理。

返回值保证和 NapCat 的规定一致，可查阅 NapCat 的相关规定。

下面介绍几个常用的值。

通用

retcode

result['retcode']: int：当 retcode 为 0 时表示操作成功，否则表示发生意外。

result = await api.post_group_message("123456", "喵喵喵") # 异步
if result['retcode'] == 0:
    print("发送成功")
else:
    print("发送失败")

发送消息相关的返回值

message_id

result['data']['message_id']: int：表示此条消息的 ID，可以用于转发消息。

data = await self.api.post_private_msg(msg.self_id, text="Star NcatBot 谢谢喵: https://github.com/liyihao1110/ncatbot")
forward_messages.append(data["data"]["message_id"])
await self.api.send_group_forward_msg(
    group_id=msg.group_id,
    messages=forward_messages,
)

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot