Feishu Interactive Cards & Buttons Skill

Complete skill package for Hermes Agent to send interactive cards with buttons in Feishu.

Package Structure

feishu-buttons/
├── SKILL.md          # This documentation
├── src/              # Python source files
│   ├── approval.py   # Main approval workflow with buttons
│   ├── builder.py    # Card building utilities
│   └── cardkit.py   # Card sending helpers
└── scripts/         # Utility scripts (optional)

Installation

1. Copy this skill folder to your Hermes Agent's skills/social-media/ directory
2. The Python files in src/ should be accessible from your Hermes installation
3. Requires hermes_feishu_plugin to be installed for full functionality

Core Concepts

1. Interactive Card Format

Feishu interactive cards use a JSON structure:

{
  "config": {"wide_screen_mode": true},
  "header": {
    "title": {"content": "Title", "tag": "plain_text"},
    "template": "orange"
  },
  "elements": [
    {"tag": "markdown", "content": "Message content"},
    {
      "tag": "action",
      "actions": [
        {
          "tag": "button",
          "text": {"tag": "plain_text", "content": "Button Label"},
          "type": "primary",
          "value": {"action": "value", "data": "payload"}
        }
      ]
    }
  ]
}

2. Button Types

3. Action Value

The value field in a button is passed back when clicked:

"value": {
  "hermes_action": "approve_once",
  "approval_id": "123",
  "session_key": "session123",
  "chat_id": "chat123"
}

Usage Example

Send Approval Card

from src.approval import send_approval_card

card = {
    "config": {"wide_screen_mode": True},
    "header": {
        "title": {"content": "⚠️ Confirm Action", "tag": "plain_text"},
        "template": "orange"
    },
    "elements": [
        {"tag": "markdown", "content": "Do you want to proceed?"},
        {
            "tag": "action",
            "actions": [
                {"tag": "button", "text": {"tag": "plain_text", "content": "✅ Confirm"}, "type": "primary", "value": {"action": "confirm"}},
                {"tag": "button", "text": {"tag": "plain_text", "content": "❌ Cancel"}, "type": "danger", "value": {"action": "cancel"}}
            ]
        }
    ]
}

await adapter.send_card(chat_id, card)

Handle Button Callback

async def handle_callback(callback_data):
    action = callback_data.get("action")
    if action == "confirm":
        # Process confirmation
        pass
    elif action == "cancel":
        # Process cancellation
        pass

Source Files Reference

approval.py

Main implementation for approval workflow with buttons:

• send_exec_approval() - Send approval card with buttons
• handle_card_action() - Process button click callbacks
• update_approval_card() - Update card after action

builder.py

Card building utilities:

• build_streaming_pre_answer_card() - Build streaming response card
• build_complete_card() - Build final response card
• split_reasoning_text() - Extract reasoning from response

cardkit.py

Low-level card sending:

• send_interactive_card() - Send interactive card
• patch_interactive_card() - Update existing card

Dependencies

• Python 3.11+
• hermes_feishu_plugin (for Feishu adapter)
• json (standard library)
• asyncio (standard library)

Platform Notes

This skill is specifically designed for Feishu (Lark) platform. For other messaging platforms:

• Discord: Use Discord's component-based buttons
• Telegram: Use inline keyboards
• Slack: Use interactive buttons

Each platform has its own message format for interactive elements.