小程序业务需求要用到客服消息，在此记录。

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

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

小程序内：开发者在小程序内添加客服消息按钮组件，用户可在小程序内唤起客服会话页面，给小程序发消息；

已使用过的小程序客服消息会聚合显示在微信会话“小程序客服消息”内，用户可以在小程序外查看历史客服消息，并给小程序客服发消息。

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

客服消息类型 目前支持文本及图片类型消息

为尽量满足小程序开发者的需求，小程序可通过以下两种方式下发客服消息：

调用发送客服消息接口；

使用公众平台网页版客服工具

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

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

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

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

小程序也可以直接使用微信公众平台网页版客服工具或者移动端小程序客服小助手进行客服消息回复。

客服小助手小程序码：

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

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

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

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

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

示例：

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

开发者通过检验 signature 对请求进行校验（下面有校验方式）。若确认此次 GET请求来自微信服务器，请原样返回 echostr参数内容，则接入生效，成为开发者成功，否则接入失败。加密/校验流程如下：

将token、timestamp、nonce三个参数进行字典序排序

将三个参数字符串拼接成一个字符串进行sha1加密

开发者获得加密后的字符串可与signature对比，标识该请求来源于微信

验证URL有效性成功后即接入生效，成为开发者。

第三步：接收消息和事件

当某些特定的用户操作引发事件推送时（如用户向小程序客服发送消息、或者进入会话等情况），微信服务器会将消息（或事件）的数据包以POST 请求发送到开发者配置的 URL，开发者可以依据自身业务逻辑进行响应。

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

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

直接回复success（推荐方式）

直接回复空串（指字节长度为0的空字符串，而不是结构体中content字段的内容为空）

若接口文档有指定返回内容，应按文档说明返回

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

开发者在5秒内未回复任何内容

开发者回复了异常数据

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

在页面中使用 可以显示进入客服会话按钮。

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

各消息类型的推送JSON、XML数据包结构如下。（以下只示例JSON格式）

文本消息

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

图片消息

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

小程序卡片消息

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

进入会话事件

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

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

目前允许的动作列表如下，不同动作触发后，允许的客服接口下发消息条数和下发时限不同。

用户动作 允许下发条数限制 下发时限

用户发送消息 5 条 48 小时

请求地址（POST）

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

获取接口调用凭据

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

下发消息示例：

发送文本消息

发送文本消息时，支持添加可跳转小程序的文字连接：

文本内容…点击跳小程序

说明：

data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序；

data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；

对于不支持 data-miniprogram-appid 项的客户端版本（6.5.16 以下），如果有 herf 项，则仍然保持跳 href 中的链接；

小程序发带小程序文字链的文本消息，data-miniprogram-appid必须是该小程序的appid。

发送图片消息

发送图文链接

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

发送小程序卡片

image 类型的 media_id : 通过 新增素材接口上传图片文件 获得，建议大小为 520*416

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

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

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

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

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

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

参数说明及示例：

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

此接口需要客服消息接口权限。

如果不满足发送客服消息的触发条件，则无法下发输入状态。

下发输入状态，需要客服之前 30 秒内跟用户有过消息交互。

在输入状态中（持续 15 秒），不可重复下发输入态。

在输入状态中，如果向用户下发消息，会同时取消输入状态。

请求地址（POST）

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

获取接口调用凭据

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

请求示例

开发者可在接收和发送客服消息的过程中获取或上传临时素材。

接收到用户消息之后，可通过获取临时素材接口获取消息中的临时素材

获取客服消息内的临时素材。即下载临时的多媒体文件。目前小程序仅支持下载图片文件。

请求地址（GET）

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

获取接口调用凭据

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

media_id => 媒体文件 ID

返回值说明

如果调用成功，会直接返回图片二进制内容，如果请求失败，会返回 JSON 格式的数据。

调用示例

使用 CURL 命令，用 FORM 表单方式上传一个多媒体文件

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

通过上传临时素材接口可以上传临时素材，并在发送消息接口中使用。

把媒体文件上传到微信服务器。目前仅支持图片。用于发送客服消息或被动回复用户消息。

请求地址（POST）

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

请求参数

media => form-data 中媒体文件标识，有filename、filelength、content-type等信息

type => 合法值：image

返回示例：

调用示例

使用 CURL 命令，用 FORM 表单方式上传一个多媒体文件

curl -F [email protected]

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