DingTalk Bot 連携
Multica エージェントをあなた自身の DingTalk アプリに接続します——DingTalk オープンプラットフォームで Stream モードのロボットを作成し、その AppKey と AppSecret をコピーして Multica に貼り付ければ、DingTalk の中から DM したり、グループで @ メンションしたり、/issue と入力したりできます。
任意のエージェントを DingTalk Bot に接続すれば、チームは DingTalk の中から直接それを使えます——Bot に DM したり、グループで @ メンションしたり、スクリーンショットを送ったり、/issue と入力してアプリを開かずに Multica イシューを起票したりできます。
DingTalk 連携はコミュニティによってメンテナンスされています。毎リリースに同梱されますが、公式のサポート SLA は付きません。問題があれば GitHub issues に報告してください。
DingTalk は自分のアプリを持ち込む（BYO: bring-your-own-app）モデルを採用しています。ワークスペースの admin が DingTalk アプリを作成し、それに Stream モードのロボットを追加して、その認証情報を Multica に貼り付けます。エージェントごとに専用の DingTalk アプリを持つため、同じ組織内で複数のエージェントがそれぞれ別個に @ メンションできる異なる Bot を持てます。（これは紐づけがスキャンしてインストールするフローである Lark とは異なります。）
セットアップ全体は以下のとおりで、所要時間は約 5 分です。最終的に、Multica に貼り付ける 2 つの認証情報が得られます。
- AppKey —— アプリの client id
- AppSecret —— アプリの client secret
DingTalk アプリをセットアップする
1. アプリを作成し、Stream モードのロボットを追加する
- DingTalk オープンプラットフォームを開き、企業内部アプリ（企业内部应用）を作成します。
- そのアプリを開き、ロボット（机器人）機能を追加します。
- ロボット設定で、メッセージ受信モードを Stream モード（推送模式）に設定します。これにより、Bot は webhook を受け取るのではなく、長時間維持される push 接続を通じて外向きに接続するようになります。
これがプラットフォーム層で Multica が必要とするすべてです——Bot は Stream モードで外向きに接続するので、公開アドレスを設定する必要はありません。
| 設定 | なぜそこにあるか |
|---|---|
| 企業内部アプリ | ロボットを保持し、AppKey / AppSecret 認証情報を発行するアプリのコンテナです。 |
| ロボット機能 | @ メンションされ、返信を投稿する Bot のアイデンティティを作成します。 |
| Stream モード | Bot は長時間維持される Stream 接続を通じて外向きに接続します——公開 webhook／URL は不要です。 |
| ロボット送信権限 | Bot が DingTalk にメッセージを送り返せるようにします（エージェントの返信や能動的なメッセージ）。 |
| メッセージ読み取り権限 | Bot が 1:1 メッセージと、自分を @ メンションしたグループメッセージを受け取れるようにします。 |
webhook URL も OAuth リダイレクト URL もありません。ロボットは Stream モードで動作し、BYO は OAuth を使わないからです。
DingTalk にはネイティブの入力中／リアクションのインジケーターがないため——Slack とは異なり——Bot は処理を始めると短い「処理中」の合図を先に返し、完全な返信はエージェントの処理が終わってから届きます。短時間に連投したメッセージは 1 つの合図にまとめられます。
2. ロボットに権限を付与する
ロボットに、メッセージを受信し、メッセージを送り返すために必要なスコープ（ロボットのメッセージ送信権限）を付与します。送信権限がないと、エージェントは動作しても返信を配信できません。
3. AppKey と AppSecret をコピーする
アプリの 凭证与基础信息（認証情報と基本情報）を開き、以下をコピーします。
- AppKey —— これがアプリの client id です
- AppSecret —— これがアプリの client secret です
4. Multica で接続する
- Agents → あなたのエージェント からそのエージェントを開き、Integrations タブ（または左サイドバーの Integrations 区画）を開きます。
- Connect DingTalk をクリックします。
- AppKey と AppSecret を貼り付け、Connect をクリックします。
- エージェントに Connected to DingTalk と表示されます。Bot はこれで、自身の Stream 接続を通じて待ち受けています。
2 つの認証情報は同じ DingTalk アプリのものでなければならず、そのアプリはちょうど 1 つのエージェントに対応します。すでに別のエージェントやワークスペースに接続されているアプリを接続しようとすると拒否されます。アプリを別のエージェントへ移すには、まず切断してください。新しいアプリでエージェントを再接続すると、そのエージェントの Bot がその場で更新されます。
複数のエージェントでこれを設定しますか？ フロー全体をエージェントごとに 1 回ずつ繰り返してください——各エージェントが専用の DingTalk アプリと専用の AppKey / AppSecret を持ち、組織内で別々の Bot として表示されます。
この連携でできること
| 場所 | 動作 |
|---|---|
| エージェント → Integrations | owner と admin には Connect DingTalk が表示され、接続すると Connected to DingTalk バッジと Disconnect コントロールに切り替わります。 |
| Bot に DM | ワークスペースメンバーが 1:1 チャットで Bot に直接メッセージを送ります。会話はそのエージェントとの Multica chat セッションになり、すべてのメッセージが読み取られます。 |
| グループで @ メンション | Bot をグループに追加し、@ メンションします。読み取られるのはメンションしたメッセージだけで、Bot はグループ全体を聞いているわけではありません。 |
| 画像を送る | DM の画像も、グループで @ メンションと一緒に送った画像も、会話に入りエージェントが見られるようになります——PNG・JPEG・GIF・WebP・BMP に対応し、1 メッセージあたり最大 4 枚、1 枚あたり 10 MB までです。各画像は Multica のストレージにコピーされるため、DingTalk の一時リンクが失効した後も会話の中に表示され続けます。ファイルと音声には対応していません。 |
/issue コマンド | /issue <タイトル> で始めると、入力内容からあなた名義の Multica イシューを直接かつ同期的に作成し、同じ会話へ ID とタイトルを返します。続く行は説明になります。同じ DingTalk メッセージの画像はチャット側にのみ添付され、直接作成したイシューにはコピーされません。 |
/new コマンド | /new <あなたのメッセージ> で始めると、そのメッセージを過去の文脈なしで実行します。/new だけを送ると、同じ fresh-start の意図が次の空でないメッセージに適用され、空の turn は作られません。既存の会話履歴はそのまま残ります。 |
| 返信 | エージェントの回答は、同じ 1:1 チャットまたはグループに投稿し返されます。 |
Bot を使う（メンバー）
最初のメッセージ：アカウントを紐づける
初めて Bot を @ メンションするか DM すると、Bot は アカウントを紐づける プロンプトで返信し、それはプロダクト内の /dingtalk/bind ページを指しています。リンクをタップして Multica にサインインすると、あなたの DingTalk アイデンティティがあなたの Multica メンバーシップに紐づきます——これによって、エージェントがあなたとして振る舞えるようになります（たとえば /issue はあなたの名義でイシューを起票します）。このリンクは使い切りで、約 15 分で失効します。新しいものが必要なら、もう一度 Bot にメッセージを送るだけです。
Bot を使えるのは ワークスペースのメンバー だけです。メンバーでない場合や、アイデンティティの紐づけをスキップした場合、Bot は実行されません——あなたのメッセージは破棄されます（内容は保存せず、監査のために記録されます）。
対話とコマンド
- グループで —— Bot をグループに追加してから、
@your-bot <あなたのメッセージ>とします。フォローアップのたびに再度メンションしてください（Bot は自分をメンションしたメッセージだけを読みます）。 - 1:1 チャットで —— Bot を開いて直接メッセージを送ります。メンションは不要で、すべてのメッセージが読み取られます。
- 画像を送る —— スクリーンショットや写真を、テキストの有無を問わず送れます。会話に入り、エージェントが参照できます。対応形式は PNG・JPEG・GIF・WebP・BMP、1 メッセージあたり最大 4 枚、1 枚あたり 10 MB までです。
- イシューを起票する ——
/issue Safari でログインのリダイレクトが壊れていると送り、必要なら続く行に説明を書きます。Multica は同期的にイシューを作成し、ID とタイトルをチャットに返します。同じメッセージの画像はチャットに残り、イシューには添付されません。 - 新しく始める ——
/new <あなたのメッセージ>と送ると、そのメッセージを過去の文脈なしで実行します。/newだけを送れば、fresh-start を次の空でないメッセージに適用できます。どちらも既存の会話履歴は削除しません。
管理と切断
ワークスペース全体の管理は Settings → Integrations にあります。
- Connected bots は、ワークスペース内のすべての Bot と、それぞれが紐づくエージェントを一覧表示します（すべてのメンバーから見えます）。
- Disconnect は owner / admin 専用 です。切断すると Bot は DingTalk メッセージの受信を停止し、その接続が破棄されます。インストール記録は監査のために保持され、あとで再接続できます。
権限
- 接続 / 切断 にはワークスペースの owner または admin が必要です。
- Bot との対話 には、DingTalk アイデンティティを紐づけたワークスペースメンバーであることが必要です。それ以外の人は一律に破棄されます。
- 破棄されたメッセージの本文が保存されることはありません——監査のために破棄理由だけが記録されます。
セルフホストのセットアップ
Multica Cloud では連携はすでに利用可能です——このセクションは飛ばしてください。
セルフホストの場合、DingTalk は保存時の暗号化キーを設定するまでオフです。このキーは各アプリの AppSecret をデータベース保存前に暗号化します。AppKey は機密情報ではないインストールのルーティング識別子として平文で保存されます。BYO にはデプロイレベルの OAuth の client id/secret は不要です——各インストールは admin が貼り付けた認証情報を使います。
-
32 バイトのキーを生成し、API サーバーに設定します。
MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>たとえば:
openssl rand -base64 32。 -
API を再起動します。キーを設定するまで、Settings → Integrations には「DingTalk integration not enabled」という通知が表示され、Connect DingTalk のエントリポイントは非表示のままになります。
キーはちょうど 32 バイトにデコードされなければなりません——openssl rand -base64 32 はそれを満たします。これは長く使い続けるシークレットとして扱ってください。ローテーションしたり紛失したりすると、すでに保存済みの認証情報が復号できなくなり、すべての Bot を再接続せざるを得なくなります。「アカウントを紐づける」リンクは、Web アプリの URL（MULTICA_APP_URL、未設定時は FRONTEND_ORIGIN にフォールバック）から生成されます。通常のデプロイではこれは既に設定されているため、追加で設定するものはありません。