飛書インタラクティブカード

飛書インタラクティブカードを構築、送信、処理します。

ベース URL: https://open.feishu.cn/open-apis/im/v1

使用シナリオ: 朝礼確認、アラート処理、タスク確認、ステータス更新

認証とトークン取得

feishu_skills のルートディレクトリから共有スクリプトを実行します。

TOKEN="$(./scripts/get_feishu_token.sh)"

リクエストヘッダーはすべて Authorization: Bearer ${TOKEN} を使用します。

ビジネスインターフェースがトークン無効、期限切れ、または 401 を返した場合、強制的に更新した後、元のリクエストを一度だけ再試行します。

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（期限切れでなければ直接再利用、デフォルトでは5分前に更新）

カードの送信

POST /open-apis/im/v1/messages?receive_id_type=chat_id

{
  "receive_id": "<chat_id>",
  "msg_type": "interactive",
  "content": "<card_json_string>"
}

⚠️ content は文字列化された JSON である必要があります。

カード構造

{
  "config": {"wide_screen_mode": true},
  "header": {
    "title": {"tag": "plain_text", "content": "タイトル"},
    "template": "blue"
  },
  "elements": [
    {"tag": "div", "text": {"tag": "lark_md", "content": "**太字**"}},
    {"tag": "action", "actions": [
      {"tag": "button", "text": {"tag": "plain_text", "content": "確認"}, "type": "primary", "value": {"action": "confirm"}}
    ]}
  ]
}

常用要素

ボタン

{
  "tag": "action",
  "actions": [
    {
      "tag": "button",
      "text": {"tag": "plain_text", "content": "確認"},
      "type": "primary",
      "value": {"action": "confirm", "data": "extra_info"}
    }
  ]
}

ボタンタイプ: default / primary / danger

セレクター

{
  "tag": "select_static",
  "placeholder": {"tag": "plain_text", "content": "選択してください"},
  "options": [
    {"text": {"tag": "plain_text", "content": "オプション1"}, "value": "opt1"},
    {"text": {"tag": "plain_text", "content": "オプション2"}, "value": "opt2"}
  ],
  "value": {"key": "select_result"}
}

コールバック処理

ユーザーがボタンをクリックすると、飛書は WebSocket イベントを送信します。

{
  "type": "card.action.trigger",
  "action": {
    "value": {"action": "confirm", "data": "extra_info"}
  }
}

コールバックを処理した後、カードを更新できます。

PATCH /open-apis/im/v1/messages/{message_id}

ベストプラクティス

1. ボタンに value を持たせる（コールバック識別用）
2. 新しいメッセージの代わりにカードを更新する（画面の乱雑さを減らす）
3. 危険な操作には danger タイプを使用する