在线消息接口概览
在线消息接口的接入流程、事件地址、返回约束和常见错误码。
消息接口
七鱼消息接口向开发者服务器提供了与七鱼服务器交互的能力。通过消息接口，开发者服务器可以自己控制访客与客服的交互行为。关于消息接口调用方式的参考代码，以及将微信消息转发到七鱼的快捷方式，可参考 message_interface。
现阶段，该功能只针对专业版及以上企业开放。AppKey 和 AppSecret 是调用接口的两个必要参数，首次进入对应后台模块时 AppSecret 为空，点击“重置”后会第一次生成，之后再次重置即为更换。
调用流程
下面是一次完整的访客咨询客服的调用时序图：
正常流程说明
- 用户发送消息给应用服务器，触发请求分配客服的动作。除了发送消息触发外，应用服务器也可以使用指定命令来触发分配，例如在微信公众号中添加单独的客服菜单，用户点击后触发分配客服。
- 应用服务器向七鱼服务器请求分配客服。请求中必须带上用户 ID，用来标识消息来自哪个用户，也可以带上指定的客服分组 ID、客服 ID 等参数。
- 七鱼服务器根据请求参数分配空闲客服。分配成功后，服务器会生成一个新会话，并通知客服有访客进入。
- 七鱼服务器将分配结果返回给应用服务器。建议应用服务器缓存会话状态，当用户继续说话时，只需要将消息转给七鱼服务器，无需再次请求分配客服。
- 应用服务器可以更新用户最新资料，包括昵称、电话、邮件等基础信息，也可以包含最近订单、最新状态等扩展信息。更新用户资料接口调用后立即生效，客服可以马上看到。
- 七鱼将新的用户资料通知给客服，显示在会话窗口右上角。
- 应用服务器将用户消息传到七鱼服务器。
- 七鱼将用户消息传递给客服。
- 客服回复消息。
- 七鱼服务器将客服消息推送到应用服务器。
- 应用服务器将消息回复给用户。
- 用户咨询完毕，客服主动关闭会话，或者用户长时间没有回答，系统判断超时自动关闭后，会话结束。
- 七鱼服务器通知应用服务器会话结束。如果应用服务器缓存了会话信息，可在此时移除相关缓存。
- 如果需要告知用户会话已经结束，或者需要邀请用户对客服服务进行评价，可在会话结束后进行。
- 用户对服务进行评价。除会话结束时，在会话过程中任意时候用户也可以进行评价。
- 应用服务器将用户评价结果告诉七鱼服务器。
异常流程说明
- 用户发送消息后，如果应用服务器不经过请求分配客服，直接将消息转到七鱼服务器，七鱼服务器将自动触发客服分配流程。如果企业开通了机器人服务，且用户为第一次访问，则自动分配给机器人；若用户之前已经有人工接待过，则继续分配给之前的客服。
- 请求分配的客服不在线时，将返回
14005，并附上后台设置的客服不在线提示文案。此时消息仍可继续转发到七鱼服务器，这些消息会进入留言列表。客服上线后，可从留言列表中重新发起会话并回复。进入留言后，如果超过 5 分钟用户都没有再发送消息，这条留言会关闭，这时客服才能在留言列表中看到。 - 如果请求分配的客服接待访客已达到上限，将返回
14006，表示访客需要排队。应用服务器可以通过查询排队状态接口查看当前队列中有多少人，并反馈给用户。
调用说明
- 所有接口都只支持 POST 请求。
- 除上传文件外，其他接口请求
Content-Type为application/json;charset=utf-8。 - 所有接口返回 JSON，同时使用 UTF-8 编码。
数据校验
参考 通用说明 - 数据校验。
设置接收事件地址
除了向七鱼服务器发送消息和请求，七鱼也会向开发者服务器推送消息和事件。目前会推送以下事件：
- 客服发送的消息。
- 会话开始通知。此事件只有通过发消息触发分配客服时才会发送。
- 会话结束通知。
为了接收这些事件通知，开发者需要在管理后台的“系统 > 扩展与集成 > 开发者 ID > 消息与事件接收 URL”中设置接收 URL。
注意事项：
- 接收到所有通知事件后，请在 10 秒内返回一个空字符串。超过 10 秒没有返回，或者返回字符串非空，七鱼服务器将认为请求发送失败，并进入重发。
- 如果是普通消息，请使用
msgId字段做去重。 - 所有请求内容都是 JSON 格式字符串。为了避免消息泄露并保护用户隐私，强烈建议用于接收通知的 URL 使用 HTTPS 协议。
常见错误码
| 错误码 | 说明 |
|---|---|
| 14001 | appKey 不正确 |
| 14002 | checksum 校验出错 |
| 14003 | 传递的 time 参数不正确 |
| 14004 | 内容格式不是 JSON，或者缺乏必备字段，或者参数不正确 |
| 14005 | 没有客服在线 |
| 14006 | 用户需要排队 |
| 14007 | 用户没有请求过客服 |
| 14008 | IP 被禁或不在白名单中 |
| 14009 | 接口调用太频繁，请稍后重试 |
| 14010 | 没有客服在线，且留言功能关闭 |
| 14011 | 没有调用该接口的权限 |
| 14301 | 参数错误 |
| 14500 | 服务器内部错误或系统错误 |
| 14515 | 没有权限 |
| 14200 | 参数类型不支持 |
消息收发
使用消息接口接入七鱼客服时，如果用户需要联系客服，则先将消息发送到开发者服务器，再由应用服务器发送到七鱼服务器，最后由七鱼服务器发送给对应客服。客服回复消息后，消息先到七鱼服务器，再由七鱼服务器推送到管理后台填写的事件接收 URL，最后由应用服务器转发给用户。
给七鱼发送消息
该能力用于开发者服务器替访客向客服发送消息。目前仅支持开发者服务器替用户发送消息。
发送消息时，如果用户尚未分配过客服，该消息将自动转给机器人，由机器人回答。如果需要发送消息给人工客服，可以先在 在线系统事件对接 中完成“请求分配客服”，等分配到客服后再发送消息。
为了防止网络延时造成错误，如果用户在上一次会话结束后的 10 秒内又发送消息，这条消息会自动发给上一个会话的客服。
给访客发送消息
该能力用于开发者服务器替客服向访客发送消息，目前仅支持会话中的人工会话和机器人会话。当访客处于人工会话或机器人会话中时，可发送客服消息给访客，并记录到会话中。
如果会话是通过开放接口产生的，则无法通过该能力发送消息，会提示 fromType not supported。
接收七鱼消息
客服或机器人回复消息后，七鱼平台会把消息推送给开发者。推送地址是开发者在七鱼管理后台配置的消息与事件接收 URL。字段格式、鉴权参数和示例请查看 在线系统事件对接 - 接收七鱼消息。
上传文件
文件上传支持 MultiPart 和 base64 两种方式。上传文件时同样需要计算 checksum，这两种方式中 checksum 使用的 md5 都是文件内容 md5 的小写值。两种方式的文件大小限制均为 5 MB。
上传成功后，应用服务器可以使用返回的文件 URL 发送图片、语音等文件类消息。
未读消息查询
未读消息查询用于查询最近 72 小时的未读消息数，请求频率限制为 1 次/秒。
这篇文档有帮助吗？