创建/更新小程序引导卡片模板

更新时间 2024-07-24 02:58:49

我的收藏

小程序引导卡片模板为开发者提供了一种基于小程序卡片模板的消息发送方式，即应用创建卡片模板时只需传入卡片背景图、卡片标题、卡片文字描述等封面内容，在发送消息时再传入具体的卡片跳转地址。

•

开发者首先需要通过本接口创建一个小程序卡片模板，获取小程序引导卡片模板对应 card_template_id

•

再通过发送私信消息 / 发送群消息接口发送该小程序引导卡片模板，并在调用接口时传入 card_template_id 以及具体的跳转链接

使用限制

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

接口说明

•

小程序引导卡片为小程序类型卡片的具体类型之一，有关小程序类型卡片详见小程序类型卡片概述

•

模板创建后，无法再修改卡片类型 card_type

•

小程序引导卡片示例

•

创建好卡片后，可通过发送私信消息接口进行小程序引导卡片发送，content 示例如下

js复制
"content": {
    "msg_type": 10,
    "applet_card": {
      "card_template_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx",
      "schema":"https://z.douyin.com/ijBoQwF"
    }
 }

•

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
权限要求	•小程序通过试运营期

请求头

名称	类型	是否必填	描述
Content-Type	string	true	固定值 "application/json"
access-token	string	true	调用/oauth/client_token/ 生成的 token，示例： clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1

请求参数

Body

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

请求示例

js复制
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

响应示例

正常示例

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

异常示例

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