Feishu / Lark メッセージング スキル

Feishu (飞书、ByteDance の中国企業向けプラットフォーム) および Lark (国際版) のメッセージング専門家です。カスタム Bot ウェブフックまたはアプリ Bot API 経由で、Feishu/Lark グループチャットにメッセージ、インタラクティブカード、マーケティングコンテンツを送信することが仕事です。

前提条件

利用可能な認証情報を確認してください:

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}"

2 つの統合モード

モード	必要な認証情報	機能
カスタム Bot ウェブフック (シンプル)	FEISHU_WEBHOOK_URL (+ オプション: FEISHU_WEBHOOK_SECRET)	テキスト、リッチテキスト、インタラクティブカードを単一グループに送信
アプリ Bot API (フル機能)	FEISHU_APP_ID + FEISHU_APP_SECRET	任意のチャットに送信、画像アップロード、ユーザーへの @mention、カード管理、イベント受信

認証情報が設定されていない場合は、ユーザーに以下を指示してください:

カスタム Bot ウェブフック (最速セットアップ):

1. Feishu/Lark グループチャットを開く
2. 上部のグループ名をクリックしてグループ設定を開く
3. ボット > ボットを追加 > カスタムボット に進む
4. ボットに名前を付け、必要に応じて署名検証シークレットを設定
5. ウェブフック URL をコピーして .env に追加:

   FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/{webhook_id}
   FEISHU_WEBHOOK_SECRET=your_secret_here  # オプション、署名付きウェブフック用
   

アプリ Bot API (高度な使用例):

1. Feishu Open Platform または Lark Developer Console に移動
2. 新しいアプリを作成し、Bot 機能を有効化
3. 必要なパーミッション im:message:send_as_bot, im:chat:readonly を追加
4. アプリを公開・承認後、.env に追加:

   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   

ウェブフック URL フォーマット

• Feishu (中国): https://open.feishu.cn/open-apis/bot/v2/hook/{webhook_id}
• Lark (国際): https://open.larksuite.com/open-apis/bot/v2/hook/{webhook_id}

API ベース URL

• Feishu (中国): https://open.feishu.cn/open-apis
• Lark (国際): https://open.larksuite.com/open-apis

---

1. カスタム Bot ウェブフックメッセージ

1.1 プレーンテキストメッセージ

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."
    }
  }'

グループ内の全員に @mention:

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 リッチテキストメッセージ (ポスト)

リッチテキストは、太字、リンク、@mention、画像を構造化フォーマットでサポートします。

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": "所有人"}
            ]
          ]
        }
      }
    }
  }'

英語版 (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"}
            ]
          ]
        }
      }
    }
  }'

リッチテキスト タグ リファレンス

タグ	用途	属性
text	プレーンテキスト	text, un_escape (ブール値、\n など を解釈)
a	ハイパーリンク	text, href
at	@mention	user_id ("all" で全員に @mention), user_name
img	画像 (App Bot のみ)	image_key (事前にアップロード必要)
media	ビデオ/ファイル (App Bot のみ)	file_key, image_key

1.3 署名付きウェブフックリクエスト

FEISHU_WEBHOOK_SECRET が設定されている場合、ウェブフックは署名検証を要求します。

署名付きリクエストを生成:

# タイムスタンプと署名を計算
TIMESTAMP=$(date +%s)
STRING_TO_SIGN="${TIMESTAMP}\n${FEISHU_WEBHOOK_SECRET}"
SIGN=$(printf '%b' "${STRING_TO_SIGN}" | openssl dgst -sha256 -hmac "" -binary | openssl base64)

# 適切な HMAC-SHA256 署名の場合:
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 署名アルゴリズムの詳細:

1. timestamp + "\n" + secret を署名対象の文字列として連結
2. その文字列に対して空のキーで HMAC-SHA256 を計算
3. 結果を Base64 エンコード
4. リクエスト JSON ボディに timestamp と sign の両方を含める

---

2. インタラクティブカードメッセージ

インタラクティブカードは最も強力なメッセージフォーマットです。ヘッダー、コンテンツセクション、画像、アクションボタン、構造化レイアウトをサポートします。

2.1 基本カード構造

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

ヘッダーカラーテンプレート

テンプレート	色	最適な用途
blue	青	一般情報、更新
green	緑	成功、ポジティブなニュース
red	赤	緊急、アラート、エラー
orange	オレンジ	警告、対応が必要
purple	紫	イベント、クリエイティブ
indigo	インディゴ	技術、エンジニアリング
turquoise	ターコイズ	成長、マーケティング
yellow	黄	ハイライト、ヒント
grey	グレー	ニュートラル、低優先度
wathet	ライトブルー	デフォルト、クリーン

2.2 カード要素リファレンス

Markdown コンテンツブロック:

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

区切り線:

{
  "tag": "hr"
}

注記 (小さいグレーのフッターテキスト):

{
  "tag": "note",
  "elements": [
    {"tag": "plain_text", "content": "Sent via OpenClaudia Marketing Toolkit"}
  ]
}

画像ブロック:

{
  "tag": "img",
  "img_key": "img_v2_xxx",
  "alt": {"tag": "plain_text", "content": "Image description"},
  "title": {"tag": "plain_text", "content": "Image Title"}
}

アクションボタン:

{
  "tag": "action",
  "actions": [
    {
      "tag": "button",
      "text": {"tag": "plain_text", "content": "View Details"},
      "type": "primary",
      "url": "https://example.com/details"
    },
    {
      "tag": "button",
      "text": {"tag": "plain_text", "content": "Dismiss"},
      "type": "default"
    }
  ]
}

ボタンタイプ: primary (青), danger (赤), default (グレー)

マルチカラムレイアウト:

{
  "tag": "column_set",
  "flex_mode": "bisect",
  "columns": [
    {
      "tag": "column",
      "width": "weighted",
      "weight": 1,
      "elements": [
        {"tag": "markdown", "content": "**Left Column**\nContent here"}
      ]
    },
    {
      "tag": "column",
      "width": "weighted",
      "weight": 1,
      "elements": [
        {"tag": "markdown", "content": "**Right Column**\nContent here"}
      ]
    }
  ]
}

2.3 完全なカード例: 製品発表

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "interactive",
    "card": {
      "header": {
        "title": {
          "tag": "plain_text",
          "content": "New Feature Launch: AI-Powered Analytics"
        },
        "template": "turquoise"
      },
      "elements": [
        {
          "tag": "markdown",
          "content": "We are thrilled to announce our latest feature!\n\n**AI-Powered Analytics** is now available to all Pro and Enterprise users.\n\nKey highlights:\n- **Smart Insights**: Automatic trend detection and anomaly alerts\n- **Natural Language Queries**: Ask questions in plain English\n- **Predictive Forecasting**: 90-day revenue and growth projections\n- **Custom Dashboards**: Drag-and-drop report builder"
        },
        {
          "tag": "hr"
        },
        {
          "tag": "markdown",
          "content": "**Availability:** Rolling out now, fully live by end of week\n**Documentation:** [View the guide](https://example.com/docs/analytics)\n**Feedback:** Reply in this thread or submit via [feedback form](https://example.com/feedback)"
        },
        {
          "tag": "action",
          "actions": [
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Try It Now"},
              "type": "primary",
              "url": "https://example.com/analytics"
            },
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Read Docs"},
              "type": "default",
              "url": "https://example.com/docs/analytics"
            }
          ]
        },
        {
          "tag": "note",
          "elements": [
            {"tag": "plain_text", "content": "Product Team | Released 2025-01-15"}
          ]
        }
      ]
    }
  }'

---

3. アプリ Bot API (フル機能)

アプリ Bot API には FEISHU_APP_ID と FEISHU_APP_SECRET が必要です。任意のチャットへの送信、画像アップロード、メッセージ管理など、フル機能のメッセージング機能を提供します。

3.1 テナント アクセストークンを取得

すべてのアプリ Bot API 呼び出しには tenant_access_token が必要です。トークンは 2 時間後に期限切れになります。

# Feishu (中国) の場合
FEISHU_API_BASE="https://open.feishu.cn/open-apis"

# Lark (国際) の場合
# FEISHU_API_BASE="https://open.larksuite.com/open-apis"

TENANT_TOKEN=$(curl -s -X POST "${FEISHU_API_BASE}/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{
    \"app_id\": \"${FEISHU_APP_ID}\",
    \"app_secret\": \"${FEISHU_APP_SECRET}\"
  }" | python3 -c "import json,sys; print(json.load(sys.stdin).get('tenant_access_token',''))")

echo "Token: ${TENANT_TOKEN:0:10}..."

3.2 ボットが属するチャットをリスト表示

curl -s "${FEISHU_API_BASE}/im/v1/chats?page_size=20" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
for chat in data.get('data', {}).get('items', []):
    print(f\"Chat ID: {chat['chat_id']}  |  Name: {chat.get('name', 'N/A')}  |  Type: {chat.get('chat_type', 'N/A')}\")
"

3.3 チャットにメッセージを送信

CHAT_ID="oc_xxxxx"  # 実際の chat_id に置き換え

# テキストメッセージを送信
curl -s -X POST "${FEISHU_API_BASE}/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"receive_id\": \"${CHAT_ID}\",
    \"msg_type\": \"text\",
    \"content\": \"{\\\"text\\\": \\\"Hello from the App Bot!\\\"}\"
  }"

API 経由でリッチテキストメッセージを送信:

curl -s -X POST "${FEISHU_API_BASE}/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"receive_id\": \"${CHAT_ID}\",
    \"msg_type\": \"post\",
    \"content\": $(python3 -c "
import json
content = {
    'zh_cn': {
        'title': 'App Bot 消息',
        'content': [
            [
                {'tag': 'text', 'text': '这是一条通过 App Bot API 发送的 '},
                {'tag': 'a', 'text': '富文本消息', 'href': 'https://example.com'},
                {'tag': 'text', 'text': '。'}
            ]
        ]
    }
}
print(json.dumps(json.dumps(content)))
")
  }"

API 経由でインタラクティブカードを送信:

curl -s -X POST "${FEISHU_API_BASE}/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"receive_id\": \"${CHAT_ID}\",
    \"msg_type\": \"interactive\",
    \"content\": $(python3 -c "
import json
card = {
    'header': {
        'title': {'tag': 'plain_text', 'content': 'Marketing Update'},
        'template': 'turquoise'
    },
    'elements': [
        {'tag': 'markdown', 'content': '**Campaign Performance This Week**\n\n- Impressions: **120,450** (+12%)\n- Clicks: **8,320** (+8%)\n- Conversions: **342** (+15%)\n- Cost per Conversion: **\$14.20** (-5%)'},
        {'tag': 'hr'},
        {'tag': 'action', 'actions': [
            {'tag': 'button', 'text': {'tag': 'plain_text', 'content': 'View Full Report'}, 'type': 'primary', 'url': 'https://example.com/report'}
        ]},
        {'tag': 'note', 'elements': [{'tag': 'plain_text', 'content': 'Auto-generated by OpenClaudia Marketing Toolkit'}]}
    ]
}
print(json.dumps(json.dumps(card)))
")
  }"

3.4 画像をアップロード

画像をアップロードして、カードとリッチテキストメッセージで使用するための image_key を取得します。

IMAGE_KEY=$(curl -s -X POST "${FEISHU_API_BASE}/im/v1/images" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" \
  -F "image_type=message" \
  -F "image=@/path/to/image.png" | python3 -c "import json,sys; print(json.load(sys.stdin).get('data',{}).get('image_key',''))")

echo "Image key: ${IMAGE_KEY}"

3.5 特定ユーザーに送信 (メールまたは user_id で)

# メール経由 (receive_id_type=email)
curl -s -X POST "${FEISHU_API_BASE}/im/v1/messages?receive_id_type=email" \
  -H "Authorization: Bearer ${TENANT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"receive_id\": \"user@company.com\",
    \"msg_type\": \"text\",
    \"content\": \"{\\\"text\\\": \\\"Direct message from the marketing bot.\\\"}\"
  }"

---

4. メッセージテンプレート

4.1 製品発表

send_product_announcement() {
  local TITLE="$1"
  local VERSION="$2"
  local FEATURES="$3"
  local DOCS_URL="$4"
  local CTA_URL="$5"

  curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
    -H "Content-Type: application/json" \
    -d "$(python3 -c "
import json
card = {
    'msg_type': 'interactive',
    'card': {
        'header': {
            'title': {'tag': 'plain_text', 'content': '${TITLE}'},
            'template': 'green'
        },
        'elements': [
            {'tag': 'markdown', 'content': '**Version ${VERSION}** is now available!\n\n${FEATURES}'},
            {'tag': 'hr'},
            {'tag': 'action', 'actions': [
                {'tag': 'button', 'text': {'tag': 'plain_text', 'content': 'Get Started'}, 'type': 'primary', 'url': '${CTA_URL}'},
                {'tag': 'button', 'text': {'tag': 'plain_text', 'content': 'Release Notes'}, 'type': 'default', 'url': '${DOCS_URL}'}
            ]},
            {'tag': 'note', 'elements': [{'tag': 'plain_text', 'content': 'Product Team | $(date +%Y-%m-%d)'}]}
        ]
    }
}
print(json.dumps(card))
")"
}

4.2 チーム更新 / 週間レポート

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "interactive",
    "card": {
      "header": {
        "title": {"tag": "plain_text", "content": "Weekly Marketing Report - W03 2025"},
        "template": "blue"
      },
      "elements": [
        {
          "tag": "column_set",
          "flex_mode": "bisect",
          "columns": [
            {
              "tag": "column",
              "width": "weighted",
              "weight": 1,
              "elements": [
                {"tag": "markdown", "content": "**Traffic**\n\nSessions: **45,230**\nUnique Visitors: **32,100**\nBounce Rate: **42%**"}
              ]
            },
            {
              "tag": "column",
              "width": "weighted",
              "weight": 1,
              "elements": [
                {"tag": "markdown", "content": "**Conversions**\n\nSignups: **580**\nTrials: **120**\nPaid: **34**"}
              ]
            }
          ]
        },
        {"tag": "hr"},
        {
          "tag": "markdown",
          "content": "**Top Performing Content:**\n1. \"10 Tips for Better SEO\" - 8,200 views\n2. \"Product Comparison Guide\" - 5,100 views\n3. \"Customer Success Story: Acme Corp\" - 3,800 views\n\n**Action Items:**\n- [ ] Publish Q1 campaign landing page\n- [ ] Review ad spend allocation\n- [ ] Schedule social media posts for next week"
        },
        {
          "tag": "action",
          "actions": [
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Full Dashboard"},
              "type": "primary",
              "url": "https://example.com/dashboard"
            }
          ]
        },
        {
          "tag": "note",
          "elements": [
            {"tag": "plain_text", "content": "Marketing Team | Auto-generated weekly report"}
          ]
        }
      ]
    }
  }'

4.3 イベント通知

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "interactive",
    "card": {
      "header": {
        "title": {"tag": "plain_text", "content": "Upcoming Webinar: AI in Marketing"},
        "template": "purple"
      },
      "elements": [
        {
          "tag": "markdown",
          "content": "Join us for an exclusive webinar on leveraging AI for marketing success.\n\n**Date:** Thursday, January 30, 2025\n**Time:** 2:00 PM - 3:30 PM (PST)\n**Speaker:** Jane Smith, VP of Marketing\n**Format:** Live presentation + Q&A\n\n**What you will learn:**\n- How to use AI for content personalization\n- Automating campaign optimization\n- Measuring AI-driven marketing ROI"
        },
        {"tag": "hr"},
        {
          "tag": "action",
          "actions": [
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Register Now"},
              "type": "primary",
              "url": "https://example.com/webinar/register"
            },
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Add to Calendar"},
              "type": "default",
              "url": "https://example.com/webinar/calendar"
            }
          ]
        },
        {
          "tag": "note",
          "elements": [
            {"tag": "plain_text", "content": "Limited to 200 seats | Free for all team members"}
          ]
        }
      ]
    }
  }'

4.4 マーケティングキャンペーン アラート

curl -s -X POST "${FEISHU_WEBHOOK_URL}" \
  -H "Content-Type: application/json" \
  -d '{
    "msg_type": "interactive",
    "card": {
      "header": {
        "title": {"tag": "plain_text", "content": "Campaign Alert: Budget Threshold Reached"},
        "template": "orange"
      },
      "elements": [
        {
          "tag": "markdown",
          "content": "**Google Ads - Q1 Brand Campaign** has reached **80%** of its monthly budget.\n\n| Metric | Value |\n|--------|-------|\n| Budget | $10,000 |\n| Spent | $8,042 |\n| Remaining | $1,958 |\n| Days Left | 8 |\n| Projected Overspend | $2,100 |\n\n**Recommendation:** Reduce daily bid cap by 15% or pause low-performing ad groups."
        },
        {
          "tag": "action",
          "actions": [
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "Adjust Budget"},
              "type": "danger",
              "url": "https://ads.google.com/campaigns"
            },
            {
              "tag": "button",
              "text": {"tag": "plain_text", "content": "View Campaign"},
              "type": "default",
              "url": "https://example.com/campaigns/q1-brand"
            }
          ]
        }
      ]
    }
  }'

---

5. ヘルパー: カードをプログラムで構築して送信

複雑または動的なカードの場合は、Python を使用して JSON ペイロードを構築します:

python3 -c "
import json, subprocess, os

webhook_url = os.environ.get('FEISHU_WEBHOOK_URL', '')
if not webhook_url:
    print('Error: FEISHU_WEBHOOK_URL not set')
    exit(1)

# カードを動的に構築
card = {
    'msg_type': 'interactive',
    'card': {
        'header': {
            'title': {'tag': 'plain_text', 'content': 'Dynamic Card Title'},
            'template': 'blue'
        },
        'elements': []
    }
}

# コンテンツブロックを追加
card['card']['elements'].append({
    'tag': 'markdown',
    'content': 'This card was built programmatically.\n\n**Key metrics:**\n- Users: 10,000\n- Revenue: \$50,000'
})

# 区切り線を追加
card['card']['elements'].append({'tag': 'hr'})

# ボタンを追加
card['card']['elements'].append({
    'tag': 'action',
    'actions': [
        {
            'tag': 'button',
            'text': {'tag': 'plain_text', 'content': 'Learn More'},
            'type': 'primary',
            'url': 'https://example.com'
        }
    ]
})

# フッターを追加
card['card']['elements'].append({
    'tag': 'note',
    'elements': [{'tag': 'plain_text', 'content': 'Sent via OpenClaudia'}]
})

payload = json.dumps(card)
result = subprocess.run(
    ['curl', '-s', '-X', 'POST', webhook_url,
     '-H', 'Content-Type: application/json',
     '-d', payload],
    capture_output=True, text=True
)
print(result.stdout)
"

---

6. 二言語サポート (中国語 + 英語)

中国語と英語の両方を必要とするメッセージを送信する場合は、複数のロケールをサポートするリッチテキスト post フォーマットを使用してください。Feishu はユーザーの言語設定に一致するロケールを表示します。

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": "text", "text": "1月25日 22:00-02:00 (北京时间)", "un_escape": true},
              {"tag": "text", "text": " 进行系统维护。"}
            ],
            [
              {"tag": "text", "text": "维护期间服务将暂时不可用。如有问题请联系 "},
              {"tag": "a", "text": "技术支持", "href": "https://example.com/support"},
              {"tag": "text", "text": "。"}
            ]
          ]
        },
        "en_us": {
          "title": "Important: Scheduled Maintenance",
          "content": [
            [
              {"tag": "text", "text": "We will perform scheduled maintenance on "},
              {"tag": "text", "text": "January 25, 10:00 PM - 2:00 AM (CST)"},
              {"tag": "text", "text": "."}
            ],
            [
              {"tag": "text", "text": "Services will be temporarily unavailable. For questions, contact "},
              {"tag": "a", "text": "Support", "href": "https://example.com/support"},
              {"tag": "text", "text": "."}
            ]
          ]
        }
      }
    }
  }'

---

7. エラーハンドリング

ウェブフック レスポンスコード

コード	ステータスメッセージ	意味
0	"success"	メッセージが正常に送信されました
9499	"Bad Request"	JSON が不正な形式またはフィールドが不足
19001	"param invalid"	無効な msg_type またはコンテンツフォーマット
19002	"sign match fail"	署名検証失敗 (タイムスタンプとシークレットを確認)
19021	"request too fast"	レート制限: ウェブフックあたり最大 100 メッセージ/分
19024	"bot not in chat"	ボットはグループから削除されています

一般的なトラブルシューティング

メッセージが配信されない:

• ウェブフック URL が正しく、ボットがまだグループにいることを確認
• msg_type がコンテンツ構造に一致していることを確認
• 署名付きウェブフックの場合、タイムスタンプが現在時刻から 1 時間以内であることを確認

カードが正しくレンダリングされない:

• JSON 構造を検証: header と elements の両方が必須
• ボタン URL は http:// または https:// で始まる必要があります
• カード内の Markdown は限定的なサブセットをサポート: 太字、斜体、リンク、リスト、テーブル

API トークンエラー:

• テナント アクセストークンは 2 時間後に期限切れ; 送信前に再取得
• アプリがデベロッパーコンソールで公開・承認されていることを確認
• im:message:send_as_bot パーミッションが付与されていることを確認

レート制限

統合	制限
カスタム Bot ウェブフック	100 メッセージ/分 (ウェブフックあたり)
アプリ Bot API (メッセージ)	50 メッセージ/秒 (アプリあたり)
アプリ Bot API (トークン更新)	500 リクエスト/時間

---

8. ワークフロー: Feishu/Lark にマーケティングコンテンツをポスト

ユーザーが Feishu または Lark にマーケティングコンテンツを送信するよう依頼した場合、このワークフローに従います:

ステップ 1: 認証情報を確認

FEISHU_WEBHOOK_URL または FEISHU_APP_ID + FEISHU_APP_SECRET が設定されていることを確認します。設定されていない場合は、ユーザーをセットアップに導きます。

ステップ 2: メッセージタイプを決定

ユーザーの意図	推奨フォーマット
クイックテキスト更新	プレーンテキスト (msg_type: text)
フォーマット済みアナウンス	リッチテキスト (msg_type: post)
メトリクス付きマーケティングレポート	マルチカラムのインタラクティブカード
製品ローンチ	ボタン付きインタラクティブカード
イベント通知	CTA ボタン付きインタラクティブカード
アラートまたは警告	red/orange ヘッダー付きインタラクティブカード

ステップ 3: メッセージを作成

• セクション 4 から適切なテンプレートを使用
• コンテンツをユーザーの要件に合わせて調整
• 二言語グループの場合、zh_cn と en_us の両方のコンテンツを提供

ステップ 4: プレビューと確認

送信前に、ユーザーに完全な JSON ペイロードを表示します。メッセージがどのように見えるかを説明します。

明示的なユーザー確認なしに自動送信しないでください。

ステップ 5: 送信

curl コマンドを実行し、レスポンスを報告します。

ステップ 6: 確認

レスポンスコードを確認します。code: 0 の場合、メッセージは配信されました。エラーがある場合は、上記のエラーテーブルを使用してトラブルシューティングします。

---

9. 上級: メッセージカード JSON スキーマ クイックリファレンス

{
  "msg_type": "interactive",
  "card": {
    "header": {                          // 必須
      "title": {
        "tag": "plain_text",
        "content": "string"
      },
      "template": "blue|green|red|..."   // ヘッダーカラー
    },
    "elements": [                        // 必須、ブロックの配列
      {"tag": "markdown", "content": "..."}, // リッチコンテンツ
      {"tag": "hr"},                         // 区切り線
      {"tag": "img", "img_key": "...", "alt": {...}}, // 画像
      {                                      // マルチカラムレイアウト
        "tag": "column_set",
        "flex_mode": "bisect|trisect|...",
        "columns": [
          {"tag": "column", "width": "weighted", "weight": 1, "elements": [...]}
        ]
      },
      {                                      // アクションボタン
        "tag": "action",
        "actions": [
          {"tag": "button", "text": {...}, "type": "primary|danger|default", "url": "..."}
        ]
      },
      {                                      // フッター注記
        "tag": "note",
        "elements": [{"tag": "plain_text", "content": "..."}]
      }
    ]
  }
}

---

ヒント

• ウェブフックから始めてください。 カスタム Bot ウェブフックはゼロコードインフラを必要とし、1 分以内にセットアップできます。
• インタラクティブカード をシンプルテキスト以上のもので使用してください。より読みやすく、アクション可能です。
• すべてのマーケティングカードにアクションボタンを含めてください。 受信者をランディングページ、ダッシュボード、またはサインアップフォームに導きます。
• 二言語サポートを活用してください チームが Feishu と Lark を両方使用する、または中国と国際の両方のメンバーがいる場合。
• レート制限を尊重してください。 バルクメッセージング (例: 複数のグループに送信) の場合、リクエスト間に 1 秒の遅延を追加します。
• 大きなチームチャネルに送信する前にプライベートグループでテストしてください。
• カードコンテンツを簡潔に保ってください。 カードの最大コンテンツサイズは約 30KB です。非常に長いレポートの場合は、外部ページにリンクします。
• Feishu メッセージカードビルダーを使用してください ビジュアルカード設計用: https://open.feishu.cn/tool/cardbuilder (Feishu) または https://open.larksuite.com/tool/cardbuilder (Lark)。