分类： 订阅消息

从基础库 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 的编号时，可分别触发一次消息下发（即每张保单每月可基于该模版触发一次消息下发）。

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

设备订阅消息

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

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

详见设备订阅消息文档。