feishu-im

Lark のメッセージとグループ管理

IM API を通じてメッセージを送信し、グループチャットを管理して、グループ機能を設定します。

Base URL: https://open.feishu.cn/open-apis/im/v1

認証と Token の取得

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

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

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

業務 API から無効な Token、期限切れ、または 401 が返された場合は、強制的に更新した後、元のリクエストを 1 回だけ再試行します：

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

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（有効期限内であればそのまま再利用し、デフォルトでは 5 分前に更新します）

---

メッセージ操作

API	エンドポイント	説明
メッセージを送信	POST /messages?receive_id_type=open_id	テキスト／カード／画像／ファイルに対応
一括送信	POST /messages/batch_send	最大 200 人
メッセージに返信	POST /messages/{message_id}/reply	-
メッセージを取り消す	DELETE /messages/{message_id}	24 時間以内
メッセージを緊急扱いにする	PATCH /messages/{message_id}/urgent_app	-
メッセージをピン留め	POST /pins	-
リアクションを追加	POST /messages/{message_id}/reactions	-

テキストメッセージを送信:

{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\":\"Hello\"}"
}

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

receive_id_type: open_id / user_id / email / chat_id

---

インタラクティブカード

カードを送信:

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

カードの構造:

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

よく使われる要素:

• div: テキストブロック（lark_md / plain_text に対応）
• hr: 区切り線
• action: ボタングループ
• img: 画像
• note: 注記

---

グループチャット管理

API	エンドポイント	説明
グループチャットを作成	POST /chats	-
グループ情報を取得	GET /chats/{chat_id}	-
グループ情報を更新	PUT /chats/{chat_id}	グループ名／説明／アバターを変更
グループチャットを解散	DELETE /chats/{chat_id}	-
グループチャットを検索	GET /chats/search	-

グループチャットを作成:

{
  "name": "项目群",
  "description": "项目讨论",
  "user_id_list": ["ou_xxx", "ou_yyy"]
}

---

グループメンバー管理

API	エンドポイント	説明
メンバー一覧を取得	GET /chats/{chat_id}/members	-
メンバーを追加	POST /chats/{chat_id}/members	1 回につき最大 50 人
メンバーを削除	DELETE /chats/{chat_id}/members	-
グループオーナーを譲渡	PUT /chats/{chat_id}/owner	-

---

グループ機能の設定

API	エンドポイント	説明
グループのお知らせ	PATCH /chats/{chat_id}/announcement	-
グループのピン留め	POST /chats/{chat_id}/top_notice/put_top_notice	-
グループメニュー	POST /chats/{chat_id}/menu_tree	-
グループタブ	POST /chats/{chat_id}/chat_tabs	-

グループのお知らせを設定:

{
  "content": "群公告内容",
  "i18n_contents": {
    "zh_cn": "中文公告",
    "en_us": "English Announcement"
  }
}

---

ベストプラクティス

1. 一括送信を優先（API 呼び出しを削減）
2. カードの content は文字列化が必須
3. グループメンバー操作は 1 回につき最大 50 人
4. メッセージの取り消しは 24 時間以内に限られます