创建/更新留资卡片

我的收藏

Scope: im.message_card 需要申请权限需要用户授权

该接口用于创建 / 更新留资卡片

该接口涉及 scope 在用户点击授权，开发者获取到 code 调用 /oauth/access_token/ 接口时，返回的 scope 参数中将不再包含该 scope；授权(authorize), 取消授权(unauthorize) Webhook 事件中 scope 参数同样不会包含该 scope，开发者仍可以使用该 access_token 调用本接口。授权用户可以在设置-账号与安全-授权管理-经营授权中查看 / 取消已授权的 im 能力。抖音开放平台将于近期补齐 access_token 返回该 scope 的能力。

使用限制

•

支持创建多个留资卡片，目前每个应用支持最多创建 1000 个。

•

该能力需要用户进行 web 扫码授权，当前仅支持一个用户授权一个应用，详见授权概述

•

当前开放用户范围：小程序品牌号及员工号和认证企业号及其员工号；后续将基于抖音经营者实际诉求逐步拓展开放用户范围。

接口说明

•

样式示例

卡片配置	样式
`{ "title":"同类型", "media_id":"@9VwNxuKKBZ03MXG7M8ooWM6+iib0bqafYog16knsa1AUPKajyCTkLAhFvjLE1QtoXGXEjzkBJNYG2NHSHyblWX2M2bZ5mT1hatJT3UhT8k+LWeDC54fwY0ZOD4Lc1JSX", "components":[ 1, 2, 3 ] }`

•

如果用户填写了留资信息会在端上展示，并通过私信 webhook 回调给开发者

•

创建好留资卡片后，可通过发送私信消息、发送群消息接口进行留资卡片发送，content 示例如下

"content": {
    "msg_type": 8,
    "retain_consult_card": {
      "card_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx"
    }
 }

基本信息

名称	描述
HTTP URL	https://open.douyin.com/im/save/retain_consult_card/
HTTP Method	POST
Scope	im.message_card
权限要求	新能力上线能力实验室后，经营者可在“控制台-能力管理-能力实验室”中申请。后期能力若转为正式开放能力，可在“控制台-能力管理-互动管理”中申请。

请求头

名称	类型	是否必填	描述
Content-Type	string	true	固定值 "application/json"
access-token	string	true	调用 /oauth/access_token/ 生成的 token，此 token 需要用户授权示例： act.1d1021d2aee3d41fee2d2adfwdf56badMFZnrhFhfWotu3Ecuiuka27L56lr

Query

名称	类型	是否必填	描述	示例
open_id	string	true	调用 /oauth/access_token/ 获取，用户唯一标志	ba253642-0590-40bc-9bdf-9a1334b94059

Body

名称	类型	是否必填	描述	示例
card_id	string	false	留资卡片ID，修改卡片时需要填写	@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==
components	list<int>	true	需要添加的输入框，至少传入一个 •1：姓名 •2：手机号 •3：城市	[1,2]
media_id	string	true	图片的 ID。通过图片上传接口获取图片尺寸建议：宽263高120 尺寸不一样会自动适配短边占满	@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==
title	string	true	卡片标题	留资卡片

请求示例

curl -X POST 'https://open.douyin.com/im/save/retain_consult_card/?open_id=ba253642-0590-40bc-9bdf-9a1334b94059' -H 'Content-Type:application/json' -H 'access-token:act.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1123daf13ad' --data '{"title":"同类型","media_id":"@9VwNxuKKBZ03MXG7M8ooWM6+iib0bqafYog16knsa1AUPKajyCTkLAhFvjLE1QtoXGXEjzkBJNYG2NHSHyblWX2M2bZ5mT1hatJT3UhT8k+LWeDC54fwY0ZOD4Lc1JSX","components":[1,2,3]}'

响应参数

名称		类型	描述	示例
card_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

响应示例

正常示例

{
  "card_id": "@72MqHzC5kqIEgB56A10R9n1psdsNe8gPbkeqQAHKbHp1G4Vlci1qTF5dPUOM0K8i",
  "extra": {
    "error_code": 0,
    "description": "",
    "sub_error_code": 0,
    "sub_description": "",
    "now": 1660109415,
    "logid": "202208101330140102250990080401DB11"
  },
  "data": {
    "error_code": 0,
    "description": ""
  }
}

异常示例

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

创建/更新留资卡片在线调试

​使用限制​

​接口说明​

​基本信息​

​请求头​

​Query​

​Body​

​请求示例​

​响应参数​

​响应示例​

​正常示例​

​异常示例​