# 客服消息使用指南

为丰富小程序的服务能力，提高服务质量，微信为小程序提供客服消息能力，以便小程序用户可以方便快捷地与小程序服务提供方进行沟通。

# 功能介绍

用户可使用小程序客服消息功能，与小程序的客服人员进行沟通。

客服消息会话入口有两个：

1、小程序内：开发者在小程序内添加客服消息按钮组件，用户可在小程序内唤起客服会话页面，给小程序发消息；

2、已使用过的小程序客服消息会聚合显示在微信会话「小程序客服消息」盒子内，用户可以在小程序外查看历史客服消息，并给小程序发送消息。

客服消息下发条件：小程序用户在小程序内唤起客服会话或用户给小程序客服发送消息，具体下发时间有效期及消息条数限制见客服消息下发条件说明

客服消息类型：目前支持文本、图片、小程序卡片类型消息。

为尽量满足小程序开发者的需求，小程序可通过以下3种方式下发客服消息：1. 调用发送客服消息接口；2. 使用网页端客服工具；3. 使用移动端「客服小助手」小程序。

# 下发条件说明

当用户和小程序客服产生特定动作的交互时（具体动作列表请见下方说明），小程序可向用户下发客服消息。

目前允许的动作列表如下，不同动作触发后，允许下发消息条数和下发时限不同。下发条数达到上限后，会返回错误码。

可发送客服消息条数不累加，上述用户动作会触发可下发条数及可下发时限的更新，可下发消息条数更新为当前可下发条数限制的最大值，有效下发时间限制也更新为最长有效时间。

# 调用客服消息接口发送客服消息

当用户给小程序客服发消息，微信服务器会将消息（或事件）的数据包（JSON或者XML格式）POST到开发者填写的URL。开发者收到请求后可以调用接口进行异步回复。

如小程序的客服消息权限集已授权给第三方平台，则所有的客服消息将推送到第三方平台的服务器，不再推送到开发者的服务器或推送到网页版客服工具

# 填写消息推送配置

登录小程序，在“设置-开发设置-消息推送”启用消息推送功能并完成相关信息配置（包括服务器地址、Token、及加密方式等）。

启用并设置服务器配置后，用户发送的消息以及开发者需要的事件推送，都将被微信转发至开发者URL中。

# 接口调用

小程序客服消息API文档

# 网页端客服工具与移动端小程序客服工具

小程序也可以直接使用网页端微信小程序客服或者移动端「客服小助手」小程序进行客服消息回复。

客服小助手小程序码

若小程序没有启用消息推送，则用户发送的消息将会被转发至网页端微信小程序客服和移动端「客服小助手」，客服人员可在网页端微信小程序客服和移动端「客服小助手」中接入并回复用户。

如小程序的客服消息权限集已授权给第三方平台，则所有的客服消息将推送到第三方平台的服务器，不再推送到开发者的服务器或推送到网页版客服工具。

注意：“用户通过客服消息按钮进入会话”事件将不会转发至网页端客服工具。

# 绑定客服人员

使用网页端与移动端小程序客服工具前，小程序管理员需在小程序后台完成客服人员的绑定。目前小程序支持绑定不多于100个客服人员。

# 移动端「客服小助手」小程序使用说明

# 登录并接入

已被绑定的小程序客服人员可微信搜索「客服小助手」或扫码登录「客服小助手」小程序，并选择对应的小程序账号，登录后即可看到与小程序对话的用户，可选择接入对话。

# 切换客服状态

点击在线状态，可以选择客服在线状态、客服离线状态： 选择客服在线状态后，即使退出客服小程序，仍可在“服务通知”中接收到用户咨询的消息提醒； 选择客服离线状态后，将无法收到客服消息与消息提醒。

# 接收与发送消息

打开「客服小助手」小程序后，进入“待接入列表”可选择用户会话进行接入； 已经接入的会话，客服人员可以在48小时内和用户进行对话，目前支持发送文本、图片、小程序卡片类型的消息。

# 网页端微信小程序客服工具使用说明

# 登录并接入

已被绑定的小程序客服人员可扫码登录网页端微信小程序客服，并选择对应的小程序账号，登录后即可看到与小程序对话的用户，可选择接入对话。

# 切换客服状态

点击在线状态，可以选择在线状态、离线状态

# 接收消息

手动接入：客服人员上线后，可在“待接入”列表中，手动接入待回复的用户会话。

自动接入：当待接入的用户会话太多时，可以在设置-接入与回复中，开启自动接入。

# 发送消息

已经接入的会话，客服人员可以在48小时内和用户进行对话，目前支持发送文本、图片、小程序卡片类型的消息。

# 使用规范

小程序客服消息使用除必须遵守《微信小程序平台运营规范》外，还不能违反以下规则，包括但不限于：

1. 不允许恶意诱导用户进行可能触发客服消息下发的操作，以达到可向用户下发客服消息目的
2. 不允许恶意骚扰，下发与用户发送的消息没有关联的、对用户造成骚扰的消息
3. 不允许恶意营销，下发内容涉嫌虚假夸大、违法类营销信息
4. 不允许使用客服消息向用户下发虚假、色情、暴力等违反国家法律规定的信息

# 客服消息开发文档

# 客服消息

# 在页面使用客服消息

需要将 button 组件 open-type 的值设置为 contact，当用户点击后就会进入客服会话，如果用户在会话中点击了小程序消息，则会返回到小程序，开发者可以通过 bindcontact 事件回调获取到用户所点消息的页面路径 path 和对应的参数 query，开发者需根据路径自行跳转。此外，开发者可以通过设置 session-from 将会话来源透传到客服。

示例代码

<button open-type="contact" bindcontact="handleContact" session-from="sessionFrom"></button>

Page({
    handleContact (e) {
        console.log(e.detail.path)
        console.log(e.detail.query)
    }
})

返回参数说明

# 后台接入消息服务

用户向小程序客服发送消息、或者进入会话等情况时，开发者填写的服务器 URL （如果使用的是云开发，则是配置的云函数）将得到微信服务器推送过来的消息和事件，开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送。

# 后台接入消息报错自查

# 报错表现

用户发送消息出现系统文案 “该小程序提供的服务出现故障，请稍后再试”。

# 报错原因

小程序配置callback后，用户发送的消息会推送到第三方服务器，如推送失败就会报错。

# 自查方式

# 1.小程序开启消息推送（小程序后台-开发管理-开发设置-消息推送）

# 2.小程序把「客服权限」授权给第三方平台（小程序后台-设置-第三方设置-第三方平台授权管理）

# *特殊情况

对于开启云函数且没开启云托管的小程序，用户发送的消息会推送到云函数，不会走到小程序客服系统，也不会callback给第三方服务器或者小程序消息推送的服务器地址。

# 将消息转发到客服

如果小程序处于开发模式，普通微信用户向小程序客服发消息时，微信服务器会先将消息POST到开发者填写的url上，如果希望将消息转发到客服系统，则需要开发者在响应包中返回MsgType为transfer_customer_service的消息，微信服务器收到响应后会把当次发送的消息转发至客服系统。

用户被客服接入以后，客服关闭会话以前，处于会话过程中时，用户发送的消息均会被直接转发至客服系统。当会话超过30分钟客服没有关闭时，微信服务器会自动停止转发至客服，而将消息恢复发送至开发者填写的url上。

用户在等待队列中时，用户发送的消息仍然会被推送至开发者填写的url上。

这里特别要注意，只针对微信用户发来的消息才进行转发，而对于其他任何事件都不应该转接，否则客服在客服系统上就会看到一些无意义的消息了。

调用说明

<xml> 
  <ToUserName><![CDATA[touser]]></ToUserName>  
  <FromUserName><![CDATA[fromuser]]></FromUserName>  
  <CreateTime>1399197672</CreateTime>  
  <MsgType><![CDATA[transfer_customer_service]]></MsgType>
</xml>

请求参数说明

# 客服管理

# 获取客服基本信息

该接口提供小程序下所有客服基本信息的列表获取。

调用说明

http请求方式: GET https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN

请求参数说明

返回说明

返回数据示例（正确时的JSON返回结果）

{
      "kf_list" : [
         {
            "kf_account" : "",
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1001",
            "kf_nick" : "ntest1",
            "kf_wx" : "kfwx1",
            "kf_openid": "kfopenid1"
         },
         {
            "kf_account" : "test1@test" ,
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1002",
            "kf_nick" : "ntest2",
            "kf_wx" : "kfwx2",
            "kf_openid": "kfopenid2"
         },
         {
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1003",
            "kf_nick" : "ntest3",
            "kf_openid": "kfopenid3"
         }
      ]
}

返回参数说明

# 获取在线客服列表

该接口提供小程序下所有在线客服列表的获取。

调用说明

http请求方式：GET https://api.weixin.qq.com/cgi-bin/customservice/getonlinekflist?access_token=ACCESS_TOKEN

请求参数说明

返回说明

返回参数示例

{
"kf_online_list" : [
    {
        "kf_account" : "test1@test" ,
        "status" : 1,
        "kf_id" : "1001",
        "kf_openid": "kfopenid1"
    },
    {
        "kf_account" : "",
        "status" : 1,
        "kf_id" : "1002",
        "kf_openid": "kfopenid2"
    }
]
}

返回参数说明

# 添加客服账号

该接口将给定的客服微信号添加为小程序客服账号。

调用说明

http请求方式: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN

请求参数示例

{
    "kf_wx" : "test1",
    "business_id" : 1
}

请求参数说明

返回说明

返回参数示例

// 返回数据示例（正确时的JSON返回结果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

# 删除客服账号

该接口根据给定的客服编号删除小程序客服账号。

调用说明

http请求方式: GET https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

请求参数说明

返回参数示例

// 返回数据示例（正确时的JSON返回结果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

# 设置客服管理员

该接口将小程序客服编号对应客服账号设置为客服管理员。

调用说明

http请求方式: GET https://api.weixin.qq.com/customservice/kfaccount/setadmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

请求参数说明

返回说明

返回参数示例

// 返回数据示例（正确时的JSON返回结果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

# 取消客服管理员

该接口根据小程序客服编号，解除对应客服账号客服管理员身份。

调用说明

http请求方式: GET https://api.weixin.qq.com/customservice/kfaccount/canceladmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID

请求参数说明

返回说明

返回参数示例

// 返回数据示例（正确时的JSON返回结果）：
{
    "errcode" : 0,
    "errmsg" : "ok"
}

# 主要返回码

# 小程序客服子商户能力介绍及开发文档

# 功能介绍

客服子商户能力，是微信公众平台为综合服务平台型小程序提供的客服能力支持。 一个小程序账号可为平台内的商户创建多个子商户账号，创建后在小程序客服组件唤起子商户单独的会话。多个子商户会话独立，可为用户提供更优质的客服体验。

# 开放范围

对【电商平台】类目小程序开放。权限开通流程登录小程序管理后台，进入“设置-接口设置”，开通能力。子商户账号数量上限开通后，单个小程序账号可申请子商户账号上限为500个，如需申请上调，请以《小程序客服子商户数量上调申请_小程序名称》为主题，发送邮件至placeofminiprogram@qq.com，邮件内注明小程序账号appid、小程序名称、使用背景、需要申请的账号量、业务下已有产品(包括app/网站/公众号)信息。审核通过后可提高子商户数量上限。

# 开发文档

# 创建商户

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/register?access_token=ACCESS_TOKEN

JSON数据包如下

{
    "account_name": "apple",
    "nickname": "苹果",
    "icon_media_id":"media_id"
    "transfer_to_commkf": true
}

返回报文示例

{ "business_id": 1 }

参数说明

返回码说明

# 更新商户信息

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/update?access_token=ACCESS_TOKEN

JSON数据包如下

{
    "business_id": 1,
    "nickname": "苹果",
    "icon_media_id":""
}

返回报文示例

{
    "errcode": 0,
    "errmsg": "ok"
}

说明

1. nickname为空则不更新昵称
2. icon_media_id为空则不更新头像

参数说明

返回码说明

# 拉取单个商户信息

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/get?access_token=ACCESS_TOKEN

JSON数据包如下

{
    "business_id": 1
}
或
{
    "account_name": "apple"
}

返回报文示例

{
    "business_info":
    {
        "business_id": 1,
        "account_name": "apple",
        "nickname":"苹果",
        "icon_url":"icon_url"
    }
}

参数说明

返回码说明

# 拉取多个商户信息

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/list?access_token=ACCESS_TOKEN

JSON数据包如下

{
    "offset": 0,
    "count": 100
}

返回报文示例

{
    "list": [
        {
            "business_id": 1,
            "account_name": "apple",
            "nickname":"苹果",
            "icon_url":"icon_url"
        },
        {
            "business_id": 2,
            "account_name": "apple",
            "nickname":"苹果",
            "icon_url":"icon_url"
        }
    ]
}

说明: 某一次请求的返回的数据量小于count数，说明请求的数据已经到了末端

参数说明

# 接收消息推送

具体说明可以参考客服消息接收消息和事件 推送时会增加一个参数BusinessId，代表消息是从子商户的会话中过来的。 以发送文本消息为例:

JSON格式示例

{
    "ToUserName": "toUser",
    "FromUserName": "fromUser",
    "CreateTime": 1482048670,
    "MsgType": "text",
    "Content": "this is a test",
    "MsgId": 1234567890123456,
    "BusinessId": 1
}

XML格式示例

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>
    <FromUserName><![CDATA[fromUser]]></FromUserName>
    <CreateTime>1482048670</CreateTime>
    <MsgType><![CDATA[text]]></MsgType>
    <Content><![CDATA[this is a test]]></Content>
    <MsgId>1234567890123456</MsgId>
    <BusinessId>1</BusinessId>
</xml>

# 发送客服消息

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/send?access_token=ACCESS_TOKEN

JSON数据包

除请求url不同外，postdata可直接参考原有发送客服消息JSON数据包，并在此基础上加上参数businessid 。以发

送文本消息为例:

{
    "touser":"OPENID",
    "businessid":1,
    "msgtype":"text",
    "text":
    {
    "content":"Hello World"
    }
}

# 客服输入状态

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/typing?access_token=ACCESS_TOKEN

JSON数据包

除请求url不同外，postdata可直接参考原有客服输入状态接口的JSON数据包，并在此基础上增加参数 businessid，示例如下:

{
    "businessid":1,
    "touser":"OPENID",
    "command":"Typing"
}

# 小程序组件发起子商户客服会话

button 增加一个属性 business-id，表示子商户 ID。