创建/更新留资卡片
收藏该接口用于创建 / 更新留资卡片
该接口涉及 scope 在用户点击授权，开发者获取到 code 调用 /oauth/access_token/ 接口时，返回的 scope 参数中将不再包含该 scope；授权(authorize), 取消授权(unauthorize) Webhook 事件中 scope 参数同样不会包含该 scope，开发者仍可以使用该 access_token 调用本接口。授权用户可以在
设置-账号与安全-授权管理-经营授权中查看 / 取消 已授权的 im 能力。抖音开放平台将于近期补齐 access_token 返回该 scope 的能力。使用限制
- •支持创建多个留资卡片，目前每个应用支持最多创建 1000 个。
- •该能力需要用户进行 web 扫码授权，当前仅支持一个用户授权一个应用，详见 授权概述
- •当前开放用户范围：小程序品牌号及员工号 和 认证企业号及其员工号；后续将基于抖音经营者实际诉求逐步拓展开放用户范围。
接口说明
- •样式示例
卡片配置 | 样式 |
| |
- •如果用户填写了留资信息会在端上展示，并通过私信 webhook 回调给开发者
"content": { "msg_type": 8, "retain_consult_card": { "card_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx" } }
基本信息
名称 | 描述 |
HTTP URL | |
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 | ba253642-0590-40bc-9bdf-9a1334b94059 |
Body
名称 | 类型 | 是否必填 | 描述 | 示例 |
card_id | string | false | 留资卡片ID，修改卡片时需要填写 | @8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w== |
components | list<int> | true | 需要添加的输入框，至少传入一个
| [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": "参数不合法" } }
