开放接口投放卡片实例

通过本文你将了解如何通过开放接口将一张卡片投放到不同的场域中。

说明

在投放卡片实例之前，确保已经完成如下的准备工作：

基本概念

使用卡片投放接口，可以通过一次调用，将同一个卡片实例，进行跨场域投放，目前已支持的场域包括IM群聊、IM机器人、吊顶、协作、文档。

对于一次投放，主要包括四个元素：卡片实例id（outTrackId）、统一投放id（openSpaceId）、卡片场域属性(openSpaceModel)、卡片投放属性（openDeliverModel），本文主要介绍这四个要素的含义及使用。

卡片实例 id

在创建卡片时，由开发者生成并作为入参，即为outTrackId，用于唯一标识一张卡片。在投放卡片时，使用卡片实例id唯一标识一张卡片。

开放场域 id

在卡片投放中，采用了场域和场域id的概念，根据场域及其场域id可以唯一标识某个场域（如某个群聊、某个人的协作tab等），目前支持的场域以及场域id的含义如下：

场域类型	场域类型	场域id	场域id含义
群聊	im_group	openConversationId	会话id
机器人单聊	im_robot	用户id(userId/unionId)	员工id
吊顶	one_box	openConversationId	会话id
协作	cooperation_feed	用户id(userId/unionId)	员工id
文档	doc	docKey	文档Key

说明

如果在调用创建群会话接口时没有保存OpenConversationId，可以通过调用获取群会话的OpenConversationId接口通过chatId获取OpenConversationId。

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

openSpaceId

在投放接口中，使用openSpaceId作为统一投放id，openSpaceId采用固定协议且支持版本升级，主要由版本、场域类型、场域id三部分内容组成。

一个openSpaceId包含多个场域id，并且可以在多次投放中复用，其具体协议内容可参见服务端API-投放卡片接口。

卡片场域属性

对于同一个卡片实例，在同一个场域下，有一些相同的属性（如IM群聊场域下的通知属性），在投放接口中将这些属性统一定义为卡片的场域属性，一个卡片实例在一个场域下拥有唯一的场域属性。

同时，卡片实例只有设置了某个场域属性，才能被投放至该场域。为卡片设置场域属性有两种方式：

在创建卡片时设置场域属性；

有些卡片在创建时没有设置某些场域的属性，开放接口为此提供了为卡片设置场域属性的接口，调用此接口即可为已经创建的卡片设置某个场域的属性，使其可被投放至该场域中，详情参见新增或者更新卡片的场域信息。

说明

投放卡片至文档，不需要设置相应的场域属性。

卡片投放属性

相对于卡片场域属性，在将卡片投放至某个场域时，有一些属性在每次投放中不相同（如IM群聊场域下的@人信息），在投放接口中将这些属性定义为卡片投放属性。

在每次投放时，如果想要将卡片投放至某个场域，需要传入对应场域的投放属性。

投放流程及示例

在了解了上述概念后，本文将以IM群聊、吊顶、协作三个场域的多场域投放为例，介绍投放卡片的流程及示例。其主要流程如下图：

调用服务端API-创建卡片接口，实现创建卡片实例并获取outTrackId。

若卡片未增加场域属性，则需要调用服务端API-新增或者更新卡片的场域信息接口为卡片配置场域属性。

HTTP

PUT /v1.0/card/instances/spaces HTTP/1.1
Host:api.dingtalk.com
x-acs-dingtalk-access-token:String
Content-Type:application/json

{
  "outTrackId" : "example_out_track_id",
  "imGroupOpenSpaceModel" : { // 群聊场域属性
    "supportForward" : false, // 是否支持转发
    "lastMessageI18n" : { // 消息lastMessage
      "ZH_CN": "卡片",
      "EN_US": "card"
    },
    "searchSupport" : { // 搜索属性
      "searchIcon" : "@lALPDgQ9q8hFhlHNAXzNAqI",
      "searchTypeName" : "{\"zh_CN\":\"示例\",\"zh_TW\":\"示例\",\"en_US\":\"Example\"}",
      "searchDesc" : "搜索描述示例"
    },
    "notification" : { // 通知属性
      "alertContent" : "你收到了一个卡片消息",
      "notificationOff" : false
    }
  },
  "topOpenSpaceModel" : { // 吊顶场域
    "spaceType" : "ONE_BOX"
  },
  "coFeedOpenSpaceModel" : { // 协作场域属性
    "title" : "示例卡片"
  }
}

获取要被投放的场域id，构造openSpaceId。

openSpaceId由三部分组成：协议版本、场域类型、场域id，当前版本的格式为：

dtv1.card://spaceType1.spaceId1;spaceType2.spaceId2

场域类型及场域id见开放场域 id 章节，格式为：

dtv1.card//im_group.example_open_conversation_id;one_box.example_open_conversation_id;cooperation_feed.example_user_id;doc.example_doc_key

具体openSpaceId示例：

dtv1.card//im_group.cidp4GhVCQ==;one_box.cidp4GhVCQ==;cooperation_feed.manager****67;doc.Me********z2

构造目标场域的投放模型，并统一调用服务端API-投放卡片接口，实现卡片投放。

HTTP

POST /v1.0/card/instances/deliver HTTP/1.1
Host:api.dingtalk.com
Content-Type:application/json

{
  "outTrackId" : "example_out_track_id",
  "openSpaceId" : "dtv1.card//cooperation_feed.example_user_id;.im_group.example_conversation;one_box.example_conversation",
  "userIdType" : 1,
  "imGroupOpenDeliverModel" : { // 群聊投放属性
    "robotCode" : "example_robot_code", // 机器人code
    "recipients" : ["example_user_id_1", "example_user_id_2"] // 消息接收者
  },
  "topOpenDeliverModel" : { // 吊顶投放属性
    "expiredTimeMills" : 1665473229000, // 吊顶过期时间,毫秒
    "userIds" : ["example_user_id_3", "example_user_id_4"], // 可以看到吊顶的用户
    "platforms" : ["android", "ios", "win", "mac"] // 可以看到吊顶的设备
  },
  "coFeedOpenDeliverModel" : { // 协作投放属性
    "bizTag" : "example_biz_tag", // 协作业务tag
    "gmtTimeLine" : 1665473229000 // 排序时间,毫秒
  },
  "docOpenDeliverModel" : { // 文档投放属性
    "userId" : "example_user_id" // 操作者id
  }
}

投放效果展示

如图展示了上述示例中，将同一张卡片投放到IM群聊、吊顶和协作中的效果。

开放接口投放卡片实例

基本概念#

卡片实例 id#

开放场域 id#

openSpaceId#

卡片场域属性#

卡片投放属性#

投放流程及示例#

投放效果展示#