人与人会话中机器人发送互动卡片
更新于 2023-02-20调用本接口实现人与人会话中机器人发送互动卡片。
接口功能介绍
调用本接口，开通实现发送互动卡片。具体示例如下图所示。
卡片特殊能力用法
-
循环组件用法：内容塞入
-
会话列表lastMessage显示：
- 什么是lastmessage
指的是在会话列表页面透出的消息
- 设置特殊key：
sys_lastMessageI18n。 - value值：
{\"zh_CN\":\"蚂蚁分工\",\"zh_TW\":\"螞蟻分工\",\"zh_HK\":\"螞蟻分工\",\"ja_JP\":\"アリの分業\",\"en_US\":\"Ant division of labor\"}" - 举例说明：
"cardData": { "cardParamMap": { "sys_lastMessageI18n": "{\"zh_CN\":\"蚂蚁分工\",\"zh_TW\":\"螞蟻分工\",\"zh_HK\":\"螞蟻分工\",\"ja_JP\":\"アリの分業\",\"en_US\":\"Ant division of labor\"}"}}
- 什么是lastmessage
指的是在会话列表页面透出的消息
权限
要调用此API，需要以下权限之一。
应用类型 | 是否支持 | 权限 | API Explorer调试 |
|---|---|---|---|
| 企业内部应用 | 支持 | chat相关接口的管理权限 | API Explorer |
| 第三方企业应用 | 支持 | chat相关接口的管理权限 | API Explorer |
| 第三方个人应用 | 暂不支持 | chat相关接口的管理权限 | 暂不支持 |
请求方法
Header参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
x-acs-dingtalk-access-token | String | 是 | 调用该接口的访问凭证。
|
Body参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
cardTemplateId | String | 是 | |
openConversationId | String | 否 | 会话ID。
|
receiverUserIdList | Array of String | 否 | 用户ID列表。 |
outTrackId | String | 是 | 唯一标示卡片的外部编码。 说明
是由开发者自己生成并作为入参传递给钉钉的，钉钉只在对应使用到outTrackId的场景，帮助开发者对TrackId进行记录。 |
robotCode | String | 否 | 机器人编码。
|
callbackRouteKey | String | 否 | 卡片回调时的路由Key，用于查询注册的callbackUrl。 说明
可以为空，不填写默认无需回调。 |
cardData | Object | 是 | 卡片模板内容。 |
cardParamMap | Map<String, String> | 否 | 卡片公有数据。 |
privateData | Map<String, Object> | 否 | 指定用户可见的按钮列表：
说明
对应receiverUserIdList、userIdType字段关于用户ID的值填写方式：
|
Object | 否 | 指定用户可见的按钮列表：
| |
cardParamMap | Map<String, String> | 否 | 卡片私有数据。 |
userIdType | Integer | 否 | 用户ID类型：
|
atOpenIds | Map<String, String> | 否 | 消息@人。格式：
说明
如果key、value都为**@ALL**则判断@所有人。 |
cardOptions | Object | 否 | 卡片属性。 |
supportForward | Boolean | 否 | 是否支持转发：
|
pullStrategy | Boolean | 否 | 是否开启卡片纯拉模式：
|
返回参数
名称 | 类型 | 描述 |
|---|---|---|
success | Boolean | 接口调用是否成功。 |
result | Object | 创建卡片结果。 |
processQueryKey | String | 用于业务方后续查看已读列表的查询key。 |
示例
请求示例
返回示例
错误码
HttpCode | 错误码 | 错误信息 | 说明 |
|---|---|---|---|
400 | param.empty | 入参为空 | 入参为空 |
400 | callbackUrl.empty | 回调地址为空 | 回调地址为空 |
400 | param.invalid | 无效参数 | 无效参数 |
400 | permission.checkFailed | 发送动态卡片权限校验失败 | 发送动态卡片权限校验失败 |
400 | queryChatbot.wrong | 查询机器人失败 | 查询机器人失败 |
400 | cardInstance.wrong | 创建卡片实例失败，先检查卡片模板是否已发布 | 创建卡片实例失败，先检查卡片模板是否已发布 |
400 | cidParse.wrong | 单聊会话ID解码失败 | 单聊会话ID解码失败 |
400 | card.templateEmpty | 卡片模板ID为空 | 卡片模板ID为空 |
400 | userInfo.convertError | 消息接收者UID解码错误 | 消息接收者UID解码错误 |
400 | card.outTraceIdError | 卡片业务标识信息格式非法 | 卡片业务标识信息格式非法 |
400 | card.outTraceIdEmpty | 业务标识outTrackId为空 | 业务标识outTrackId为空 |
400 | chatbot.notFound | 机器人不存在 | 机器人不存在 |
400 | invalidParameter.cid.empty | 单聊会话id为空 | 单聊会话id为空 |
400 | sendCardMessageFailed | 发送卡片失败 | 发送卡片失败 |
400 | duplicateKey | 卡片模板占位符有重复Key | 卡片模板占位符有重复Key |
400 | getPictureFailed | 获取图片url失败 | 获取图片url失败 |
400 | org.notOwn.group | 单聊会话不属于当前企业 | 单聊会话不属于当前企业 |
400 | send.oa.timeout | 发工作通知超时，请稍后重试 | 发工作通知超时，请稍后重试 |
400 | outTrackId.exceed.limit | outTrackId长度超限 | outTrackId长度超限 |
500 | systemBusy | 系统繁忙 | 系统异常错误 |
500 | systemError | 系统错误 | 系统错误 |
