机器人消息接口概览

字段	类型	注释
appKey	string	七鱼分配给企业的appKey
time	long	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksum	string	用于校验数据的完整性，SHA1(appSecret + md5 + time)，由三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

备注： appKey 和 appSecert 可在七鱼企业管理后台“系统-扩展与集成-开发者ID”页查看。 checksum 中的 md5 为 POST请求的 body 内容字符串的 md5 哈希值（小写形式），即 md5 = MD5(bodyContent).toLowerCase()，如果是上传文件，则是整个文件内容的md5。出于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。

计算 checksum 的 Java 示例代码如下：

 public class QiyuPushCheckSum {
  private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
  public static String encode(String appSecret, String md5, String time) {
    String content = appSecret + md5 + time;
    try {
      MessageDigest messageDigest = MessageDigest.getInstance("sha1");
      messageDigest.update(content.getBytes());
      return getFormattedText(messageDigest.digest());
    } catch (Exception e) {
      throw new RuntimeException(e);
    }
  }
  private static String getFormattedText(byte[] bytes) {
    int len = bytes.length;
    StringBuilder buf = new StringBuilder(len * 2);
    for (int j = 0; j < len; j++) {
      buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
      buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
    }
    return buf.toString();
  }
}

返回状态码

code	说明
200	无错误
14001	appKey不存在
14002	checksum计算错误
14003	time已过期
14004	内容错误，字段格式或字段值不合法
14008	ip黑名单
14009	触发接口频率限制
14500	系统错误，通常是服务器内部错误
14501	内容长度限制
14515	无接口访问权限

对接场景示例

这里介绍一个基本的机器人会话对接流程，基于此流程可实现一个最基础的机器人对话能力对接。除了基本的会话流程接口外，我们还提供了其他丰富的功能接口，用于提高访客和人工客服咨询/答疑效率，接入方可在接口明细查看相应的接口介绍，自行对接在会话过程中，完善咨询体验。

对接前提

已经在七鱼机器人平台搭建了机器人。

调用时序图

对接步骤

调用/openapi/robot/session/create 创建会话接口，创建一个机器人会话。uid + productId 作为访客在七鱼系统里的唯一标志，一个访客同一时间最多只存在一个机器人会话，在这通会话生命周期内，该访客发送的问答消息都会记入这一通会话中。

调用/openapi/robot/session/chat 问答接口，机器人将根据配置的FAQ知识库/寒暄知识库/BOT流程，以及转人工策略和未知回复策略等，按照相应的处理优先级顺序，找到当前消息最佳回答。机器人回答主要可分为两大类，第一类是用来回复访客，接入方按机器人给的回答内容展示给访客；第二类是触发转人工事件，此事件表示该访客需要人工客服接入处理，接入方可实现人机无缝转接。

每一条回复访客的机器人消息，会带上是否允许评价等信息，接入方可基于这些信息实现消息评价功能，访客评价后接入方可通过/openapi/robot/session/msgEvaluation接口，将相应评价结果同步到七鱼，七鱼会生成对应的消息纬度数据报表，便于接入方管理数据和知识。

在访客输入消息过程中，接入方可基于/openapi/robot/session/msgAssociate 输入联想接口，实现访客输入提示，提高访客咨询效率和使用体验。该功能接入方按需对接即可。

访客发送一条消息后，除了正常的机器人回复流程外，接入方还可以根据/openapi/robot/session/msgPredict 服务先知接口，实现访客意图推荐功能，功能以按钮或卡片等形式给访客选择，提高咨询效率和使用体验。该功能接入方按需对接即可。

机器人服务过程中，接入方可基于机器人会话评价/openapi/robot/evaluation/setting接口，获取机器人支持的评价模式，实现评价功能，收集访客对这一通机器人会话整体的评价。并通过/openapi/robot/evaluation/comment接口，将访客对会话的评价上传到七鱼机器人平台，七鱼会生成相应的会话纬度满意度统计报表，便于接入方管理数据和知识。

若接入方在访客端实现了访客主动转人工功能，由于这种转人工场景并不是由机器人触发的，七鱼机器人对这种原因结束的会话没有感知，造成机器人历史数据的不完整。此时，接入方应对接 /openapi/robot/session/close 机器人会话关闭接口，主动告知机器人访客通过其他途径转到了人工客服。这样七鱼平台生成的机器人会话数据才能保证完整。若接入方未实现此接口，则七鱼系统会在访客10min未产生新的消息后，自动结束掉这一通机器人会话。

机器人消息接口概览

目录