接入订阅消息能力
简介
为了帮助开发者对用户在不同场景下的内容/服务消费进行连续性的管理和触达,促进用户持续转化,提升服务质量,抖音开放平台提供订阅消息能力。
能力介绍
场景 | 场景描述 | 场景示例 |
模板管理 | 开发者通过开发者平台或 OpenAPI 管理消息模版。 | |
用户订阅 | 开发者在小程序内拉起订阅弹窗:
| |
消息下发 | 用户授权特定模版后,开发者发送模版消息触达用户。 触达方式:
|
前置条件
- •订阅消息准入条件:
- ◦小程序状态:已上线
- ◦面向在抖音开放平台经营的小程序全量开放。
- •订阅消息模版使用及申请原则:
- ◦小程序在申请订阅消息模版时仅能选择对应服务类目的消息模版。
- ◦小程序在下发订阅消息时需遵循抖音开放平台规定的频次要求。
- •订阅消息清退机制:
平台会对订阅率、退订率、点击率和投诉率等数据进行监测,如不符合规范要求,平台将对相关订阅消息进行清退。
接入流程
模板管理
- •公共模板:小程序仅能使用当前服务类目对应的公共模板创建小程序模板,如现有公共模板无法满足业务需求,开发者可根据平台规范申请创建新模板,若修改消息下发频率或使用额外触达能力则需要官方审核,创建后的模板将进入审核环节,审核通过后,该模板将出现在公共模板库中,供同类目其他小程序开发者共同使用。
- •小程序模板: 开发者基于公共模板创建的当前小程序可以下发消息的定制化模板,消息下发频率与触达能力与公共模板相同。开发者可通过开发者后台或 OpenAPI 获取消息 ID(小程序模板的唯一 ID)用于后续订阅消息的下发。小程序仅能使用自身创建的小程序模板。
开发者平台
路径:抖音开放平台 -> 控制台 -> 能力 -> 互动能力 -> 订阅消息。
OpenAPI
代码示例见本教程中消息下发-开发者自主下发
公共模板管理:
新建公共模板:createTpl
查询公共模版库:queryTplList
查询小程序新建的公共模板列表: queryCreatedTplList
小程序模板管理:
添加小程序模板:addAppTpl
查询小程序模板列表:queryAppTpl
删除已添加的小程序模板:deleteAppTpl
用户订阅
主动拉起授权弹窗
JS API:tt.requestSubscribeMessage
代码示例:
// 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); }, }); } })
订阅事件通知
Webhook:user_subscribe_action
说明:用户订阅模板或拒绝订阅模板时,会推送用户订阅动作事件给开发者。
事件参数示例:
{ "event": "user_subscribe_action", "clieng_key": "tt5daf2b12c28579**", "FromUserID": "12934983615879**", "content": { "msg_id": "MSG351287538173587336778382563**", "time": 1714029835, "subscribe_action": 1 } }
用户订阅状态查询
OpenAPI:
查询用户模板订阅状态:queryUserSubscribe
消息下发
开发者自主下发
OpenAPI:
给用户发送订阅消息:notifyUser
请求示例:
curl --location --request POST 'https://open.douyin.com/api/notification/v2/subscription/notify_user/' \ --header 'access-token: clt.828745d039ea5257c2dadd0d9f263a64CvAcJRBeZ7VhZukAHxVFcXGn*******' \ --header 'content-type: application/json' \ --data ' { "msg_id": "MSG35128757637369807924748699***", "open_id": "-cg5WWbptADwbO**", "data": { "小程序模板keyword1": "测试值1", "小程序模板keyword2": "测试值2" }, "notify_type":[1,2] "page": "pages/index?a=b" } '
代码示例:
- •SDK 方式接入(官方推荐):
import ( "context" "errors" credential "github.com/bytedance/douyin-openapi-credential-go/client" openApiSdkClient "github.com/bytedance/douyin-openapi-sdk-go/client" ) func NotifyUser(ctx context.Context) (errNo int32, errMsg string, err error) { // 控制台-开发-开发配置-小程序Key var appId = "tt5daf2b12c2857***" var appSecret = "ce842aa2db63bf351cdba292e05f41c5955fd***" // 初始化SDK client opt := new(credential.Config). SetClientKey(appId). SetClientSecret(appSecret) // token获取与注入 // credential包提供了默认的token获取方法,但是该实现方式是基于单实例的,如果用户多实例场景使用会出现token互刷的问题。 // 开发者如果有多实例部署的需求可以自行实现token获取的逻辑 credentialHandler, err := credential.NewCredential(opt) if err != nil { return errNo, errMsg, err } token, err := credentialHandler.GetClientToken() if err != nil { return errNo, errMsg, err } // 初始化参数 var key1 = "小程序模板key1" var key2 = "小程序模板key2" var val1 = "小程序模板val1" var val2 = "小程序模板val2" var msgId = "MSG35128757127369095129904351***" var openId = "T25CX9BGuQLeA***" var notifyTypePush, notifyTypeNotice = 1, 2 var notifyType = []*int{¬ifyTypePush, ¬ifyTypeNotice} var page = "pages/index?a=b" sdkClient, err := openApiSdkClient.NewClient(opt) if err != nil { return errNo, errMsg, err } sdkRequest := &openApiSdkClient.SubscriptionNotifyUserRequest{ AccessToken: token.AccessToken, Data: map[string]*string{ key1: &val1, key2: &val2, }, MsgId: &msgId, OpenId: &openId, NotifyType: notifyType, Page: &page, } // sdk调用 sdkResponse, err := sdkClient.SubscriptionNotifyUser(sdkRequest) if err != nil { return errNo, errMsg, err } if sdkResponse == nil { return errNo, errMsg, errors.New("resp is nil") } errNo = *sdkResponse.ErrNo errMsg = *sdkResponse.ErrMsg return }
- •多语言 http 代码示例 notifyUser(路径:开发-服务端OpenAPI-给用户发送订阅消息-在线调试-代码示例) :
官方平台代发
为了更适配小程序的消息发送需求,订阅消息模板新增代发功能。小程序开发者可以在模板库里面选择支持代发的公共模板来创建小程序消息模板,在配置时可选择是否允许官方平台代替小程序拉起“订阅消息授权”弹框,以及是否需要官方平台进行过订阅消息的代发。详细介绍参考订阅消息上线可代发模板。
支持的授权下发方:
- •抖音短剧官方运营:短剧小程序已支持代发追剧提醒消息,在小程序中点击追剧后拉起抖音订阅消息,获取用户接收订阅追剧消息授权,授权完成后,将在抖音侧边栏消息通知里向用户发送追剧消息提醒,引导用户完成复访。选择此下发方后,开发者无法通过给用户发送订阅消息接口发送对应模板的订阅消息
- •开发者自主下发:选择此配置后,与正常订阅消息模板使用、发送流程相同,在用户同意订阅消息发送后,开发者仍可以通过本接口发送对应小程序模板的订阅消息