水缸机器人

Appearance

DTO 参考 ​

消息响应 ​

MessageResponse ​

发送消息/文件的 API 通用响应。

字段类型说明
id()String消息 ID（可用于后续撤回）
timestamp()String发送时间（RFC3339 东八区）
extInfo()MessageExtInfo扩展信息（可能为 null）

MessageExtInfo ​

消息扩展信息。

字段类型说明
refIdx()String引用消息索引（用于 quote 系列方法的 refIdx 参数）

StreamMessageResponse ​

流式消息发送响应。

字段类型说明
id()String消息 ID / stream_msg_id（首片）
timestamp()String发送时间（RFC3339）
extInfo()MessageExtInfo扩展信息
remainMsgLen()Integer流式消息剩余长度（续片/结束片返回）

EmptyResponse ​

空响应体，对应返回 {} 的 API 端点（撤回、禁言、审批等）。无字段。

消息场景与元素 ​

MessageScene ​

消息场景上下文，携带消息索引和鉴权信息。

字段类型说明
source()String场景来源（如 "default"）
ext()List<String>扩展数据列表（key=value 格式）

常用方法：

方法返回类型说明
msgIdx()String消息索引（引用回复的关键参数）
refMsgIdx()String被引用消息的索引（引用消息时有值）
authToken()String鉴权令牌

引用回复

msgIdx() 返回的值（如 REFIDX_xxx）是 quote 系列方法的 refIdx 参数。详见 Markdown 消息 - 引用回复。

ARKData ​

结构化卡片消息数据（message_type=3 时出现）。

字段类型说明
prompt()String用户操作提示文本
arkType()String卡片类型标识
arkName()String卡片类型中文名称
fields()Map<String, Object>卡片字段键值对

MsgElement ​

消息元素（引用消息时携带嵌套内容，支持递归）。

字段类型说明
msgIdx()String消息元素引用索引
author()Map<String, Object>消息发送者
messageType()int内容类型（0=文本, 3=卡片, 103=引用）
content()String消息正文
attachments()List<Map>附件列表
arkData()ARKData结构化卡片数据
msgElements()List<MsgElement>嵌套消息元素（递归）

消息构建 ​

MessageMarkdown ​

Markdown 消息负载。

字段类型说明
content()StringMarkdown 文本内容
forceVerifyImageResource()boolean是否校验图片转存结果

工厂方法：

方法说明
MessageMarkdown.of(content)创建 Markdown 消息
MessageMarkdown.of(content, forceVerify)创建 Markdown 消息（可指定校验）

MediaInfo ​

富媒体消息的 media 字段（msg_type=7 时使用）。

字段类型说明
fileInfo()String来自上传接口返回的 file_info

MessageReference ​

消息引用，用于引用回复。

字段类型说明
messageId()String被引用的消息 ID

InputNotify ​

输入中状态提示（仅单聊 msg_type=6）。

字段类型说明
inputType()int输入类型，固定 1
inputSecond()int持续时间（秒），最长 60

工厂方法：

方法说明
InputNotify.typing(seconds)创建"正在输入..."状态

Card ​

图文卡片消息（仅群聊 msg_type=8）。

字段类型说明
type()CardType卡片类型
content()CardContent卡片内容

工厂方法：

方法说明
Card.create(title, desc, picUrl, url)创建图文卡片

RenderData ​

按钮渲染数据。

字段类型说明
label()String按钮文字（最多 10 字符）
visitedLabel()String点击后文字
style()int按钮样式（0=灰, 1=蓝, 2=白字, 3=蓝底）

Action ​

按钮行为。

字段类型说明
type()ButtonActionType行为类型（JUMP/CALLBACK/COMMAND）
permission()Permission操作权限
data()String回调数据 / URL / 指令文本
unsupportTips()String低版本客户端提示
enter()Boolean指令按钮：点击后自动发送
reply()Boolean指令按钮：是否带引用回复

Permission ​

按钮权限。

字段类型说明
type()PermissionType权限类型
specifyUserIds()List<String>指定用户列表

工厂方法 / 常量：

方法说明
Permission.ALL所有人可用
Permission.admin()仅管理员
Permission.specify(userIds)指定用户

富媒体上传 ​

UploadResponse ​

富媒体上传响应。

字段类型说明
fileUuid()String文件唯一标识
fileInfo()String文件信息（发消息时透传）
ttl()int有效期（秒），0=长期
id()String消息 ID（srv_send_msg=true 时返回）
rawUrl()String下载链接（分片合并后返回）

UploadPrepareResponse ​

分片预上传响应。

字段类型说明
uploadId()String上传任务 ID
blockSize()String分片大小（字节）
parts()List<PartInfo>分片信息列表
uploadConfig()UploadConfig上传配置

嵌套记录：

PartInfo — 单个分片

字段类型说明
index()int分片序号
presignedUrl()String预签名上传 URL
blockSize()String分片大小

UploadConfig — 上传配置

字段类型说明
concurrency()int并发数
retryTimeout()int重试超时（秒）
retryDelay()int重试延迟（秒）

群信息 ​

GroupInfo ​

群基础信息。

字段类型说明
groupOpenid()String群 OpenID
groupName()String群名称
groupFingerMemo()String群简介
groupClassText()String群分类
groupTags()List<String>群标签列表
groupMemberNum()int群成员数量

BotGroupState ​

机器人在群内的状态。

字段类型说明
memberOpenid()String机器人在群内的 member_openid
joinedAt()String入群时间（RFC3339）
allowProactiveMsg()boolean是否允许主动发送消息
recvMsgSetting()RecvMsgSetting接收消息设置
memberRole()MemberRole群成员角色

常用方法：

方法返回类型说明
isOwner()boolean是否为群主
isAdmin()boolean是否为管理员（含群主）

分享链接 ​

UrlLinkResponse ​

生成分享链接响应。

字段类型说明
retcode()int响应码
msg()String响应消息
data()UrlLinkData数据对象

常用方法：

方法返回类型说明
getUrlLink()String获取分享链接（失败返回 null）

入群审批 ​

JoinRequest ​

入群申请（位于 dto.message.approval 包，注意不要与框架的 Request 混淆）。

字段类型说明
joinRequestId()String申请 ID
memberOpenid()String申请人 OpenID
username()String申请人昵称
applyAt()String申请时间（RFC3339）
applySource()ApplySource申请来源（SELF_APPLY/INVITED）
invitedBy()String邀请人 OpenID
riskTips()String安全提示
bot()boolean是否为机器人
verifyInfo()VerifyInfo验证信息

JoinRequestListResponse ​

入群申请列表响应。

字段类型说明
list()List<JoinRequest>申请列表
nextCursor()String下一页游标（空串=末页）

JoinApprovalStrategy ​

入群自动审批策略。

字段类型说明
strategyId()String策略 ID
groupOpenids()List<String>关联群 OpenID 列表
groupIds()List<String>关联 QQ 群号列表
whitelistUserCount()int白名单号码数
isEnable()StrategyEnable启用状态
expireAt()String过期时间
createdAt()String创建时间
updatedAt()String更新时间
remark()String备注

JoinApprovalStrategyCreateResponse ​

创建/修改策略响应。

字段类型说明
strategyId()String策略 ID
isEnable()StrategyEnable启用状态
expireAt()String过期时间

JoinApprovalStrategyListResponse ​

策略列表响应。

字段类型说明
strategies()List<JoinApprovalStrategy>策略列表
nextCursor()String下一页游标

WhitelistUsersResponse ​

白名单操作响应。

字段类型说明
strategyId()String策略 ID
whitelistUserCount()int操作后白名单总数
updatedAt()String更新时间

禁言 ​

GroupMuteStateResponse ​

群禁言状态响应。

字段类型说明
globalRule()GlobalMuteRule全员禁言配置
members()List<MemberMuteState>禁言中的成员列表

GlobalMuteRule ​

全员禁言规则。

字段类型说明
mode()MuteMode禁言模式
scheduleRules()List<MuteScheduleRule>定时禁言规则
recurringRules()List<MuteRecurringRule>周期禁言规则

常用方法：isAllMuted()、isScheduled()、isNone()

MemberMuteState ​

成员禁言状态。

字段类型说明
memberOpenid()String成员 OpenID
muteExpireAt()String禁言到期时间
username()String成员昵称
unionOpenid()String统一标识

面板 ​

PanelRecord ​

面板记录。

字段类型说明
panelId()String面板 ID
scope()PanelScope生效场景
targetType()PanelTargetType作用范围
items()List<PanelItem>面板元素列表
remark()String备注
version()Integer版本号

PanelListResponse ​

面板列表响应。

字段类型说明
records()List<PanelRecord>面板列表
nextCursor()String下一页游标

PanelCreateResponse ​

创建面板响应。

字段类型说明
panelId()String面板 ID

PanelUpdateResponse ​

修改面板响应。

字段类型说明
version()Integer新版本号

菜单 ​

查询菜单响应。

字段类型说明
menu()Menu菜单配置

修改菜单响应。

字段类型说明
version()Integer新版本号

枚举类型 ​

消息相关 ​

枚举值说明
MsgType.TEXT0普通文本
MsgType.MARKDOWN2Markdown
MsgType.INPUT_NOTIFY6输入中状态
MsgType.MEDIA7富媒体
MsgType.CARD8图文卡片
FileType.IMAGE1图片
FileType.VIDEO2视频
FileType.VOICE3语音
FileType.FILE4文件
CardType.TUWEN"tuwen"图文卡片
InputMode.APPEND"append"追加模式
InputMode.REPLACE"replace"替换模式
StreamContentType.TEXT"text"纯文本
StreamContentType.MARKDOWN"markdown"Markdown

按钮相关 ​

枚举值说明
ButtonStyle.GRAY0灰线框
ButtonStyle.BLUE1蓝线框
ButtonStyle.WHITE2白字
ButtonStyle.BLUE_BG3蓝底白字
ButtonActionType.JUMP0跳转
ButtonActionType.CALLBACK1回调
ButtonActionType.COMMAND2指令
PermissionType.SPECIFY_USER0指定用户
PermissionType.ADMIN1管理员
PermissionType.ALL2所有人

群相关 ​

枚举值说明
MemberRole.MEMBER"member"普通成员
MemberRole.OWNER"owner"群主
MemberRole.ADMIN"admin"管理员
RecvMsgSetting.ALL"all"接收所有消息
RecvMsgSetting.ONLY_MENTION"only_mention"仅 @机器人
RecvMsgSetting.MENTION_AND_CONTEXT"mention_and_context"@机器人 + 上下文
MuteMode.NONE"none"未开启禁言
MuteMode.ALWAYS"always"始终禁言
MuteMode.SCHEDULE"schedule"定时禁言
MuteOp.ADD"add"增加禁言
MuteOp.UPDATE"update"更新禁言
MuteOp.DEL"del"解除禁言

审批相关 ​

枚举值说明
ApprovalAction.APPROVE"approve"通过
ApprovalAction.DECLINE"decline"拒绝
StrategyEnable.ON"on"启用
StrategyEnable.OFF"off"关闭
ApplySource.SELF_APPLY—直接申请
ApplySource.INVITED—被邀请
GroupActionOp.ADD"add"添加关联群
GroupActionOp.DEL"del"删除关联群
WhitelistUsersOp.ADD"add"添加白名单
WhitelistUsersOp.DEL"del"删除白名单

面板相关 ​

枚举值说明
PanelScope.C2C"c2c"单聊
PanelScope.GROUP"group"群聊
PanelTargetType.ALL"all"全局生效
PanelTargetType.SPECIFIC"specific"指定目标
PanelTargetOp.ADD"add"添加关联
PanelTargetOp.DEL"del"删除关联
PanelItemType.COMMAND—指令
PanelItemType.LINK—链接

菜单相关 ​

枚举值说明
MenuItemType.SWITCH—开关
MenuItemType.SEND_MESSAGE—发送消息
MenuItemType.LINK—链接跳转
MenuItemType.MENU—子菜单
SubMenuItemType.SEND_MESSAGE—发送消息
SubMenuItemType.LINK—链接跳转