# 创建应用消息流卡片
应用消息流卡片是飞书为应用提供的消息触达能力，让应用可以直接在消息流发送消息，重要消息能更快触达用户。
**注意事项**：**说明**：飞书客户端在 V7.6 及以上版本开始支持应用消息流卡片。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/im/v2/app_feed_card
HTTP Method | POST
接口频率限制 | [10 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 创建、更新、删除应用消息流卡片(im:app_feed_card:write)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
app_feed_card | open_app_feed_card | 否 | 应用消息卡片
biz_id | string | 否 | 业务 ID（非必填字段，开发者可自定义业务 ID 以方便管理数据；若不传入，则 API 响应体中会返回系统自动分配的业务 ID）
**示例值**："096e2927-40a6-41a3-9562-314d641d09ae"
**数据校验规则**：
- 长度范围：`0` ～ `200` 字符
title | string | 否 | 主标题（在用户界面中最多展示一行，自动省略超出部分的内容；不支持定义字号及颜色）
**示例值**："主标题"
**数据校验规则**：
- 长度范围：`0` ～ `60` 字符
avatar_key | string | 否 | 头像 key
**示例值**："v3_0041_007bca9f-67ba-4199-bf00-4031b12cf226"
**数据校验规则**：
- 长度范围：`0` ～ `100` 字符
preview | string | 否 | 预览信息（在用户界面中最多展示一行，自动省略超出部分的内容；支持多个字段拼接、特殊符号和 emoji；不支持定义字号及颜色）
**示例值**："预览信息"
**数据校验规则**：
- 长度范围：`0` ～ `120` 字符
status_label | open_feed_status_label | 否 | 状态标签（非必填字段，如未选择该字段，则默认展示卡片触达时间）
text | string | 是 | 标签文字
**示例值**："标签文字"
**数据校验规则**：
- 长度范围：`1` ～ `20` 字符
type | string | 是 | 标签类型
**示例值**："primary"
**可选值有**：
- primary：主类型
- secondary：次要类型
- success：成功类型
- danger：危险类型
**默认值**：`primary`
buttons | open_app_feed_card_buttons | 否 | 交互按钮（非必填字段，如未传入该字段，则不展示按钮；最多展示 2 个按钮）
buttons | open_app_feed_card_button\[\] | 是 | 按钮组合
**数据校验规则**：
- 长度范围：`0` ～ `2`
multi_url | open_app_feed_card_url | 否 | 跳转 URL（仅支持 https 协议）
url | string | 否 | 默认 URL
**示例值**："https://www.feishu.cn/"
**数据校验规则**：
- 最大长度：`700` 字符
android_url | string | 否 | Android 平台 URL
**示例值**："https://www.feishu.cn/"
**数据校验规则**：
- 最大长度：`700` 字符
ios_url | string | 否 | iOS 平台 URL
**示例值**："https://www.feishu.cn/"
**数据校验规则**：
- 最大长度：`700` 字符
pc_url | string | 否 | PC URL
**示例值**："https://www.feishu.cn/"
**数据校验规则**：
- 最大长度：`700` 字符
action_type | string | 是 | 交互类型（按钮交互方式可配置跳转 URL 页面，也可配置 webhook 回调）
**示例值**："url_page"
**可选值有**：
- url_page：URL 页面
- webhook：回调
text | open_app_feed_card_text | 是 | 文字
text | string | 是 | 文本
**示例值**："文本"
**数据校验规则**：
- 长度范围：`1` ～ `30` 字符
button_type | string | 否 | 按钮类型
**示例值**："default"
**可选值有**：
- default：默认
- primary：主要
- success：成功
**默认值**：`default`
action_map | map<string, string> | 否 | action 字典
**示例值**：{"foo": "bar"}
link | open_app_feed_link | 否 | 卡片整体跳转链接（创建时该参数为必填参数）
link | string | 否 | 链接
**注意**：仅支持 HTTPS 协议，以及网页应用或小程序的 Applink（会校验 appid 是否正确）。
**示例值**："https://www.feishu.cn/"
**数据校验规则**：
- 最大长度：`700` 字符
time_sensitive | boolean | 否 | 即时提醒状态（设置为 true 后，卡片在消息列表临时置顶；设置为 false，消息卡片不置顶）
**示例值**：false
**默认值**：`false`
notify | app_feed_notify | 否 | 通知设置，当前可设置通知是否关闭，为空时默认进行通知
close_notify | boolean | 否 | 是否关闭通知
**示例值**：true
**默认值**：`false`
custom_sound_text | string | 否 | 自定义语音播报文本内容（仅支持移动端）
**示例值**："您有新的订单"
**数据校验规则**：
- 最大长度：`20` 字符
with_custom_sound | boolean | 否 | 是否播报自定义语音（仅支持移动端；播报语音包暂不支持切换，默认为女声）
**示例值**：true
**默认值**：`false`
user_ids | string\[\] | 否 | 用户 ID 列表（ID 类型与 user_id_type 的取值一致。如果
是商店应用，因不支持获取用户 userID 权限，所以无法值使用 user_id 类型的用户 ID）
**示例值**：["ou_a0553eda9014c201e6969b478895c230"]
**数据校验规则**：
- 长度范围：`1` ～ `20`
### 请求体示例
```json
{
"app_feed_card": {
"biz_id": "096e2927-40a6-41a3-9562-314d641d09ae",
"title": "主标题",
"avatar_key": "v3_0041_007bca9f-67ba-4199-bf00-4031b12cf226",
"preview": "预览信息",
"status_label": {
"text": "标签文字",
"type": "primary"
},
"buttons": {
"buttons": [
{
"multi_url": {
"url": "https://www.feishu.cn/",
"android_url": "https://www.feishu.cn/",
"ios_url": "https://www.feishu.cn/",
"pc_url": "https://www.feishu.cn/"
},
"action_type": "url_page",
"text": {
"text": "文本"
},
"button_type": "default",
"action_map": {
"foo": "bar"
}
}
]
},
"link": {
"link": "https://www.feishu.cn/"
},
"time_sensitive": false,
"notify": {
"close_notify": true,
"custom_sound_text": "您有新的订单",
"with_custom_sound": true
}
},
"user_ids": [
"ou_a0553eda9014c201e6969b478895c230"
]
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
failed_cards | open_failed_user_app_feed_card_item\[\] | 失败的卡片
biz_id | string | 业务 ID
user_id | string | 用户 ID
reason | string | 原因
**可选值有**：
- 0：未知
- 1：无权限
- 2：未创建
- 3：频率限制
- 4：重复
biz_id | string | 卡片业务 ID
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"failed_cards": [
{
"biz_id": "bdf22389-87ec-4890-9eb6-78a7efaeecbb",
"user_id": "ou_88553eda9014c201e6969b478895c223",
"reason": "NOT_CREATED"
}
],
"biz_id": "b90ce43a-fca8-4f42-92f4-794bff206ee5"
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 230001 | param is invalid | 根据 error message 确定错误的字段及原因