机器人发送互动卡片（普通版）

POST

/v1.0/im/v1.0/robot/interactiveCards/send

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

本文档介绍了机器人发送互动卡片（普通版）。

接口功能介绍

通过应用机器人发送普通版互动卡片消息，相比于高级版，普通版通过内置卡片模板，减少卡片模板构建过程，以提升开发效率，更多详情参见互动卡片普通版。

桌面端

移动端

权限

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

应用类型	是否支持	权限	API Explorer调试
企业内部应用	支持	企业内机器人发送消息权限	API Explorer
第三方企业应用	支持	企业内机器人发送消息权限	API Explorer
第三方个人应用	暂不支持	企业内机器人发送消息权限	暂不支持

错误码

HttpCode	错误码	错误信息	说明
400	system.error	未知的系统错误	未知的系统错误
400	param.error	参数无效	参数无效
400	param.isNotJson	参数必须是json	参数必须是json
400	invalid.user	无效的用户ID	无效的用户ID
400	invalid.openConversationId	无效的openConversationId	无效的openConversationId
400	invalid.robotCode	无效的机器人标识	无效的机器人标识
400	template.isNotExist	模板不存在	模板不存在
400	create.cardInstance.failed	创建互动卡片实例失败	创建互动卡片实例失败
400	send.cardMsg.failed	发送互动卡片消息失败	发送互动卡片消息失败
400	invalid.bizId	互动卡片BIZID无效	互动卡片BIZID无效
400	cardInstance.notExist	互动卡片实例不存在	互动卡片实例不存在
400	cardMessage.sendFailed	发送互动卡片消息失败	发送互动卡片消息失败

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.dingtalk.com/v1.0/im/v1.0/robot/interactiveCards/send' \
--header 'x-acs-dingtalk-access-token;' \
--header 'Content-Type: application/json' \
--data-raw '{
  "cardTemplateId" : "String",
  "openConversationId" : "String",
  "singleChatReceiver" : "String",
  "cardBizId" : "String",
  "robotCode" : "String",
  "callbackUrl" : "String",
  "cardData" : "String",
  "userIdPrivateDataMap" : "String",
  "unionIdPrivateDataMap" : "String",
  "sendOptions" : {
    "atUserListJson" : "String",
    "atAll" : Boolean,
    "receiverListJson" : "String",
    "cardPropertyJson" : "String"
  },
  "pullStrategy" : Boolean
}'

响应示例

{
  "processQueryKey": "string"
}

请求参数

Header 参数

x-acs-dingtalk-access-token

string

必需

调用该接口的访问凭证。

企业内部应用，调用获取企业内部应用的accessToken接口获取。

第三方企业应用，调用获取第三方应用授权企业的accessToken接口获取。

Body 参数application/json

cardTemplateId

string

必需

卡片搭建平台模板ID，固定值填写为StandardCard。

openConversationId

string

可选

接收卡片的加密群ID，特指多人群会话（非单聊）。说明基于群模板创建的群企业内部应用，详情参见创建群。第三方企业应用，详情参见创建群。安装群聊酷应用的群。企业内部应用，详情参见群聊酷应用。第三方企业应用，详情参见酷应用。 openConversationId和singleChatReceiver 二选一必填。

singleChatReceiver

string

可选

单聊会话接收者json串。说明 openConversationId和singleChatReceiver 二选一必填。

cardBizId

string

必需

唯一标识一张卡片的外部ID，卡片幂等ID，可用于更新或重复发送同一卡片到多个群会话。说明最长不超过100字符，建议长度在64字符以内。一般情况下，如果使用了新的 cardTemplateId 或 cardData 等参数，则需要生成一个全新的 outTrackId，否则更改不会生效。

robotCode

string

必需

机器人的编码。企业内部应用，参见机器人名词表-robotCode内容，获取robotCode。第三方企业应用，参见机器人名词表-robotCode内容，获取robotCode。

callbackUrl

string

可选

可控制卡片回调的URL，不填则无需回调。

cardData

string

必需

卡片模板文本内容参数，卡片json结构体。

userIdPrivateDataMap

string

可选

卡片模板userId差异用户参数，json结构体。

unionIdPrivateDataMap

string

可选

卡片模板unionId差异用户参数，json结构体。

sendOptions

object

互动卡片发送选项。

可选

atUserListJson

string

可选

消息@人，最大@人员人数为30。 JSON格式如下： [ { "nickName": "张三", "userId": "userId0001" }, { "nickName": "李四", "unionId": "unionId001" } ]

receiverListJson

string

可选

消息仅部分人可见的接收人列表。说明为空时则群所有人可见。 JSON格式： [ { "userId": "userId0001" }, { "unionId": "unionId001" } ]

cardPropertyJson

string

可选

卡片特殊属性json字符串。

示例

返回响应

🟢200成功

application/json

Body

processQueryKey

string

必需

用于业务方后续查看已读列表的查询key。

修改于 2024-01-09 10:20:57

自定义机器人发送群消息

更新机器人发送互动卡片（普通版）

机器人发送互动卡片（普通版）

接口功能介绍#

权限#

错误码#

请求参数

返回响应

接口功能介绍

权限

错误码