# 通用字段与消息体

## 调用与返回约定

所有业务接口通过 `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` 引用消息。

发送文本示例：

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

发送链接示例：

```bash
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":"描述"}}'
```