feishu-notify

by alex098929

Install this Skill

curl -fsSL -o feishu-notify.zip https://skill.seembox.com/api/v1/skills/feishu-notify/download && unzip feishu-notify.zip

Download feishu-notify.zip

SKILL.md About

---
name: feishu-notify
description: This skill should be used when users need to send notifications to Feishu (Lark) via webhook. It supports multiple message types including text, rich text, interactive cards, and images. Users must configure webhook URLs in ~/.openclaw/skills/feishu-notify/config.json before using this skill.
---

# 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.

_meta.json Metadata

{
  "ownerId": "kn77aptqjfc246ehn3akjz7rxx8308jh",
  "publishedAt": 1773903819700,
  "slug": "feishu-notify",
  "version": "1.0.1"
}