htsy-skill/references/api-customer.md

# 客服与知识库

阅读本文件处理客服会话、客服消息、客服 AI、知识库、飞书配置、客服微号列表等操作。

## 客服接口

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 客服消息-发送 | `POST /api/customer/msg/send` | `chatType`(string, 必填，群group 好友 friend)；`sender`(int64, 必填，接收者id)；`botId`(int64, 必填，机器人Id)；`botType`(int64, 必填，机器人类型)；`msgType`(string, 必填，消息类型)；`text`(MessageText, 可选，文本消息)；`image`(MessageImage, 可选，图片消息)；`sticker`(MessageSticker, 可选，表情消息)；`video`(MessageVideo, 可选，视频消息)；`audio`(MessageAudio, 可选，音频)；`file`(MessageFile, 可选，文件)；`compositeImage`(MessageCompositeImage, 可选，合成图消息)；`miniProgram`(MessageMiniProgram, 可选，小程序消息)；`link`(MessageLink, 可选，链接消息)；`inviteGroup`(MessageInviteGroup, 可选，入群邀请 inviteGroup)；`freeVideo`(MessageFreeVideo, 可选，视频号 freeVideo)；`group`(MessageGroup, 可选，群号)；`liveBroadcastRoom`(MessageLiveBroadcastRoom, 可选，直播间消息)；`dialogue`(Dialogue, 可选，话术库id)；`materialGroup`(repeated MaterialGroup, 可选，素材组)；... 另有 5 个字段 | `message`(MessageItem，消息)；`time`(int64，发送时间)；`sender`(string，发送者的wxid， 有可能是botwxid，有可能是好友的wxid)；`senderBot`(bool，是否是机器人)；`senderAvatar`(string，发送者头像)；`name`(string，昵称)；`status`(string，状态)；`failReason`(string，原因)；`msgId`(string，消息id)；`wxMsgId`(string，微信的msgId)；... |
| 消息撤回 | `POST /api/customer/msg/retract` | `chatType`(string, 必填，群group 好友 friend)；`sender`(int64, 必填，接收者id)；`botId`(int64, 必填，机器人Id)；`botType`(int64, 必填，机器人类型)；`msgId`(string, 必填，微信官方的msgID) | 空对象或无业务数据 |
| 发送话术库 | `POST /api/customer/msg/send/dialogue` | `chatType`(string, 必填，群group 好友 friend)；`sender`(int64, 必填，接收者id)；`botId`(int64, 必填，机器人Id)；`botType`(int64, 必填，机器人类型)；`msgType`(string, 必填，消息类型)；`text`(MessageText, 可选，文本消息)；`image`(MessageImage, 可选，图片消息)；`sticker`(MessageSticker, 可选，表情消息)；`video`(MessageVideo, 可选，视频消息)；`audio`(MessageAudio, 可选，音频)；`file`(MessageFile, 可选，文件)；`compositeImage`(MessageCompositeImage, 可选，合成图消息)；`miniProgram`(MessageMiniProgram, 可选，小程序消息)；`link`(MessageLink, 可选，链接消息)；`inviteGroup`(MessageInviteGroup, 可选，入群邀请 inviteGroup)；`freeVideo`(MessageFreeVideo, 可选，视频号 freeVideo)；`group`(MessageGroup, 可选，群号)；`liveBroadcastRoom`(MessageLiveBroadcastRoom, 可选，直播间消息)；`dialogue`(Dialogue, 可选，话术库id)；`materialGroup`(repeated MaterialGroup, 可选，素材组)；... 另有 5 个字段 | `list`(repeated MsgRecordItem，消息) |
| 消息转发 | `POST /api/customer/msg/forward` | `chatType`(string, 必填，群group 好友 friend)；`sender`(int64, 必填，接收者id)；`botId`(int64, 必填，机器人Id)；`botType`(int64, 必填，机器人类型)；`message`(MessageItem, 必填，消息) | `message`(MessageItem，消息)；`time`(int64，发送时间)；`sender`(string，发送者的wxid， 有可能是botwxid，有可能是好友的wxid)；`senderBot`(bool，是否是机器人)；`senderAvatar`(string，发送者头像)；`name`(string，昵称)；`status`(string，状态)；`failReason`(string，原因)；`msgId`(string，消息id)；`wxMsgId`(string，微信的msgId)；... |
| 客服会话-所有的消息对象 | `POST /api/customer/list` | `targetType`(string, 必填，不传默认都有：群group 好友 friend)；`botId`(int64, 可选，可不传，用作筛选：机器人Id)；`name`(string, 可选，可不传，用作筛选：名称)；`msgType`(int64, 必填，0所有 1 已接待已读 2 接待中已读 3 接待中未读 4已接待 5接待中)；`offset`(int64, 可选，上一次最后一条的开始时间)；`start`(int64, 可选，从第几条开始)；`limit`(int64, 可选，不传默认1万条，一次多少条)；`customerUserId`(int64, 可选，客服账号id，只有主账号请求有效)；`isCollect`(bool, 可选，true 筛选出收藏的客户)；`tag`(repeated int64, 可选，标签)；`qwTag`(repeated string, 可选，企微标签 第一个主体 后面接标签值) | `list`(repeated MsgItem)；`offset`(int64，最后一条消息的时间戳)；`last`(bool，是否已结束)；`total`(int64，总数) |
| 客服会话-所有的消息对象中进行搜索 | `POST /api/customer/list/search` | `targetType`(string, 必填，不传默认都有：群group 好友 friend)；`targetId`(int64, 可选，可不传，用作筛选：群groupID 好友 friendId)；`botId`(int64, 可选，可不传，用作筛选：机器人Id)；`name`(string, 可选，可不传，用作筛选：名称)；`msgType`(int64, 必填，0所有 1 已接待已读 2 接待中已读 3 接待中未读 4已接待 5接待中)；`start`(int64, 必填，从第几条开始)；`limit`(int64, 必填，不传默认1万条，一次多少条)；`customerUserId`(int64, 可选，客服账号id，只有主账号请求有效)；`tag`(repeated int64, 可选，标签)；`qwTag`(repeated string, 可选，企微标签 第一个主体 后面接标签值) | `list`(repeated MsgSearchItem)；`offset`(int64，最后一条消息的时间戳)；`last`(bool，是否已结束)；`total`(int64，总数) |
| 客服会话-某个消息对象的聊天记录 | `POST /api/customer/record/list` | `startTime`(int64, 必填，开始时间)；`endTime`(int64, 必填，结束时间)；`offset`(int64, 必填，上一次最后一条的开始时间)；`limit`(int64, 必填，一次多少条)；`nextId`(int64, 必填，下一个id)；`ids`(string, 必填，botID_FriendId_GroupId) | `list`(repeated MsgRecordItem，记录列表)；`offset`(int64，最后一条消息的时间戳)；`last`(bool，是否已结束)；`total`(int64，总数)；`nextId`(int64，下一个id) |
| 客服会话-获取聊天界面的群或者客户的最新一条数据 | `POST /api/customer/latest` | `customerUserId`(int64, 可选，客服账号id，只有主账号请求有效)；`idList`(repeated string, 必填，[]botID_FriendId_GroupId) | `list`(repeated MsgLatestReplyItem) |
| 客服会话-改变同一条聊天记录的接待状态 | `POST /api/customer/msg/change` | `msgType`(int64, 必填，1 已接待已读 2 接待中已读 3 接待中未读 4已接待 5接待中)；`ids`(string, 必填，botID_FriendId_GroupId) | `msgType`(int64，改变后的状态 1 已接待已读 2 接待中已读 3 接待中未读 4已接待 5接待中) |
| 客服会话-标记这条消息已读 | `POST /api/customer/msg/read` | `sendTime`(int64, 可选，发送时间)；`ids`(string, 必填，botID_FriendId_GroupId) | 空对象或无业务数据 |
| 根据senderInfo获取 | `POST /api/customer/sender/info` | `senders`(repeated string, 必填，格式为: sender-bot 或者 sender-friend 或者 sender-group) | `senderList`(repeated SenderInfo，发送者的info) |
| 客服会话-根据cdn参数下载资源 | `POST /api/customer/download` | `cdnType`(int32, 必填，c2c 2 微信：)；`qwCdn`(QwCdn, 可选)；`msgType`(string, 可选)；`botId`(int64, 可选)；`traceId`(string, 可选，聊天记录的traceId)；`chatType`(string, 可选，聊天类型) | `link`(string) |
| 客服会话-客服转接 | `POST /api/customer/switch` | `userId`(int64, 必填，转接给哪一个用户的用户id)；`ids`(repeated string, 必填，转接的对象；botId_friendId_GroupId) | `fail`(string)；`failList`(repeated string) |
| 客服配置-添加关键词过滤，客户过滤，接收群设置 | `POST /api/customer/config/add` | `userId`(int64, 必填，子账号)；`groupRange`(repeated int64, 可选，监听退群进群事件的群范围)；`friendFilter`(repeated int64, 可选，需要过滤的客户)；`friendRange`(repeated int64, 可选，只接收的客户)；`keyWordRule`(repeated keyWordRuleItem, 可选，关键词规则：eg：[{"content":"文本","type":"eq"}])；`tagRange`(repeated string, 可选，只接收拥有这个标签的客户)；`allocationUpperLimit`(int64, 可选，接待上限)；`isRealRead`(bool, 可选，是否点到企微的未读)；`config`(google.protobuf.Value, 可选，个人配置)；`filters`(repeated Filter, 可选，条件筛选)；`receivedAutoDel`(receiveAutoDelItem, 可选，已接待自动延时或者立即删除)；`receiveGroupRange`(map<int64, int64>, 可选，设置客服接待的客户群，以及指定客户群的监听的微号)；`receptionTimeRange`(repeated ReceptionTimeRangeItem, 可选，上班时间范围)；`defaultReplyList`(repeated DefaultReply, 可选，默认回复) | 空对象或无业务数据 |
| 客服配置-主账号获取子账号自身的配置 | `POST /api/customer/config/get` | `userId`(int64, 可选) | `id`(int64，id)；`accountId`(int64，主账号id)；`userId`(int64，子账号id)；`groupRange`(repeated int64，可见群)；`friendFilter`(repeated int64，需要过滤的客户)；`friendRange`(repeated int64，只接收的客户)；`keyWordRule`(repeated keyWordRuleItem，关键词规则：eg：[{"content":"文本","type":"eq"}])；`tagRange`(repeated string，只接收拥有这个标签的客户)；`allocationUpperLimit`(int64，接待上限)；`username`(string，账号)；... |
| 客服配置-子账号获取自身的配置 | `POST /api/customer/config/getByUserId` | `{}` | `id`(int64，id)；`accountId`(int64，主账号id)；`userId`(int64，子账号id)；`groupRange`(repeated int64，可见群)；`friendFilter`(repeated int64，需要过滤的客户)；`friendRange`(repeated int64，只接收的客户)；`keyWordRule`(repeated keyWordRuleItem，关键词规则：eg：[{"content":"文本","type":"eq"}])；`tagRange`(repeated string，只接收拥有这个标签的客户)；`allocationUpperLimit`(int64，接待上限)；`username`(string，账号)；... |
| 客服配置-子账号设置自己的个人设置 | `POST /api/customer/config/user/set` | `config`(google.protobuf.Value, 可选，个人配置)；`isRealRead`(bool, 可选，是否点到企微的未读) | 空对象或无业务数据 |
| 客服配置-根据id删除相关配置 | `POST /api/customer/config/del` | `id`(int64, 可选) | 空对象或无业务数据 |
| 客服配置-对客服配置进行更新 | `POST /api/customer/config/update` | `id`(int64, 必填，id)；`userId`(int64, 必填，子账号)；`groupRange`(repeated int64, 可选，可见群)；`friendFilter`(repeated int64, 可选，需要过滤的客户)；`friendRange`(repeated int64, 可选，只接收的客户)；`keyWordRule`(repeated keyWordRuleItem, 可选，关键词规则：eg：[{"content":"文本","type":"eq"}])；`tagRange`(repeated string, 可选，只接收拥有这个标签的客户)；`allocationUpperLimit`(int64, 可选，接待上限)；`isRealRead`(bool, 可选，是否点到企微的未读)；`config`(google.protobuf.Value, 可选，个人配置)；`filters`(repeated Filter, 可选，条件筛选)；`receivedAutoDel`(receiveAutoDelItem, 可选，已接待自动延时或者立即删除)；`receiveGroupRange`(map<int64, int64>, 可选，设置客服接待的客户群，以及指定客户群的监听的微号)；`receptionTimeRange`(repeated ReceptionTimeRangeItem, 可选，上班时间范围)；`defaultReplyList`(repeated DefaultReply, 可选，默认回复) | 空对象或无业务数据 |
| 客服配置-获取客服配置列表 | `POST /api/customer/config/list` | `page`(int64, 可选)；`pageSize`(int64, 可选) | `list`(repeated CustomerConfigItem)；`total`(int64)；`last`(bool)；`page`(int64)；`pageSize`(int64) |
| 客服配置-批量更新客服分配上限 | `POST /api/customer/config/batch/allocationUpperLimit` | `list`(repeated HttpCustomerBatchUpdateAllocationUpperLimitItem, 可选) | 空对象或无业务数据 |
| 客服配置-变更客服的状态 | `POST /api/customer/config/update/status` | `userId`(int64, 必填，暂留字段 给主账号使用)；`status`(int64, 必填，0 离线 1 在线) | `status`(int64，0 离线 1 在线) |
| 客服工具栏-获取工具栏列表 | `POST /api/customer/tool/list` | `page`(int64, 可选)；`pageSize`(int64, 可选) | `list`(repeated CustomerToolItem)；`total`(int64)；`last`(bool)；`page`(int64)；`pageSize`(int64) |
| 客服工具栏-工具栏列表新增 | `POST /api/customer/tool/add` | `name`(string, 可选)；`link`(string, 可选) | `id`(int64) |
| 客服工具栏-工具栏列表更新 | `POST /api/customer/tool/update` | `id`(int64, 可选，id)；`name`(string, 可选，工具栏名称)；`link`(string, 可选，工具链接)；`switch`(bool, 可选，是否开启)；`sortValue`(int64, 可选，排序值，值越大在越前面) | 空对象或无业务数据 |
| 客服工具栏-工具栏列表排序 | `POST /api/customer/tool/sort` | `list`(repeated ToolItem, 可选) | 空对象或无业务数据 |
| 客服工具栏-工具栏列表删除 | `POST /api/customer/tool/del` | `id`(int64, 可选) | 空对象或无业务数据 |
| 客服工具栏-工具栏开关 | `POST /api/customer/tool/switch` | `id`(int64, 可选)；`switch`(bool, 可选) | 空对象或无业务数据 |
| 客服会话-批量删除接待列表中对象 | `POST /api/customer/msg/del` | `idList`(repeated string, 必填，[]botID_FriendId_GroupId) | 空对象或无业务数据 |
| 客服会话-语音消息转文字 | `POST /api/customer/msg/voice/convert` | `ids`(string, 必填，botId_friendId_GroupId)；`msgId`(string, 必填，消息id) | `text`(string) |
| 客服会话-查看账号下的客服消息 | `POST /api/customer/info` | `userId`(int64, 可选，可以查询某个客服下的情况，userId为0就是未分配的客户) | `userId`(int64，客服账号id)；`total`(int64，总数)；`receive`(int64，接待中)；`received`(int64，已接待)；`nickName`(string，客服名称)；`avatar`(string，客服头像)；`receiveList`(repeated string，接待中对象)；`receivedList`(repeated string，已接待对象)；`isOnLine`(bool，是否在线) |
| 客服会话-统计账号下的客服消息 | `POST /api/customer/info/count` | `{}` | `total`(int64，总数)；`allocated`(int64，已分配数)；`undistributed`(int64，未分配数)；`customerList`(repeated CustomerInfoItem，账号下的客服列表) |
| 客服会话-设置为收藏 | `POST /api/customer/set/collect` | `isCollect`(bool, 可选，是否收藏)；`ids`(string, 必填，botID_FriendId_GroupId) | 空对象或无业务数据 |
| 客服会话-客服系统未分配的详情 | `POST /api/customer/info/count/unDistributed` | `{}` | `list`(repeated CustomerUnDistributedItem) |
| 客服会话-主动接待客户 | `POST /api/customer/friend/receive` | `chatType`(string, 可选，群group 好友 friend)；`friendId`(int64, 可选，客户id)；`groupId`(int64, 可选，群id)；`botId`(int64, 可选，机器人的id)；`userId`(int64, 可选，客服id)；`isForced`(bool, 可选，是否强制接待 默认为是) | 空对象或无业务数据 |
| 客服统计-按时间范围查询 | `POST /api/customer/info/statistics` | `startTime`(int64, 可选)；`endTime`(int64, 可选) | `list`(repeated StatisticsDataItem) |
| 客服统计-主动调用统计接口 | `POST /api/customer/info/statisticsByDate` | `dateTime`(int64, 可选) | 空对象或无业务数据 |
| 账号配置-列表 | `POST /api/customer/config/group/info` | `{}` | `id`(int64，id)；`botList`(CustomerConfigGroupBotItem，过滤的微号)；`friendList`(repeated int64，需要过滤的客户)；`corpList`(repeated string，需要过滤的主体)；`whiteListGroup`(repeated int64，白名单群Id)；`keyWordRule`(repeated keyWordRuleItem，关键词规则：eg：[{"content":"文本","type":"eq"}])；`groupMemberList`(repeated int64，需要过滤的群成员ids)；`friendAndGroupWxids`(repeated string，需要过滤的客户和群成员wxids)；`linkFilter`(repeated LinkFilterItem，链接过滤)；`miniProgramFilter`(repeated MiniProgramFilterItem，小程序过滤)；... |
| 账号配置-分页加载过滤客户 | `POST /api/customer/config/group/filterFriend` | `page`(int64, 可选)；`pageSize`(int64, 可选)；`botType`(int64, 可选)；`name`(string, 可选) | `friendList`(repeated string，需要过滤的客户)；`total`(int64)；`last`(bool)；`page`(int64)；`pageSize`(int64) |
| 账号配置-设置过滤的企微号 | `POST /api/customer/config/group/add/bot` | `botIds`(repeated int64, 必填，需要过滤的企微id) | 空对象或无业务数据 |
| 账号配置-设置过滤的客户 | `POST /api/customer/config/group/add/friend` | `friendIds`(repeated int64, 必填，需要过滤的客户id)；`FriendAndGroupMemberWxids`(repeated string, 必填，需要过滤的客户或者群成员的wxid)；`wxFriendAndGroupMemberWxids`(repeated string, 必填，个微-需要过滤的客户或者群成员的wxid) | 空对象或无业务数据 |
| 账号配置-移除过滤的客户 | `POST /api/customer/config/group/del/friend` | `friendIds`(repeated int64, 必填，需要过滤的客户id)；`FriendAndGroupMemberWxids`(repeated string, 必填，需要过滤的客户或者群成员的wxid)；`wxFriendAndGroupMemberWxids`(repeated string, 必填，个微-需要过滤的客户或者群成员的wxid) | 空对象或无业务数据 |
| 账号配置-设置放行的企微客户 | `POST /api/customer/config/group/release/qwFriend` | `qwFriendWxids`(repeated string, 必填，需要放行的企微)；`isDel`(bool, 必填，是否删除) | 空对象或无业务数据 |
| 账号配置-更新 | `POST /api/customer/config/group/update` | `id`(int64, 可选，id)；`botList`(CustomerConfigGroupBotItem, 可选，过滤的微号)；`friendList`(repeated int64, 可选，需要过滤的客户)；`corpList`(repeated string, 可选，需要过滤的主体)；`keyWordRule`(repeated keyWordRuleItem, 可选，关键词规则：eg：[{"content":"文本","type":"eq"}])；`groupMemberList`(repeated int64, 可选，需要过滤的群成员ids)；`friendAndGroupWxids`(repeated string, 可选，需要过滤的客户和群成员wxids)；`linkFilter`(repeated LinkFilterItem, 可选，链接过滤)；`miniProgramFilter`(repeated MiniProgramFilterItem, 可选，小程序过滤)；`freeVideoFilter`(repeated FreeVideoFilterItem, 可选，视频号过滤)；`wxFriendAndGroupWxids`(repeated string, 可选，个微需要过滤的客户和群成员wxids)；`Allocation`(string, 可选，分配模式 auto 自动 manual 手动)；`qwFriendWxids`(repeated string, 必填，需要放行的企微) | 空对象或无业务数据 |
| 客服配置-批量设置工作时间和默认回复 | `POST /api/customer/config/defaultReply/batch` | `userIds`(repeated int64, 必填，userIds)；`receptionTimeRange`(repeated ReceptionTimeRangeItem, 可选，上班时间范围)；`defaultReplyList`(repeated DefaultReply, 可选，默认回复) | 空对象或无业务数据 |
| 客服-重新分配接待池 | `POST /api/customer/reallocate` | `userIds`(repeated int64, 必填，按子账号重新分配)；`botIds`(repeated int64, 必填，指定微号的客户重新分配) | 空对象或无业务数据 |
| 客服-ai回复 | `POST /api/customer/ai/reply` | `ids`(string, 必填，botID_FriendId_GroupId) | `content`(string，回复) |
| 微号列表 | `POST /api/bot/list` | `botType`(int32, 必填，微号类型 1 个微 2 企微)；`status`(int64, 可选，在线状态 在线状态 0未接入 1 离线 2 过期 3 在线)；`keyword`(string, 可选，搜索的微号名字)；`accountId`(int64, 必填，账号id) | `list`(repeated BotInfo，列表) |
| 海豚私域客服，用于回复海豚私域产品。 海豚私域是一款完善且高效的私域流量管理运营产品,帮助客户更加高效地管理私域客户。是企业微信在私域方面的补充。 | `POST /api/aiReply` | `query`(string, 必填，问题) | `answer`(string，回答) |


## 常用示例

```bash
htsy-cli call /api/customer/chat/list -d '{"page":1,"pageSize":20}'
htsy-cli call /api/customer/message/list -d '{"page":1,"pageSize":20}'
htsy-cli call /api/bot/list -d '{"page":1,"pageSize":20,"botType":1}'
```