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

POST /open-apis/im/v1/messages?receive_id_type=chat_id

{
  "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.

Card Structure

{
  "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)

Supported Elements

lark_md Syntax

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

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

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)

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)

Confirmation Card

Generic yes/no card. Use for any binary decision.

{
  "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.

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

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

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.

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)

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

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