連携

Lark / Feishu 連携設定ガイド

本ガイドでは、Lark（Feishu）開発者プラットフォームでカスタムアプリを作成し、ボット機能・API 権限・イベント／コールバック購読を設定して、Kocoro に登録するまでを案内します。完了すると、メンバーは Lark / Feishu のチャットでボットにメッセージを送ったり @メンションしたりでき、エージェントが返信します。

はじめる前に

カスタムアプリを作成できる Lark / Feishu アカウント。
インストール・初期化済みの Kocoroと、作成済みのエージェントが少なくとも 1 つあること。
Lark / Feishu 開発者プラットフォームと Kocoro サービスにアクセスできるネットワーク環境。

1
カスタムアプリを作成
Lark 開発者プラットフォーム（open.larksuite.com/app、Feishu は open.feishu.cn/app）にログインし、「Create Custom App」をクリックします。
図 1：Lark / Feishu 開発者プラットフォームで「Create Custom App」をクリック。
2
アプリ情報を入力して作成
ダイアログでアプリ名と説明を入力し、アプリアイコンを選択またはアップロードして「Create」をクリックします。
図 2：アプリ名・説明・アイコンを入力して「Create」をクリック。
3
App ID と App Secret をコピー
アプリの管理画面を開き、左サイドバーの「Credentials & Basic Info」へ進みます。App ID と App Secret をコピーします。この認証情報で Kocoro が Lark / Feishu に接続します。
App Secret は安全に保管してください。漏洩した場合は同じページでリセットできます。
図 3：「Credentials & Basic Info」で App ID と App Secret をコピー。
4
Kocoro に Lark / Feishu ボットを追加
Kocoro を開き、「Capabilities → Connectors」へ進み、「Lark」/「Feishu」の「Add Bot」をクリックします。ダイアログ（ステップ 1/3）で前のステップの App ID と App Secret を貼り付け、「Next」をクリックします。
Feishu はワンクリック認証（OAuth）に対応していないため、アプリの認証情報をご利用ください。
図 4：Kocoro で App ID と App Secret を入力（ステップ 1/3）。
5
Encrypt Key を取得
「Events & Callbacks → Encryption Strategy」へ進み、Encrypt Key の「Reset」をクリックして生成し、Kocoro に貼り付けます。
図 5：「Encryption Strategy」で Encrypt Key をリセットしてコピー。
6
「Bot」機能を追加
Lark / Feishu 管理画面に戻り、「Add Features」へ進み、「Bot」カードの「Add」をクリックします。これでアプリがボットとして Lark / Feishu でメッセージを送受信できます。
図 6：「Add Features」で「Bot」機能を追加。
7
API 権限を開通
「Permissions & Scopes」へ進み、「Add permission scopes」をクリックします。検索ボックスに下記のスコープ一覧を貼り付け、全選択して「Add Scopes」をクリックします（全 10 項目）。
im:resource,contact:contact.base:readonly,contact:user.base:readonly,im:message.group_at_msg:readonly,im:message.p2p_msg:readonly,im:message:send_as_bot,im:message,cardkit:card:write,im:message:readonly,im:message.reactions:read
Kocoro のボット追加ダイアログで「Open permissions page」をクリックすると、これらのスコープが自動で入力されます。
図 7：「Permissions & Scopes」で 10 項目のスコープを一括追加。
8
Kocoro で登録を完了
Kocoro のボット追加ダイアログ（ステップ 2/3）に戻ります：ステップ 5 でコピーした Encrypt Key を「Get Encrypt Key」欄に貼り付け、「Add Bot」と「Configure permissions」が完了していることを確認（リンクで確認可能）。「Choose Agent」で応答させるエージェントを選び、任意で「Display Name」を設定して「Register Bot」をクリックします。
図 8：Kocoro で Encrypt Key を貼り付け、エージェントを選んで登録（ステップ 2/3）。
9
イベントの Request URL を設定
「Events & Callbacks → Event Configuration」へ進み、購読方式を「Send notifications to developer's server」にして、「Request URL」に下記の URL を入力して保存します。
https://api.shannon.run/api/v1/channels/feishu/events
図 9：「Send notifications to developer's server」を選び Request URL を入力。
10
「Message received」イベントを追加
「Event Configuration」ページで「Add Events」をクリックし、「Message received (im.message.receive_v1)」を検索して選択し、「Add」をクリックします。
im.message.receive_v1
図 10：「Message received」イベントを追加。
11
コールバックの Request URL を設定
「Callback Configuration」タブに切り替え、購読方式を「Send callbacks to developer's server」にして、「Request URL」にイベントと同じ URL を入力して保存します。
https://api.shannon.run/api/v1/channels/feishu/events
図 11：「Send callbacks to developer's server」を選び Request URL を入力。
12
「Card callback」を追加
「Callback Configuration」ページで「Add callback」をクリックし、「Card」カテゴリで「Card callback communication (card.action.trigger)」を選択し、「Add」をクリックします。
card.action.trigger
図 12：「Card callback communication」を追加。
13
アプリを公開して設定を反映
最後に Lark / Feishu 管理画面の「Version Management & Release」へ進み、利用可能範囲を設定して「Save」でバージョンを作成・公開します。設定はアプリが公開（管理者承認）された後に反映されます。
「The current configuration will take effect after the app is published.」というバナーが表示されている場合は、このステップが必要です。
図 13：「Version Management & Release」でアプリを保存・公開。