接入说明

七鱼提供了两种小程序客服接入方式，分别为授权接入（推荐）和密钥接入方式，授权接入 Demo如下：

微信小游戏仅支持密钥接入方式

授权接入

七鱼提供微信小程序快速接入方案，需要开发人员在小程序内添加一个客服咨询的入口，然后由小程序超管在七鱼后台按照提示扫码授权即可。

开发工作

咨询客服入口代码段：

<button
  type="primary"
  size="40"
  session-from="nickName={{userInfo.nickName}}|avatarUrl={{userInfo.avatarUrl}}"
  open-type="contact"
>联系客服</button>

此处使用的是微信小程序提供的button组件open-type必须为"contact"。集成完毕后就已经完成了开发侧工作，之后就是提交发布了。若原先已经有小程序了且也有此按钮只是接了其他客服系统，那按钮可以复用，直接修改下session-from内容后重新发布就行。

管理员扫码

小程序超管扫码接入操作区域以及引导说明样例如下：

点击确定之后会直接跳转微信的授权扫码界面，超管使用个人微信账号扫码并确认授权。

扫码成功后可在七鱼后台【服务中心】-【在线系统】-【设置】-【在线接入】-【微信小程序】中查看到绑定的微信小程序。

测试流程

使用客服账号登录七鱼智能接待的客服平台，登录后更改当前账号的状态（离线变更为在线）

在微信中找到接入的微信小程序，点击进入微信小程序，进行在线咨询。随意发送一次会话内容。

此时在七鱼客服智能平台上，可以看到进线咨询的用户即时IM会话，正常使用客服平台功能进行接待

密钥接入

七鱼提供微信小程序密钥接入方案，需要在七鱼和小程序后台按照提示填写必要信息进行绑定。

开发工作

咨询客服入口代码段：

wx.openCustomerServiceConversation({})

此处使用的是微信小程序提供的openCustomerServiceConversation方法。进入客服会话。要求在用户发生过至少一次 touch 事件后才能调用。集成完毕后就已经完成了开发侧工作，之后就是提交发布了。

获取小程序信息

在微信小程序后台【小程序-开发-开发管理-开发设置-开发者ID】页面中，获取复制您要绑定的小程序名称、小程序ID及小程序密钥。

接入信息填写

在七鱼【在线系统-设置-在线接入-微信小程序】点击按钮“绑定微信小程序”，选择“密钥接入”，点击确定

填写刚复制所得的小程序名称、小程序ID及小程序密钥，点击下一步

完成消息推送配置

在微信小程序后台【小程序-开发-开发管理-开发设置-消息推送】中，点击“启用”。在确认小程序管理员身份后，将下方消息推送URL粘贴到URL服务器地址内，填写Token（令牌），生成EncodingAESKey（消息加密密钥）。

注意：消息加密方式和对接格式请务必选择“安全模式”和“XML”

将Token（令牌）和生成EncodingAESKey（消息加密密钥）填入七鱼后台的第二步弹窗，点击提交，

返回小程序后台，提交以上修改。即完成绑定接入。即可直接在七鱼收发该小程序的私信消息。

获取小程序access_token

通过微信小程序发送消息，需要使用从微信获取的access_token，微信文档中建议开发者使用中控服务器统一获取和刷新access_token，七鱼提供两种中控服务器对接方式，分别支持七鱼或企业作为中控服务器来管理小程序的access_token，并对外提供获取微信小程序access_token接口。以下分别阐述对接方式，可参考微信文档。

七鱼作为中控服务器

若选择七鱼做为access_token中控服务器，就严禁企业再额外直接调用微信的access_token获取接口，此操作会导致我们缓存的access_token失效，导致发送消息失败。接口请求说明

接口调用为POST方式;

Content-Type为：application/json;charset=utf-8;

接口checksum校验规则同消息接口;

参数说明

字段	类型	必填	说明
appid	String	是	小程序appid
secret	String	是	小程序secret

请求地址

POST https://qiyukf.com/openapi/wechat/miniprogram/access_token?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463216914&checksum=e72be4487b6fc03e0f914fc11e4053d771598d93
Content-Type:application/json;charset=utf-8

返回值格式说明

字段	类型	说明
code	int	返回码
message	String	access_token获取结果

接口返回示例

{
	"code": 200,
	"message": "{\"expires_in\":7144,\"access_token\":\"10_819-492EoXNz8u_2Crfx8da3BrSOSHtbT9O71OtwvxjWCvb2zk7FW8cYFqJLMpY1Wd8o61XnGTGiTH6-kCLg_DwZelsveq4mc92DKHCQaUDaGtRiZvQ-2OG9PtvNtrpmxHIe-omOptweBhjIFXPfAIAOGY\"}"
}

message中，expires_in为access_token在微信服务器的有效时间，单位为秒，access_token为获取到的微信凭证。企业所有获取access_token的地方都可直接来七鱼服务器调用本接口获取，企业亦可根据返回的有效时间在自己服务器缓存access_token,避免多次http调用，但若发现当前缓存的access_token失效(调用微信小程序发消息接口会有失效错误码40001，详细见微信文档)，需再次请求本接口，获取最新access_token。

示例请求代码

public void testGetWxMiniAccessToken() throws Exception {
    String url = "http://qiyukf.com/openapi/wechat/miniprogram/access_token?appKey=消息接口AppKey&time=%d&checksum=%s";
    JSONObject params = new JSONObject();
    params.put("appid", "appid");
    params.put("secret", "appsecret");
    long time = System.currentTimeMillis() / 1000;
    String checksum = QiyuPushCheckSum.encode("消息接口AppSecret", MD5.md5(params.toJSONString()).toLowerCase(), time);
    System.out.println(checksum);
    url = String.format(url, time, checksum);
    String response = HttpClientPool.getInstance().postMethod(url, params.toJSONString());
    System.out.println(response);
}

企业作为中控服务器

若企业有自身管理access_token的业务需求,则七鱼支持设置从企业那里获取access_token,可在管理后台设置页面设置使用企业自己服务器做为access_token中控服务器，而后七鱼就会使用企业接口获取access_token。

接口调用说明

七鱼使用POST方式调用企业access_token接口;

接口请求的Content-Type为：application/x-www-form-urlencoded;charset=utf-8

调用校验，在调用access_token接口时，七鱼会将appSecret，time，nonce三个参数使用sha1哈希算法生成checkSum校验和（同消息接口checksum校验和示例代码），其中time为精确到秒的时间戳，nonce为一串随机生成的字符串,参数放在Http Request Header中传输;

请求头参数说明

字段	类型	说明
appId	String	企业分配给七鱼的appId
nonce	String	描述信息
time	Long	当前UTC时间戳，精确到秒数
checkSum	String	SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time，并转化成16进制的小写字符串作为checkSum

请求体参数说明

字段	类型	必填	说明
appid	String	是	需获取access_token的小程序apppid
secret	String	是	需获取access_token的小程序secret

企业接口返回说明

返回说明：返回类型为JSON，同时进行UTF-8编码，返回格式同微信返回access_token格式。

返回示例

{"access_token":"ACCESS_TOKEN","expires_in":7200}

返回格式说明

字段	类型	说明
access_token	String	access_token获取结果
expires_in	int	access_token有效时间，单位：秒

接入说明

目录