投放卡片

POST

/v1.0/card/instances/deliver

**
接口调用量说明**钉钉标准版接口累计可调用次数为1万次/月，当前接口会消耗调用次数。若该调用量无法满足需求，你可升级钉钉专业版(Open API调用量50万次/月)或钉钉专属版(Open API调用量500万次/月)扩容调用次数。

调用本接口实现卡片投放。

接口功能介绍

调用本接口实现多个指定场域的卡片投放。具体展示如下图：

说明

目前支持将卡片投放至以下场域：IM群聊、IM机器人单聊、吊顶、协作、文档。

接口调用说明

在将卡片投放到不同的场域时，使用outTrackId唯一标识一张卡片，通过openSpaceId标识需要被投放的场域及其场域Id，通过openDeliverModels传入不同场域下的投放属性。

说明

若需要被投放的卡片实例不支持该场域，需要先调用appendSpace接口增加该场域（将卡片投放至文档不需要）。

场域类型及其sapceId定义如下：

场域类型	SpaceType	SpaceId	SpaceId含义
IM群聊	IM_GROUP	openConversationId	会话id
IM机器人单聊	IM_ROBOT	userId/unionId	员工id
吊顶	ONE_BOX	openConversationId	会话id
协作	COOPERATON_FEED	userId/unionId	员工id
文档	DOC	docKey	文档key

权限

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

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

错误码

HttpCode	错误码	错误信息	说明
400	param.empty	param.empty	入参为空
400	param.outTrackIdEmpty	param.outTrackIdEmpty	业务标识outTrackId为空
400	param.openSpaceIdEmpty	param.openSpaceIdEmpty	投放openSpaceId为空
400	param.openDeliverModelEmpty	param.openDeliverModelEmpty	场域投放模型为空
400	param.spaceDeliverModelEmpty	param.spaceDeliverModelError	场域投放模型格式错误
400	param.openSpaceIdInvalid	param.openSpaceIdInvalid	openSpaceId不符合规范
400	param.cardNotExist	param.cardNotExist	卡片不存在
500	system.busy	system.busy	系统繁忙
500	system.busy	system.busy	系统繁忙

请求参数

Header 参数

Body 参数application/json

示例

{
  "outTrackId" : "String",
  "openSpaceId" : "String",
  "imRobotOpenDeliverModel" : {
    "spaceType" : "String"
  },
  "imGroupOpenDeliverModel" : {
    "robotCode" : "String",
    "atUserIds" : {
      "key" : "String"
    },
    "recipients" : [ "String" ]
  },
  "topOpenDeliverModel" : {
    "expiredTimeMillis" : Long,
    "userIds" : [ "String" ],
    "platforms" : [ "String" ]
  },
  "coFeedOpenDeliverModel" : {
    "bizTag" : "String",
    "gmtTimeLine" : Long
  },
  "docOpenDeliverModel" : {
    "userId" : "String"
  },
  "userIdType" : Integer
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST '/v1.0/card/instances/deliver' \
--header 'x-acs-dingtalk-access-token;' \
--header 'Content-Type: application/json' \
--data-raw '{
  "outTrackId" : "String",
  "openSpaceId" : "String",
  "imRobotOpenDeliverModel" : {
    "spaceType" : "String"
  },
  "imGroupOpenDeliverModel" : {
    "robotCode" : "String",
    "atUserIds" : {
      "key" : "String"
    },
    "recipients" : [ "String" ]
  },
  "topOpenDeliverModel" : {
    "expiredTimeMillis" : Long,
    "userIds" : [ "String" ],
    "platforms" : [ "String" ]
  },
  "coFeedOpenDeliverModel" : {
    "bizTag" : "String",
    "gmtTimeLine" : Long
  },
  "docOpenDeliverModel" : {
    "userId" : "String"
  },
  "userIdType" : Integer
}'

返回响应

🟢200成功

application/json

Body

示例

{
    "success": true,
    "result": [
        {
            "spaceType": "string",
            "spaceId": "string",
            "success": true,
            "carrierId": "string",
            "errorMsg": "string"
        }
    ]
}

修改于 2025-09-08 06:28:05

创建卡片

更新卡片

投放卡片

接口功能介绍#

接口调用说明#

权限#

错误码#

请求参数

请求示例代码

返回响应

接口功能介绍

接口调用说明

权限

错误码