给用户发送订阅消息

收藏
我的收藏

接口说明

  1. 发送订阅消息V1 接口预期下线时间为2024.07.01,接口文档下线后V1接口停止维护,后续建议统一使用该接口发送订阅消息
  2. 用户产生了订阅模板消息的行为后,可以通过该接口发送模板消息给用户。功能参考订阅消息

前提条件

  • 通过设置该接口入参的 notify_type 字段发送抖音内横幅或抖音外实时提醒消息说明:
  1. 前提条件:
    1. 小程序模版需支持实时提醒能力:
      1. 开发者在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新公共模版时在“是否使用额外触达能力”选中“实时提醒”选项;
      2. 开发者基于已具备实时提醒能力的公共模版选择“添加”生成小程序模版。
    2. 用户需同意打开提醒能力(任一操作完成即可):
      1. 开发者在小程序中拉起订阅组件后,用户针对特定小程序模版点击右侧的“添加提醒”或点击模板右侧的提醒方式跳转“选择提醒方式”中勾选“横幅提醒”,最后点击“同意”;
      2. 用户在订阅消息管理页针对特定小程序模版勾选“横幅提醒”;
  2. 传参要求:开发者在接口中 notify_type 字段传入 1;
  3. 开发者可订阅 抖音内横幅或抖音站外实时提醒触达用户失败事件 获取触达用户失败原因。
  • 首页推荐频道提醒说明:
  1. 前提条件:
    1. 消息模板需支持信息流通知能力:
      1. 开发者在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新公共模版时在“是否使用额外触达能力”选中“信息流通知”选项;
      2. 开发者基于已具备信息流通知能力的公共模版选择“添加”生成小程序模版。
    2. 用户需同意打开提醒能力(任一操作完成即可):
      1. 开发者在小程序中拉起订阅组件后,小程序模板支持首页推荐频道提醒则默认勾选该能力,可在小程序模板右侧的提醒方式跳转“选择提醒方式”中取消勾选(旧版本抖音需勾选“在首页推荐频道提醒”);
      2. 用户在订阅消息管理页针对特定小程序模板勾选“推荐页卡片”(旧版本抖音需打开“订阅消息在首页feed提醒”)。
  2. 传参要求:
    1. page 为空则不创建异形卡;
    2. 模板关键词数量 < 1 ,不生成异形卡,且超过4个关键词创建卡片时会进行截断。
  3. 开发者可订阅 用户授权订阅卡事件 获取订阅异形卡模板授权成功消息。
  4. 额度说明:订阅异形卡额度与小程序模板下发消息额度相同,不进行额外扣减。
  5. 卡片创建规则:下发订阅消息成功且消息内容审核通过信息流通知审核则创建卡片。
  6. 展现规则:
    1. 时效:异形卡在对应消息成功发送后24小时内有效,若用户24小时内因未打开抖音、未进行刷feed操作请求异形卡或因用户频控导致指定卡片结果无法下发,则该条卡片结果作废且不再创建;
    2. 频控:用户单天内针对同一小程序仅能收到一次订阅消息异形卡提醒(已授权状态下默认开发者给用户当天下发的第一条订阅消息触发)。
    3. 消息读取状态:在侧边栏小程序落地页读取消息后,不展现异形卡。
  • 消息额度说明:
  1. 开发者可在抖音开放平台-控制台-选中小程序-互动能力-订阅消息-模版库-申请新模版时选择默认模版消息额度或自定义模版消息额度,审核成功后消息额度生效,用户在基于公共模板创建小程序模板时,会在页面上方显示当前公共模板额度;创建小程序模板后额度无法变更。
  2. 针对存量一次性模版,用户订阅一次该模版,开发者 365 天内可发送 x 条(默认为2)模版消息,用户再次订阅该模版,开发者发送模版消息额度累加(x 为创建)。
  3. 针对存量长期模版,用户订阅一次该模版,开发者每 30 天可发送 x 条(默认为8)模版消息,用户再次订阅该模版,开发者发送模版消息额度不做累加。
  • 可代发模板说明:
  1. 若模板库中的公共模板为可代发模板,开发者在添加模板时可进行如下配置:
    1. 授权弹出订阅消息权限:开启授权后,官方平台将代替你拉起“订阅消息授权”弹框
    2. 授权下发方:
      1. 抖音短剧官方运营:平台兜底发送订阅消息,开发者无法下发对应模板的订阅消息
      2. 开发者自主下发:与非可代发模板相同,开发者可以通过 OpenAPI 发送订阅消息
  1. 添加可代发模板后,可以修改模板说明 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
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 状态码错误码错误码描述排查建议
20028001038
参数错误
按err_msg检查入参
20028001005

服务内部错误,请重试

自行重试,重试后仍报错请联系平台 Oncall 解决

20028014028
只对抖音/抖音极速版/头条开放
20028014029
新手村权限拦截

需要小程序通过试运营期,详见 小程序试运营期管理规范

20028014026

发送消息太频繁了,请稍后再试

20028014027
存在敏感内容

当前订阅消息发送内容存在敏感词,请更改内容后重新发送

20028001006
网络调用错误,请重试

自行重试,重试后仍无效请联系平台 Oncall 解决

20028014040

当前模版仅支持授权业务方发送消息

确认当前模板是否为可代发,代发中的可代发模板暂不支持开发者自主下发

20028014025

被禁止使用订阅通知功能

小程序订阅消息能力被封禁,请联系平台 Oncall 解决

20028014042

小程序已下线禁止使用订阅消息

仅线上小程序可使用订阅消息能力

20028014037

模版状态不可用

当前小程序模板已经被封禁,请更换小程序模板或联系平台 Oncall 解决

20028014041

当前发送消息额度已消耗完

用户在该周期内订阅模板后开发者可以下发的消息数已达上限

20028014036

用户拒绝接收

用户在订阅消息管理页关闭订阅消息通知

20028014043

用户未订阅该模版

引导用户订阅当前要下发的小程序模板,详见 接入订阅消息能力

20028014044

用户被封禁或不存在

该用户无法收到站内信,请联系平台 Oncall 解决

20028001003
access_token无效
重新请求生成access_token
20028001008
access_token过期,请刷新或重新授权
重新请求生成access_token
20028001016
当前应用已被封禁或下线
clientKey被封禁或者下线
20028001014
应用未授权任何能力
确认应用是否授权能力
20028001018
应用未获得该能力
开通相关能力
20028001019
应用该能力已被封禁

该能力被封禁,请联系平台 Oncall 解决

20028001007
参数不合法
根据错误信息检查请求参数是否填写正常

Bug & Tip​

    请求 body 的Content-Type限定为application/json。
    对单个用户推送消息,频率限制为 1 次/秒。​
    订阅消息分为一次性订阅和长期订阅,详情参考订阅消息。​
    示例参数中模板内容data中 key/value 与模板元素的对应关系如下图,模板元素查询参考订阅消息:​