投放卡片新版SDK
更新于 2024-04-23
接口功能介绍
调用本接口实现多个指定场域的卡片投放。具体展示如下图：
目前支持将卡片投放至以下场域：IM群聊、IM单聊酷应用、IM机器人单聊、吊顶、协作、文档。
接口调用说明
在将卡片投放到不同的场域时，使用outTrackId唯一标识一张卡片，通过openSpaceId标识需要被投放的场域及其场域Id，通过openDeliverModels传入不同场域下的投放属性。
若需要被投放的卡片实例不支持该场域，需要先调用appendSpace接口增加该场域（将卡片投放至文档不需要）。
场域类型及其sapceId定义如下：
| 场域类型 | SpaceType | SpaceId | SpaceId含义 |
|---|---|---|---|
| IM群聊 | IM_GROUP | openConversationId | 会话id |
| IM单聊酷应用 | IM_SINGLE | 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 |
| 第三方个人应用 | 暂不支持 | 互动卡片实例写权限 | 暂不支持 |
请求方法
Header参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
x-acs-dingtalk-access-token | String | 是 | 调用该接口的访问凭证。
|
Body参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
outTrackId | String | 是 | 外部卡片实例Id。 说明
|
openSpaceId | String | 是 | 表示场域及其场域id，其格式为 |
imSingleOpenDeliverModel | Object | 否 | 单聊场域投放参数。 |
atUserIds | Map<String, String> | 否 | 消息@人。格式：{"key":"value"}。
说明
如果key、value都为"@ALL"则判断@所有人。 示例： Loading... |
extension | Map<String, String> | 否 | 扩展字段，示例如下： Loading... |
imRobotOpenDeliverModel | Object | 否 | IM机器人单聊投放参数。 说明
机器人与人的单聊，直接用支持机器人单聊的应用来发送。 |
spaceType | String | 否 | IM机器人单聊若未设置其他投放属性，需设置spaeType为 |
extension | Map<String, String> | 否 | 扩展字段，示例如下： Loading... |
robotCode | String | 否 | 机器人编码。 |
imGroupOpenDeliverModel | Object | 否 | 群聊投放参数。 |
robotCode | String | 否 | 用于发送卡片的机器人编码。
说明
若使用 |
atUserIds | Map<String, String> | 否 | 消息@人。格式：{"key":"value"}。
说明
如果key、value都为"@ALL"则判断@所有人。 示例： Loading... |
recipients | Array of String | 否 | 指定接收者的userId。 |
extension | Map<String, String> | 否 | 扩展字段，示例如下： Loading... |
topOpenDeliverModel | Object | 否 | 吊顶投放参数。 |
expiredTimeMillis | Long | 否 | 过期时间戳。 说明
若使用 |
userIds | Array of String | 否 | 可以查看该吊顶卡片的userId。 |
platforms | Array of String | 否 | 可以查看该吊顶卡片的设备，包含 Loading... 说明
若为空，则所有设备可见 |
coFeedOpenDeliverModel | Object | 否 | 协作投放参数。 |
bizTag | String | 否 | 业务标识。 说明
|
gmtTimeLine | Long | 否 | 协作场域下的排序时间。 说明
若使用 |
docOpenDeliverModel | Object | 否 | 文档投放参数 |
userId | String | 否 | 员工userId信息。 说明
若使用 |
userIdType | Integer | 否 | 用户id类型：
说明
|
返回参数
名称 | 类型 | 描述 |
|---|---|---|
success | Boolean | 调用结果。 |
result | Array | 投放结果列表。 |
spaceType | String | 场域类型 ：
|
spaceId | String | 场域Id。 |
success | Boolean | 投放成功。 |
carrierId | String | 投放结果id。 说明
IM场域返processQueryKey，用于业务后续查看消息已读列表，其他场域暂不返回。 |
errorMsg | String | 场域投放错误信息。 |
示例
请求示例
返回示例
错误码
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 | 系统繁忙 |
