钉钉开放平台
解决方案
钉钉PaaS
文档&帮助
应用中心
生态&合作
开发者社区
登录
文档首页
应用开发
AI 开发
工作台开放
连接器开发
数据开放
智能硬件接入
能力全景图
开发工具
钉钉设计开放
更新日志
服务支持
选择应用类型
企业内部应用开发

创建卡片新版SDK

更新于 2025-02-17

接口调用量说明钉钉标准版接口累计可调用次数为1万次/月，当前接口会消耗调用次数。若该调用量无法满足需求，你可升级钉钉专业版(Open API调用量50万次/月)或钉钉专属版(Open API调用量500万次/月)扩容调用次数。
调用本接口可以从指定的模版中创建卡片实例。

接口功能介绍

调用本接口创建卡片实例，可以设置卡片的基本数据、设置动态数据源、卡片所在场域等内容。具体展示如下图：

权限

要调用此API，需要以下权限之一。

应用类型

是否支持

权限

API Explorer调试

企业内部应用支持互动卡片实例写权限API Explorer
第三方企业应用支持互动卡片实例写权限API Explorer
第三方个人应用暂不支持互动卡片实例写权限暂不支持

请求方法

Loading...

Header参数

名称

类型

是否必填

描述

x-acs-dingtalk-access-token

String

是

调用该接口的访问凭证。

Body参数

名称

类型

是否必填

描述

userId

String

否

卡片创建者的userId。

cardTemplateId

String

是

卡片内容模板ID，可通过登录开发者后台 > 卡片平台获取。

outTrackId

String

是

外部卡片实例Id。

说明

  • 开发者自己生成并作为入参传递给钉钉的，钉钉只在对应使用到 outTrackId 的场景，帮助开发者对TrackId进行记录

  • 一个 outTrackId 唯一标识一张卡片，如果需要使用新的 cardTemplateId 或 cardData 等参数创建一张新的卡片，需要设置全新的 outTrackId，否则更改不会生效。

callbackType

String

否

卡片回调的类型：

  • STREAM：stream模式
  • HTTP：http模式
说明

注意参数均为大写。

详情参见卡片互动-事件回调文档。

callbackRouteKey

String

否

卡片回调HTTP模式时的路由 Key，用于查询注册的 callbackUrl。

  • 企业内部应用可通过调用服务端API-注册卡片回调地址接口，根据填写的callbackRouteKey入参字段获取。

  • 第三方企业应用可通过调用服务端API-注册卡片回调地址接口，根据填写的callbackRouteKey入参字段获取。

cardData

Object

是

卡片数据，示例：

Loading...

cardParamMap

Map<String, String>

否

卡片模板内容替换参数：

  • key：参数名（最长不超过100B）
  • value: 参数值（最长不超过1KB）
说明

  • 属性字段只支持 String 类型，非 String 类型的属性填写请参考文档：API 卡片数据的填写说明。
  • 务必确保属性值的类型与卡片搭建器中所配置的变量类型相匹配，否则可能出现属性不生效，或者在移动端无法显示等问题。

privateData

Map<String, Object>

否

用户的私有数据：

  • key：用户userId信息
  • value：用户私有数据

示例：

Loading...

Object

否

私有数据用户userId。

cardParamMap

Map<String, String>

否

卡片模板内容替换参数：

  • key：参数名（最长不超过100B）
  • value: 参数值（最长不超过1KB）
说明

  • cardParamMap 中的属性字段只支持 String 类型，非 String 类型的属性填写请参考文档：API 卡片数据的填写说明。

  • 务必确保属性值的类型与卡片搭建器中所配置的变量类型相匹配，否则可能出现属性不生效，或者在移动端无法显示等问题。

openDynamicDataConfig

Object

否

动态数据源配置。

dynamicDataSourceConfigs

Array

否

动态数据源配置列表。

dynamicDataSourceId

String

否

数据源的唯一 ID, 调用方指定。

说明

使用动态数据源功能时该参数字段必填。

constParams

Map<String, String>

否

回调数据源时回传的固定参数。 示例：

Loading...

pullConfig

Object

否

数据源拉取配置。

说明

使用动态数据源功能时该参数字段必填。

pullStrategy

String

否

拉取策略，可选值：

  • NONE：不拉取，无动态数据
  • INTERVAL：间隔拉取
  • ONCE：只拉取一次
说明

使用动态数据源功能时该参数字段必填。

interval

Integer

否

拉取的间隔时间。

说明

  • 只在将pullStrategy设置为INTERVAL的时候生效。
  • 最小拉取间隔时间3s。

timeUnit

String

否

拉取的间隔时间的单位， 可选值：

  • SECONDS：秒
  • MINUTES：分钟
  • HOURS：小时
  • DAYS：天
说明

只在将pullStrategy设置为INTERVAL的时候生效。

imSingleOpenSpaceModel

Object

否

IM单聊酷应用场域信息，具体表现如下：

说明

单聊酷应用详情参考接入单聊酷应用。

supportForward

Boolean

否

是否支持转发, 默认 false。

lastMessageI18n

Map<String, String>

否

支持国际化的LastMessage，key为语言枚举值，value为lastMessage内容。

目前支持的语言枚举值：

  • ZH_CN：简体中文
  • ZH_TW：繁体中文
  • EN_US：英文
  • JA_JP：日语:
  • VI_VN：越南语

searchSupport

Object

否

支持卡片消息可被搜索字段。

searchIcon

String

否

类型的icon，供搜索展示使用。

searchTypeName

String

否

卡片类型名。

searchDesc

String

否

供消息展示与搜索的字段。

说明

  • 最大限制200个字符，超过存储截断200。

notification

Object

否

卡片的通知属性信息。

alertContent

String

否

通知内容，若不填写则使用默认文案：如你收到1条新消息。

notificationOff

Boolean

否

是否推送通知，默认为 false。

imGroupOpenSpaceModel

Object

否

IM 群聊场域信息。

supportForward

Boolean

否

是否支持转发：

  • true：支持
  • false：不支持
说明

若使用imGroupOpenSpaceModel对象，则该字段必填。

lastMessageI18n

Map<String, String>

否

支持国际化的LastMessage，目前支持的语言枚举值：

  • ZH_CN：简体中文
  • ZH_TW：繁体中文:
  • EN_US：英文
  • JA_JP：日语
  • VI_VN：越南语
说明

key为语言枚举值，value为lastMessage内容。

示例：

Loading...

searchSupport

Object

否

支持卡片消息可被搜索字段。

searchIcon

String

否

类型的icon，供搜索展示使用。

searchTypeName

String

否

卡片类型名。

searchDesc

String

否

供消息展示与搜索的字段。

说明

  • 最大限制200个字符，超过存储截断200。

notification

Object

否

通知信息。

alertContent

String

否

通知内容。

说明

若不填写则使用默认文案：如你收到1条新消息。

notificationOff

Boolean

否

是否关闭推送通知：

  • true：关闭
  • false：不关闭
说明

默认为 false

imRobotOpenSpaceModel

Object

否

IM 机器人单聊场域信息。

supportForward

Boolean

否

是否支持转发：

  • true：转发
  • false：不转发
说明

若使用imRobotOpenSpaceModel对象，则该字段必填。

lastMessageI18n

Map<String, String>

否

支持国际化的LastMessage，目前支持的语言枚举值：

  • ZH_CN：简体中文
  • ZH_TW：繁体中文:
  • EN_US：英文
  • JA_JP：日语
  • VI_VN：越南语
说明

key为语言枚举值，value为lastMessage内容。

示例：

Loading...

searchSupport

Object

否

支持卡片消息可被搜索字段。

searchIcon

String

否

类型的icon，供搜索展示使用。

searchTypeName

String

否

卡片类型名。

searchDesc

String

否

供消息展示与搜索的字段。

说明

  • 最大限制200个字符，超过存储截断200。

notification

Object

否

卡片的通知属性信息。

alertContent

String

否

通知内容。

说明

若不填写则使用默认文案：如你收到1条新消息。

notificationOff

Boolean

否

是否关闭推送通知：

  • true：关闭
  • false：不关闭
说明

默认为 false

coFeedOpenSpaceModel

Object

否

协作场域信息（废弃）。

title

String

否

卡片标题（废弃）。

说明

若使用coFeedOpenSpaceModel对象，则该字段必填。

topOpenSpaceModel

Object

否

吊顶场域信息。

spaceType

String

否

吊顶场域属性，通过增加spaeType使卡片支持吊顶场域。

说明

  • 吊顶对应spaceType为ONE_BOX。
  • 若使用topOpenSpaceModel对象，则该字段必填。

cardAtUserIds

Array of String

否

被@人的userId列表:

说明

  • 设置此字段，可以实现在卡片中@人的效果；
  • 同时需要在卡片的 markdown 内容中添加：<a atId=example_user_id> 用户昵称<a> ；

示例：比如卡片模板中的一个 markdown 变量名为 markdown_content，则卡片变量需要设置为：

Loading...

userIdType

Integer

否

用户id类型：

  • 1（默认）：userId模式

  • 2：unionId模式

说明

userIdType 字段的填写请参考：userIdType 字段的填写说明。

返回参数

名称

类型

描述

success

Boolean

创建是否成功。

result

String

outTrackId, 外部卡片实例Id。

说明

由开发者自己生成并作为入参传递。

示例

请求示例

Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

返回示例

Loading...

错误码

HttpCode

错误码

错误信息

说明

400

param.empty

param.empty

入参为空

400

param.cardTemplateIdEmpty

param.cardTemplateIdEmpty

卡片模版 Id 为空

400

param.outTrackIdEmpty

param.outTrackIdEmpty

业务标识 outTrackId 为空

400

param.userIdEmpty

param.userIdEmpty

用户 userId 为空

400

param.cardPublicDataEmpty

param.cardPublicDataEmpty

卡片公共数据为空

400

param.userIdNotExist

param.userIdNotExist

用户 userId 不存在

400

param.dynamicDataMappingEmpty

param.dynamicDataMappingEmpty

动态数据源数据映射为空

400

param.dynamicSourceIdEmpty

param.dynamicSourceIdEmpty

动态数据源配置 ID 为空

400

param.dynamicDataPullConfigEmpty

param.dynamicDataPullConfigEmpty

动态数据源拉取配置为空

400

param.dynamicDataPullIntervalInvalid

param.dynamicDataPullIntervalInvalid

动态数据源拉取间隔时间为空或非法

400

param.dynamicDataPullIntervalTimeUnitInvalid

param.dynamicDataPullIntervalTimeUnitInvalid

动态数据源拉取间隔时间单位为空或非法

400

param.dynamicDataSourcePullStrategyEmpty

param.dynamicDataSourcePullStrategyEmpty

动态数据源拉取策略为空

400

param.dynamicDataMappingPathEmpty

param.dynamicDataMappingPathEmpty

动态数据源数据映射路径为空

400

param.dynamicDataValueTypeEmpty

param.dynamicDataValueTypeEmpty

动态数据源数据类型为空

400

param.contentUnsafe

param.contentUnsafe

卡片数据不能通过安全审查

400

param.openSpaceModelInvalid

param.openSpaceModelInvalid

错误的场域属性模型

400

param.cardNotExist

param.cardNotExist

卡片不存在

400

param.invalid

param.invalid

存在非法参数

400

param.cardAlreadyExist

param.cardAlreadyExist

卡片已经存在

400

param.templateNotExist

param.templateNotExist

模板不存在

400

param.templateUnpublished

param.templateUnpublished

模板未发布

500

system.busy

system.busy

系统繁忙

这篇文档是否有帮助？
点击纠错