# 客服消息使用指南

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

# 一、功能介绍

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

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

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

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

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

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

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

# 二、下发条件说明

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

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

用户动作	允许下发条数限制	下发时限
用户发送信息	5 条	48 小时
用户进入客服消息	2 条	1 分钟

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

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

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

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

# 3.1 填写消息推送配置

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

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

# 3.2 接口调用

小程序客服消息API文档

# 四、客服工具

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

以下是客服小助手小程序码：

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

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

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

# 4.1 绑定客服人员

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

# 4.2 移动端「客服小助手」小程序

# 登录并接入

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

# 切换客服状态

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

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

# 接收与发送消息

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

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

# 登录并接入

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

# 切换客服状态

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

# 接收消息

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

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

# 发送消息

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

# 五、使用规范

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

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

# 六、开发文档

# 6.1 在页面使用客服消息

需要将 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)
    }
})

返回参数说明

参数	类型	说明
path	String	小程序消息指定的路径
query	Object	小程序消息指定的查询参数

# 6.2 后台接入消息服务

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

# 6.3 后台接入消息报错自查

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

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

自查方式：

小程序开启消息推送（小程序后台-开发管理-开发设置-消息推送）
小程序把「客服权限」授权给第三方平台（小程序后台-设置-第三方设置-第三方平台授权管理）

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

# 6.4 将消息转发到客服

如果小程序处于开发模式，普通微信用户向小程序客服发消息时，微信服务器会先将消息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>

请求参数说明

参数	是否必须	描述
ToUserName	是	接收方OpenID账号
FromUserName	是	开发者微信号
CreateTime	是	消息创建时间戳（整型）
MsgType	是	transfer_customer_service

# 6.5 客服管理服务端

# 七、客服子商户

# 7.1 功能介绍

客服子商户能力，是微信公众平台为综合服务平台型小程序提供的客服能力支持。

一个小程序账号可为平台内的商户创建多个子商户账号，创建后在小程序客服组件唤起子商户单独的会话。多个子商户会话独立，可为用户提供更优质的客服体验。

# 7.2 开放范围

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

# 7.3 服务端接口

有些接口和普通账号共用，在正常参数的基础上加上参数 businessid

# 7.4 接收消息推送

具体说明可以参考客服消息接收消息和事件推送时会增加一个参数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>

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

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