网易七鱼 API
  1. iframe 对接
网易七鱼 API
  • 概述
  • 通用说明
    • 数据校验
    • 通用错误码列表
    • 服务端登录
      • 服务端登录
      • 获取SDK接入地址
  • CRM 对接
    • 概述
    • 文档约定
    • 对接方式对比与建议
    • Appendix I 错误码
    • 轻量 CRM 对接
      • 概述
      • Web SDK 调用
      • iOS SDK 调用
      • Android SDK 调用
      • 参数说明
    • CRM 接口对接
      • 概述
      • 跨域访问
      • 接口认证方式
      • 访客身份识别
      • 自定义接口参数
      • 获取 token
      • 在线会话获取用户信息
      • 呼叫中心获取电话用户信息
      • 更新用户信息
      • 在线会话获取用户订单信息
      • 呼叫中心获取用户订单信息
      • 更新订单信息
    • 七鱼用户认证机制
      • 概述
      • 术语
      • 认证过程
      • 实施流程
      • 授权接口
      • 认证接口
      • 版本支持
      • 示例代码
      • 注意事项
  • iframe 对接
    • 展示效果
    • 展示区域
    • 参数配置
    • 样例
  • 客户管理
    • 客户信息变更事件
    • 客户标签
      • 概览
      • 获取客户标签信息
      • 修改客户标签
      • 批量修改客户标签
      • 客户标签变更事件
    • 客户导出
      • 概述
      • 接口鉴权
      • 接口示例
      • 接口访问步骤
    • 获取用户服务记录
      • 概述
      • 接口鉴权
      • 接口示例
    • 客户导入
      POST
  • 员工管理
    • 客服管理
      • 创建客服
      • 修改客服
      • 删除客服
      • 获取客服列表
      • 查询单个客服信息
    • 客服组管理
      • 创建客服组
      • 修改客服组
      • 删除客服组
      • 分配客服到客服组
      • 获取客服组列表
      • 获取客服组下员工列表
  • 在线系统
    • 接口消息
      • 概述
      • 调用流程
      • 调用说明
      • 数据校验
      • 设置接收事件地址
      • 常见错误码
    • 消息收发
      • 概述
      • 给七鱼发送消息-文本消息
      • 给七鱼发送消息-图片消息
      • 给七鱼发送消息-语音消息
      • 接收七鱼消息
      • 上传文件-MultiPart 方式
      • 上传文件-base64 方式
    • 事件
      • 请求分配客服
      • 客服组排队情况查询
      • 更新用户资料
      • 获取评价设置
      • 评价客服
      • 查询排队状态
      • 主动退出排队
      • 接收会话开始通知
      • 接收会话结束通知
      • 接收客服主动邀评通知
      • 接收用户进入排队通知
      • 接收用户离开排队通知
      • 会话结束推送会话数据
      • 接收会话变更信息通知
      • 接收会话质检事件通知
    • 消息推送
      • 消息推送-发送文本时
      • 消息推送-发送图片时
      • 消息推送-发送富文本时
    • 数据接口
      • 概述
      • 实时数据报表
      • 客服质量报表
      • 客服考勤报表
      • 客服考勤明细
      • 历史数据总览
      • 客服工作量报表
      • 客服满意度报表
    • 订单绩效对接
      • 概述
      • 数据同步流程
      • 接口鉴权
      • 订单属性
      • 示例
      • 上传订单信息接口
      • 订单绩效导出接口
    • 获取会话记录
      • 概述
      • 接口鉴权
      • 接口示例
      • 接口访问步骤
      • 接口地址
      • 字段说明
    • 商品、订单查询
      • 一、 业务流程说明
      • 二、访客端样式
      • 三、接口定义
    • 获取会话关联的用户信息
      POST
    • 行为轨迹
      POST
    • 微信模板消息
      POST
    • 获取咨询分类
      POST
    • 获取在线会话的服务小记记录
      POST
    • 更新会话服务小记
      POST
  • 呼叫系统
    • 呼叫时间对接
      • 概述
      • 数据校验
      • 调用说明
      • curl请求样例如下
      • 第三方接口需返回的数据的说明
      • 第三方接口样例
    • 外呼任务
      • 创建外呼任务
        • 概述
        • 分配到客服
        • 分配到客服组
        • 按客户关系分配
        • 按自定义的客户分配
        • 自动外呼任务
      • 补充自动外呼号码
      • 获取外呼任务详情
      • 获取外呼任务明细详情
      • 编辑手动外呼任务
      • 删除外呼任务号码
    • 服务记录
      • 获取服务记录模板
    • 数据接口
      • 呼叫总览数据
      • 呼叫坐席历史数据
      • 呼叫团队历史总览数据
    • 呼叫工具条
      • 概述
      • 初始化 SDK
      • SDK 事件
      • SDK 方法
      • 获取SDK接入地址
    • 外呼机器人
      • 外呼机器人事件对接
      • 获取机器人话术列表
      • 模糊搜索获取话术列表
      • 获取外呼拦截组配置列表
      • 获取所有可用外呼线路列表
      • 创建外呼机器人任务
      • 获取指定任务的话术中变量
      • 向外呼任务中导入客户
      • 从已呼客户列表重新添加到呼叫任务
      • 获取已经完成外呼的客户信息列表
      • 启动外呼任务
      • 暂停外呼任务
      • 终止外呼任务
      • 获取任务详情
  • 机器人
    • 服务先知-常见问题
    • 服务先知-快捷短语
    • 一触即达
      • 概述
      • 对接方式
      • 对接示例
      • Velocity语法赋值
      • 移动SDK接入指南
    • 知识库管理
      • 概述
      • 获取知识库的问题
      • 获取知识库的知识点
      • 通过分类名称获取当前分类下topN标准问
      • 通过标准问获取当前机器人默认答案
      • 通过常见问题模板id获取常见问题列表
      • 知识库分类查询接口
      • 获取问题列表
      • 获取问题详情信息
      • 删除问题
      • 添加问题
      • 更新问题
      • 更新问题规则答案
      • 更新问题忽略相似问接口
    • 会话评价
      • 概述
      • 获取机器人评价设置
      • 提交机器人会话评价
    • 统计接口
      • 概述
      • 获取机器人会话统计总揽数据
      • 转人工会话统计
    • 消息接口
      • 概述
      • 概念/名词解释
      • 接口通用说明
      • 对接场景示例
      • 会话类接口
        • 会话类接口
        • 创建机器人会话
        • 常见问题
        • 快捷短语
        • 输入联想
        • 获取机器人消息回复
        • 机器人回复消息评价
        • 机器人会话满意度评价
        • 关闭机器人会话
        • 文件上传
        • 机器人辅助人工客服
      • 获取机器人切换配置
      • 微信公众号切换机器人
      • 企业微信切换机器人
  • 工单系统
    • 概述
    • 接口鉴权
    • 接口协议
    • 错误码
    • 工单推送
      • 说明
      • 请求体说明
    • 工单自定义字段同步
      • 基本用法
    • 创建工单
    • 修改工单
    • 批量修改工单
    • 申领工单
    • 转交工单
    • 回复工单
    • 催单接口
    • 完结工单
    • 重新打开工单
    • 搜索工单
    • 获取工单详情
    • 获取工单日志列表
    • 获取工单过滤器列表
    • 获取过滤器下的工单数量
    • 获取过滤器下的工单
    • 获取工单关注人
    • 获取工单模板
    • 获取工单模板字段
    • 获取工单分类
  • 短信
    • 接口鉴权
    • 创建短信发送任务
    • 获取短信任务状态
  • 平台电商(Platform OpenAPI)
    • 接口鉴权
    • 接口协议
    • 获取会话记录
      • 概述
      • 接口鉴权
      • 接口示例
      • 接口访问步骤
      • 字段说明
    • 第三方登录
    • 创建商户
    • 修改商户
    • 启用商户
    • 停用商户
    • 修改商户密码
    • 获取商户列表
    • 获取商户信息
  1. iframe 对接

参数配置

嵌入页面后,大多数企业是需要该页面能获取当前界面的一些信息的,比如需要知道当前登录的客服是谁,在当前聊天窗口中的访客是谁等。考虑到此点,七鱼在配置 iframe 的时候可以配置一些参数,在客服点击tab 访问 iframe 的时候通过 GET 请求带过去。具体参数有以下四大类:
1、映射参数
截图中红色标注区域为七鱼可提供映射的参数,黄色标注区域为映射至企业所用的参数名。
图2
图3
注:七鱼提供的客服账号需要开发者自己处理与实际客服人员的对应关系。如果轻量对接中没有传用户唯一 id和手机号,七鱼就无法映射回传给开发者。
2、固定参数
图4
顾名思义,固定参数就是写死不变的,企业可以根据自身需求将七鱼请求 iframe 时候需要带上的固定参数给到 iframe 配置人员。 3、加密参数
考虑到 iframe 页面直接从七鱼页面发起,做用户和来源校验比较困难。七鱼访问 iframe 页面时,会拼接客服账号,用户账号等信息,为了避免越权访问,七鱼在页面的 url 中增加了 signature 参数,用于参数的完整性校验,以及确认链接由七鱼系统发起。 在调用的 url 最后,增加 signature 参数,signature 参数值通过企业的 AppSecret 和 url 的参数串拼接,然后取 sha1 哈希值得到。 同时,为了保证 url 的时效性,url 会附带一个 timestamp 参数,为生成 url 时的时间戳。对于 timestamp 不在指定范围(过早或过晚)的调用,被访问方可以拒绝。
java 代码示例如下:
// 假设 iframe 页面计算各个参数后,url 为:https://iframe.custom.com/path?param1=value1&param2=value2&paramN=valueN
String url = "https://iframe.custom.com/path?param1=value1&param2=value2&paramN=valueN";
String appSecret = "6226D081B3DB401E94AB61A864DF93B2"; // 取扩展与集成页面 开发者ID 下的 AppSecret
String queryString = "param1=value1&param2=value2&paramN=valueN"; // 可通过 javax.servlet.http.HttpServletRequest#getQueryString() 获取
String signature = org.apache.commons.codec.digest.DigestUtils.sha1Hex(appSecret + queryString);
// 得到最终的url
url = url + "&signature=" + signature;
为了保持对之前的兼容,同时保留了下面的 md5 校验参数,具体实现方式是: 开发者提供用于加密校验的MD5_Key秘钥和固定加密字段Target,七鱼在请求的时候会将 MD5_Key 与当前的请求时间及Target三者做md5加密,并在url拼接时带上以下3个参数:
图5
七鱼考虑到iframe 页面的信息安全因素,提供了MD5校验,具体实现方式是:开发者提供用于加密校验的MD5_Key秘钥和固定加密字段Target,七鱼在请求的时候会将MD5_Key与当前的请求时间及Target三者做md5加密,并在url拼接时带上以下3个参数:
参数说明
authAcceptWay加密方式,该值固定为“md5”开发者可以直接舍弃
md5MD5 加密值
authTime请求时间,格式为yyyyMMdd HH:mm:ss
开发者可以通过已有的MD5秘钥和固定加密字段Target以及七鱼请求带过来的authTime来验证md5值的有效性。以下是参数生成方法:
String authTime = TimeUtil.readableByDateTimeOfTimestamp(now);

String md5 = MD5.md5(md5Key.trim() + authTime.trim() + target.trim()).toLowerCase();
4、自定义接口参数
该参数比较特殊,不是七鱼人员可配置的,是开发者在轻量 CRM对接中传递给七鱼的。 以下是七鱼开发指南对于自定义接口参数的说明:
图6
该参数本身是在用户 CRM 信息接口中使用的,可以在用户发起会话的时候由开发者动态配置参数,然后客服查看访客更多信息(七鱼调用企业 CRM接口)时,七鱼可以在请求中把这类参数回传给企业 CRM 接口。iframe 也使用了这套逻辑,并且不区分 area,会将所有的"type"和"crm_param"类型的参数透传给iframe页面,企业在iframe页面中通过url拼接上来的qiyuCustomer 字段进行取值即可。

【网易七鱼】API开发者 微信交流群

用微信扫右侧二维码,加入【网易七鱼】API开发者 交流群,互助沟通

扫码加入交流群
上一页
展示区域
下一页
样例
Built with