# 客服消息使用指南

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

# 功能介绍

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

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

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

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

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

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

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

# 下发条件说明

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

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

用户动作 允许下发条数限制 下发时限
用户发送信息 5条 48小时

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

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

当用户给小程序客服发消息,微信服务器会将消息(或事件)的数据包(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)
    }
})

返回参数说明

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

# 后台接入消息服务

用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器 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>

请求参数说明

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

# 客服管理

# 获取客服基本信息

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

调用说明

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"
         }
      ]
}

返回参数说明

参数 说明
kf_nick 客服昵称
kf_id 客服编号
kf_headimgurl 客服头像
kf_wx 客服微信号
kf_openid 客服openid

# 获取在线客服列表

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

调用说明

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"
    }
]
}

返回参数说明

参数 说明
status 客服在线状态,1: Web在线
kf_id 客服编号
kf_openid 客服openid

# 添加客服账号

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

调用说明

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

请求参数示例

{
    "kf_wx" : "test1"
}

请求参数说明

参数 是否必须 说明
kf_wx 客服微信号

返回说明

返回参数示例

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

# 删除客服账号

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

调用说明

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

请求参数说明

参数 是否必须 说明
kf_openid 客服openid

返回参数示例

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

# 设置客服管理员

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

调用说明

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

请求参数说明

参数 是否必须 说明
kf_openid 客服openid

返回说明

返回参数示例

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

# 取消客服管理员

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

调用说明

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

请求参数说明

参数 是否必须 说明
kf_openid 客服openid

返回说明

返回参数示例

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

# 主要返回码

返回码 说明
0 成功
65400 API不可用,即没有开通/升级到新版客服功能
65401 无效客服帐号
65402 客服帐号尚未绑定微信号,不能投入使用
65403 客服昵称不合法
65404 客服帐号不合法
65405 帐号数目已达到上限,不能继续添加
65406 已经存在的客服帐号
65407 邀请对象已经是该小程序客服
65408 本小程序已经有一个邀请给该微信
65409 无效的微信号
65410 邀请对象绑定小程序客服数达到上限
65411 该帐号已经有一个等待确认的邀请,不能重复邀请
65412 该帐号已经绑定微信号,不能进行邀请
65413 不存在对应用户的会话信息
65414 客户正在被其他客服接待
40003 非法的openid
40005 不支持的媒体类型
40009 媒体文件长度不合法

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

# 功能介绍

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

# 开放范围

对【电商平台】类目小程序开放。权限开通流程登录小程序管理后台,进入“设置 - 接口设置”,开通能力。子商户帐号数量上限开通后,单个小程序帐号可申请子商户帐号上限为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"
}

返回报文示例

{ "business_id": 1 }

参数说明

参数 必填 说明
account_name 创建商户时用到,一个account_name只能创建一次,account_name为6-30字符,必须为英文、数字、或者下划线,区分大小写。
nickname 商户昵称,会在客户端会话里展示,4-30字符(中文视为2字符),由中文、英文、数字组成
icon_media_id 头像,图片类型,需要用临时素材接口得到:新增临时素材;为空则不更新头像

返回码说明

参数 说明
45070 account_name对应账号已经被创建(一个account_name对应一个business_id)
45077 子商户数量已达到上限
45078 昵称不合法,请检查是否满足 nickname 规则
45079 昵称含有违规词汇
40007 icon_media_id不是合法的media_id
40004 icon_media_id类型不对,应该为图片类型
45091 account_name不合法,请检查是否满足account_name规则

# 更新商户信息

接口调用请求说明

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为空则不更新头像

参数说明

参数 必填 说明
business_id 创建商户时得到的商户id
nickname 商户昵称,会在客户端会话里展示,4-30字符(中文视为2字符),由中文、英文、数字组成;为空则不更新昵称
icon_media_id 头像,图片类型,需要用临时素材接口得到:新增临时素材;为空则不更新头像

返回码说明

参数 说明
45071 business_id对应的商户不存在
45077 子商户数量已达到上限
45078 昵称不合法,请检查是否满足 nickname 规则
45079 昵称含有违规词汇
40007 icon_media_id不是合法的media_id
40004 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"
    }
}

参数说明

参数 必填 说明
business_id 创建商户时得到的商户 id ,与account_name选填一个
account_name 创建商户时用到的account_name,与business_id选填一个

返回码说明

参数 说明
45071 business_id/account_name对应的商户不存在

# 拉取多个商户信息

接口调用请求说明

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 数,说明请求的数据已经到了末端

参数说明

参数 必填 说明
offset 用于分页拉取,从0开始
count 一次拉取的商户个数,最多为200

# 接收消息推送

具体说明可以参考客服消息接收消息和事件 推送时会增加一个参数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 和 contact-button 组件都增加一个属性 business-id,表示子商户 ID。