# 新版一次性订阅消息开发指南 Beta

# 1 接入指引

# 1.1 接入前准备

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

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

# 1.2 申请模版

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

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

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

intro

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

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

notify_type 卡片业态 类目 下发code获取方式 模版定义 addMessageTemplate接口 tid
2001 购物(实体物流)服务动态 商家自营/保健品、商家自营/珠宝玉石、商家自营/图书报刊/音像/影视/游戏/动漫、商家自营/食品饮料、商家自营/成人用品 (医疗器械类)、商家自营/酒类、商家自营/成品油、商家自营/纪念币、商家自营/生鲜/初级食用农产品、商家自营/电话卡销售、商家自营/预付卡、商家自营/成人情趣用品、商家自营/百货商场/购物中心、商家自营/母婴食品、电商平台/电商平台 将微信支付订单号作为 code 链接 10000001
2002 购物(自提)服务动态 商家自营/母婴用品、商家自营/保健品、商家自营/珠宝玉石、商家自营/食品饮料、商家自营/成人用品 (医疗器械类)、商家自营/酒类、商家自营/纪念币、商家自营/图书报刊/音像/影视/游戏/动漫等出版物、商家自营/生鲜/初级食用农产品、商家自营/电话卡销售、商家自营/预付卡、商家自营/成人情趣用品、商家自营/百货商场/购物中心、电商平台/电商平台 将微信支付订单号作为 code 链接 10000002
2003 购物(虚拟发货)服务动态 IT科技/基础电信运营商、IT科技/电信业务代理商、IT科技/转售移动通信、商家自营/预付卡、电商平台/电商平台 将微信支付订单号作为 code 链接 10000003
2004 快递寄送服务动态 物流服务/邮政、物流服务/收件/派件、物流服务/快递柜、物流服务/货物运输 将微信支付订单号作为 code 链接 10000004
2005 保险购买服务动态 金融业/保险、金融业/银行 将微信支付订单号作为 code 链接 10000005
2006 购物&餐饮(同城配送)服务动态 商家自营/保健品、商家自营/珠宝玉石、商家自营/食品饮料、商家自营/成人用品 (医疗器械类)、商家自营/酒类、商家自营/成品油、商家自营/纪念币、商家自营/生鲜/初级食用农产品、商家自营/电话卡销售、商家自营/预付卡、商家自营/成人情趣用品、商家自营/百货商场/购物中心、商家自营/母婴食品、电商平台/电商平台、餐饮服务/外卖平台、餐饮服务/餐饮服务场所/餐饮服务管理企业 将微信支付订单号作为 code 链接 10000006
2007 购物&餐饮&本地生活(等候领取)服务动态 餐饮服务/餐饮服务场所/餐饮服务管理企业 将微信支付订单号作为 code 链接 10000007
2008 酒店预订服务动态 旅游服务/住宿服务 将微信支付订单号作为 code 链接 10000021
2009 机票服务动态 交通服务/航空 将微信支付订单号作为 code 链接 10000024
2010 火车票、汽车票、船票服务动态 交通服务/火车/高铁/动车、交通服务/长途汽车 将微信支付订单号作为 code 链接 10000022
2011 景区门票服务动态 旅游服务/景区服务 将微信支付订单号作为 code 链接 10000029
1001 打车服务动态 交通服务/出租车、交通服务/网约车、交通服务/顺风车/拼车 通过前端获取 code 链接 10000017
1003 同城配送服务动态 商家自营/保健品、商家自营/珠宝玉石、商家自营/食品饮料、商家自营/成人用品 (医疗器械类)、商家自营/酒类、商家自营/成品油、商家自营/纪念币、商家自营/生鲜/初级食用农产品、商家自营/电话卡销售、商家自营/预付卡、商家自营/成人情趣用品、商家自营/百货商场/购物中心、商家自营/母婴食品、电商平台/电商平台、餐饮服务/外卖平台、餐饮服务/餐饮服务场所/餐饮服务管理企业 通过前端获取 code 链接 10000019
1004 取餐等候服务动态 餐饮服务/餐饮服务场所/餐饮服务管理企业 通过前端获取 code 链接 10000020
1005 餐厅排队服务动态 餐饮服务/餐饮服务场所/餐饮服务管理企业 通过前端获取 code 链接 10000018

# 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 后,会触发平台下发订阅消息,开发者可通过接入微信小程序消息推送服务接收订阅消息下发失败事件。

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

参数 描述
ToUserName 小程序账号ID
FromUserName 用户openid
CreateTime 时间戳
MsgType 消息类型,固定为"event"
Event 事件类型,固定为"notify_service_msg_send_result"
openid 用户openid
notify_code 动态更新令牌
notify_type 卡片id
card_status 状态id
fail_ret 错误码:-10001 系统错误;-10002 内容安全校验不通过;-1003 未添加订阅消息模版;-1004 用户拒收此 模版;-1005 消息下发过于频繁被拦截
fail_msg 错误信息

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:目前暂无计划延长实时类卡片激活时间与更新时间。对于交易类的卡片,考虑到存在预售、服务预约等场景,后续计划支持开发者设置一个「开始更新时间」,从「开始更新时间」起计算30天可更新时间。

# 通知机制

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

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

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

# 模版

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