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

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 or Lark Developer Console
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

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}" | openssl dgst -sha256 -hmac "" -binary | base64)

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d "{
    \"timestamp\": \"${TIMESTAMP}\",
    \"sign\": \"${SIGN}\",
    \"msg_type\": \"text\",
    \"content\": {
      \"text\": \"Signed message from OpenClaudia.\"
    }
  }"

Feishu signature algorithm details:

1. Concatenate timestamp + "\n" + secret as the string to sign
2. Compute HMAC-SHA256 with an empty key over that string
3. Base64-encode the result
4. Include both timestamp and sign in the request JSON body

2. Interactive Card Messages

Interactive cards are the most powerful message format. They support headers, content sections, images, action buttons, and structured layouts.

2.1 Basic Card Structure

{
  "msg_type": "interactive",
  "card": {
    "header": {
      "title": {
        "tag": "plain_text",
        "content": "Card Title Here"
      },
      "template": "blue"
    },
    "elements": []
  }
}

Header Color Templates

2.2 Card Elements Reference

Markdown Content Block:

{
  "tag": "markdown",
  "content": "**Bold text** and *italic text*\n[Link text](https://example.com)\nList:\n- Item 1\n- Item 2"
}

Divider:

{
  "tag": "hr"
}

Note (small gray footer text):

{
  "tag": "note",
  "elements": [
    {"tag": "plain_text", "content":