抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

创建/更新小程序卡片模板
收藏
我的收藏

小程序引导卡片模板为开发者提供了一种基于小程序卡片模板的消息发送方式,即应用创建卡片模板时只需传入卡片背景图、卡片标题、卡片文字描述等封面内容,在发送消息时再传入具体的卡片跳转地址。
    •开发者首先需要通过本接口创建一个小程序卡片模板,获取小程序引导卡片模板对应 card_template_id
    •再通过流式对话接口发送该小程序引导卡片模板,并在调用接口时传入 card_template_id 以及具体的跳转链接

使用限制

同一分身应用,可以配置最多 10 万张小程序引导卡片模板,调用限制为近 30 天可创建 / 更新小程序引导卡片模板 5000 次。

接口说明

    •模板创建后,无法再修改卡片类型 card_type
    •小程序引导卡片示例
    •创建好卡片后,可通过流式对话接口进行小程序引导卡片发送,content 示例如下
"content": "{\"msg_type\": 10,\"applet_card\":{\"card_template_id\": \"@4F9T1avCDMhjO3LyYo04GKep1GeGPPuGOZF2nD+TGmSw1Z\",\"app_id\":\"tt3ergjdge84gdwksb\", \"path\":\"api/apiPage/apiPage\", \"query\":\"{\\\"text\\\":\\\"nihao\\\"}\"}}"
    •schema 获取方式
    ◦通过接口生成 Generate,通过 expire_time 参数控制过期时间,过期后需重新生成。
    ◦在小程序界面点击右上角 ... > 分享 > 复制链接,链接有效期为45天,过期后需重新生成。
    •接口存在防重复提交机制,应用多次调用接口传入相同的 content, media_id, title, app_id 参数创建小程序引导卡片,接口会返回相同的 card_template_id

基本信息

名称
描述
HTTP URL
https://open.douyin.com/api/douyin/v1/im/set_applet_template/
HTTP Method
POST
Scope
im.microapp_card
若开发者需要使用 AI 分身消息卡片能力(小程序卡片、自定义用户信息收集卡),需提供分身应用 AppID 至对接运营同学加白,平台加白后即可开始对接

请求头

名称
类型
是否必填
描述
Content-Type
string
true
固定值 "application/json"
access-token
string
true
当 AI 分身调用时,调用
生成的token
​
当服务商代调用时,调用
生成的token

请求参数

Body

名称
类型
是否必填
描述
示例
card_template_id
string
false
模板ID,修改模板时需要填写创建模板返回的模板ID
@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==
card_type
int
false
卡片类型,创建模板时必传
    •1:小程序卡片
1
content
string
false
卡片内容,最长 30 字
点击加入
media_id
string
false
图片的 ID,调用图片上传接口获取。
创建模板时必传
推荐比例16:9,尺寸840*474
@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==
app_id
string
true
跳转小程序 AppID
tt5daf2b12c11da13910
title
string
false
卡片标题
创建模板时必传,最长 26 字
邀请你一起打荣耀巅峰匹配赛
​

请求示例

curl -X POST 'https://open.douyin.com/api/douyin/v1/im/set_applet_template/' -H 'Content-Type:application/json' -H 'access-token:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1' --data '{"card_type":1,"title":"title测试","content":"content测试","media_id":"@9VwNxuKKBZ03MXG7M8ooWM6+iib0bqafYog16knsa1AUPKajyCbkeFIfvjDAhgpsWGXCimkBdNNS2dWASnfgCXqIi7Z6mT1hatJT3UhT8k963Osx4MrrU60NZwIlVg3j","name":"name测试","icon_media_id":"@9VwNxuKKBZ03MXG7M8ooWM6+iib0bqafYog16knsa1AUPKajyCbkeFIfvjDAhgpsWGXCimkBdNNS2dWASnfgCXqIi7Z6mT1hatJT3UhT8k963Osx4MrrU60NZwIlVg3j"}'

响应参数

名称
​
类型
描述
示例
data
​
struct
​
​
​
card_template_id
string
模板 ID
@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==
extra
​
struct
​
​
​
description
string
错误码描述
​
​
error_code
int
错误码
0
​
logid
string
标识请求的唯一 id
202008121419360101980821035705926A
​
now
int
毫秒级时间戳
1597213176393
​
sub_description
string
子错误码描述
​
​
sub_error_code
int
子错误码
0

响应示例

正常示例

{ "extra": { "now": 1660109739, "logid": "20220810133539010174255181020C5143", "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "" }, "data": { "error_code": 0, "description": "", "card_template_id": "@72MqHzC5kqIEgB56A10R9n1psNsNe8gPbkeqQAHKbHqoQ5jL3za3OAGvMtWtnszA" } }

异常示例

{ "extra": { "sub_description": "", "sub_error_code": 0, "description": "参数不合法", "error_code": 2100005, "logid": "202203271807199888808121990491456D", "now": 1648375639 }, "data": { "error_code": 2100005, "description": "参数不合法" } }
​

错误码

HTTP 状态码
错误码
描述
排查建议
200
0
请求成功
​
​
​
​