---
headers: true
---

# 客服消息使用指南

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

## 一、功能介绍

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

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

1、小程序内：开发者在小程序内添加[客服消息按钮组件](/miniprogram/dev/component/button.md)，用户可在小程序内唤起客服会话页面，给小程序发消息；

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/68b81164-a4a0-4658-afb8-b042b7f8545e.png)

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

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

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

## 二、下发条件说明

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

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

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

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

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

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

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

### 3.1 填写消息推送配置

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/8ac58d7c-9ee2-4753-82ee-826b3da2e575.png)

![](https://res8.wxqcloud.qq.com.cn/wxdoc/f31a5b6d-32dc-47a2-8328-25d53ea091e6.png)

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/40dd926e-7646-4a3c-bf1f-7a499177d21c.png)

### 3.2 接口调用

[小程序客服消息API文档](/miniprogram/dev/server/API/kf-mgnt/README.md)

## 四、客服工具

小程序也可以直接使用[网页端微信小程序客服](https://mpkf.weixin.qq.com)或者移动端「客服小助手」小程序进行客服消息回复。

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/d7b0164b-d87a-4995-8479-778e18886a26.png)

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

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

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

### 4.1 绑定客服人员

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

![](https://res8.wxqcloud.qq.com.cn/wxdoc/6c5235f8-25c5-488c-a6d7-96bc4dd1ee9f.png)

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

#### 登录并接入

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

#### 切换客服状态

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

![](https://res.wx.qq.com/op_res/uQn5PUsI8uQzCzEUh-y5PySkx1zk3e7YmlzW5JU_3v9M-H3fmkN8OvLeeZeuL0BhQVOEmrToP43oIDGti5KEPw)

#### 接收与发送消息

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

![](https://res.wx.qq.com/op_res/Ca1Kvi4QD9sCH-77wqSG5gZSiYUvbT1z0Y05XiCG0wzJR8jR6SNa9mG0jcWxSVC3SAURQVQzv6iHgutFKMP_fg)

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

#### 登录并接入

已被绑定的小程序客服人员可扫码登录[网页端微信小程序客服](https://mpkf.weixin.qq.com)，并选择对应的小程序账号，登录后即可看到与小程序对话的用户，可选择接入对话。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/5839a0b0-7750-480b-aa25-69797fdb53b6.png)

#### 切换客服状态

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

![](https://res.wx.qq.com/op_res/sVBtkgXbfgFp1FEP63VyCDwOsbGiGPF7evG9RjkPUcpYLWDq1oYB5-Etg8_xKFwCLx90GbflE0lK7BTC1NvZvg)

#### 接收消息

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

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

![](https://res.wx.qq.com/op_res/EIcm7DwOE8uWcWSYjpskDzCFWFPyrpOkTQDCCr4FttTQLt56fqLxuGC81otQNBUAzzOJ9D3RVzMJ__xOHami9A)

#### 发送消息

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

![](https://res.wx.qq.com/op_res/RB-KJfdI43b3RgxmpwSTQDN3GwlowyFvG8wARzJawXOyAaTtJoso8W4JHbzecE5JRqxM6g74PBahzOWEx4T_Ag)

## 五、使用规范

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

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

## 六、开发文档

### 6.1 在页面使用客服消息

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

**示例代码**

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

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

**返回参数说明**

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

### 6.2 后台接入消息服务

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

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

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

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

**自查方式：**

1. 小程序开启消息推送（小程序后台 - 开发管理 - 开发设置 - 消息推送）
    ![](https://res.wx.qq.com/op_res/rsVC2CsIdOadPgt22djjEb-YpsGq9B-dRv6k6vTAOT4iBioV_ZTk2yM8sLeiojkf3nvdW81_AqSjn8Q1UFk8ug)
2. 小程序把「客服权限」授权给第三方平台（小程序后台 - 设置 - 第三方设置 - 第三方平台授权管理）
    ![](https://res.wx.qq.com/op_res/rsVC2CsIdOadPgt22djjEXoXTrkdHIiJRa8nNaBt3NYAAur83jjqLx4_phqmBmmofP0wy2DAnbUxMr0QttbLDg)

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

### 6.4 将消息转发到客服

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

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

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

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

**调用说明**

```XML
<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 客服管理服务端

- [获取所有客服账号](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_getkflist.md)
- [获取在线客服列表](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_getonlinekflist.md)
- [添加客服账号](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_addkfaccount.md)
- [删除客服账号](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_delkfaccount.md)
- [设置客服管理员](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_setkfadmin.md)
- [取消客服管理员](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_cancelkfadmin.md)

## 七、客服子商户

### 7.1 功能介绍

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

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

### 7.2 开放范围

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

### 7.3 服务端接口

- [客服子商户 API 文档](/miniprogram/dev/server/API/kf-mgnt/kf-management/README.md)
- [发送客服消息](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_sendcustommessage.md)
- [客服输入状态](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_typing.md)

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

### 7.4 接收消息推送

具体说明可以参考[客服消息接收消息和事件](/miniprogram/dev/framework/open-ability/customer-message/receive.md)
推送时会增加一个参数BusinessId，代表消息是从子商户的会话中过来的。
以发送文本消息为例:

**JSON 格式示例**

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

**XML 格式示例**

```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。
