Feishu Card

Send visually rich interactive card messages to Feishu chats via Open API.

When to Use

• Sending formatted content to Feishu groups or DMs (reports, summaries, tutorials, alerts)
• Any message where plain text formatting is insufficient
• Do NOT use for simple one-line replies — use normal message tool instead

Quick Start

1. Build a card JSON object following Schema 2.0 structure
2. Send it using the bundled scripts/send_card.py

# From card JSON file
python3 scripts/send_card.py --chat-id oc_xxx --card-file card.json

# From inline JSON string
python3 scripts/send_card.py --chat-id oc_xxx --card '{"schema":"2.0",...}'

# From stdin (useful for piping generated JSON)
echo '{"schema":"2.0",...}' | python3 scripts/send_card.py --chat-id oc_xxx --stdin

The script auto-reads credentials from ~/.openclaw/openclaw.json (feishu.appId / appSecret). Override with FEISHU_APP_ID and FEISHU_APP_SECRET env vars.

Card Structure (Minimal)

{
  "schema": "2.0",
  "config": {"wide_screen_mode": true},
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "Title"}
  },
  "body": {
    "elements": [
      {"tag": "markdown", "content": "**Hello** world"}
    ]
  }
}

Available Elements

Header colors: blue, wathet, turquoise, green, yellow, orange, red, carmine, violet, purple, indigo, grey

Critical Rules

1. content must be double-serialized — json.dumps(card) produces a string, which goes into the API payload's content field
2. Schema 2.0 does NOT support note tag — use markdown italic instead
3. No @mentions in cards — use normal messages for @
4. Always use Python for sending — avoid shell + nested JSON escaping
5. Markdown subset is limited — no tables, no HTML, no headings (use bold instead)

References

• Schema details & all element types: See references/card-schema.md
• Ready-to-use templates (notification, report, tutorial, alert): See references/templates.md

Workflow for Building a Card

1. Pick a template from references/templates.md or start from the minimal structure above
2. Customize header (color, title, subtitle) and body elements
3. Write the card JSON to a temp file or construct in Python
4. Send using scripts/send_card.py
5. Verify in Feishu that rendering is correct

Common Patterns

Generate card in Python and send via stdin:

import json, subprocess
card = {"schema": "2.0", "header": {...}, "body": {...}}
proc = subprocess.run(
    ["python3", "scripts/send_card.py", "--chat-id", "oc_xxx", "--stdin"],
    input=json.dumps(card), text=True, capture_output=True
)
print(proc.stdout)

Inline card construction for Agent use:

import json
card = {
    "schema": "2.0",
    "config": {"wide_screen_mode": True},
    "header": {"template": "blue", "title": {"tag": "plain_text", "content": title}},
    "body": {"elements": elements}
}
# Write to /tmp/card.json, then call send_card.py