给用户发送订阅消息
收藏
我的收藏接口说明
前提条件
- 通过设置该接口入参的 notify_type 字段发送抖音内横幅或抖音外实时提醒消息说明:
- 前提条件:
- 小程序模版需支持实时提醒能力:
- 开发者在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新公共模版时在“是否使用额外触达能力”选中“实时提醒”选项;
- 开发者基于已具备实时提醒能力的公共模版选择“添加”生成小程序模版。
- 用户需同意打开提醒能力(任一操作完成即可):
- 开发者在小程序中拉起订阅组件后,用户针对特定小程序模版点击右侧的“添加提醒”或点击模板右侧的提醒方式跳转“选择提醒方式”中勾选“横幅提醒”,最后点击“同意”;
- 用户在订阅消息管理页针对特定小程序模版勾选“横幅提醒”;
- 传参要求:开发者在接口中 notify_type 字段传入 1;
- 开发者可订阅 抖音内横幅或抖音站外实时提醒触达用户失败事件 获取触达用户失败原因。
- 首页推荐频道提醒说明:
- 前提条件:
- 消息模板需支持信息流通知能力:
- 开发者在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新公共模版时在“是否使用额外触达能力”选中“信息流通知”选项;
- 开发者基于已具备信息流通知能力的公共模版选择“添加”生成小程序模版。
- 用户需同意打开提醒能力(任一操作完成即可):
- 开发者在小程序中拉起订阅组件后,小程序模板支持首页推荐频道提醒则默认勾选该能力,可在小程序模板右侧的提醒方式跳转“选择提醒方式”中取消勾选(旧版本抖音需勾选“在首页推荐频道提醒”);
- 用户在订阅消息管理页针对特定小程序模板勾选“推荐页卡片”(旧版本抖音需打开“订阅消息在首页feed提醒”)。
- 传参要求:
- page 为空则不创建异形卡;
- 模板关键词数量 < 1 ,不生成异形卡,且超过4个关键词创建卡片时会进行截断。
- 开发者可订阅 用户授权订阅卡事件 获取订阅异形卡模板授权成功消息。
- 额度说明:订阅异形卡额度与小程序模板下发消息额度相同,不进行额外扣减。
- 卡片创建规则:下发订阅消息成功且消息内容审核通过信息流通知审核则创建卡片。
- 展现规则:
- 时效:异形卡在对应消息成功发送后24小时内有效,若用户24小时内因未打开抖音、未进行刷feed操作请求异形卡或因用户频控导致指定卡片结果无法下发,则该条卡片结果作废且不再创建;
- 频控:用户单天内针对同一小程序仅能收到一次订阅消息异形卡提醒(已授权状态下默认开发者给用户当天下发的第一条订阅消息触发)。
- 消息读取状态:在侧边栏小程序落地页读取消息后,不展现异形卡。
- 消息额度说明:
- 开发者可在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新模版时选择默认模版消息额度或自定义模版消息额度,审核成功后消息额度生效,用户在基于公共模板创建小程序模板时,会在页面上方显示当前公共模板额度;创建小程序模板后额度无法变更。
- 针对存量一次性模版,用户订阅一次该模版,开发者 365 天内可发送 x 条(默认为2)模版消息,用户再次订阅该模版,开发者发送模版消息额度累加(x 为创建)。
- 针对存量长期模版,用户订阅一次该模版,开发者每 30 天可发送 x 条(默认为8)模版消息,用户再次订阅该模版,开发者发送模版消息额度不做累加。
- 可代发模板说明:
- 若模板库中的公共模板为可代发模板,开发者在添加模板时可进行如下配置:
- 授权弹出订阅消息权限:开启授权后,官方平台将代替你拉起“订阅消息授权”弹框
- 授权下发方:
- 抖音短剧官方运营:平台兜底发送订阅消息,开发者无法下发对应模板的订阅消息
- 开发者自主下发:与非可代发模板相同,开发者可以通过 OpenAPI 发送订阅消息
- 添加可代发模板后,可以修改模板说明 1 中的权限配置
使用限制
无
基本信息
名称 | 描述 |
---|---|
HTTP URL | https://open.douyin.com/api/notification/v2/subscription/notify_user/ |
HTTP Method | POST |
Scope | notification.openapi.common |
权限要求 | 服务商代调用场景下,需商家授予服务商运营管理权限集:
|
请求参数
请求头
access-token必填String
当非服务商时,调用https://open.douyin.com/oauth/client_token/生成的token
当服务商时,调用https://open.douyin.com/api/tpapp/v2/auth/get_auth_token/生成的token
当服务商时,调用https://open.douyin.com/api/tpapp/v2/auth/get_auth_token/生成的token
content-type必填String
示例:application/json
固定值"application/json"
Body展开全部子属性
data必填Map
模板内容
展开子属性
msg_id必填String
消息模板的 id,来自添加模板接口
open_id必填String
接收消息目标用户的 open_id,参考 code2session
notify_typeList
示例:[1,2]
发送消息模式列 表;
- 枚举说明:
1 表示仅发送实时提醒(抖音内横幅或抖音外实时提醒消息);
2 表示仅发送站内信; - 传入参数说明:
[1] 仅发送实时提醒(如订阅模板不支持实时提醒或用户未订阅提醒通知,则不支持发送);
[2] 如订阅模板不支持实时提醒或用户未订阅提醒通知,则不支持发送。仅发送站内信;
[1,2] 同时支持发送站内信和实时提醒消息(如订阅模板不支持实时提醒或用户未订阅提醒通知,则不支持发送)。
展开子属性
pageString
示例:pages/presaleCoupon/couponDetails/ticketDetails?orderId=****
小程序页面链接,由页面的query和path参数构成;目前暂不支持跳转外部链接
请求示例
curl --location --request POST 'https://open.douyin.com/api/notification/v2/subscription/notify_user/' \ --header 'access-token: 0801121846735352506a356a6' \ --header 'content-type: application/json' \ --data ' { "msg_id": "MSG38489d04608c5f0fdeb565fc5114afff6410*******", "open_id": "36d4bd3c8****", "data": { "物品名称": "测试值0", "购买金额": "测试值1" }, "notify_type":[1,2], "page": "pages/index?a=b" } '
响应参数
Body
err_msg必填String
示例:“”
错误信息
err_no必填Int32
示例:0
错误码,0 是成功,其它为异常
log_id必填String
示例:202008121419360101980821035705926A
标识请求的唯一id,在接口异常时用于问题排查
响应示例
正常响应示例异常响应示例
{ "err_no": 0, "err_msg": "", "log_id": "202008121419360101980821035705926A" }
错误码
HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
---|---|---|---|
200 | 28001038 | 参数错误 | 按err_msg检查入参 |
200 | 28001005 | 服务内部错误,请重试 | 自行重试,重试后仍报错请联系平台 Oncall 解决 |
200 | 28014028 | 只对抖音/抖音极速版/头条开放 | |
200 | 28014029 | 新手村权限拦截 | 需要小程序通过试运营期,详见 小程序试运营期管理规范 |
200 | 28014026 | 发送消息太频繁了,请稍后再试 | |
200 | 28014027 | 存在敏感内容 | 当前订阅消息发送内容存在敏感词,请更改内容后重新发送 |
200 | 28001006 | 网络调用错误,请重试 | 自行重试,重试后仍无效请联系平台 Oncall 解决 |
200 | 28014040 | 当前模版仅支持授权业务方发送消息 | 确认当前模板是否为可代发,代发中的可代发模板暂不支持开发者自主下发 |
200 | 28014025 | 被禁止使用订阅通知功能 | 小程序订阅消息能力被封禁,请联系平台 Oncall 解决 |
200 | 28014042 | 小程序已下线禁止使用订阅消息 | 仅线上小程序可使用订阅消息能力 |
200 | 28014037 | 模版状态不可用 | 当前小程序模板已经被封禁,请更换小程序模板或联系平台 Oncall 解决 |
200 | 28014041 | 当前发送消息额度已消耗完 | 用户在该周期内订阅模板后开发者可以下发的消息数已达上限 |
200 | 28014036 | 用户拒绝接收 | 用户在订阅消息管理页关闭订阅消息通知 |
200 | 28014043 | 用户未订阅该模版 | 引导用户订阅当前要下发的小程序模板,详见 接入订阅消息能力 |
200 | 28014044 | 用户被封禁或不存在 | 该用户无法收到站内信,请联系平台 Oncall 解决 |
200 | 28001003 | access_token无效 | 重新请求生成access_token |
200 | 28001008 | access_token过期,请刷新或重新授权 | 重新请求生成access_token |
200 | 28001016 | 当前应用已被封禁或下线 | clientKey被封禁或者下线 |
200 | 28001014 | 应用未授权任何能力 | 确认应用是否授权能力 |
200 | 28001018 | 应用未获得该能力 | 开通相关能力 |
200 | 28001019 | 应用该能力已被封禁 | 该能力被封禁,请联系平台 Oncall 解决 |
200 | 28001007 | 参数不合法 | 根据错误信息检查请求参数是否填写正常 |
Bug & Tip
- •请求 body 的
Content-Type
限定为application/json。
- •对单个用户推送消息,频率限制为 1 次/秒。
- •订阅消息分为一次性订阅和长期订阅,详情参考订阅消息。
- •示例参数中模板内容
data
中 key/value 与模板元素的对应关系如下图,模板元素查询参考订阅消息:- ◦
点击纠错