Back to Details

feishu-card

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Feishu Interactive Card

飞书交互卡片

Build, send, and handle callbacks for Feishu interactive message cards. Cards replace plain text messages for any communication that benefits from structured layout or user actions (buttons, selects).
构建、发送飞书交互消息卡片并处理其回调。对于任何受益于结构化布局或用户操作（按钮、选择器）的通信场景，卡片可替代纯文本消息。

When to Use

适用场景

  • Morning briefings (confirm/adjust/add task buttons)
  • Evening reviews (acknowledge/defer buttons)
  • Alert notifications (auto-fix/ignore/escalate buttons)
  • Skill test results (listen/retest/mark-stable buttons)
  • Any yes/no or multi-choice confirmation
  • Status updates that need acknowledgment
  • 晨间简报（确认/调整/新增任务按钮）
  • 晚间复盘（确认/延后按钮）
  • 告警通知（自动修复/忽略/升级按钮）
  • 技能测试结果（查看/重测/标记为稳定按钮）
  • 任何是/否或多选确认场景
  • 需要确认接收的状态更新

Sending a Card

发送卡片

API

API

POST /open-apis/im/v1/messages?receive_id_type=chat_id
json
{
  "receive_id": "<chat_id>",
  "msg_type": "interactive",
  "content": "<card_json_string>"
}
Critical: The 
content
field must be a JSON string (stringified JSON), not a raw object.
POST /open-apis/im/v1/messages?receive_id_type=chat_id
json
{
  "receive_id": "<chat_id>",
  "msg_type": "interactive",
  "content": "<card_json_string>"
}
重要提示：
content
字段必须是JSON字符串（序列化后的JSON），不能是原始对象。

Card Structure

卡片结构

json
{
  "config": { "wide_screen_mode": true },
  "header": {
    "title": { "tag": "plain_text", "content": "Card Title" },
    "template": "blue"
  },
  "elements": [
    { "tag": "div", "text": { "tag": "lark_md", "content": "**Bold** and `code` supported" } },
    { "tag": "hr" },
    { "tag": "action", "actions": [
      { "tag": "button", "text": { "tag": "plain_text", "content": "Confirm" }, "type": "primary", "value": { "action": "confirm" } },
      { "tag": "button", "text": { "tag": "plain_text", "content": "Adjust" }, "type": "default", "value": { "action": "adjust" } }
    ]}
  ]
}
json
{
  "config": { "wide_screen_mode": true },
  "header": {
    "title": { "tag": "plain_text", "content": "Card Title" },
    "template": "blue"
  },
  "elements": [
    { "tag": "div", "text": { "tag": "lark_md", "content": "**Bold** and `code` supported" } },
    { "tag": "hr" },
    { "tag": "action", "actions": [
      { "tag": "button", "text": { "tag": "plain_text", "content": "Confirm" }, "type": "primary", "value": { "action": "confirm" } },
      { "tag": "button", "text": { "tag": "plain_text", "content": "Adjust" }, "type": "default", "value": { "action": "adjust" } }
    ]}
  ]
}

Header Templates (Colors)

头部模板（颜色）

TemplateColorUse For
blue
BlueNormal briefings, info
green
GreenSuccess, completed
red
RedAlerts, failures
orange
OrangeWarnings, degraded
purple
PurpleSpecial, creative
turquoise
TealSkill/tech results
grey
GreyLow priority, FYI
模板颜色适用场景
blue
蓝色常规简报、信息通知
green
绿色成功、完成状态
red
红色告警、失败
orange
橙色警告、服务降级
purple
紫色特殊、创意类内容
turquoise
青绿色技能/技术结果
grey
灰色低优先级、仅供参考

Supported Elements

支持的元素

ElementTagPurpose
Rich text
div
+ 
lark_md
Markdown-like content
Divider
hr
Visual separator
Action buttons
action
+ 
button
Clickable actions
Select menu
action
+ 
select_static
Dropdown selection
Note/footer
note
Small gray footer text
Column set
column_set
Multi-column layout
Image
img
Inline image
元素标签用途
富文本
div
+ 
lark_md
类Markdown内容
分割线
hr
视觉分隔符
操作按钮
action
+ 
button
可点击操作
下拉选择菜单
action
+ 
select_static
下拉选择
备注/页脚
note
灰色小号页脚文本
多列布局
column_set
多栏布局
图片
img
行内图片

lark_md
Syntax

lark_md
语法

Feishu's 
lark_md
tag supports a subset of Markdown:
  • **bold**
    , 
    *italic*
    , 
    ~~strikethrough~~
  • [link text](url)
  • <at id=ou_xxx>name</at>
    for mentions
  • Newlines: use 
    \n
    within the string
飞书的
lark_md
标签支持Markdown的子集：
  • **bold**
    、
    *italic*
    、
    ~~strikethrough~~
  • [link text](url)
  • <at id=ou_xxx>name</at>
    用于@用户
  • 换行：字符串内使用
    \n

Card Templates

卡片模板

Morning Briefing Card

晨间简报卡片

See references/card-morning-briefing.json for the full template.
Structure:
  1. Header: date + greeting (template: blue)
  2. Section 1: Anomalies (red text if any, green "No anomalies" if clear)
  3. Section 2: Today's action queue (numbered list with priority tags)
  4. Section 3: Action buttons (Confirm / Adjust / Add Task)
  5. Footer: generation timestamp
完整模板见references/card-morning-briefing.json
结构：
  1. 头部：日期 + 问候（模板：蓝色）
  2. 第一部分：异常情况（如有则显示红色文本，无异常则显示绿色的"无异常"）
  3. 第二部分：今日待办队列（带优先级标签的有序列表）
  4. 第三部分：操作按钮（确认 / 调整 / 新增任务）
  5. 页脚：生成时间戳

Alert Card

告警卡片

See references/card-alert.json for the full template.
Structure:
  1. Header: alert type + service name (template: red)
  2. Body: What happened, impact assessment
  3. Action buttons (Auto-fix / Ignore / Escalate)
完整模板见references/card-alert.json
结构：
  1. 头部：告警类型 + 服务名称（模板：红色）
  2. 正文：事件描述、影响评估
  3. 操作按钮（自动修复 / 忽略 / 升级上报）

Skill Test Result Card

技能测试结果卡片

See references/card-skill-test.json for the full template.
Structure:
  1. Header: skill name + pass/fail (template: green/red)
  2. Body: Test metrics, pass count, details
  3. Action buttons (Retest / Mark Stable / Archive)
完整模板见references/card-skill-test.json
结构：
  1. 头部：技能名称 + 通过/失败（模板：绿色/红色）
  2. 正文：测试指标、通过数量、详情
  3. 操作按钮（重测 / 标记为稳定 / 归档）

Confirmation Card

确认卡片

Generic yes/no card. Use for any binary decision.
json
{
  "header": { "title": { "tag": "plain_text", "content": "Confirmation Required" }, "template": "orange" },
  "elements": [
    { "tag": "div", "text": { "tag": "lark_md", "content": "**Question**: Description of what needs confirming" } },
    { "tag": "action", "actions": [
      { "tag": "button", "text": { "tag": "plain_text", "content": "Yes, proceed" }, "type": "primary", "value": { "action": "confirm", "context": "unique_id" } },
      { "tag": "button", "text": { "tag": "plain_text", "content": "No, cancel" }, "type": "danger", "value": { "action": "cancel", "context": "unique_id" } }
    ]}
  ]
}
通用是/否卡片，适用于所有二元决策场景。
json
{
  "header": { "title": { "tag": "plain_text", "content": "Confirmation Required" }, "template": "orange" },
  "elements": [
    { "tag": "div", "text": { "tag": "lark_md", "content": "**Question**: Description of what needs confirming" } },
    { "tag": "action", "actions": [
      { "tag": "button", "text": { "tag": "plain_text", "content": "Yes, proceed" }, "type": "primary", "value": { "action": "confirm", "context": "unique_id" } },
      { "tag": "button", "text": { "tag": "plain_text", "content": "No, cancel" }, "type": "danger", "value": { "action": "cancel", "context": "unique_id" } }
    ]}
  ]
}

Handling Callbacks

处理回调

STATUS (2026-02-10): WebSocket currently does NOT subscribe to 
card.action.trigger
events. Buttons on cards are display-only for now. Use the text fallback approach below until card callback support is added.
状态（2026-02-10）：WebSocket当前暂未订阅
card.action.trigger
事件。目前卡片上的按钮仅用于展示。在卡片回调支持上线前，请使用下方的文本兜底方案。

Current Approach: Text Fallback

当前方案：文本兜底

Since card button clicks cannot be received yet:
  1. Include clear text instructions in the card footer: "Reply '确认' to confirm, '调整' to adjust, '加任务' to add"
  2. User replies with a text message → AI agent receives via 
    im.message.receive_v1
    (works today)
  3. Parse the text reply to determine the action
由于目前暂无法接收卡片按钮点击事件：
  1. 在卡片页脚添加清晰的文本指引："回复'确认'进行确认，回复'调整'进行调整，回复'加任务'新增任务"
  2. 用户回复文本消息 → AI agent通过
    im.message.receive_v1
    事件接收（当前已支持）
  3. 解析文本回复判断对应的操作

Future: Full Card Callbacks (when 
card.action.trigger
is supported)

未来方案：完整卡片回调（待
card.action.trigger
事件支持后启用）

When user clicks a button on a card, Feishu sends a callback event via WebSocket.
The callback arrives as a 
card.action.trigger
event containing:
  • action.value
    : The 
    value
    object from the button definition
  • operator.open_id
    : Who clicked
  • token
    : For response verification
Callback processing:
  1. Parse 
    action.value
    to determine what was clicked
  2. Execute the corresponding action (e.g., mark today-actions as confirmed)
  3. Update the original card to reflect the new state (e.g., change button to "Confirmed" checkmark)
  4. Optionally send a brief follow-up message
Use the 
PATCH /open-apis/im/v1/messages/:message_id
API to update the card content after a button click.
当用户点击卡片上的按钮时，飞书会通过WebSocket发送回调事件。
回调为
card.action.trigger
事件，包含：
  • action.value
    ：按钮定义中的
    value
    对象
  • operator.open_id
    ：点击用户的ID
  • token
    ：用于响应校验
回调处理流程：
  1. 解析
    action.value
    判断点击的按钮对应的操作
  2. 执行对应操作（例如将今日待办标记为已确认）
  3. 更新原始卡片以反映新状态（例如将按钮改为带对勾的"已确认"）
  4. 可选择发送简短的后续消息
使用
PATCH /open-apis/im/v1/messages/:message_id
API在按钮点击后更新卡片内容。

Best Practices

最佳实践

  • One primary action: Each card should have one obvious primary button (type: 
    primary
    ) and secondary options
  • Value context: Always include enough context in button 
    value
    to reconstruct what the button is about (e.g., date, task_id)
  • Concise content: Cards are for quick scanning. Keep text short. Use 
    lark_md
    formatting for emphasis.
  • No walls of text: If content is long, summarize in card and link to a Feishu doc for details
  • Template colors: Match the header color to the sentiment (red=alert, green=success, blue=info)
  • 单个主操作：每张卡片应设置1个明确的主按钮（类型：
    primary
    ）和其他次选项
  • 值上下文：始终在按钮的
    value
    中包含足够的上下文信息，以便明确按钮对应的操作对象（例如日期、任务ID）
  • 内容简洁：卡片用于快速浏览，文本尽量简短，使用
    lark_md
    格式突出重点
  • 避免大段文本：如果内容较长，在卡片中做摘要，链接到飞书文档查看详情
  • 模板颜色匹配：头部颜色需匹配消息属性（红色=告警，绿色=成功，蓝色=信息）

Dependencies

依赖

  • Feishu IM API (POST messages with 
    msg_type: interactive
    )
  • WebSocket connection (receives 
    card.action.trigger
    events)
  • See 
    FEISHU_API_HANDBOOK.md
    API #4 for interactive card details
  • 飞书IM API（发送
    msg_type: interactive
    类型的消息）
  • WebSocket连接（接收
    card.action.trigger
    事件）
  • 详见
    FEISHU_API_HANDBOOK.md
    API #4 了解交互卡片的详细说明

Integration Points

集成点

  • daily-briefing
    skill: Sends briefing as card instead of plain text
  • ops-rhythm
    skill: Evening review uses card format
  • n8n-ops
    skill: Alerts sent as red cards
  • skill-lab
    skill: Test results sent as cards
  • feishu-sync
    skill: Triggers sync after card confirmation
  • daily-briefing
    skill：以卡片而非纯文本形式发送简报
  • ops-rhythm
    skill：晚间复盘使用卡片格式
  • n8n-ops
    skill：告警以红色卡片形式发送
  • skill-lab
    skill：测试结果以卡片形式发送
  • feishu-sync
    skill：卡片确认后触发同步操作