分类： 消息

微信客户端 8.0.32 及以上版本支持

为了让用户更便捷地使用微信小程序的打车服务，我们在位置消息详情页的菜单中，新增了用微信小程序打车的入口，接入说明详见：接入文档

产品示意图

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

获取客服消息内的临时素材

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

新增图片素材

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

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

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

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

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

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

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

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

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

如果是使用自有服务器接收的消息推送，则需返回如下格式的 XML 数据：

<xml>
    <ToUserName><![CDATA[touser]]></ToUserName>
    <FromUserName><![CDATA[fromuser]]></FromUserName>
    <CreateTime>1399197672</CreateTime>
    <MsgType><![CDATA[transfer_customer_service]]></MsgType>
</xml>

参数说明

如果是使用云函数接收的消息推送，则需在云函数被客服消息触发后返回同样格式的 JSON 数据：

// ...
exports.main = async (event, context) => {
  // 判断处理客服消息 ...
  // 最后返回 JSON
  return {
    MsgType: 'transfer_customer_service',
    ToUserName: 'touser',
    FromUserName: 'fromuser',
    CreateTime: parseInt(+new Date / 1000),
  }
}

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

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

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

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

各消息类型的推送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
}

参数说明

图片消息

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

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
}

参数说明

微信小程序卡片消息

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

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>

JSON 格式

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

参数说明

进入会话事件

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

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

参数说明

在页面使用客服消息

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

示例代码

<button open-type="contact" bindcontact="handleContact"></button>

Page({
    handleContact (e) {
        console.log(e.detail.path)
        console.log(e.detail.query)
    }
})

返回参数说明

后台接入消息服务

用户向微信小程序客服发送消息、或者进入会话等情况时，开发者填写的服务器配置 URL / 云开发云函数 / 云托管服务将得到微信服务器推送过来的消息和事件，开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送。

从基础库 2.22.0 开始支持

用户在订阅微信小程序长期订阅消息时，可以根据自己的使用情况添加提醒。添加后，用户在收到消息时，在微信内将由横幅通知提醒。

当用户添加了提醒，开发者通过 wx.getSetting 获取的该模板的订阅状态为 'acceptWithAlert'。

订阅弹窗样式如下：

从基础库 2.18.0 开始支持

当前微信小程序订阅消息通知与微信消息的通知的提示音是一样的，对于部分订阅消息模板，增加了语音提醒能力，播报语料中的部分字段支持开发者自定义。

当开发者调用wx.requestSubscribeMessage时，如果只订阅了1条消息，并且该模板支持开启语音提醒，用户在订阅时可以选择开启语音提醒。开启后，在接收订阅消息时会同步播报语音提醒。

当用户开启了语音提醒，开发者通过wx.getSetting获取该模板的订阅状态时，会显示为’acceptWithAudio’。

订阅弹窗的样式如下：

当前支持开启语音提醒的模板及播报语料如下：

以下情况会导致语音提醒无法播报：

1. 用户将服务通知设置为免打扰
2. 用户开启了手机静音模式或手机音量过低
3. 用户未打开微信新消息通知，可引导用户前往微信-“我”-“设置”-“新消息通知”中打开
4. 用户未打开系统对微信的通知
5. 用户开启了低电量模式
6. 用户版本过低：需要iOS 8.0.6与安卓8.0.3及以上

1 接入指引

1.1 接入前准备

开发者首先需要明确自己的服务业态，选择对应的业态卡片进行接入。

开发者根据不同卡片的模版规则，向平台进行同步。每个卡片有若干状态模版（如“呼叫车辆中”、“司机赶往上车点中”等），每个模版有不同的必填字段与选填字段（如“司机车牌号”、“预计到达上车点时间”等），平台依据状态流转信息向用户下发通知。

1.2 申请模版

开发者需要登录微信小程序管理后台 ，在「功能-订阅消息-公共模版库-一次性订阅」中查询可以申请的模板，审核通过后可使用。

模版有对应类目要求，符合类目要求的微信小程序可在公共模版库优先看到新版模版。

需要注意的是，添加此类模版后，模版id不支持通过原方式进行订阅与下发，请勿通过wx.requestSubscribeMessage向用户申请订阅该模版。

此外，开发者、代开发服务商可通过服务端接口 addMessageTemplate 添加模版， tid 见下文， kidList 请传入空数组。

目前共支持支持模版情况如下：

1.3 将微信支付订单号作为 code 的模版开发指南

1.3.1 获取 code

当用户在微信小程序内进行支付后，根据下单渠道不同获取对应的code ：
（1）当前订单为普通微信支付订单
开发者可获得微信支付订单号，可直接作为 code 。
（2）当前订单为微信支付分订单
开发者可获得微信支付服务订单号，可直接作为 code 。

该 code 在当次服务进程中唯一，后续开发者更新用户的服务状态均通过此 code 进行。

注意事项：

1. 需要注意的是，微信支付订单号从生成到可被校验存在一定的时延可能，若收到报错为notify_code 不存在，建议在1分钟后重试。
2. 对于合单支付场景，需要使用子单的订单号作为 code ，多个子单可用于激活多个卡片，互不干扰。
3. 仅支持当前微信小程序的微信支付订单号/微信支付服务订单号，请勿使用其他微信小程序、公众号支付、APP支付的订单号。
4. 不同的下单渠道在调用服务端接口 setUserNotify 时，需要在传入的字段中进行相应的声明。

1.3.2 激活卡片

开发者需在支付完成24小时内调用服务端接口 setUserNotify 传入初始化卡片状态与状态相关字段（见1.1中各模版定义链接），以首次激活 code ，后续才可以继续通过 setUserNotify 更新服务的动态。

1.3.3 更新卡片状态

code 并激活后，开发者可在激活后30天内调用服务端接口 setUserNotify ，更新卡片状态与状态相关字段（见见1.1中各模版定义链接）。超过30天，或状态无可变更的下一状态时（如状态更新到“订单已完成”），不再允许开发者更新。

1.4 通过前端获取 code 的模版开发指南

1.4.1 获取 code

从基础库 2.26.2 开始支持

开发者需要在前端将触发服务的 button 组件的 open-type 的值设置为 liveActivity ，设置 activity-type 参数为notify_type。当用户点击 button 后，可以通过 bindcreateliveactivity 事件回调获取到 code 。

该 code 在当次服务进程中唯一，后续开发者更新用户的服务状态均通过此 code 进行。

注意事项：

1. 平台会对相关 button 组件进行检测，包括是否诱导用户点击、通过与卡片无关的按钮获取 code 等。

代码示例：

<button open-type="liveActivity" activity-type="1001" bindcreateliveactivity="onLiveActivityCreate">立即呼叫</button>

Page({
  onLiveActivityCreate (evt) {
    console.log(evt.detail.code)
  }
})

1.4.2 激活卡片

开发者需要在获取后5分钟内调用服务端接口 setUserNotify 传入初始化卡片状态与状态相关字段（见1.1中各模版定义链接），以首次激活 code ，后续才可以继续通过 setUserNotify 更新服务的动态。

1.4.3 更新卡片状态

code 激活后，可在激活后24小时内调用服务端接口 setUserNotify ，更新卡片状态与状态相关字段（见1.1中各模版定义链接）。超过24小时，或状态无可变更的下一状态时（如状态更新到“订单已完成”），不再允许开发者更新。

1.5 监听事件开发指南

开发者调用服务端接口 setUserNotify 后，会触发平台下发订阅消息，开发者可通过接入微信小程序消息推送服务接收订阅消息下发失败事件。

订阅消息下发失败事件参数如下：

JSON格式示例如下：

{
    "ToUserName":"gh_e5e82d93a62a",
    "FromUserName":"o7esq5PHRGBQYmeNyfG064wEFVpQ",
    "CreateTime":1699428279,
    "MsgType":"event",
    "Event":"notify_service_msg_send_result",
    "openid":"o7esq5PHRGBQYmeNyfG064wEFVpQ",
    "notify_code":"p1.4200002043202311087295582095",
    "notify_type":2006,
    "card_status":4,
    "fail_ret":-1004,
    "fail_msg":"user reject message "
}

1.6 其他功能开发指南

1.6.1 查询卡片状态

由于卡片状态的更新有一套严格的校验机制，在开发者向微信小程序平台同步信息的过程中，存在信息丢失、更新不及时等场景，因此开发者可以通过服务端接口 getUserNotify 查询 code 对应在平台侧存储的状态与服务相关信息。

1.6.2 传入扩展信息

开发者通过此功能除了可以向用户下发通知，还可以通过服务端接口 getUserNotifyExt 传入更多服务相关信息，实现更多功能，当前支持的能力包括：

1. 交易评价升级：https://docs.qq.com/doc/DV2J4U1ltSExScnBB

2 相关接口文档

激活与更新卡片：setUserNotify

查询卡片状态：getUserNotify

配置更多服务相关信息：setUserNotifyExt

3 Q&A

以下Q&A回答了部分开发者关心的内容，更多提问可前往微信开放社区提问。

激活与更新机制

通知机制

Q：为什么有的状态变更会下发通知，有的不会？对于不下发通知的状态，我是否没有必要按照模版传入？ A：微信小程序将根据用户需求，动态调整下发内容，因此开发者可将所有的状态变按照模版传入，无需根据微信小程序侧调整重新接入。

Q：为什么有的字段传入后会在卡片中展示，有的不会？对于不展示的字段，我是否没有必要按照模版传入？ A：微信小程序将根据用户需求，动态调整下发内容，因此开发者可将所有的字段变按照模版传入，无需根据微信小程序侧调整重新接入。

Q：通过此方案下发的通知，部分会与以前的订阅消息冲突，会不会重复打扰用户？ A：对于通过此方式下发的消息，建议开发者先手动不下发相似的订阅消息模版，且不再弹出相似的订阅消息申请弹窗。后续微信小程序侧将上线一定的策略统一帮助开发者拦截。

模版

Q：我当前的业务形态没有被满足，后续是否还会开放更多的模版？ A：平台会不断根据用户、开发者反馈设计新的模版，也欢迎开发者提交模版设计。