htsy-skill/htsy/references/api-common.md

通用字段与消息体

调用与返回约定

所有业务接口通过 htsy-cli call <接口路径> -d '<JSON>' 调用。空请求体使用 {}。接口返回通常由网关包装为成功响应，文档中的“常用返回字段”指 data 内部字段。

通用字段：

字段	说明
page, pageSize	分页页码和每页数量，通常从 1 开始。
botType	微号类型：1 个微，2 企微。
codeType	席位/授权码类型：常见 1 客户端/本地，2 协议/云端。
botId	微号机器人 ID。
botKey	席位码/授权码。
wxid	微信实体 ID，可指客户、群或微号自身。
targetType	发送目标类型，常见 friend 客户、group 群。
时间字段	未特别说明时按毫秒时间戳处理。

api.common.Message

用于消息发送、素材、话术、群发、SOP 等场景。顶层字段：msgType 必填；根据 msgType 只填对应消息体字段，例如 text、image、link。

msgType	消息体字段	字段说明
text	text	content 文本内容；atList 客户 ID 列表；at at 字符串列表。
image	image	link 图片链接。
sticker	sticker	link 表情链接。
video	video	link 视频链接。
audio	audio	link 语音链接；可选 fileId, size, voiceTime, aesKey, md5。
file	file	link 文件链接；fileName 指定文件名。
link	link	title, link, imgUrl, desc。
miniProgram	miniProgram	appid, pagePath, title, imgUrl, appIcon, appName, username。
group	group	id 群 wxid；可选 promotionalMsgList, promotionalMsgInterval。
inviteGroup	inviteGroup	入群邀请计划：id, name, groups, rule, botType, type, autoStop, checkInGroup 等。
dialogue	dialogue	id 话术库 ID。
materialGroup	materialGroup	素材组列表，每项结构接近 Message，另有 materialId。
freeVideo	freeVideo	视频号字段：objectId, objectNonceId, userName, nickName, avatar, desc, thumbUrl, url, feedType。
liveBroadcastRoom	liveBroadcastRoom	直播间字段：feedType, coverUrl, thumbUrl, avatar, nickname, desc, url, extras, objectId, objectNonceId。
bizCard	bizCard	名片消息，按业务返回的名片数据填写。
note	note	笔记消息，按业务返回的笔记数据填写。

通用可选字段：role 角色名；delayTime 延迟毫秒；delayType 延迟单位 s/m/h；materialId 素材 ID；traceId 发送追踪；top 是否置顶；quoteMessage/quoteId 引用消息。

发送文本示例：

htsy-cli call /api/bot/wx/msg/send -d '{"botId":1001,"targetId":2002,"targetType":"friend","botType":1,"msgType":"text","text":{"content":"hello"}}'

发送链接示例：

htsy-cli call /api/bot/wx/msg/send -d '{"botId":1001,"targetId":2002,"targetType":"friend","botType":1,"msgType":"link","link":{"title":"标题","link":"https://example.com","imgUrl":"https://example.com/a.jpg","desc":"描述"}}'