feishu-interactive-cards（飞书互动卡）

Feishu Interactive Cards

Core Principle

When replying to Feishu and there is ANY uncertainty: send an interactive card instead of plain text.

Interactive cards let users respond via buttons rather than typing, making interactions faster and clearer.

When to Use

Must use interactive cards:

• User needs to make a choice (yes/no, multiple options)
• Confirmation required before action
• Displaying todos or task lists
• Creating polls or surveys
• Collecting form input
• Any uncertain situation

Plain text is OK:

• Simple notifications (no response needed)
• Pure data display (no interaction)
• Confirmed command results

Example:

• Wrong: "I deleted the file for you" (direct execution)
• Right: Send card "Confirm delete file?" [Confirm] [Cancel]

Quick Start

1. Start Callback Server (Long-Polling Mode)

cd E:\openclaw\workspace\skills\feishu-interactive-cards\scripts
node card-callback-server.js

Features:

• Uses Feishu long-polling (no public IP needed)
• Auto-reconnects
• Sends callbacks to OpenClaw Gateway automatically

2. Send Interactive Card

# Confirmation card
node scripts/send-card.js confirmation "Confirm delete file?" --chat-id oc_xxx

# Todo list
node scripts/send-card.js todo --chat-id oc_xxx

# Poll
node scripts/send-card.js poll "Team activity" --options "Bowling,Movie,Dinner" --chat-id oc_xxx

# Custom card
node scripts/send-card.js custom --template examples/custom-card.json --chat-id oc_xxx

3. Use in Agent

When Agent needs to send Feishu messages:

// Wrong: Send plain text
await message({
  action: "send",
  channel: "feishu",
  message: "Confirm delete?"
});

// Right: Send interactive card
await exec({
  command: `node E:\\openclaw\\workspace\\skills\\feishu-interactive-cards\\scripts\\send-card.js confirmation "Confirm delete file test.txt?" --chat-id ${chatId}`
});

Card Templates

See examples/ directory for complete card templates:

• confirmation-card.json - Confirmation dialogs
• todo-card.json - Task lists with checkboxes
• poll-card.json - Polls and surveys
• form-card.json - Forms with input fields

For detailed card design patterns and best practices, see references/card-design-guide.md.

Callback Handling

Callback server automatically sends all card interactions to OpenClaw Gateway. For detailed integration guide, see references/gateway-integration.md.

Quick example:

// Handle confirmation
if (callback.data.action.value.action === "confirm") {
  const file = callback.data.action.value.file;

  // ⚠️ SECURITY: Validate and sanitize file path before use
  // Use OpenClaw's built-in file operations instead of shell commands
  const fs = require('fs').promises;
  const path = require('path');

  try {
    // Validate file path (prevent directory traversal)
    const safePath = path.resolve(file);
    if (!safePath.startsWith(process.cwd())) {
      throw new Error('Invalid file path');
    }

    // Use fs API instead of shell command
    await fs.unlink(safePath);

    // Update card
    await updateCard(callback.context.open_message_id, {
      header: { title: "Done", template: "green" },
      elements: [
        { tag: "div", text: { content: `File ${path.basename(safePath)} deleted`, tag: "lark_md" } }
      ]
    });
  } catch (error) {
    // Handle error
    await updateCard(callback.context.open_message_id, {
      header: { title: "Error", template: "red" },
      elements: [
        { tag: "div", text: { content: `Failed to delete file: ${error.message}`, tag: "lark_md" } }
      ]
    });
  }
}

Best Practices

Card Design

• Clear titles and content
• Obvious button actions
• Use danger type for destructive operations
• Carry complete state in button value to avoid extra queries

Interaction Flow

User request -> Agent decides -> Send card -> User clicks button
-> Callback server -> Gateway -> Agent handles -> Update card/execute

Error Handling

• Timeout: Send reminder if user doesn't respond
• Duplicate clicks: Built-in deduplication (3s window)
• Failures: Update card to show error message

Performance

• Async processing: Quick response, long tasks in background
• Batch operations: Combine related actions in one card

Configuration

Configure in ~/.openclaw/openclaw.json:

{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "YOUR_APP_ID",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  },
  "gateway": {
    "enabled": true,
    "port": 18789,
    "token": "YOUR_GATEWAY_TOKEN"
  }
}

Callback server reads config automatically.

Troubleshooting

Button clicks not working:

• Check callback server is running
• Verify Feishu backend uses "long-polling" mode
• Ensure card.action.trigger event is subscribed

Gateway not receiving callbacks:

• Start Gateway: E:\openclaw\workspace\scripts\gateway.cmd
• Check token in ~/.openclaw\openclaw.json

Card display issues:

• Use provided templates as base
• Validate JSON format
• Check required fields

Security

⚠️ CRITICAL: Never pass user input directly to shell commands!

This skill includes comprehensive security guidelines. Please read references/security-best-practices.md before implementing callback handlers.

Key security principles:

• Always validate and sanitize user input
• Use Node.js built-in APIs instead of shell commands
• Implement proper permission checks
• Prevent command injection vulnerabilities
• Use event_id for deduplication

References

• Security Best Practices - READ THIS FIRST!
• Feishu Card Documentation
• OpenClaw Docs