微信小程序客服消息
小程序业务需求要用到客服消息,在此记录。
功能介绍
用户可使用小程序客服消息功能,与小程序的客服人员进行沟通。
客服消息会话入口有两个:
-
小程序内:开发者在小程序内添加客服消息按钮组件,用户可在小程序内唤起客服会话页面,给小程序发消息;
-
已使用过的小程序客服消息会聚合显示在微信会话“小程序客服消息”内,用户可以在小程序外查看历史客服消息,并给小程序客服发消息。
客服消息下发条件
小程序用户在小程序内唤起客服会话或用户给小程序客服发送消息,具体下发时间有效期及消息条数限制见客服消息下发条件说明
客服消息类型
目前支持文本及图片类型消息
为尽量满足小程序开发者的需求,小程序可通过以下两种方式下发客服消息:
-
调用发送客服消息接口;
-
使用公众平台网页版客服工具
调用客服消息接口发送客服消息
当用户给小程序客服发消息,微信服务器会将消息(或事件)的数据包(JSON或者XML格式)POST到开发者填写的URL。开发者收到请求后可以调用接口进行异步回复。
如小程序的客服消息权限集已授权给第三方平台,则所有的客服消息将推送到第三方平台的服务器,不再推送到开发者的服务器或推送到网页版客服工具
填写消息推送配置
登录小程序,在“设置-开发设置-消息推送”启用消息推送功能并完成相关信息配置(包括服务器地址、Token、及加密方式等)。
启用并设置服务器配置后,用户发送的消息以及开发者需要的事件推送,都将被微信转发至开发者URL中。
网页版客服工具与移动端小程序客服工具
小程序也可以直接使用微信公众平台网页版客服工具或者移动端小程序客服小助手进行客服消息回复。
客服小助手小程序码:
若小程序没有启用消息推送,则用户发送的消息将会被转发至网页版和移动端小程序客服工具,客服人员可在网页版与移动端小程序客服工具中接入并回复用户。
如小程序的客服消息权限集已授权给第三方平台,则所有的客服消息将推送到第三方平台的服务器,不再推送到开发者的服务器或推送到网页版客服工具。
注意:“用户通过客服消息按钮进入会话”事件将不会转发至网页版客服工具。
使用网页版与移动端小程序客服工具前,小程序管理员需在小程序后台完成客服人员的绑定。目前小程序支持绑定不多于100个客服人员。
使用说明(后台接入消息服务)
一、在页面使用客服消息
需要将button组件 open-type 的值设置为contact,当用户点击后就会进入客服会话,如果用户在会话中点击了小程序消息,则会返回到小程序,开发者可以通过bindcontact 事件回调获取到用户所点消息的页面路径 path 和对应的参数 query。
示例:
<button open-type="contact" bindcontact="handleContact"></button>
二、后台接入消息服务
用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置
URL将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送。
第一步:填写服务器配置
登录小程序后台后,在「开发」-「开发设置」-「消息推送」中,管理员扫码启用消息服务,填写服务器地址(URL)、令牌(Token)和 消息加密密钥(EncodingAESKey)等信息。
URL: 开发者用来接收微信消息和事件的接口 URL。开发者所填写的URL 必须以http:// 或 https:// 开头,分别支持 80 端口和 443 端口。
Token: 可由开发者可以任意填写,用作生成签名(该 Token 会和接口 URL 中包含的Token 进行比对,从而验证安全性)。
EncodingAESKey: 由开发者手动填写或随机生成,将用作消息体加解密密钥。
同时,开发者可选择消息加解密方式:明文模式(默认)、兼容模式和安全模式。可以选择消息数据格式:XML格式(默认)或 JSON 格式。
模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考消息加解密说明。
第二步:验证消息的确来自微信服务器
开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:
signature 微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
参数 | 说明 |
---|---|
timestamp | 时间戳 |
nonce | 随机数 |
echostr | 随机字符串 |
开发者通过检验 signature 对请求进行校验(下面有校验方式)。若确认此次 GET请求来自微信服务器,请原样返回 echostr参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下:
-
将token、timestamp、nonce三个参数进行字典序排序
-
将三个参数字符串拼接成一个字符串进行sha1加密
-
开发者获得加密后的字符串可与signature对比,标识该请求来源于微信
验证URL有效性成功后即接入生效,成为开发者。
第三步:接收消息和事件
当某些特定的用户操作引发事件推送时(如用户向小程序客服发送消息、或者进入会话等情况),微信服务器会将消息(或事件)的数据包以POST 请求发送到开发者配置的 URL,开发者可以依据自身业务逻辑进行响应。
微信服务器在将用户的消息发给开发者服务器地址后,微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。
如果在调试中,发现用户无法收到响应的消息,可以检查是否消息处理超时。关于重试的消息排重,有msgid 的消息推荐使用 msgid 排重。
事件类型消息推荐使用 FromUserName + CreateTime排重。
服务器收到请求必须做出下述回复,这样微信服务器才不会对此作任何处理,并且不会发起重试,否则,将出现严重的错误提示。详见下面说明:
-
直接回复success(推荐方式)
-
直接回复空串(指字节长度为0的空字符串,而不是结构体中content字段的内容为空)
-
若接口文档有指定返回内容,应按文档说明返回
对于客服消息,一旦遇到以下情况,微信会在小程序会话中向用户下发系统提示“该小程序客服暂时无法提供服务,请稍后再试”:
-
开发者在5秒内未回复任何内容
-
开发者回复了异常数据
如果开发者希望增强安全性,可以在开发者中心处开启消息加密,这样,用户发给小程序的消息以及小程序被动回复用户消息都会继续加密,详见消息加解密说明。
三、接收消息和事件
在页面中使用 <button open-type="contact" />
可以显示进入客服会话按钮。
当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时,微信服务器会将消息或事件的数据包发送到开发者填写的URL。开发者收到请求后可以使用