作者： Next

当用户和微信小程序客服产生特定动作的交互时（具体动作列表请见下方说明），微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前为 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：平台会不断根据用户、开发者反馈设计新的模版，也欢迎开发者提交模版设计。

功能介绍

消息能力是微信小程序能力中的重要组成，我们为开发者提供了订阅消息能力，以便实现服务的闭环和更优的体验。

订阅消息推送位置：服务通知

订阅消息下发条件：开发者通过一定的方式触发用户主动订阅

订阅消息卡片跳转能力：点击查看详情可跳转至该微信小程序的页面

消息分类

新版一次性订阅消息Beta

新版一次性订阅消息是一种无需用户在弹窗中主动订阅即可向用户下发消息的能力，用户的订阅方式为：

1. 当用户在微信小程序中进行微信支付后，开发者可将微信支付订单号作为 code 向用户下发服务通知
2. 开发者可在微信小程序中将触发服务的 button 组件的 open-type 的值设置为 liveActivity，当用户点击 button 后可获得 code ，后续可使用此 code 向用户下发服务通知

此下发方式由平台定义模版，开发者根据自身业务选择模版进行接入。

详见订阅消息接入 Beta开发指南文档。

一次性订阅消息（用户通过弹窗订阅）

一次性订阅消息用于解决用户使用微信小程序后，后续服务环节的通知问题。

开发者在微信小程序中调用 requestSubscribeMessage 接口后，将向用户展示弹窗，用户可打开自己想要接受的消息开关。用户订阅后，开发者可不限时间地下发一条对应的服务消息；每条消息可单独订阅或退订。

详见微信小程序订阅消息开发指南文档。

长期订阅消息（用户通过弹窗订阅）

一次性订阅消息可满足微信小程序的大部分服务场景需求，但线下公共服务领域存在一次性订阅无法满足的场景，如航班延误，需根据航班实时动态来多次发送消息提醒。为便于服务，我们提供了长期性订阅消息，用户订阅一次后，开发者可长期下发多条消息。

目前长期性订阅消息仅向政务民生、医疗、交通、金融、教育等线下公共服务开放，后期将逐步支持到其他线下公共服务业务。

详见微信小程序订阅消息开发指南文档。

同时长期订阅消息支持语音提醒与添加提醒能力。

长期订阅限频消息

为满足介于长期订阅与一次性订阅之间的部分业务场景需求，长期订阅消息现细分为「不限频」与「限频」两种类型。其中，限频类型支持用户完成一次订阅后，开发者按照预设频次（如每日一次、每月一次等）向用户下发消息。

需特别说明的是，限频消息引入「必填字段」概念，该字段将作为频次校验的核心标识（code）。例如：用户持有三张当月到期的保单（保单 1、保单 2、保单 3），若对应的「保单到期提醒」消息模版频次限制为每月一次，则开发者在「保单编号」这一必填字段中分别填入保单 1、保单 2 的编号时，可分别触发一次消息下发（即每张保单每月可基于该模版触发一次消息下发）。

限频消息的开发方式与长期订阅消息保持一致，开发者可进入公共模版库，选择与自身微信小程序类目匹配的消息模版。当前限频消息暂向金融等指定行业开放，若开发者存在更多模版需求，可通过行业对接人员反馈，或前往微信开放社区提交需求反馈。

设备订阅消息

设备订阅消息是一种特殊类型的订阅消息，它属于长期订阅消息类型，且需要完成「设备接入」才能使用。

设备订阅消息用于在设备触发某些需要人工介入的事件时（例如设备发生故障、设备耗材不足等），向用户发送消息通知。

详见设备订阅消息文档。

从基础库 2.20.1 开始支持

当微信小程序需要打开另一个微信小程序让用户进行快捷操作时，可将要打开的微信小程序以半屏的形态跳转。

调用流程

打开半屏微信小程序

1. 2.23.1以下版本基础库，开发者需要在全局配置app.json的embeddedAppIdList字段中声明需要半屏跳转的微信小程序，若不配置将切换为普通的微信小程序跳转微信小程序。2.23.1及以上版本起无需配置。

配置示例：

{
  "embeddedAppIdList": ["wxe5f52902cf4de896"]
}

2. 开发者通过调用wx.openEmbeddedMiniProgram半屏跳转微信小程序。

半屏微信小程序环境判断

开发者可以通过调用wx.getEnterOptionsSync读取apiCategory参数，当值为embedded时，可以判断此时微信小程序被半屏打开。

返回原微信小程序

被半屏打开的微信小程序可以以通过调用wx.navigateBackMiniProgram返回上一个微信小程序。

使用限制

使用过程有以下限制，若不符合以下所有条件将被自动切换为普通的微信小程序跳转微信小程序，不影响用户使用：

1. 被半屏跳转的微信小程序需要通过来源微信小程序的调用申请，开发者可在 微信小程序管理后台「设置」-「第三方设置」-「半屏微信小程序管理」板块发起申请，最多可以申请添加100个微信小程序（单个微信小程序最多可被 10000 个微信小程序添加）；
2. 2.23.1版本以下基础库，被半屏打开的微信小程序需要在app.json的embeddedAppIdList字段中声明；
3. 当前微信小程序需为竖屏；
4. 被半屏跳转的微信小程序需为非个人主体微信小程序（不含小游戏）。

通过双人音视频通话功能（1v1 VoIP），用户可以直接在微信小程序内进行一对一视频通话或音频通话，提升微信小程序服务质量，且功能所需的开发成本极低。

从基础库 2.20.1 开始支持

申请开通

暂只针对国内主体如下类目的微信小程序开放，需要先通过类目审核，再在微信小程序管理后台，「开发」-「开发管理」-「接口设置」中自助开通该接口权限。

前端接口

• 开启双人通话：wx.setEnable1v1Chat
• 加入（创建）双人通话：wx.join1v1Chat
• 退出（销毁）双人通话：wx.exitVoIPChat
• 更新房间麦克风/耳机静音设置：wx.updateVoIPChatMuteConfig
• 监听房间成员变化：wx.onVoIPChatMembersChanged
• 监听房间成员通话状态变化：wx.onVoIPChatSpeakersChanged
• 监听通话中断：wx.onVoIPChatInterrupted
• 监听实时语音通话成员视频状态变化：wx.onVoIPVideoMembersChanged

调用流程

1. 通过 wx.setEnable1v1Chat 接口将用户的接听状态enable设置为true，该设置仅在当次微信小程序生命周期有效，微信小程序每次冷启动后均需要重新设置。
2. 通过 wx.join1v1Chat 接口传入呼叫方信息caller与接听方信息listener发起呼叫，接听方与呼叫方均需在微信小程序内。

计费

微信为单个微信小程序提供每个自然月1000分钟的免费通话时长，1分钟语音通话时长扣除1分钟免费通话时长，1分钟视频通话时长扣除15分钟免费时长。超出部分需另行付费。 免费时长领取与套餐包购买需前往微信服务市场进行操作。