:wxfrwk:`小程序订阅消息 <open-ability/subscribe-message>`
========================================================

功能介绍
--------------

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

- 订阅消息推送位置：服务通知
- 订阅消息下发条件：用户自主订阅
- 订阅消息卡片跳转能力：点击查看详情可跳转至该小程序的页面

.. image:: https://res.wx.qq.com/wxdoc/dist/assets/img/request-subscribe-message.3851318e.jpg

消息类型
--------------

1. 一次性订阅消息

   一次性订阅消息用于解决用户使用小程序后，后续服务环节的通知问题。用户自主订阅后，
   开发者可不限时间地下发一条对应的服务消息；每条消息可单独订阅或退订。

2. 长期订阅消息

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

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

订阅消息语音提醒
---------------

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

当开发者调用 :func:`wx.requestSubscribeMessage` 时仅订阅1条消息且该模板支持开启语音提醒，用户在订阅时可以选择开启语音提醒。
开启后将在接收订阅消息时会同步播报语音提醒。当用户开启了语音提醒，该模板的订阅状态为'acceptWithAudio'。

订阅弹窗样式如下：

.. image:: https://res.wx.qq.com/wxdoc/dist/assets/img/request-subscribe-message-with-audio.477c085f.png

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

+--------------+----------+------+--------------+
|     标题     |   类型   | 类目 |   播报语料   |
+==============+==========+======+==============+
| 收款到账通知 | 长期订阅 | 银行 | 小程序收款元 |
+--------------+----------+------+--------------+

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

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

使用说明
--------------

步骤一：获取模板 ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

在微信公众平台手动配置获取模板 ID：
登录 https://mp.weixin.qq.com 获取模板，如果没有合适的模板，可以申请添加新模板，审核通过后可使用。

.. image:: https://res.wx.qq.com/wxdoc/dist/assets/img/subscribe-message.b562750a.jpg

步骤二：获取下发权限
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

详见小程序端消息订阅接口 :func:`wx.requestSubscribeMessage`

步骤三：调用接口下发订阅消息
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

详见服务端消息发送接口 :func:`subscribeMessage.send`

注意事项
--------------

用户勾选 “总是保持以上选择，不再询问” 之后，下次订阅调用 :func:`wx.requestSubscribeMessage` 不会弹窗，
保持之前的选择，修改选择需要打开小程序设置进行修改。

订阅消息事件推送
--------------------

1. 当用户触发订阅消息弹框后，用户的相关行为事件结果会推送至开发者所配置的服务器地址。

   XML格式示例

   .. code:: XML

       <xml>
           <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
           <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
           <CreateTime>1610969440</CreateTime>
           <MsgType><![CDATA[event]]></MsgType>
           <Event><![CDATA[subscribe_msg_popup_event]]></Event>
           <SubscribeMsgPopupEvent>
               <List>
                   <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
                   <SubscribeStatusString><![CDATA[accept]]></SubscribeStatusString>
                   <PopupScene>2</PopupScene>
               </List>
               <List>
                   <TemplateId><![CDATA[9nLIlbOQZC5Y89AZteFEux3WCXRRRG5Wfzkpssu4bLI]]></TemplateId>
                   <SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
                   <PopupScene>2</PopupScene>
               </List>
           </SubscribeMsgPopupEvent>
       </xml>

   JSON 格式示例

   .. code:: JSON

       {
         "ToUserName": "gh_123456789abc",
         "FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
         "CreateTime": "1620973045",
         "MsgType": "event",
         "Event": "subscribe_msg_popup_event",
         "SubscribeMsgPopupEvent": [   {
               "TemplateId": "hD-ixGOhYmUfjOnI8MCzQMPshzGVeux_2vzyvQu7O68",
               "SubscribeStatusString": "accept",
               "PopupScene": "0"
           }],
       }

   参数说明

   +-----------------------+------------------------------------+
   |         参数          |                说明                |
   +=======================+====================================+
   | ToUserName            | 小程序帐号ID                       |
   +-----------------------+------------------------------------+
   | FromUserName          | 用户openid                         |
   +-----------------------+------------------------------------+
   | CreateTime            | 时间戳                             |
   +-----------------------+------------------------------------+
   | TemplateId            | 模板id（一次订阅可能有多个id）     |
   +-----------------------+------------------------------------+
   | SubscribeStatusString | 订阅结果（accept接收；reject拒收） |
   +-----------------------+------------------------------------+
   | PopupScene            | 弹框场景，0代表在小程序页面内      |
   +-----------------------+------------------------------------+

2. **当用户在手机端服务通知里消息卡片右上角“...”管理消息时，或者在小程序设置管理中的订阅消息管理页面内管理消息时，相应的行为事件会推送至开发者所配置的服务器地址。（目前只推送取消订阅的事件，即对消息设置“拒收”）**

   XML 格式示例

   .. code:: XML

       <xml>
           <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
           <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
           <CreateTime>1610969440</CreateTime>
           <MsgType><![CDATA[event]]></MsgType>
           <Event><![CDATA[subscribe_msg_change_event]]></Event>
           <SubscribeMsgChangeEvent>
               <List>          <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
                   <SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
               </List>
           </SubscribeMsgChangeEvent>
       </xml>

   JSON 格式示例

   .. code:: JSONv

       {
             "ToUserName": "gh_123456789abc",
             "FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
             "CreateTime": "1610968440",
             "MsgType": "event",
             "Event": "subscribe_msg_change_event",
             "SubscribeMsgChangeEvent": [  {
                       "TemplateId":"BEwX0BOT3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
                       "SubscribeStatusString": "reject"
             }],
       }

   参数说明

   +-----------------------+--------------------------------+
   |         参数          |              说明              |
   +=======================+================================+
   | ToUserName            | 小程序帐号ID                   |
   +-----------------------+--------------------------------+
   | FromUserName          | 用户openid                     |
   +-----------------------+--------------------------------+
   | CreateTime            | 时间戳                         |
   +-----------------------+--------------------------------+
   | TemplateId            | 模板id（一次订阅可能有多个id） |
   +-----------------------+--------------------------------+
   | SubscribeStatusString | 订阅结果（reject拒收）         |
   +-----------------------+--------------------------------+

3. **调用订阅消息接口发送消息给用户的最终结果，会推送下发结果事件至开发者所配置的服务器地址。**

   XML格式示例

   .. code:: XML

       <xml>
           <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
           <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
           <CreateTime>1610969468</CreateTime>
           <MsgType><![CDATA[event]]></MsgType>
           <Event><![CDATA[subscribe_msg_sent_event]]></Event>
           <SubscribeMsgSentEvent>
               <List>       <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
                   <MsgID>1700827132819554304</MsgID>
                   <ErrorCode>0</ErrorCode>
                   <ErrorStatus><![CDATA[success]]></ErrorStatus>
               </List>
           </SubscribeMsgSentEvent>
       </xml>

   JSON 格式示例

   .. code:: JSON

       {
           "ToUserName": "gh_123456789abc",
           "FromUserName": "o7esq5PHRGBQYmeNyfG064wEFVpQ",
           "CreateTime": "1620963428",
           "MsgType": "event",
           "Event": "subscribe_msg_sent_event",
           "SubscribeMsgSentEvent": {
             "List": {
               "TemplateId": "BEwX0BO-T3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
               "MsgID": "1864323726461255680",
               "ErrorCode": "0",
               "ErrorStatus": "success"
                 }
             }
       }

   参数说明

   +--------------+--------------------------------+
   |     参数     |              说明              |
   +==============+================================+
   | ToUserName   | 小程序帐号ID                   |
   +--------------+--------------------------------+
   | FromUserName | 用户openid                     |
   +--------------+--------------------------------+
   | CreateTime   | 时间戳                         |
   +--------------+--------------------------------+
   | TemplateId   | 模板id（一次订阅可能有多个id） |
   +--------------+--------------------------------+
   | MsgID        | 消息id（调用接口时也会返回）   |
   +--------------+--------------------------------+
   | ErrorCode    | 推送结果状态码（0表示成功）    |
   +--------------+--------------------------------+
   | ErrorStatus  | 推送结果状态码对应的含义       |
   +--------------+--------------------------------+

   .. note:: 注意：失败仅包含因异步推送导致的系统失败