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

# 微号管理与消息发送

阅读本文件处理微号列表、微号分组、登录二维码、状态查询、发送消息、撤回、退出登录、二维码、迁移等操作。消息体结构见 [api-common.md](api-common.md)。

## 微号接口

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 微号机器人列表 | `POST /api/bot/wx/list` | `page`(int64, 可选，page)；`pageSize`(int64, 可选，pageSize)；`ids`(repeated int64, 可选，机器人ids)；`name`(string, 可选，机器人名称)；`statusList`(repeated int64, 可选，状态筛选)；`groupId`(int64, 可选，分组id，-1未分组 0所有机器人 大于0 根据分组选择机器人)；`botType`(int32, 必填，类型 1 个微 2企微)；`corpId`(string, 可选，主体id)；`threePartyService`(string, 可选，三方服务过滤部分字段使用)；`moduleName`(string, 可选)；`codeType`(int32, 可选，客户端类型 1本地 2云端)；`loginPlatform`(int32, 可选，登录平台 1 mac 2 Windows 3 ipad)；`onlyAbnormal`(bool, 可选，筛选出异常微号)；`botFunctionType`(int32, 必填，1 全功能 2 发单 3 群发 4 接粉) | `list`(repeated HttpBotInfo)；`page`(int64)；`pageSize`(int64)；`total`(int64)；`last`(bool) |
| 消息发送 | `POST /api/bot/wx/msg/send` | `botId`(int64, 必填，机器人id)；`targetId`(int64, 必填，群id获取联系人id)；`targetType`(string, 必填，发送对象 friend group)；`botType`(int32, 必填，类型 1 个微 2企微)；`msgType`(string, 必填，消息类型)；`text`(MessageText, 可选，文本消息)；`image`(MessageImage, 可选，图片消息)；`sticker`(MessageSticker, 可选，表情消息)；`video`(MessageVideo, 可选，视频消息)；`audio`(MessageAudio, 可选，音频)；`compositeImage`(MessageCompositeImage, 可选，合成图消息)；`miniProgram`(MessageMiniProgram, 可选，小程序消息)；`link`(MessageLink, 可选，链接消息)；`inviteGroup`(MessageInviteGroup, 可选，入群邀请 inviteGroup)；`freeVideo`(MessageFreeVideo, 可选，视频号 freeVideo)；`materialId`(int64, 可选，素材id) | `recordId`(int64)；`status`(string) |
| 单条消息记录信息 | `POST /api/bot/wx/msg/record/get` | `id`(int64, 可选)；`botType`(int32, 必填，类型 1 个微 2企微) | `id`(int64)；`status`(string，消息状态)；`failReason`(string，失败原因)；`retractStatus`(string，撤回状态 空 为可撤回 wait等待撤回,success成功 fail 失败)；`createTime`(int64，消息的创建时间)；`msgType`(string，消息类型)；`text`(MessageText，文本消息)；`image`(MessageImage，图片消息)；`sticker`(MessageSticker，表情消息)；`video`(MessageVideo，视频消息)；... |
| 消息记录列表(待确认需求) | `POST /api/bot/wx/msg/record/list` | `page`(int64, 可选)；`pageSize`(int64, 可选)；`botId`(int32, 可选)；`groupId`(int32, 可选)；`botType`(int32, 必填，类型 1 个微 2企微) | `list`(repeated MsgRecord)；`page`(int64)；`pageSize`(int64)；`total`(int64)；`last`(bool) |
| 消息撤回 | `POST /api/bot/wx/msg/record/retract` | `id`(int64, 可选)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 分组-创建 | `POST /api/bot/wx/category/add` | `name`(string, 必填，分组的名字)；`botType`(int32, 必填，类型 1 个微 2企微) | `id`(int64，id) |
| 分组-更新 | `POST /api/bot/wx/category/update` | `id`(int64, 必填，分组id)；`name`(string, 必填，分组名字)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 分组-删除 | `POST /api/bot/wx/category/del` | `id`(int64, 必填，分组id)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 分组-列表 | `POST /api/bot/wx/category/list` | `page`(int64, 可选，page)；`pageSize`(int64, 可选，pageSize)；`name`(string, 可选，分组名字)；`botType`(int32, 必填，类型 1 个微 2企微) | `list`(repeated CategoryItem，分组列表)；`page`(int64，page)；`pageSize`(int64，pageSize)；`total`(int64，total)；`last`(bool，last) |
| 分组-添加机器人 | `POST /api/bot/wx/category/botAdd` | `id`(int64, 必填，分组id)；`botIds`(repeated int64, 必填，组内-机器人id列表)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 分组-删除机器人 | `POST /api/bot/wx/category/botDel` | `id`(int64, 必填，分组id)；`botIds`(repeated int64, 必填，组内-机器人id列表)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 子账号拥有的机器人列表 | `POST /api/bot/wx/user/list` | `userId`(int64, 必填，子账号id)；`page`(int64, 必填，page)；`pageSize`(int64, 必填，pageSize)；`botName`(string, 可选，机器人名字)；`botType`(int32, 必填，类型 1 个微 2企微) | `list`(repeated HttpBotInfo，机器人列表)；`page`(int64，page)；`pageSize`(int64，pageSize)；`total`(int64，total)；`last`(bool，last) |
| 修改机器人描述 | `POST /api/bot/wx/remark/update` | `id`(int64, 必填，机器人id)；`remark`(string, 必填，备注)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 修改机器人备注名 | `POST /api/bot/wx/name/update` | `id`(int64, 必填，机器人id)；`name`(string, 必填，别名)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 消息发送统计-根据日期 | `POST /api/bot/wx/stats/msgSendData/byDate` | `date`(string, 可选，日期,不传默认为今日)；`botId`(int64, 必填，机器人id)；`botType`(int32, 必填，类型 1 个微 2企微) | `msgNum`(int64，消息发送数量)；`groupNum`(int64，在多少个群发送)；`friendNum`(int64，给多少个好友发消息)；`planNum`(int64，参与计划数) |
| 检查机器人在线状态 | `POST /api/bot/wx/checkOnline` | `ids`(repeated int64, 必填，检查的ids)；`botType`(int32, 必填，类型 1 个微 2企微) | `list`(repeated CheckResultItem，结果) |
| 更新机器人信息 | `POST /api/bot/wx/updateInfo` | `ids`(repeated int64, 必填，检查的ids)；`botType`(int32, 必填，类型 1 个微 2企微) | `list`(repeated ResultItem，结果) |
| 分组-排序 | `POST /api/bot/wx/category/sort` | `list`(repeated HttpCategorySortItem, 必填，列表)；`botType`(int32, 必填，类型 1 个微 2企微) | 空对象或无业务数据 |
| 获取机器人的个人二维码 | `POST /api/bot/wx/user/qrCode` | `style`(int32, 必填，选择样式)；`botId`(int64, 必填，机器人id)；`botType`(int32, 必填，1个微 2 企微)；`wxid`(string, 可选，微号的wxid) | 空对象或无业务数据 |
| 云端-获取登录二维码 | `POST /api/bot/wx/login/getQrcode` | `botKey`(string, 必填，botKey)；`addressId`(string, 可选，代理的城市代码)；`loginType`(int64, 必填，登录类型 0默认服务器登录 1 微蜂的app登录)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`clientVersion`(string, 必填，客户端版本 4.1.12 和 4.1.16)；`clientPlatform`(int32, 必填，客户端平台类型 1 mac 2 pc 3 ipad)；`token`(string, 可选，h5获取二维码的时候，授权token) | `code`(string，登录码)；`expireTime`(int64，二维码的过期时间 多少秒) |
| 云端-获取登录二维码登录状态 | `POST /api/bot/wx/login/scanStatus` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | `wxStatus`(int32，扫码状态,1 等待 2 成功 4取消)；`authStatus`(int32，授权状态 1成功 2失败)；`failReason`(string，失败原因)；`needVerifyCode`(bool，是否需要登录验证码)；`authUrl`(string，验证链接)；`loginAuthParam`(LoginAuthParam，登录验证参数)；`authQrcode`(string，验证二维码 app扫码) |
| 云端-新登录发送验证码 | `POST /api/bot/wx/login/codeVerify` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`code`(string, 必填，验证码) | 空对象或无业务数据 |
| 退出登录 | `POST /api/bot/wx/logout` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | 空对象或无业务数据 |
| 获取账号下的所有企微号的所在主体,需要主体id则需要从这里获取 | `POST /api/bot/wx/corp/list` | `{}` | `list`(repeated CorpInfoItem) |
| 更新微号的状态 | `POST /api/bot/wx/updateBotStatus` | `botId`(int64, 必填，微号id)；`botStatus`(int32, 必填，微号状态 0正常 1封禁)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | 空对象或无业务数据 |
| 微号管理-清空所有指令 | `POST /api/bot/wx/cleanAll/cmd` | `botId`(int64, 必填，微号id)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | 空对象或无业务数据 |
| 微号扫码添加好友 | `POST /api/bot/wx/scanQrcode/addFriend` | `botId`(int64, 必填，微号id)；`botType`(int32, 必填，机器人类型 1是个微 2企微) | 空对象或无业务数据 |
| 迁移微号 | `POST /api/bot/wx/transferBot` | `botIds`(repeated int64, 可选)；`targetAccountId`(int64, 可选)；`botType`(int32, 可选) | `successIds`(repeated int64，成功Id列表)；`failList`(repeated failItem，失败列表) |
| 联系人统计，目前只有客户数 | `POST /api/bot/wx/contactStats` | `ids`(repeated int64, 可选)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | `list`(repeated ContactStatsStatsItem，列表) |
| 登录码-自动登录 | `POST /api/bot/wx/login/autoLogin` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`addressId`(string, 可选，代理地址) | 空对象或无业务数据 |
| 登录码-推送确认登录 | `POST /api/bot/wx/login/push/confirmLogin` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | 空对象或无业务数据 |
| 解除微号异常 | `POST /api/bot/wx/releaseAbnormal` | `botIds`(repeated int64, 必填，微号ids)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | 空对象或无业务数据 |
| 微号管理-微号休眠状态变更 | `POST /api/bot/wx/sleep/update` | `botIds`(repeated int64, 必填，微号id)；`isSleep`(bool, 必填，是否休眠 true 是 false 否)；`botType`(int32, 可选) | `list`(repeated HttpWxbotSleepStatusUpdateItem) |
| 微号管理-微号扫码进群 | `POST /api/bot/wx/scanQrcode/joinGroup` | `botId`(int64, 必填，微号id)；`botType`(int32, 必填，机器人类型 1是个微 2企微)；`qrcodeUrl`(string, 可选，二维码的链接)；`groupUrl`(string, 可选，二维码扫描出来的群链接) | 空对象或无业务数据 |
| 云端h5-获取登录二维码 | `POST /api/bot/wx/login/h5/getQrcode` | `botKey`(string, 必填，botKey)；`addressId`(string, 可选，代理的城市代码)；`loginType`(int64, 必填，登录类型 0默认服务器登录 1 微蜂的app登录)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`clientVersion`(string, 必填，客户端版本 4.1.12 和 4.1.16)；`clientPlatform`(int32, 必填，客户端平台类型 1 mac 2 pc 3 ipad)；`token`(string, 可选，h5获取二维码的时候，授权token) | `code`(string，登录码)；`expireTime`(int64，二维码的过期时间 多少秒) |
| 云端h5-获取登录二维码登录状态 | `POST /api/bot/wx/login/h5/scanStatus` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微) | `wxStatus`(int32，扫码状态,1 等待 2 成功 4取消)；`authStatus`(int32，授权状态 1成功 2失败)；`failReason`(string，失败原因)；`needVerifyCode`(bool，是否需要登录验证码)；`authUrl`(string，验证链接)；`loginAuthParam`(LoginAuthParam，登录验证参数)；`authQrcode`(string，验证二维码 app扫码) |
| 云端h5-新登录发送验证码 | `POST /api/bot/wx/login/h5/codeVerify` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`code`(string, 必填，验证码) | 空对象或无业务数据 |
| 云端h5-唤醒登录 | `POST /api/bot/wx/login/h5/autoLogin` | `botKey`(string, 必填，botKey)；`botType`(int32, 必填，机器人类型 1是个微 2是企微)；`addressId`(string, 可选，代理地址) | 空对象或无业务数据 |
| 微号管理-修改微号头像 | `POST /api/bot/wx/user/modifyHeadImg` | `botId`(int64, 必填，微号id)；`botType`(int32, 必填，微号类型) | `link`(string，头像链接) |
| 微号管理-修改微号别名(仅支持企微云端号,本地号没有,个微号也没有) | `POST /api/bot/wx/user/modifyAliasName` | `id`(int64, 必填，微号id)；`aliasName`(string, 必填，别名) | 空对象或无业务数据 |
| 微号管理-刷新wstoken | `POST /api/bot/wx/user/refreshWsToken` | `botId`(int64, 必填，微号id)；`botType`(int32, 必填，微号类型) | `token`(string，token) |


## 常用示例

查询微号列表（`botType` 决定查询的是个微还是企微，**查企微必须传 `botType:2`**；账号下若没有个微号，照搬个微示例会得到 `total:0`）：

```bash
# 个微微号列表
htsy-cli call /api/bot/wx/list -d '{"page":1,"pageSize":20,"botType":1}'
# 企微微号列表
htsy-cli call /api/bot/wx/list -d '{"page":1,"pageSize":20,"botType":2}'
```

发送文本消息：

```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/category/add -d '{"name":"测试分组","botType":1}'
htsy-cli call /api/bot/wx/category/botAdd -d '{"id":10,"botIds":[1001,1002],"botType":1}'
```

获取登录二维码并查询状态：

```bash
htsy-cli call /api/bot/wx/login/getQrcode -d '{"botKey":"BOT_KEY","loginType":0,"botType":1,"clientVersion":"4.1.16","clientPlatform":2}'
htsy-cli call /api/bot/wx/login/scanStatus -d '{"botKey":"BOT_KEY","botType":1}'
```