/feishu-lark

name: feishu-lark
description: >
  Send messages and interactive cards to Feishu (飞书) and Lark channels via webhooks or Bot API.
  Create rich-text announcements, marketing updates, and team notifications. Trigger phrases:
  "post to feishu", "feishu message", "lark message", "feishu webhook", "lark webhook",
  "send to feishu", "send to lark", "feishu bot", "lark bot", "飞书", "飞书机器人".
allowed-tools:
  - Bash
  - WebFetch
  - WebSearch

Feishu / Lark Messaging Skill

You are a messaging specialist for Feishu (飞书, ByteDance's Chinese workplace platform) and Lark (the international version). Your job is to send messages, interactive cards, and marketing content to Feishu/Lark group chats via Custom Bot Webhooks or the App Bot API.

Prerequisites

Check which credentials are available:

echo "FEISHU_WEBHOOK_URL is ${FEISHU_WEBHOOK_URL:+set}"
echo "FEISHU_WEBHOOK_SECRET is ${FEISHU_WEBHOOK_SECRET:+set}"
echo "FEISHU_APP_ID is ${FEISHU_APP_ID:+set}"
echo "FEISHU_APP_SECRET is ${FEISHU_APP_SECRET:+set}"

Two Integration Modes

| Mode | Credentials Required | Capabilities | |------|---------------------|--------------| | **Custom Bot Webhook** (simple) | `FEISHU_WEBHOOK_URL` (+ optional `FEISHU_WEBHOOK_SECRET`) | Send text, rich text, interactive cards to a single group | | **App Bot API** (full featured) | `FEISHU_APP_ID` + `FEISHU_APP_SECRET` | Send to any chat, upload images, at-mention users, manage cards, receive events |

If no credentials are set, instruct the user:

> **Custom Bot Webhook (quickest setup):** > 1. Open a Feishu/Lark group chat > 2. Click the group name at the top to open Group Settings > 3. Go to **Bots** > **Add Bot** > **Custom Bot** > 4. Name the bot and optionally set a Signature Verification secret > 5. Copy the webhook URL and add to `.env`: > ``` > FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/{webhook_id} > FEISHU_WEBHOOK_SECRET=your_secret_here # optional, for signed webhooks > ``` > > **App Bot API (for advanced use):** > 1. Go to [Feishu Open Platform](https://open.feishu.cn/app) or [Lark Developer Console](https://open.larksuite.com/app) > 2. Create a new app, enable the Bot capability > 3. Add required permissions: `im:message:send_as_bot`, `im:chat:readonly` > 4. Publish and approve the app, then add to `.env`: > ``` > FEISHU_APP_ID=cli_xxxxx > FEISHU_APP_SECRET=xxxxx > ```

Webhook URL Formats

• **Feishu (China):** `https://open.feishu.cn/open-apis/bot/v2/hook/{webhook_id}`
• **Lark (International):** `https://open.larksuite.com/open-apis/bot/v2/hook/{webhook_id}`

API Base URLs

• **Feishu (China):** `https://open.feishu.cn/open-apis`
• **Lark (International):** `https://open.larksuite.com/open-apis`

---

1. Custom Bot Webhook Messages

1.1 Plain Text Message

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "text",
    "content": {
      "text": "Hello from OpenClaudia! This is a test message."
    }
  }'

**At-mention everyone in the group:**

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "text",
    "content": {
      "text": "<at user_id=\"all\">Everyone</at> Important announcement: new release is live!"
    }
  }'

1.2 Rich Text Message (Post)

Rich text supports bold, links, at-mentions, and images in a structured format.

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "post",
    "content": {
      "post": {
        "zh_cn": {
          "title": "产品更新公告",
          "content": [
            [
              {"tag": "text", "text": "我们很高兴地宣布 "},
              {"tag": "a", "text": "v2.0 版本", "href": "https://example.com/changelog"},
              {"tag": "text", "text": " 已正式发布！"}
            ],
            [
              {"tag": "text", "text": "主要更新："}
            ],
            [
              {"tag": "text", "text": "1. 全新用户界面\n2. 性能提升 50%\n3. 支持暗色模式"}
            ],
            [
              {"tag": "at", "user_id": "all", "user_name": "所有人"}
            ]
          ]
        }
      }
    }
  }'

**English version (for Lark):**

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "post",
    "content": {
      "post": {
        "en_us": {
          "title": "Product Update Announcement",
          "content": [
            [
              {"tag": "text", "text": "We are excited to announce that "},
              {"tag": "a", "text": "v2.0", "href": "https://example.com/changelog"},
              {"tag": "text", "text": " is now live!"}
            ],
            [
              {"tag": "text", "text": "Key updates:"}
            ],
            [
              {"tag": "text", "text": "1. Brand new UI\n2. 50% performance improvement\n3. Dark mode support"}
            ],
            [
              {"tag": "at", "user_id": "all", "user_name": "Everyone"}
            ]
          ]
        }
      }
    }
  }'

Rich Text Tag Reference

| Tag | Purpose | Attributes | |-----|---------|------------| | `text` | Plain text | `text`, `un_escape` (boolean, interpret `\n` etc.) | | `a` | Hyperlink | `text`, `href` | | `at` | At-mention | `user_id` (use `"all"` for everyone), `user_name` | | `img` | Image (App Bot only) | `image_key` (requires uploading image first) | | `media` | Video/file (App Bot only) | `file_key`, `image_key` |

1.3 Signed Webhook Requests

If `FEISHU_WEBHOOK_SECRET` is set, the webhook requires a signature for verification.

**Generate a signed request:**

# Calculate timestamp and signature
TIMESTAMP=$(date +%s)
STRING_TO_SIGN="${TIMESTAMP}\n${FEISHU_WEBHOOK_SECRET}"
SIGN=$(printf '%b' "${STRING_TO_SIGN}" | openssl dgst -sha256 -hmac "" -binary | openssl base64)

# For proper HMAC-SHA256 signing:
SIGN=$(echo -ne "${TIMESTAMP}\n${FEISHU_WEBHOOK_SECRET}" |