抖音开放平台Logo
开发者文档
小游戏
“/”唤起搜索
控制台
  • API 概览
  • C# API
  • 开放接口
  • 登录
  • 侧边栏能力
  • 设置
  • 授权
  • 添加到桌面
  • 游戏排行榜
  • 订阅消息
  • tt.requestSubscribeMessage
  • 开放数据域
  • 开放数据
  • 开放数据分组
  • 客服消息
  • 直播能力
  • 推荐流直出游戏能力
  • 公会群能力
  • 意见反馈
  • 游戏站
  • 收藏
  • 群聊
  • 关注
  • 数据分析
  • 基础
  • 渲染
  • 设备
  • 文件
  • 位置
  • 媒体
  • 网络
  • 转发
  • 数据缓存
  • 广告
  • 界面
  • 支付
  • Worker

    • tt.requestSubscribeMessage
    收藏
    我的收藏

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

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

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

    语法

    tt.requestSubscribeMessage(options)

    参数说明

    options 为 object 类型，属性如下：

    属性名类型默认值必填说明最低支持版本
    tmplIdsArray<string>是

    需要订阅的消息模板的 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<object>

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

    		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

    错误码

    errorCodeerrMsgerrorType说明最低支持版本
    118505requestSubscribeMessage:fail auth denyU
    拒绝授权

    用户未授权消息推送，在合适的场景申请订阅消息

    		1.73.0
    118501requestSubscribeMessage:fail template not exist or invalidD
    模板无效

    检查传入的模板id

    		1.73.0
    118509requestSubscribeMessage:fail templates switches all offU
    所有模板都长期拒绝

    所有模板都长期拒绝,开发者可通过tt.openSetting引导开发者去设置页开启

    		1.73.0
    118599requestSubscribeMessage:fail invalid paramsD
    入参无效

    检查入参

    		1.73.0
    118504requestSubscribeMessage:fail service errorF
    小程序框架内部错误，有需要请创建工单咨询
    		1.73.0
    118591requestSubscribeMessage:fail Internal error xxxF
    小程序框架内部错误，有需要请创建工单咨询
    		1.73.0
    118508requestSubscribeMessage:fail main switch offU
    主开关关闭

    主开关关闭,开发者可通过tt.openSetting引导开发者去设置页开启

    		1.73.0
    118585requestSubscribeMessage:fail network unavailableU
    无网调用

    用户网络不佳，若此错误频繁出现建议加入超时重试逻辑

    		1.73.0
    118506requestSubscribeMessage:fail login denyU
    用户拒绝登录

    用户拒绝登录

    		1.73.0
    118502requestSubscribeMessage:fail template type not the sameD
    一次性模板和长期模板混用

    一次性模板和长期模板混用

    		1.73.0

    扫码体验

    请使用字节宿主APP扫码

    代码示例

    错误码

    errCode
    errNo
    errMsg
    说明
    1001
    暂时未加
    no permission
    没有权限(白名单配置，暂无需关注)
    1002
    20000
    invalid params
    参数不合法
    1003
    20000
    template counts out of max bounds
    模版消息个数超过限制（最多 3 个）
    1004
    21101
    template not exist or invalid
    模版消息不存在或不合法
    1005
    21102
    template type not the same
    模版消息类型不一致，或者订阅消息是多个并包含了版本更新提醒。 在 tmplIds 数组中，多个模板 id 代表的模板类型（一次性或者永久）和 消息类型（分为普通消息和版本更新消息两类）都应该分别保持一致。例如：tmplIds 中的所有模版 id 代表的模板类型统一为一次性，消息类型全部为普通消息。
    2001
    21103
    network error
    网络问题
    2002
    21104
    service error
    服务错误
    3001
    21105
    auth deny
    拒绝授权
    3002
    21106
    login deny
    拒绝登录
    4001
    21107
    request count out of limit
    请求次数超过限制 (二期弹窗频控取消，不会再出现)
    4002
    21108
    main switch off
    总开关关闭
    4003
    21109
    templates switches all off
    请求模版消息开关均关闭
    4004
    21110
    forbidden
    后台封禁
    暂时未加
    暂时未加
    not supported by current application
    宿主不支持
    5001
    10401
    Internal error: \${附加信息}
    内部错误