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 内可以使用的权限列表。

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 指定的日程的详情。

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

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 返回一致。

GetMessageSettingApi

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

获取频道消息频率设置

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

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。