dcsunny
21 KiB
21 KiB
客服与知识库
阅读本文件处理客服会话、客服消息、客服 AI、知识库、飞书配置、客服微号列表等操作。
客服接口
| 目标 | 接口 | 请求字段 | 常用返回字段 |
|---|---|---|---|
| 客服消息-发送 | POST /api/customer/msg/send |
chatType(string, 必填，群group 好友 friend)；sender(int64, 必填，接收者id)；botId(int64, 必填，机器人Id)；botType(int32, 必填，机器人类型)；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(int32, 必填，机器人类型)；msgId(string, 必填，微信官方的msgID) |
空对象或无业务数据 |
| 发送话术库 | POST /api/customer/msg/send/dialogue |
chatType(string, 必填，群group 好友 friend)；sender(int64, 必填，接收者id)；botId(int64, 必填，机器人Id)；botType(int32, 必填，机器人类型)；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(int32, 必填，机器人类型)；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(int32, 可选)；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（实测返回 404，查微号请改用 POST /api/account/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，回答) |
常用示例
注意：上方“微号列表
POST /api/bot/list”实测返回 404，查微号请改用席位管理POST /api/account/bot/list。
# 客服会话列表（msgType: 0所有 1已接待已读 2接待中已读 3接待中未读 4已接待 5接待中）
htsy-cli call /api/customer/list -d '{"msgType":0}'
# 客服某个会话的聊天记录（ids 格式：botId_friendId_groupId）
htsy-cli call /api/customer/record/list -d '{"startTime":1,"endTime":9999999999999,"offset":0,"limit":20,"nextId":0,"ids":"1_2_3"}'
# 微号列表（席位管理；botType: 1 个微 2 企微；sort: 0默认 1过期升序 2过期降序）
htsy-cli call /api/account/bot/list -d '{"page":1,"pageSize":20,"botType":2,"sort":0}'