抖音开放平台Logo
控制台

tt.requestSubscribeMessage
收藏
我的收藏

基础库 1.73.0 开始支持本方法，低版本需做兼容处理。支持宿主：头条，抖音。订阅消息功能介绍及使用方式请参见订阅消息2.0，这是一个异步方法。

调起客户端订阅消息界面，返回用户订阅消息的操作结果。询问过用户的模板消息会被添加到用户的小程序设置页，用户可以在设置页面进行管理。

前提条件无
业务背景无
使用限制
  • Tip：只允许在以下时机中调用：bindtap 事件、tt.pay 回调函数；
  • Tip：最多一次可以传入三个模版 ID；
  • Tip：模版分为一次性模版和长期性模版，一次性模版 ID 和长期性模版 ID 不可同时使用；
注意事项无
支持沙盒
否
相关教程无

语法

tt.requestSubscribeMessage(options)

参数说明

options 为 object 类型，属性如下：

属性名类型默认值必填说明最低支持版本
tmplIdsarray是

需要订阅的消息模板的 id 的集合，最多支持传入三个 tmplId

在「开放平台控制台-进入对应小程序-能力-互动能力-消息管理-订阅消息」获取消息模版id

1.73.0
successfunction否
接口调用成功的回调函数
1.73.0
failfunction否
接口调用失败的回调函数
1.73.0
completefunction否
接口调用结束的回调函数（调用成功、失败都会执行）
1.73.0

回调成功

object 类型，属性如下：

属性名类型说明最低支持版本
templateSettingsobject

订阅结果

3.35.0
errMsgstring
"requestSubscribeMessage:ok"
3.35.0

templateSettings 参数说明

key为模板id，value为object类型。只有用户勾选了的模板才会返回。

templateSettings 类型说明

object 类型，属性如下：

属性名类型说明最低支持版本
[TEMPLAT_ID]object

用户勾选了的模板id

3.35.0

[TEMPLAT_ID] 类型说明

object 类型，属性如下：

属性名类型说明最低支持版本
statusenum

订阅结果。

3.35.0
alwaysSubscribeboolean

是否为长期订阅状态(当用户在弹窗中勾选了"总是保持以上选择，不再询问"，对应模板的订阅状态会变为长期状态，长期订阅状态的模板后续不会弹窗询问用户，直接返回用户上次的选择)。

3.35.0
allowReminderWayarray

返回模板支持的提醒方式对应的用户授权结果。

3.35.0

status 的合法值

值说明最低支持版本
accept

用户同意订阅该条 id 对应的模板消息。

3.35.0
reject

用户拒绝订阅该条 id 对应的模板消息。

3.35.0
fail

表示该条 id 对应的模版消息授权失败。

3.35.0
repeat

表示该条id对应的模板消息重复订阅。

注：该返回为长期模板特有返回。订阅消息2.0体系中，长期模板只需用户订阅一次，开发者即可不限时间的下发多条消息，但是下发的频次会有限制。重复订阅会返回repeat，但不影响开发者下发消息。

3.35.0
limit

表示用户对该条id对应的模板订阅次数达到上限。

注：该返回为一次性模板特有返回。

3.35.0

allowReminderWay 类型说明

object 类型，属性如下：

属性名类型说明最低支持版本
reminderTypeenum

提醒方式。

3.35.0
reminderStatusenum

提醒授权结果。

3.35.0

reminderType 的合法值

值说明最低支持版本
message_notice

消息通知。默认支持。

3.35.0
feed

推荐频道提醒。开发者需要申请支持信息流通知的模板。

3.35.0
push

实时提醒。开发者需要申请支持实时提醒的模板。

3.35.0

reminderStatus 的合法值

值说明最低支持版本
accept

同意。

3.35.0
reject

拒绝。

3.35.0

回调失败

object 类型，属性如下：

属性名类型说明最低支持版本
errMsgstring
接口调用失败错误信息
1.73.0

错误码

errNoerrMsg说明最低支持版本
20000invalid params
参数不合法
1.73.0
20000template counts out of max bounds
模版消息个数超过限制（最多 3 个）
1.73.0
21101template not exist or invalid
模版消息不存在或不合法
1.73.0
21102template type not the same
模版消息类型不一致，或者订阅消息是多个并包含了版本更新提醒。
1.73.0
21103network error
网络问题
1.73.0
21104service error
服务错误
1.73.0
21105auth deny
拒绝授权
1.73.0
21106login deny
拒绝登录
1.73.0
21107request count out of limit
请求次数超过限制 （二期弹窗频控取消，不会再出现）
1.73.0
21108main switch off
总开关关闭
1.73.0
21109templates switches all off
请求模版消息开关均关闭
1.73.0
21110forbidden
后台封禁
1.73.0
21502not supported by current application

宿主不支持（目前仅支持头条、抖音、抖音极速版）

1.73.0
10401Internal error: \${附加信息｝
内部错误
1.73.0

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<!-- index.ttml -->
<button type="primary" bindtap="subscribeMessage">订阅消息</button>
// index.js
Page({
  subscribeMessage() {
    // 这里填写 能力-互动能力-消息管理-订阅消息 中的模版消息id
    const updateMsgTplId = 'MSG164161657291480498528979256';
    const orderSuccessTplId = 'MSG164158927218123174309792040';

    tt.requestSubscribeMessage({
      // 开放平台申请的模版id  支持最多3个同类型模版
      tmplIds: [updateMsgTplId, orderSuccessTplId],
      success(res) {
        console.log("订阅成功: ", res);
        //订阅成功回调
        let msg1 = "";
        let and = "";
        let msg2 = "";
        if (tt.canIUse('requestSubscribeMessage.success.templateSettings')) {
          const updateResult = res.templateSettings[updateMsgTplId]
          const orderResult = res.templateSettings[orderSuccessTplId]
          msg1 = `更新提醒通知: ${updateResult.status}，是否记住选择${updateResult.alwaysSubscribe}，用户同意的提醒方式: ${updateResult.allowReminderWay.filter(reminder => reminder.reminderStatus === 'accept').map(reminder => reminder.reminderType).join('、')}`;
          msg2 = `下单成功通知: ${orderResult.status}，是否记住选择${orderResult.alwaysSubscribe}，用户同意的提醒方式: ${orderResult.allowReminderWay.filter(reminder => reminder.reminderStatus === 'accept').map(reminder => reminder.reminderType).join('、')}`;
          console.log(msg1)
          console.log(msg2)
          tt.showModal({
            title: '订阅成功',
            content: `${msg1}\n${msg2}`,
            showCancel: false
          })
        } else {
          console.log("更新提醒通知: " + res[updateMsgTplId]);
          console.log("下单成功通知: " + res[orderSuccessTplId]);
          msg1 = res[updateMsgTplId] === "accept" ? "更新提醒通知" : "";
          msg2 = res[orderSuccessTplId] === "accept" ? "下单成功通知" : "";
          and = msg1 && msg2 && "及";
          tt.showModal({
            content: `${msg1}${and}${msg2} 订阅成功`,
            showCancel: false
          })
        }
      },
      fail(res) {
        //订阅失败回调
        console.log("订阅失败,错误码: ", res.errNo);
        tt.showModal({
          title: "订阅失败",
          content: `errNo: ${res.errNo || "暂时未加"}`,
          showCancel: false
        });
      },
      complete(res) {
        //完成回调
        console.log("API调用完成: " + res.errMsg);
      },
    });
  }
})