Lark / Feishu

tenant_access_token を使った Lark IM メッセージング。AES-256-CBC 暗号化 webhook イベントにも対応。

🟡 アウトバウンド送信対応、インバウンド受信もサポート。中国本土向け Feishu（open.feishu.cn）と国際版 Lark（open.larksuite.com）の両方に対応しています。インバウンド webhook は Lark の3つのセキュリティモード（確認トークン、暗号化、署名付き HMAC）すべてを処理します。

できること

アウトバウンドテキストメッセージ送信（POST /open-apis/im/v1/messages?receive_id_type=chat_id）。 tenant access token は2時間キャッシュされ、5分前に更新されるため、大量送信時もアプリごとのtoken レート制限に達しません。
インバウンド webhook イベント受信（/webhooks/lark）。 Lark では3つのセキュリティモード（確認トークン、暗号化キー、HMAC 署名）を任意に組み合わせて使用できます。Minara は開発者コンソールで有効にしたモードをすべて尊重します。
ドメイン対応ルーティング。LARK_DOMAIN で Feishu（中国本土）か Lark 国際版かを選択できます。どちらも同じ API 形式を使用します。
**現時点ではテキストのみ。**リッチカード、画像、ファイルは今後追加予定です。現在はtenant token キャッシュと署名付き webhook の基盤が利用可能です。
**3万文字制限。**それを超えるテキストは切り捨てられます。

セットアップ

1. アプリの作成

Lark Developer Console（または国際版 Lark）にサインインします
カスタムアプリを作成します。App ID（cli_ で始まる）と App Secret を控えておきます
「権限とスコープ」で im:message:send_as_bot を付与します。インバウンドを使う場合は、Bot に必要なメッセージ受信スコープ（通常 im:message）も追加します
「イベントサブスクリプション」でリクエスト URL を https://<your-host>/webhooks/lark に設定します。Verification Token と（任意で）Encrypt Key をコピーします

2. デフォルト chat_id の確認

対象チャット（1対1またはグループ）でメッセージを送信したあと、開発者コンソールから POST /open-apis/im/v1/messages/list を呼び出すか、tenant token を使った curl で chat_id（形式：oc_xxxxxxxxxxxxxxxx）を取得します。これを LARK_DEFAULT_CHAT_ID として保存します。

3. Minara の設定

minara auth messaging add
# リストから `lark` を選択し、App ID、App Secret、Chat ID、
# Verification Token（暗号化を有効にした場合は Encrypt Key も）を貼り付けます。

またはプロジェクトルートの .env ファイルに直接記述します：

LARK_APP_ID=cli_xxxxxxxxxxxxxxxx
LARK_APP_SECRET=<opaque secret>
LARK_DEFAULT_CHAT_ID=oc_xxxxxxxxxxxxxxxx
LARK_VERIFICATION_TOKEN=<verification token>
LARK_ENCRYPT_KEY=<encrypt key, optional>
LARK_DOMAIN=open.feishu.cn          # または open.larksuite.com

4. テスト

minara auth messaging test lark

インバウンド webhook

Lark のイベントサブスクリプション URL を以下のように設定します：

https://<your-host>/webhooks/lark

3つのセキュリティモードを組み合わせて使用できます：

モード	環境変数	動作
確認トークン	`LARK_VERIFICATION_TOKEN`	デコードされたペイロードのトップレベル `token` フィールドが一致する必要があります。平文モードおよび復号後に使用されます。
暗号化	`LARK_ENCRYPT_KEY`（任意）	設定されている場合、リクエストボディは `{encrypt: "<base64>"}` 形式で届き、AES-256-CBC（key = SHA256(encrypt_key)、IV = キーの先頭 16 バイト）で復号されます。
署名	`X-Lark-Signature` ヘッダー（常に任意）	`timestamp + nonce + encrypt_key + body` を SHA-256 でハッシュした値を16進数でヘッダーに付与します。コンソールで有効にすると追加の整合性チェックになります。

URL 検証ハンドシェイク：Lark が {type:"url_verification", challenge:"..."} を送信すると、Minara は確認トークンを検証したうえで {challenge} を返します。トークンが一致しない場合は 403 を返します。

制限事項と注意点

**tenant token のレート制限。**Lark はアプリごとに 1 分間あたり約 100 回のtoken 取得を上限としています。2時間のキャッシュにより、この制限を大きく下回ります。
**content は JSON エンコードされた文字列である必要があります。**これは Lark API の仕様です。テキストメッセージでも content: JSON.stringify({text: "..."}) の形式で送信します。Minara がこの処理を自動で行います。
**カードのインタラクションは未対応。**インタラクティブカードのボタンクリックコールバックは別の webhook イベントタイプで届くため、現時点では解析されません。

トラブルシューティング

「テストメッセージでコード 99991663 が返される」

tenant access token の更新に失敗しています。開発者コンソールで LARK_APP_ID と LARK_APP_SECRET を確認してください。

「インバウンド webhook が 401 を返す」

コンソールで暗号化モードを有効にしているのに LARK_ENCRYPT_KEY を設定していない場合、すべてのインバウンド POST が復号に失敗します。コンソールで暗号化を無効にするか、環境変数を設定してください。
署名モードを有効にしている場合、保存した LARK_ENCRYPT_KEY がコンソールに表示されている値と一致するか確認してください（署名入力にも同じキーが使われます）。

「content フィールドが必須です（400）」

send_message を呼び出す際に text に空文字列を渡しています。Lark は空のボディを受け付けません。

リファレンス

環境変数：LARK_*
アウトバウンド：apps/agent/src/messaging/lark.ts
インバウンド仕様：apps/agent/src/messaging/inbound/specs/lark.ts
Lark オープンプラットフォーム：open.feishu.cn
暗号化の実装例：open.feishu.cn / Encryption case

目次