微信小程序教程
7.12.6 客服消息
阅读(

微信小程序介绍

微信小程序设计指南

微信小程序开发简介

微信小程序开发框架

微信小程序框架视图层

微信小程序框架组件

微信小程序框架 API

概述

网络

媒体

操作文件

本地存储

位置

设备

界面

Canvas绘图

WXML节点信息

第三方平台

开放接口

模板信息

微信支付

授权

用户信息

授权

客服消息

接收消息和事件

在页面中使用<contact-button/>可以显示进入客服会话按钮。

当用户在客服会话发送消息(或进行某些特定的用户操作引发的事件推送时),微信服务器会将消息(或事件)的数据包(JSON或者XML格式)POST请求开发者填写的URL。开发者收到请求后可以使用发送客服消息接口进行异步回复。

微信服务器在将用户的消息发给小程序的开发者服务器地址(开发设置处配置)后,微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次,如果在调试中,发现用户无法收到响应的消息,可以检查是否消息处理超时。关于重试的消息排重,有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime 排重。

服务器收到请求必须做出下述回复,这样微信服务器才不会对此作任何处理,并且不会发起重试,否则,将出现严重的错误提示。详见下面说明:

1、直接回复success(推荐方式)
2、直接回复空串(指字节长度为0的空字符串,而不是结构体中content字段的内容为空)

一旦遇到以下情况,微信都会在小程序会话中,向用户下发系统提示“该小程序客服暂时无法提供服务,请稍后再试”:

1、开发者在5秒内未回复任何内容
2、开发者回复了异常数据

如果开发者希望增强安全性,可以在开发者中心处开启消息加密,这样,用户发给小程序的消息以及小程序被动回复用户消息都会继续加密,详见消息加解密说明

各消息类型的推送JSON、XML数据包结构如下。

1. 文本消息

用户在客服会话中发送文本消息时将产生如下数据包:

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>
</xml>

2)JSON 格式

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

参数说明

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型)
MsgType text
Content 文本消息内容
MsgId 消息id,64位整型
2. 图片消息

用户在客服会话中发送图片消息时将产生如下数据包:

1)XML 格式

<xml>
      <ToUserName><![CDATA[toUser]]></ToUserName>
      <FromUserName><![CDATA[fromUser]]></FromUserName>
      <CreateTime>1482048670</CreateTime>
      <MsgType><![CDATA[image]]></MsgType>
      <PicUrl><![CDATA[this is a url]]></PicUrl>
      <MediaId><![CDATA[media_id]]></MediaId>
      <MsgId>1234567890123456</MsgId>
</xml>

2)JSON 格式

{
    "ToUserName": "toUser",
    "FromUserName": "fromUser",
    "CreateTime": 1482048670,
    "MsgType": "image",
    "PicUrl": "this is a url",
    "MediaId": "media_id",
    "MsgId": 1234567890123456
}

参数说明

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型)
MsgType image
PicUrl 图片链接(由系统生成)
MediaId 图片消息媒体id,可以调用获取临时素材接口拉取数据。
MsgId 消息id,64位整型
3. 小程序卡片消息

用户在客服会话中发送小程序卡片消息时将产生如下数据包:

1)XML 格式

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>
    <FromUserName><![CDATA[fromUser]]></FromUserName>
    <CreateTime>1482048670</CreateTime>
    <MsgType><![CDATA[miniprogrampage]]></MsgType>
    <MsgId>1234567890123456</MsgId>
    <Title><![CDATA[Title]]></Title>
    <AppId><![CDATA[AppId]]></AppId>
    <PagePath><![CDATA[PagePath]]></PagePath>
    <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>
    <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId>
</xml>

2)JSON 格式

{
    "ToUserName": "toUser",
    "FromUserName": "fromUser",
    "CreateTime": 1482048670,
    "MsgType": "miniprogrampage",
    "MsgId": 1234567890123456,
    "Title":"title",
    "AppId":"appid",
    "PagePath":"path",
    "ThumbUrl":"",
    "ThumbMediaId":""
}

参数说明

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型)
MsgType miniprogrampage
MsgId 消息id,64位整型
Title 标题
AppId 小程序appid
PagePath 小程序页面路径
ThumbUrl 封面图片的临时cdn链接
ThumbMediaId 封面图片的临时素材id
4. 进入会话事件

用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包:

1)XML 格式

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>  
    <FromUserName><![CDATA[fromUser]]></FromUserName>  
    <CreateTime>1482048670</CreateTime>  
    <MsgType><![CDATA[event]]></MsgType>  
    <Event><![CDATA[user_enter_tempsession]]></Event>  
    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom> 
</xml>

2)JSON 格式

{
    "ToUserName": "toUser",
    "FromUserName": "fromUser",
    "CreateTime": 1482048670,
    "MsgType": "event",
    "Event": "user_enter_tempsession",
    "SessionFrom": "sessionFrom"
}

参数说明

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 事件创建时间(整型)
MsgType event
Event 事件类型,user_enter_tempsession
SessionFrom 开发者在客服会话按钮设置的sessionFrom参数

发送客服消息

当用户和小程序客服产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口,通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。

目前允许的动作列表如下,不同动作触发后,允许的客服接口下发消息条数和下发时限不同。下发条数达到上限后,会收到错误返回码,具体请见返回码说明页:

用户动作 允许下发条数限制 下发时限
用户通过客服消息按钮进入会话 1条 1分钟
用户发送信息 5条 48小时
客服接口-发消息

接口调用请求说明

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

各消息类型所需的JSON数据包如下:

1. 发送文本消息

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

发送文本消息时,支持添加可跳转小程序的文字链

文本内容....<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>

说明:

  1. data-miniprogram-appid 项,填写小程序appid,则表示该链接跳转小程序;
  2. data-miniprogram-path项,填写小程序路径,路径与app.json中保持一致,可带参数;
  3. 对于不支持data-miniprogram-appid 项的客户端版本,如果有herf项,则仍然保持跳href中的链接;
  4. 小程序发带小程序文字链的文本消息,data-miniprogram-appid必须是该小程序的appid。

2. 发送图片消息

{
    "touser":"OPENID",
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"
    }
}

3. 发送图文链接

每次可以发送一个图文链接

{

    "touser": "OPENID",
    "msgtype": "link",
    "link": {
          "title": "Happy Day",
          "description": "Is Really A Happy Day",
          "url": "URL",
          "thumb_url": "THUMB_URL"
    }
}

4. 发送小程序卡片

{
    "touser":"OPENID",
    "msgtype":"miniprogrampage",
    "miniprogrampage":{
        "title":"title",
        "pagepath":"pagepath",
        "thumb_media_id":"thumb_media_id"
    }
}

参数说明

参数 是否必须 说明
access_token 调用接口凭证
touser 普通用户(openid)
msgtype 消息类型,文本为text,图文链接为link
content 文本消息内容
media_id 发送的图片的媒体ID,通过新增素材接口上传图片文件获得。
title 消息标题
description 图文链接消息
url 图文链接消息被点击后跳转的链接
picurl 图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80
pagepath 小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
thumb_media_id 小程序消息卡片的封面, image类型的media_id,通过新增素材接口上传图片文件获得,建议大小为520*416

返回码说明

参数 说明
-1 系统繁忙,此时请开发者稍候再试
0 请求成功
40001 获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的小程序调用接口
40002 不合法的凭证类型
40003 不合法的 OpenID,请开发者确认OpenID否是其他小程序的 OpenID
45015 回复时间超过限制
45047 客服接口下行条数超过上限
48001 api功能未授权,请确认小程序已获得该接口

转发消息

如果小程序设置了消息推送,普通微信用户向小程序客服发消息时,微信服务器会先将消息 POST 到开发者填写的 url 上,如果希望将消息转发到网页版客服工具,则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后会把当次发送的消息转发至客服系统。

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

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

这里特别要注意,只针对微信用户发来的消息才进行转发,而对于其他事件(比如用户从小程序唤起客服会话)都不应该转接,否则客服在客服系统上就会看到一些无意义的消息了。

消息转发到网页版客服工具

开发者只在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后就会把当次发送的消息转发至客服系统。

 <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

客服输入状态

开发者可通过调用“客服输入状态接口”,返回客服当前输入状态给用户。

  1. 此接口需要客服消息接口权限。
  2. 如果不满足发送客服消息的触发条件,则无法下发输入状态。
  3. 下发输入状态,需要客服之前30秒内跟用户有过消息交互。
  4. 在输入状态中(持续15s),不可重复下发输入态。
  5. 在输入状态中,如果向用户下发消息,会同时取消输入状态。

接口调用请求说明

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

JSON数据包如下:

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

预期返回:

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

参数说明

参数 是否必须 说明
access_token 调用接口凭证
touser 普通用户(openid)
command "Typing":对用户下发“正在输入"状态;"CancelTyping":取消对用户的”正在输入"状态

返回码说明

参数 说明
45072 command字段取值不对
45080 下发输入状态,需要之前30秒内跟用户有过消息交互
45081 已经在输入状态,不可重复下发

接入指引

接入微信小程序消息服务,开发者需要按照如下步骤完成:

1、填写服务器配置

2、验证服务器地址的有效性

3、依据接口文档实现业务逻辑

下面详细介绍这3个步骤。

第一步:填写服务器配置

登录微信小程序官网后,在小程序官网的“设置-消息服务器”页面,管理员扫码启用消息服务,填写服务器地址(URL)、Token 和 EncodingAESKey。

URL是开发者用来接收微信消息和事件的接口URL。 Token可由开发者可以任意填写,用作生成签名(该Token会和接口URL中包含的Token进行比对,从而验证安全性)。 EncodingAESKey由开发者手动填写或随机生成,将用作消息体加解密密钥。

同时,开发者可选择消息加解密方式:明文模式、兼容模式和安全模式。可以选择消息数据格式:XML格式或JSON格式。加密方式的默认状态是明问格式,而数据格式的默认状态是XML格式。

模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考消息加解密说明

填写服务器配置

第二步:验证消息的确来自微信服务器

开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:

参数 描述
signature 微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
timestamp 时间戳
nonce 随机数
echostr 随机字符串

开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自微信服务器,请原样返回echostr参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下: 1、将token、timestamp、nonce三个参数进行字典序排序 2、将三个参数字符串拼接成一个字符串进行sha1加密 3、开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

检验signature的PHP示例代码:

private function checkSignature()
{
    $signature = $_GET["signature"];
    $timestamp = $_GET["timestamp"];
    $nonce = $_GET["nonce"];

    $token = TOKEN;
    $tmpArr = array($token, $timestamp, $nonce);
    sort($tmpArr, SORT_STRING);
    $tmpStr = implode( $tmpArr );
    $tmpStr = sha1( $tmpStr );

    if( $tmpStr == $signature ){
        return true;
    }else{
        return false;
    }
}

PHP示例代码下载:下载

第三步:依据接口文档实现业务逻辑

验证URL有效性成功后即接入生效,成为开发者。至此用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置URL将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。

另请注意,开发者所填写的URL必须以 http:// 或 https:// 开头,分别支持80端口和443端口。

如果本教程对您帮助很大,请随意打赏。您的支持,将鼓励我们提供更好的教程!

← 键盘方向键翻页 →
返回顶部 手机访问 关注微信 返回底部

扫码访问歪脖网

随时随地,想看就看

关注歪脖网微信

分享 web 知识、交流 web 经验