抖音开放平台Logo
开发者文档
移动/网站应用
控制台
  • OpenAPI 列表
  • 移动/网站应用 OpenAPI SDK 总览
  • 状态码排查工具
  • 个人资料
  • 关系能力
  • 内容能力
  • 互动评论
  • 私信群聊
  • 私信管理
  • 群聊管理
  • 意向用户管理
  • 经营工具
  • 留资卡片
  • 创建/更新留资卡片
  • 查询留资卡片
  • 删除留资卡片
  • 小程序引导卡片
  • 图片上传
  • 获取消息中的多媒体资源
  • 企业号开放能力（内测结束暂不开放）
  • 生活服务开放能力
  • 工具能力
  • 服务市场开放能力
  • 小程序推广计划
  • 联合授权

    • 创建/更新留资卡片

    收藏
    我的收藏
    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": {
    "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": "参数不合法"
  }
}
    ​