8.8.5 客服消息

接收消息和事件

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

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

微信服务器在将用户的消息发给小程序的开发者服务器地址（开发设置处配置）后，微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，如果在调试中，发现用户无法收到响应的消息，可以检查是否消息处理超时。

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

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

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

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

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

各消息类型的推送JSON、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>
</xml>

JSON 格式

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

参数说明参考表8-110。

表8-110

图片消息

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

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>

JSON 格式

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

参数说明(如表8-111)

表8-111

进入会话事件

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

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>

JSON 格式

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

参数说明，如表8-112

表8-112

发送客服消息

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

目前允许的动作列表如下，不同动作触发后，允许的客服接口下发消息条数和下发时限不同参考表8-113。下发条数达到上限后，会收到错误。

表8-113

客服接口-发消息

接口调用请求说明

http请求方式: POST

https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

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

发送文本消息

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

发送图片消息

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

参数说明，参考表8-114。

表8-114

返回码说明(表8-115)

表8-115

临时素材接口

获取临时素材

小程序可以使用本接口获取客服消息内的临时素材（即下载临时的多媒体文件）。目前小程序仅支持下载图片文件。

接口调用请求说明： HTTP 请求方式: GET，HTTPS 调用

https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

请求示例（示例为通过curl命令获取多媒体文件）

curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

参数说明(表8-116)

表8-116

返回说明 正确情况下的返回 HTTP 头如下：

HTTP/1.1 200 OK
Connection: close
Content-Type: image/jpeg 
Content-disposition: attachment; filename="MEDIA_ID.jpg"
Date: Sun, 06 Jan 2013 10:20:18 GMT
Cache-Control: no-cache, must-revalidate
Content-Length: 339721
curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

如果返回的是视频消息素材，则内容如下：

{
"video_url":DOWN_URL
}

错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：

{
"errcode":40007,
"errmsg":"invalid media_id"
}

新增临时素材

小程序可以使用本接口把媒体文件（目前仅支持图片）上传到微信服务器，用户发送客服消息或被动回复用户消息。

接口调用请求说明 HTTP 请求方式：POST/FORM，HTTPS 调用

https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

调用示例（使用curl命令，用FORM表单方式上传一个多媒体文件）：

curl -F [email protected] "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

参数说明(表8-117)

表8-117

返回说明 正确情况下的返回 JSON 数据包结果如下：

{
  "type":"TYPE",
  "media_id":"MEDIA_ID",
  "created_at":123456789
}

参数描述参考表8-118

错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：

{
  "errcode":40004,
  "errmsg":"invalid media type"
}

接入概述

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

1、填写服务器配置

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

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

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

第一步：填写服务器配置

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

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

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

模式的选择与服务器配置在提交后都会立即生效，请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码。如图8-38。 图8-38

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

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

表8-119

开发者通过检验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示例代码下载：https://wximg.gtimg.com/shake_tv/mpwiki/cryptoDemo.zip

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

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

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