飞书交互卡片
构建、发送和处理飞书交互卡片。
使用场景: 晨报确认、告警处理、任务确认、状态更新
发送卡片
POST /open-apis/im/v1/messages?receive_id_type=chat_id
{
"receive_id": "<chat_id>",
"msg_type": "interactive",
"content": "<card_json_string>"
}
⚠️ content 必须是字符串化的 JSON。
卡片结构
{
"config": {"wide_screen_mode": true},
"header": {
"title": {"tag": "plain_text", "content": "标题"},
"template": "blue"
},
"elements": [
{"tag": "div", "text": {"tag": "lark_md", "content": "**加粗**"}},
{"tag": "action", "actions": [
{"tag": "button", "text": {"tag": "plain_text", "content": "确认"}, "type": "primary", "value": {"action": "confirm"}}
]}
]
}
常用元素
| 元素 | 说明 | 示例 |
|---|---|---|
div | 文本块 | {"tag":"div","text":{"tag":"lark_md","content":"文本"}} |
hr | 分割线 | {"tag":"hr"} |
action | 按钮组 | 见下方 |
note | 备注 | {"tag":"note","elements":[{"tag":"plain_text","content":"备注"}]} |
按钮
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {"tag": "plain_text", "content": "确认"},
"type": "primary",
"value": {"action": "confirm", "data": "extra_info"}
}
]
}
按钮类型: default / primary / danger
选择器
{
"tag": "select_static",
"placeholder": {"tag": "plain_text", "content": "请选择"},
"options": [
{"text": {"tag": "plain_text", "content": "选项1"}, "value": "opt1"},
{"text": {"tag": "plain_text", "content": "选项2"}, "value": "opt2"}
],
"value": {"key": "select_result"}
}
回调处理
用户点击按钮后，飞书会发送 WebSocket 事件：
{
"type": "card.action.trigger",
"action": {
"value": {"action": "confirm", "data": "extra_info"}
}
}
处理回调后可更新卡片：
PATCH /open-apis/im/v1/messages/{message_id}
最佳实践
- 按钮带 value（用于回调识别）
- 卡片更新代替新消息（减少刷屏）
- 危险操作用 danger 类型