客服能力

客服能力

一、概述

为丰富小程序的服务能力，京东小程序提供客服消息能力，以便小程序用户可以方便快捷地与小程序开发者客服相关人员进行沟通，适用于目前正在使用第三方客服系统的商家，便于京东小程序之间进行数据交互。

二、功能介绍

1）在开发者的小程序内，可以通过客服 button 组件唤起小程序客服会话页面，进行消息沟通过。

2）已使用过的小程序客服消息会聚合显示在京东 APP 消息中心会话列表内，便于用户快捷找到会话入口。

三、开放标准

所有入驻小程序平台的开发者均适用。

四、接入流程

1）开通客服

在小程序控制台客服管理模板点击右上角开通。

2）申请能力

在小程序控制台能力中心模块申请 “京东小程序客服能力”，工作人员会在 7 个工作日内完成能力审核，审核通过后可以获得客服相关接口权限。

3）添加成员

在小程序控制台成员管理模块添加客服成员（注意此成员非实际客服人员，而是开发者面向 C 端用户的客服形象，即该京东账号的头像昵称是开发者展示给用户的头像昵称，建议选择专用账号，不与个人账号混用），同时请务必保持该客服成员账号 APP 登录在线，否则将影响消息收发。

4）选择成员

在完成客服成员添加后，请在客服管理模块客服形象部分进行客服成员选择，进行绑定。

5）设置服务器域名

在小程序控制台 设置-开发设置 模块里设置好服务器域名。

6）设置消息推送地址

在客服管理模块消息地址部分填写消息推送地址，请务必保证该地址是服务器设置域名下的地址。

五、功能说明

接收信息

当用户在客服会话发送消息，京东服务器会将消息或事件的数据包发送到开发者填写的 URL，回调 URL 约定的返回参数如下：

{
    "sub_code":0,
    "sub_message":"接收通知成功",
    "sub_result":"接收通知成功"
}

验签

为了保证接收到消息合法性，接收方可以按照签名规则校验签名有效性，签名规则如下：

Step1：若存在 body 参数，将 body 参数的 json 串转为 Map （为了校验是否合法），再将 Map 转为 json 串同时对应生成一个参数 key=body；

Step2：将其他非 body 参数和上一步的参数（key=body，value=json串）按照 key 的英文字母逐个字符排序拼接起来，得到 key1value1key2value2...keynvaluen；

Step3：上一步得到的字符串前后都拼接山 appSecret，得到{{appSecret}}key1value1key2value2....keynvaluen{{appSecret}}

Step4：对上一步得到的字符串进行 MD5 加密，得到32位的签名，放在 key：sign 上，最终放在 url 上一并传给 isv，各消息类型的推送 JSON 数据包结构如下：

文本信息

用户在客服会话中发送文本消息时将产生如下数据包：

{
    "openId": "toUser",
    "createTime": 1604927680164,
    "type": "text",
    "content": "this is a test",
    "msgId": "1234567890123456"
}

图片信息

用户在客服会话中发送图片消息时将产生如下数据包：

{
    "openId": "toUser",
    "createTime": 1604927680164,
    "type": "image",
    "url": "this is a url",
    "imageId":"图片id",
    "msgId": "1234567890123456"
}

小程序图文信息

用户在客服会话中发送小程序图文消息时将产生如下数据包：

{
    "openId": "toUser",
    "createTime": 1604927680164,
    "type": "link",
    "title": "标题",
    "description": "描述",
    "url": "跳转地址",
    "imageUrl": "图片链接",
    "imageId": "图片id",
    "msgId": "1234567890123456"
}

小程序卡片信息

用户在客服会话中发送小程序卡片消息时将产生如下数据包：

{
    "openId": "toUser",
    "createTime": 1604927680164,
    "type": "miniprogrampage",
    "title": "标题",
    "pagePath": "小程序页面路径",
    "thumbUrl": "图片地址",
    "thumbImageId": "封面图片id",
    "msgId": "1234567890123456"
}

六、接口说明

1、发送信息

注意事项：

商家发送客服消息给用户，值得注意的是商家不能主动给用户发送消息，应该在用户发送消息后固定时段内（48小时）才能调用该接口，防止对用户造成打扰，对发送条数有限制只能在 5 条之内，如果过程中用户再次发送消息，会触发发送条数限制和发送时限的更新。 当用户给小程序客服发消息，小程序服务端会将消息的数据包通过 POST 请求发送到开发者配置的回调 URL，开发者收到请求后可以调用该接口进行异步回复。 回调 URL 约定的返回参数如下：

{
    "sub_code": 0,
    "sub_message": "接收通知成功",
    "sub_result": "接收通知成功"
}

接口名： jingdong.dd.push

请求参数：

msgtype 的合法值:

text 的结构：

例： data:"{\"content\":\"消息内容\"}"

image 的结构：

例： data:"{\"image_id\":\"111122223333\"}"

link 的结构：

例： data:"{\"thumb_url\":\"****jfs/123.jpg\",\"description\":\"描述\",\"title\":\"测试标题\",\"image_id\":\"1112222333444\"}"

miniprogrampage 的结构：

例： data:"{\"pagepath\":\"小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar\",\"thumb_media_id\":\"小程序消息卡片的封面， image 类型的 media_id，通过 新增素材接口 上传图片文件获得，建议大小为 520*416\",\"description\":\"描述\"}"

返回值

Object

返回的 JSON 数据包

errcode 的合法值

2、上传图片

接口名： jingdong.miniapp.pic.uploadImage

请求参数：

注意：上传图片请求大小要小于 2M。

响应参数：

3、下载图片

接口名： jingdong.miniapp.pic.downImage

请求参数：

响应参数：

4、Button组件

<button open-type="contact" ></button>

当 open-type="contact"时，可选配置参数如下，均为非必填，

注意：由于客服功能必须保证用户登录京东 APP 才能使用，所以在调用客服 button 组件前，请先调用 jd.login()，如果是登录状态可以直接获得 code，可以成功调用客服 button组件，如果用户没有登录就会唤起原生登录页面，如在未登录状态下直接调用客服 button 组件会返回调用失败。