Iframe窗口对接

目前环信客服云中的默认客户信息包括:客户昵称、真实姓名、ID、手机、QQ、邮箱、公司、备注等,仅可满足客户信息管理的基础需求。因具体业务模式不同,当您的企业需要展现更详细、个性化的客户信息时,环信提供了CRM系统对接的功能。

通过 Iframe 窗口集成方式实现客户订单系统或客户关系管理系统的集成。这样当客户发起会话/来电的时候,坐席端就可以看到该客户的详细信息以及该客户的订单信息。同理,如果有其他第三方系统需要集成,也可以用同样方法进行集成。

呼叫工作台与在线工作台应用的iframe窗口相同,即配置iframe窗口以后,会同时展示在在线工作台和呼叫工作台。

注:第三方系统对接为企业版、旗舰版功能。

在线工作台

默认情况,环信会传递以下URL参数来供界面备用,web页面可获取到,以供客户进行一般化的信息查询。这些参数页面可以从Parameter里取到并使用,如果使用不到,忽略即可。

  • easemobId(关联的IM服务号,忽略即可)
  • visitorImId(客服云中的客户ID,对应“资料”tab页签中的ID)
    • 对于APP/网页渠道客户,visitorImId是客户的环信IM号
    • 对于微信渠道客户,visitorImId是该客户在相应微信公众号上的openid
    • 对于微博渠道客户,visitorImId是该客户在相应微博账号上的粉丝id
    • 对于企业微信客户,visitorImId是该客户对应的企业微信userid
  • to=servicenumber(仅微信渠道有效,为微信公众号的原始ID;目前是IM服务号)
  • lang=zh lang=en (客服工作台选择语种后,可以把对应的语种参数传到iframe页面)

GET请求示例:

Request URL: https://www.yourdomain.com/?easemobId=107937&visitorImId=webim-visitor-8K2FTG9QTYWRT8EYVJ7F&to=webim-visitor-8K2FTG9QTYWRT8EYVJ7F
Request Method: GET

另外,环信可以向页面额外传递以下参数,以满足多样化的使用需求:

  • tenantId:租户ID
  • ssid: 会话ID,全局唯一,客服云界面不可见
  • originType: 渠道
  • techChannelName:关联名称
  • serviceNumber:IM服务号
  • agentId:客服ID,全局唯一,客服云界面不可见
  • email:客服登录邮箱地址
  • agentName:客服昵称
  • userId:系统客户ID,全局唯一,客服云界面不可见
  • description:客户“资料”页的描述字段
  • lang :语言字段

除此之外,如果还需要特定参数,则可通过APP或web访客端发送一个透传消息把参数传递给环信,环信会将这些参数序列化后,重新刷新自定义信息页面。

透传消息接口:

呼叫工作台

默认情况,环信会传递以下URL参数来供界面备用,web页面可获取到,以供客户进行一般化的信息查询。这些参数页面可以从Parameter里取到并使用,如果使用不到,忽略即可。

访客信息:

  • phoneNumber 访客号码:呼入时为主叫号码,呼出时为被叫号码
  • province 归属地—省
  • city 归属地—市

通话信息:

  • callNumber 主叫号码
  • calledNumber 被叫号码
  • callType 通话类型:Inbound(呼入)、Outbound(呼出)
  • contactId 通话id

坐席信息:

  • agentId 坐席ID
  • email 坐席账号
  • agentName 坐席昵称
  • trueName 坐席姓名

集成方案

具体实现方案如下:

第 1 步:制作页面

自定义信息展现功能,需要开发一个HTML/JSP/ASP界面,然后按HTTPS协议部署在公网上,以供环信客服云访问。

第 2 步:配置自定义信息接口

进入“管理员模式 > 设置 > 扩展与集成 > iframe”页面,填写窗口名称、URL、加密密钥(可选),设置是否同时加密系统自带参数(可选)、是否同步客户消息内容(可选),并保存。

该URL路径为该页面能被访问的路径即可,比如:https://IP:port/db.jsp

参数加密:

  • 加密密钥:用于对自定义的客户信息参数进行加密,参考:CRM系统对接
  • 同时加密系统自带参数:使用上述加密密钥对系统默认传递的参数进行加密

同步客户消息:

  • 同步客户消息内容:将进行中会话的访客消息(文本、图片等)投递给Iframe页面,Iframe页面可以根据实时同步的访客消息实现知识库的自动筛选/查询,智能推荐话术等功能;切换会话时,会自动投递切换后的会话中最新一条访客消息,Iframe页面可以根据访客消息内容决定是否同步更新。

注:第一个Iframe窗口默认展示在客服模式会话、历史会话页面以及管理员模式历史会话、质量检查页面;第二个Iframe窗口仅展示在客服模式的会话页面。

如果需要在提交给客户CRM系统的请求中支持对客户信息相关的参数进行加密,可以设置一个长度大于8位的加密密钥,用于对客户信息相关的参数进行加密,在收到加密的请求后,CRM系统需要使用同样的密钥进行解密。目前采用基于DES算法的对称加密方式。

注:默认情况下,加密机制只处理自定义参数,而不处理系统自带参数(如:easemobId和visitorImId)。如需加密系统默认参数,请勾选“同时加密系统自带参数”。

设置加密密钥后,客服后台会使用这个密钥加密客户信息相关的参数,客服工作台根据用户设置的URL和加密后的参数,构造一个发给CRM系统的请求。CRM系统在收到这个请求后,首先需要使用同样的加密算法和密钥解密相关的参数,然后处理该请求,并向环信客服云返回查询后的客户信息页面。

消息格式示例:

加密前:

"ext": {
        "cmd": {
            "updateVisitorInfoSrc": {
                "params": {
                    "name": "Jack",
                    "age": "40",
                    "sex": "man"
                }
            }
        }
}

加密后:

"ext": {
    "cmd": {
        "updateVisitorInfoSrc": {
            "params": {
                "name": "877523f86f18f55e",
                "age": "e86b4e789891107c",
                "sex": "d221cba8e6efd0ad"
            }
        }
    }
}

注:在没有设置加密密钥的情况下,所有参数采用明文传输,CRM系统一侧也无需进行解密。

第 3 步:自定义查询参数(可选)

编写APP或web访客端自定义消息的程序。(该步骤可选,如果不需要特殊传参数,可忽略该步骤)

Web访客端示例

使用Web插件时,可以通过在ext扩展字段指定参数的方式,向CRM系统传递自定义的参数。示例如下,请在浏览器打开该网址,并查看源码。

访客端示例:https://index-swf.github.io/webim-plugin-demo/demos/webim-plugin-crm.html

在该示例中,向CRM系统发送GET请求为:

Request URL: https://www.yourdomain.com/?customUserId=EEP4EVP9CCMTRTCKVJHX&name=Jack&age=40&sex=man&easemobId=107937&visitorImId=webim-visitor-Q922M6VHRKQG8QFXP6T9&to=webim-visitor-Q922M6VHRKQG8QFXP6T9
Request Method: GET

第 4 步:测试

打开APP/web访客端,点击“联系客服”按钮,发送一条消息到客服人员。观察环信客服云是否能正常收到消息,观察客服模式下“会话”面板最右侧的Tab页是否显示web页面客户信息,观察切换不同客户的会话是否能正常显示不同的客户信息、订单信息等。

db.jsp的示例代码如下:

<%@ page import="javax.naming.*" %>
<%@ page import="javax.sql.*" %>
<%@ page import="java.sql.*" %>
<%@ page import="javax.transaction.*" %>
CRM Integration Test:<br>
<%
    String easemobId = request.getParameter("easemobId");//该参数为环信关联的IM服务号,忽略即可
    /**
    * visitorImId是环信ID,可通过该ID查询到用户业务ID,进而查询到订单信息,客户详细信息等。
    * 如果需要额外不能获取的信息,可以借助params里面传递参数来获得。
    */
    String visitorImId = request.getParameter("visitorImId");
    String specialID1 = request.getParameter("specialID1");//可选
    String specialID2 = request.getParameter("specialID2");//可选
    String specialID3 = request.getParameter("specialID3");//可选
    InitialContext ctx = new InitialContext();
    Connection con = null;
	Statement stmt = null;
	ResultSet rs = null;
    try{
        DataSource ds = (DataSource)ctx.lookup("java:comp/env/jdbc/datasource_name");
  		con = ds.getConnection();
  		stmt = con.createStatement();		
  		rs = stmt.executeQuery("select * from user where id = ‘"+ visitorImId + “’” );
    	while(rs.next()) {
    		String name = rs.getString(2);
    		System.out.println("name :" + name);
		String phone = rs.getString(3);
		System.out.println("phone :" + phone);
		String address = rs.getString(4);
		System.out.println("Address :" + address);
		out.println("easemobId :" + easemobId);
		out.println("<br>");
    		out.println("name :" + name);
    		out.println("<br>");
    		out.println("phone :" + phone);
    		out.println("<br>");
    		out.println("address :" + address);
    		out.println("<br>");
    	}
    }catch(Exception e) {
            e.printStackTrace();
    }finally {
        try {
        	stmt.close();
        }catch(Exception e1){
		out.println(e1.toString());
		}    
        try {
        	con.close();
        }catch(Exception e2){}
    }
%>