Simple Robot v4.6.0 Help

API定义列表

此处会列举 API 模块 中、 love.forte.simbot.qguild.api 包下定义的所有 QQGuildApi 实现。

GatewayApis

love.forte.simbot.qguild.api.GatewayApis

获取网关信息。

通过 Normal 或 Shared 的形式根据bot信息获取使用 Websocket 接入时间通知的链接。

Normal

love.forte.simbot.qguild.api.Normal

获取通用 WSS 接入点

Shared

love.forte.simbot.qguild.api.Shared

获取带分片 WSS 接入点

CreateAnnouncesApi

love.forte.simbot.qguild.api.announces.CreateAnnouncesApi

机器人设置消息为指定子频道公告。

创建子频道公告

DeleteAnnouncesApi

love.forte.simbot.qguild.api.announces.DeleteAnnouncesApi

删除子频道公告

机器人删除指定子频道公告

DemandApiPermissionApi

love.forte.simbot.qguild.api.apipermission.DemandApiPermissionApi

创建频道 API 接口权限授权链接

用于创建 API 接口权限授权链接，该链接指向 guild_id 对应的频道 。

需要注意，私信场景中，当需要查询私信来源频道的权限时，应使用 src_guild_id ，即 message 中的 src_guild_id

每天只能在一个频道内发 3 条（默认值）频道权限授权链接。

GetApiPermissionListApi

love.forte.simbot.qguild.api.apipermission.GetApiPermissionListApi

获取频道可用权限列表

用于获取机器人在频道 guild_id 内可以使用的权限列表。

GetAppAccessTokenApi

love.forte.simbot.qguild.api.app.GetAppAccessTokenApi

获取调用凭证

这个API似乎是一个特殊的API，它有自己的HTTP URL: https://bots.qq.com/app/getAppAccessToken， 使用时需要专门处理。

CreateChannelApi

love.forte.simbot.qguild.api.channel.CreateChannelApi

创建子频道

用于在 guild_id 指定的频道下创建一个子频道。

  • 要求操作人具有管理频道的权限，如果是机器人，则需要将机器人设置为管理员。

  • 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。

DeleteChannelApi

love.forte.simbot.qguild.api.channel.DeleteChannelApi

删除子频道

用于删除 channel_id 指定的子频道。

  • 要求操作人具有 管理子频道 的权限，如果是机器人，则需要将机器人设置为管理员。

  • 修改成功后，会触发子频道删除事件。

注意

子频道的删除是无法撤回的，一旦删除，将无法恢复。

GetChannelApi

love.forte.simbot.qguild.api.channel.GetChannelApi

获取子频道信息

GetChannelOnlineNumsApi

love.forte.simbot.qguild.api.channel.GetChannelOnlineNumsApi

获取在线成员数

用于查询音视频/直播子频道 channel_id 的在线成员数。

GetGuildChannelListApi

love.forte.simbot.qguild.api.channel.GetGuildChannelListApi

获取子频道列表

用于获取 guild_id 指定的频道下的子频道列表。

ModifyChannelApi

love.forte.simbot.qguild.api.channel.ModifyChannelApi

修改子频道

用于修改 channel_id 指定的子频道的信息。

  • 要求操作人具有 管理子频道 的权限，如果是机器人，则需要将机器人设置为管理员。

  • 修改成功后，会触发子频道更新事件。

GetChannelMemberPermissionsApi

love.forte.simbot.qguild.api.channel.permissions.GetChannelMemberPermissionsApi

获取指定子频道的权限

用于获取 子频道 channel_id 下用户 user_id 的权限。

  • 获取子频道用户权限。

  • 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。

GetChannelRolePermissionsApi

love.forte.simbot.qguild.api.channel.permissions.GetChannelRolePermissionsApi

获取子频道身份组权限

用于获取子频道 channel_id 下身份组 role_id 的权限。

  • 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。

ModifyChannelMemberPermissionsApi

love.forte.simbot.qguild.api.channel.permissions.ModifyChannelMemberPermissionsApi

修改子频道权限

用于修改子频道 channel_id 下用户 user_id 的权限。

  • 要求操作人具有 管理子频道 的权限，如果是机器人，则需要将机器人设置为管理员。

  • 参数包括 add 和 remove 两个字段，分别表示授予的权限以及删除的权限。 要授予用户权限即把 add 对应位置 1，删除用户权限即把 remove 对应位置 1。当两个字段同一位都为 1，表现为删除权限。

  • 本接口不支持修改 可管理子频道 权限。

ModifyChannelRolePermissionsApi

love.forte.simbot.qguild.api.channel.permissions.ModifyChannelRolePermissionsApi

修改子频道身份组权限

用于修改子频道 channel_id 下身份组 role_id 的权限。

  • 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。

  • 参数包括 add 和 remove 两个字段，分别表示授予的权限以及删除的权限。 要授予身份组权限即把 add 对应位置 1，删除身份组权限即把 remove 对应位置 1。当两个字段同一位都为 1，表现为删除权限。

  • 本接口不支持修改 可管理子频道 权限。

AddPinsMessageApi

love.forte.simbot.qguild.api.channel.pins.AddPinsMessageApi

添加精华消息

用于添加子频道 channel_id 内的精华消息。

  • 精华消息在一个子频道内最多只能创建 20 条。

  • 只有可见的消息才能被设置为精华消息。

  • 接口返回对象中 message_ids 为当前请求后子频道内所有精华消息 message_id 数组。

DeletePinsMessageApi

love.forte.simbot.qguild.api.channel.pins.DeletePinsMessageApi

删除精华消息

用于删除子频道 channel_id 下指定 message_id 的精华消息。

  • 删除子频道内全部精华消息，请将 message_id 设置为 [all] DELETE_ALL_MESSAGE_ID。

GetPinsMessageApi

love.forte.simbot.qguild.api.channel.pins.GetPinsMessageApi

获取精华消息

用于获取子频道 channel_id 内的精华消息。

CreateScheduleApi

love.forte.simbot.qguild.api.channel.schedules.CreateScheduleApi

创建日程

用于在 channel_id 指定的 日程子频道 下创建一个日程。

  • 要求操作人具有 管理频道 的权限，如果是机器人，则需要将机器人设置为管理员。

  • 创建成功后，返回创建成功的日程对象。

  • 创建操作频次限制

  • 单个管理员每天限 10 次。

  • 单个频道每天 100 次。

DeleteScheduleApi

love.forte.simbot.qguild.api.channel.schedules.DeleteScheduleApi

修改日程

用于修改日程子频道 channel_id 下 schedule_id 指定的日程的详情。

  • 要求操作人具有 管理频道 的权限，如果是机器人，则需要将机器人设置为管理员。

GetScheduleApi

love.forte.simbot.qguild.api.channel.schedules.GetScheduleApi

获取日程详情

获取日程子频道 channel_id 下 schedule_id 指定的的日程的详情。

GetScheduleListApi

love.forte.simbot.qguild.api.channel.schedules.GetScheduleListApi

获取频道日程列表

用于获取 channel_id 指定的子频道中当天的日程列表。

  • 若带了参数 since ，则返回在 since 对应当天的日程列表；若未带参数 since ，则默认返回今天的日程列表。

ModifyScheduleApi

love.forte.simbot.qguild.api.channel.schedules.ModifyScheduleApi

修改日程

用于修改日程子频道 channel_id 下 schedule_id 指定的日程的详情。

  • 要求操作人具有 管理频道 的权限，如果是机器人，则需要将机器人设置为管理员。

UploadGroupFilesApi

love.forte.simbot.qguild.api.files.UploadGroupFilesApi

富媒体消息-群聊

UploadUserFilesApi

love.forte.simbot.qguild.api.files.UploadUserFilesApi

富媒体消息-单聊

DeleteThreadApi

love.forte.simbot.qguild.api.forum.DeleteThreadApi

删除帖子

该接口用于删除指定子频道下的某个帖子。

GetThreadApi

love.forte.simbot.qguild.api.forum.GetThreadApi

获取帖子详情

该接口用于获取子频道下的帖子详情。

GetThreadListApi

love.forte.simbot.qguild.api.forum.GetThreadListApi

获取帖子列表

该接口用于获取子频道下的帖子列表。

PublishThreadApi

love.forte.simbot.qguild.api.forum.PublishThreadApi

发表帖子

GetGuildApi

love.forte.simbot.qguild.api.guild.GetGuildApi

获取频道详情

用于获取 guildId 指定的频道的详情。

MuteAllApi

love.forte.simbot.qguild.api.guild.mute.MuteAllApi

禁言全员

用于将频道的全体成员（非管理员）禁言。

需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。 该接口同样可用于解除禁言，将 mute_end_timestamp 或 mute_seconds 传值为字符串'0'即可。

MuteMemberApi

love.forte.simbot.qguild.api.guild.mute.MuteMemberApi

禁言指定成员

用于禁言频道 guild_id 下的成员 user_id。

需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。 该接口同样可用于解除禁言，将 mute_end_timestamp 或 mute_seconds 传值为字符串'0'即可。

MuteMultiMemberApi

love.forte.simbot.qguild.api.guild.mute.MuteMultiMemberApi

禁言批量成员

用于将频道的指定批量成员（非管理员）禁言。

需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。 该接口同样可用于批量解除禁言，将 mute_end_timestamp 或 mute_seconds 传值为字符串'0'即可，及需要批量解除禁言的成员的user_id列表user_ids'。

DeleteMemberApi

love.forte.simbot.qguild.api.member.DeleteMemberApi

删除频道成员

用于删除 guild_id 指定的频道下的成员 user_id。

  • 需要使用的 token 对应的用户具备踢人权限。如果是机器人，要求被添加为管理员。

  • 操作成功后，会触发频道成员删除事件。

  • 无法移除身份为管理员的成员

GetGuildMemberListApi

love.forte.simbot.qguild.api.member.GetGuildMemberListApi

获取频道成员列表

用于获取 guild_id 指定的频道中所有成员的详情列表，支持分页。

有关返回结果的说明

  1. 在每次翻页的过程中，可能会返回上一次请求已经返回过的 member 信息，需要调用方自己根据 user id 来进行去重。

  2. 每次返回的 member 数量与 limit 不一定完全相等。翻页请使用最后一个 member 的 user id 作为下一次请求的 after 参数，直到回包为空，拉取结束。

GetGuildRoleMemberListApi

love.forte.simbot.qguild.api.member.GetGuildRoleMemberListApi

获取频道身份组成员列表

用于获取 guild_id 频道中指定 role_id 身份组下所有成员的详情列表，支持分页。

有关返回结果的说明

  1. 每次返回的member数量与limit不一定完全相等。特定管理身份组下的成员可能存在一次性返回全部的情况

GetMemberApi

love.forte.simbot.qguild.api.member.GetMemberApi

获取某个成员信息

用于获取 guild_id 指定的频道中 user_id 对应成员的详细信息。

DeleteMessageApi

love.forte.simbot.qguild.api.message.DeleteMessageApi

撤回消息

用于撤回子频道 channel_id 下的消息 message_id。

  • 管理员可以撤回普通成员的消息。

  • 频道主可以撤回所有人的消息。

GetMessageApi

love.forte.simbot.qguild.api.message.GetMessageApi

获取指定消息

用于获取子频道 channel_id 下的消息 message_id 的详情。

MessageSendApi

love.forte.simbot.qguild.api.message.MessageSendApi

发送消息

用于向 channel_id 指定的子频道发送消息。

  • 要求操作人在该子频道具有 发送消息 的权限。

  • 主动消息在频道主或管理设置了情况下，按设置的数量进行限频。在未设置的情况遵循如下限制:

  • 主动推送消息，默认每天往每个子频道可推送的消息数是 20 条，超过会被限制。

  • 主动推送消息在每个频道中，每天可以往 2 个子频道推送消息。超过后会被限制。

  • 不论主动消息还是被动消息，在一个子频道中，每 1s 只能发送 5 条消息。

  • 被动回复消息有效期为 5 分钟。超时会报错。

  • 发送消息接口要求机器人接口需要连接到 websocket 上保持在线状态

  • 有关主动消息审核，可以通过 Intents 中审核事件 MESSAGE_AUDIT 返回 MessageAudited 对象获取结果。

主动消息与被动消息

  • 主动消息：发送消息时，未填充 msg_id/event_id 字段的消息。

  • 被动消息：发送消息时，填充了 msg_id/event_id 字段的消息。 msg_id 和 event_id 两个字段任意填一个即为被动消息。 接口使用此 msg_id/event_id 拉取用户的消息或事件，同时判断用户消息或事件的发送时间，如果超过被动消息回复时效，将会不允许发送该消息。

更多参考 文档

发送 ARK 模板消息

通过指定 ark 字段发送模板消息。

  • 要求操作人在该子频道具有发送消息和 对应 ARK 模板 的权限。

  • 调用前需要先申请消息模板，这一步会得到一个模板 id ，在请求时填在 ark.template_id 上。

  • 发送成功之后，会触发一个创建消息的事件。

  • 可用模板参考可用模板。

更多参考 文档

发送引用消息

  • 只支持引用机器人自己发送到的消息以及用户@机器人产生的消息。

  • 发送成功之后，会触发一个创建消息的事件。

不能单独发送引用消息，引用消息需要和其他消息类型组合发送，参数请见发送消息。

更多参考 文档

发送含有消息按钮组件的消息

通过指定 keyboard 字段发送带按钮的消息，支持 keyboard 模版 和 自定义 keyboard 两种请求格式。

  • 要求操作人在该子频道具有 发送消息 和 对应消息按钮组件 的权限。

  • 请求参数 keyboard 模版 和 自定义 keyboard 只能单一传值。

  • keyboard 模版

  • 调用前需要先申请消息按钮组件模板，这一步会得到一个模板 id，在请求时填在 keyboard 字段上。

  • 申请消息按钮组件模板需要提供响应的 json，具体格式参考 InlineKeyboard。

  • 仅 markdown 消息支持消息按钮。

更多参考 文档

内嵌格式

利用 content 字段发送内嵌格式的消息。

  • 内嵌格式仅在 content 中会生效，在 Ark 和 Embed 中不生效。

  • 为了区分是文本还是内嵌格式，消息抄送和发送会对消息内容进行相关的转义。

转义内容

源字符

转义后

&

&

<

&lt;

>

&gt;

可参考使用 ContentTextDecoder 和 ContentTextEncoder

消息审核

当响应结果为上述错误码时，请求实体对象结果的API时会抛出 MessageAuditedException 异常并携带相关的对象信息。

详见文档 发送消息 中的相关描述以及 MessageAuditedException 的文档描述。

更多参考 文档

CreateDmsApi

love.forte.simbot.qguild.api.message.direct.CreateDmsApi

创建私信会话

用于机器人和在同一个频道内的成员创建私信会话。

机器人和用户存在共同频道才能创建私信会话。 创建成功后，返回创建成功的频道 id ，子频道 id 和创建时间。

参数

字段名

类型

描述

recipient_id

string

接收者 id

source_guild_id

string

源频道 id

DeleteDmsApi

love.forte.simbot.qguild.api.message.direct.DeleteDmsApi

撤回私信

用于撤回私信频道 guild_id 中 message_id 指定的私信消息。只能用于撤回机器人自己发送的私信。

DmsSendApi

love.forte.simbot.qguild.api.message.direct.DmsSendApi

发送私信

接口

POST /dms/{guild_id}/messages

功能描述

用于发送私信消息，前提是已经创建了私信会话。

  • 私信的 guild_id 在创建私信会话时以及私信消息事件中获取。

  • 私信场景下，每个机器人每天可以对一个用户发 2 条主动消息。

  • 私信场景下，每个机器人每天累计可以发 200 条主动消息。

  • 私信场景下，被动消息没有条数限制。

参数

和 [发送消息] MessageSendApi 参数一致。

返回

和 [发送消息] MessageSendApi 返回一致。

GroupMessageSendApi

love.forte.simbot.qguild.api.message.group.GroupMessageSendApi

发送消息到群

GetMessageSettingApi

love.forte.simbot.qguild.api.message.setting.GetMessageSettingApi

获取频道消息频率设置

用于获取机器人在频道 guild_id 内的消息频率设置。

UserMessageSendApi

love.forte.simbot.qguild.api.message.user.UserMessageSendApi

发送消息-单聊

单独发动消息给用户。

AddMemberRoleApi

love.forte.simbot.qguild.api.role.AddMemberRoleApi

增加频道身份组成员

用于将频道 guild_id 下的用户 user_id 添加到身份组 role_id。

  • 需要使用的 token 对应的用户具备增加身份组成员权限。如果是机器人，要求被添加为管理员。

  • 如果要增加的身份组 ID 是 [5-子频道管理员] love.forte.simbot.qguild.model.Role.DEFAULT_ID_CHANNEL_ADMIN， 需要增加 channel 对象来指定具体是哪个子频道。

CreateGuildRoleApi

love.forte.simbot.qguild.api.role.CreateGuildRoleApi

创建频道身份组

用于在 guild_id 指定的频道下创建一个身份组。

  • 需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。

  • 参数为非必填，但至少需要传其中之一，默认为空或 0。

DeleteGuildRoleApi

love.forte.simbot.qguild.api.role.DeleteGuildRoleApi

删除频道身份组

用于删除频道 guild_id 下 role_id 对应的身份组。

需要使用的 token 对应的用户具备删除身份组权限。如果是机器人，要求被添加为管理员。

GetGuildRoleListApi

love.forte.simbot.qguild.api.role.GetGuildRoleListApi

获取频道身份组列表

用于获取 guild_id 指定的频道下的身份组列表。

ModifyGuildRoleApi

love.forte.simbot.qguild.api.role.ModifyGuildRoleApi

修改频道身份组

用于修改频道 guild_id 下 role_id 指定的身份组。

  • 需要使用的 token 对应的用户具备修改身份组权限。如果是机器人，要求被添加为管理员。

  • 接口会修改传入的字段，不传入的默认不会修改，至少要传入一个参数。

RemoveMemberRoleApi

love.forte.simbot.qguild.api.role.RemoveMemberRoleApi

删除频道身份组成员

用于将 用户 user_id 从 频道 guild_id 的 role_id 身份组中移除。

  • 需要使用的 token 对应的用户具备删除身份组成员权限。如果是机器人，要求被添加为管理员。

  • 如果要删除的身份组 ID 是 [5-子频道管理员] love.forte.simbot.qguild.model.Role.DEFAULT_ID_CHANNEL_ADMIN， 需要增加 channel 对象来指定具体是哪个子频道。

GetBotGuildListApi

love.forte.simbot.qguild.api.user.GetBotGuildListApi

获取用户频道列表

用于获取当前用户（机器人）所加入的频道列表，支持分页。

当 HTTP Authorization 中填入 Bot Token 是获取机器人的数据，填入 Bearer Token 则获取用户的数据。

GetBotInfoApi

love.forte.simbot.qguild.api.user.GetBotInfoApi

获取用户详情

用于获取当前用户（机器人）详情。

由于 GetBotInfoApi 本身为 object 类型, 因此 ApiDescription 由内部对象 Description 提供而不是伴生对象。

GetBotInfoApi 得到的 User 中， User.isBot 始终为 true。

Last modified: 19 September 2024
API事件定义列表