====== 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请求示例：

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

另外，环信可以向页面额外传递以下参数，以满足多样化的使用需求（注：额外传参功能为增值功能，如有需要请联系商务开通）：

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

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

  * [[http://docs.easemob.com/cs/300visitoraccess/androidsdkapi#发送透传消息|Andoird SDK发送透传消息]]
  * [[http://docs.easemob.com/cs/300visitoraccess/iossdkapi#发送透传消息|iOS SDK发送透传消息]]


===== 呼叫工作台 =====

默认情况，环信会传递以下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页面可以根据访客消息内容决定是否同步更新。

{{:cs:400systemintegration:iframe窗口.jpg?nolink&1000|}}

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

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

注：
  - 当需要进行参数加密时，请勾选“同时加密系统自带参数”，勾选后，系统自带参数（如：easemobId和visitorImId），以及访客进线携带的访客信息字段，均会自动进行加密处理；
  - 设置加密密钥后，客服后台会使用这个密钥加密客户信息相关的参数，客服工作台根据用户设置的URL和加密后的参数，构造一个发给CRM系统的请求。CRM系统在收到这个请求后，首先需要使用同样的加密算法和密钥解密相关的参数，然后处理该请求，并向环信客服云返回查询后的客户信息页面。
  - 访客进线需要透传的参数，不会自动进行加密和解密处理，如有需要，客户可以自行对需要透传到iframe的参数进行加密处理，在iframe里自行获取参数后进行解密处理，从而确保敏感信息不被泄露；

针对需要透传到iframe里的消息格式示例：

未加密传输如下：

<code json>
"ext": {
        "cmd": {
            "updateVisitorInfoSrc": {
                "params": {
                    "name": "Jack",
                    "age": "40",
                    "sex": "man"
                }
            }
        }
}
</code>

自行加密后传输如下：

<code json>
"ext": {
    "cmd": {
        "updateVisitorInfoSrc": {
            "params": {
                "name": "877523f86f18f55e",
                "age": "e86b4e789891107c",
                "sex": "d221cba8e6efd0ad"
            }
        }
    }
}
</code>

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

**iframe相关设置位置如下：**

{{:cs:400systemintegration:客服云-访客信息透传说明-后台配置.png?nolink|}}

**未勾选同时加密系统参数时iframe参数拼接如下：**

{{:cs:400systemintegration:客服云-访客信息透传说明.jpg?nolink|}}

**勾选了同时加密系统参数时iframe参数拼接如下：**

{{:cs:400systemintegration:客服云-访客信息透传说明-加密后.jpg?nolink|}}

==== 第 3 步：自定义查询参数（可选） ====

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

=== Web访客端示例 ===

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

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

在该示例中，向CRM系统发送GET请求为：

<code http>
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
</code>

==== 第 4 步：测试 ====

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

db.jsp的示例代码如下：

<code java>

<%@ 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){}
    }
%>
</code>