Feishu Notify Skill#

This skill enables sending notifications to Feishu (Lark) using webhook URLs. It supports various message types including text messages, rich text posts, interactive cards, and images.

Configuration Requirements#

IMPORTANT: Before using this skill, you must configure your Feishu webhook URLs:

Create the configuration file at ~/.openclaw/skills/feishu-notify/config.json with the following content:

json

{
  "webhooks": {
    "default": "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-url",
    "alerts": "https://open.feishu.cn/open-apis/bot/v2/hook/your-alerts-webhook-url",
    "notifications": "https://open.feishu.cn/open-apis/bot/v2/hook/your-notifications-webhook-url"
  }
}

Configuration Structure#

• default: Default webhook URL used when no specific webhook is specified
• alerts: Webhook URL for alert messages
• notifications: Webhook URL for general notifications
• custom: You can add as many custom webhooks as needed (e.g., "devops", "finance", "marketing")

Configuration Priority#

The skill loads configuration from:

• User's config.json at ~/.openclaw/skills/feishu-notify/config.json (only source)

When to Use This Skill#

Activate this skill when:

• Users want to send notifications to Feishu groups
• Users need to send alerts or notifications to Feishu
• Users mention "send to Feishu", "notify Feishu", or "message Feishu"
• Users want to send different types of messages (text, card, image) to Feishu

Skill Components#

Scripts#

The scripts/send_message.py script provides a reliable way to send messages to Feishu via webhook. This script:

• Loads webhook URLs from user's config.json file
• Supports multiple message types (text, post, interactive, image)
• Handles message templates from templates directory (with security restrictions)
• Provides error handling and response validation

Templates#

The templates/ directory contains message templates for different scenarios:

• text_simple.json: Simple text message template
• post_rich.json: Rich text (post) message template
• card_alert.json: Interactive card for alerts
• card_notification.json: Interactive card for notifications
• card_task.json: Interactive card for task updates

References#

The references/api_documentation.md contains documentation about Feishu webhook API, including:

• Webhook authentication and format
• Supported message types and structures
• Message template specifications
• Error handling and response codes

Workflow#

When this skill is activated:

1. Check configuration - Verify that ~/.openclaw/skills/feishu-notify/config.json exists and contains valid webhook URLs. If not, prompt user to configure it.

2. Determine message type based on user's request:

   • Text message: For simple text notifications
   • Post (Rich text): For formatted messages with elements
   • Interactive card: For rich cards with buttons, images, and structured content
   • Image message: For sending image URLs

3. Select webhook based on context:

   • Use "default" if no specific webhook is mentioned
   • Use named webhooks (e.g., "alerts", "notifications") if specified
   • Use custom webhooks if provided by name

4. Build or load message:

   • Use a predefined template from templates directory
   • Or build a custom message based on user's content
   • Fill in template variables with user-provided data

5. Send message using webhook URL:

   • Run scripts/send_message.py with webhook name and message type
   • The script loads appropriate webhook URL from config.json
   • Returns delivery status and response

6. Present results to user:

   • Confirm message delivery status
   • Display any errors if delivery failed
   • Provide feedback on what was sent

Important Notes#

• Feishu webhooks use POST method with JSON body

• Each webhook URL is specific to a Feishu group/chat

• Message types include: "text", "post", "interactive", "image"

• Webhook URLs are secrets and should be kept secure

  • Never commit config.json to version control
  • Set file permissions to restrict access (chmod 600 on Unix/Linux)
  • Treat webhook URLs like API keys

• Message size limit: 200KB for most message types

• Interactive cards support buttons, images, markdown, and more

• The script validates the response from Feishu API

• Template loading is restricted to the templates/ directory for security

• The agent can call this skill autonomously (messages may be sent without explicit confirmation)

Message Types#

1. Text Message#

Simple text-only messages.

json

{
  "msg_type": "text",
  "content": {
    "text": "Your message here"
  }
}

2. Post (Rich Text) Message#

Messages with rich formatting including text, links, @mentions, images, and more.

3. Interactive Card Message#

Rich cards with structured content, buttons, images, and interactive elements.

4. Image Message#

Messages with image URLs (image_key or image_url).

Example Interactions#

User: "Send a notification to Feishu: 'Deployment completed successfully'" Action: Use "default" webhook, send text message with provided text

User: "Send an alert to Feishu about server error: 'Connection timeout'" Action: Use "alerts" webhook, use card_alert template with error details

User: "Send a task update to Feishu: Task #123 completed by John" Action: Use "notifications" webhook, use card_task template with task information

User: "Send a rich message to devops webhook about deployment status" Action: Use "devops" webhook, use post_rich template with deployment details

User: "Notify the team about the meeting at 3 PM" Action: Use "default" webhook, send text message with meeting details

Error Handling#

If configuration is missing:

• Inform user that webhook URLs need to be configured
• Provide instructions on creating ~/.openclaw/skills/feishu-notify/config.json
• Show required JSON format
• Remind user to keep webhook URLs secret

If webhook is not found:

• Check if the specified webhook name exists in config
• Suggest using "default" webhook or adding the named webhook

If message sending fails:

• Check if the webhook URL is valid
• Verify network connectivity
• Display error message from Feishu API
• Suggest checking the webhook configuration

If template loading fails:

• Ensure the template file is within the templates/ directory
• For security reasons, arbitrary JSON files cannot be used as templates
• Use predefined templates or add new ones to the templates/ directory

Template Usage#

Templates are stored in the templates/ directory with JSON format. Each template includes:

• Message type definition
• Content structure with placeholders
• Variable replacement support

Security: For security reasons, template loading is restricted to the templates/ directory only. Arbitrary JSON files cannot be used as templates.

To use a template:

1. Select the appropriate template based on the message type
2. Replace placeholder variables with actual content
3. Send using the send_message.py script with the template path

Note: When adding custom templates, place them in the templates/ directory to ensure they can be loaded by the script.