Feishu Lark

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

```bash
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

```bash
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:**

```bash
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.

```bash
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": "主要更新："}
            ],
            [