DingTalk Bot 連携

任意のエージェントを DingTalk Bot に接続すれば、チームは DingTalk の中から直接それを使えます——Bot に DM したり、グループで @ メンションしたり、スクリーンショットを送ったり、/issue と入力してアプリを開かずに Melso イシューを起票したりできます。

DingTalk 連携はコミュニティによってメンテナンスされています。毎リリースに同梱されますが、公式のサポート SLA は付きません。問題があれば GitHub issues に報告してください。

DingTalk は**自分のアプリを持ち込む（BYO: bring-your-own-app）**モデルを採用しています。ワークスペースの admin が DingTalk アプリを作成し、Stream モードのロボットを追加して、その認証情報を Melso に貼り付けます。セットアップ時に選んだエージェントが DM と新しく検出されたグループのデフォルトになります。同じロボットを複数のグループに追加し、グループごとに別のエージェントへルーティングできます。（これは紐づけがスキャンしてインストールするフローである Lark とは異なります。）

セットアップ全体は以下のとおりで、所要時間は約 5 分です。最終的に、Melso に貼り付ける 2 つの認証情報が得られます。

• AppKey —— アプリの client id
• AppSecret —— アプリの client secret

DingTalk アプリをセットアップする

1. アプリを作成し、Stream モードのロボットを追加する

1. DingTalk オープンプラットフォームを開き、企業内部アプリ（企业内部应用）を作成します。
2. そのアプリを開き、ロボット（机器人）機能を追加します。
3. ロボット設定で、メッセージ受信モードを Stream モード（推送模式）に設定します。これにより、Bot は webhook を受け取るのではなく、長時間維持される push 接続を通じて外向きに接続するようになります。

これがプラットフォーム層で Melso が必要とするすべてです——Bot は Stream モードで外向きに接続するので、公開アドレスを設定する必要はありません。

webhook URL も OAuth リダイレクト URL もありません。ロボットは Stream モードで動作し、BYO は OAuth を使わないからです。

2. ロボットに権限を付与する

ロボットに、メッセージを受信し、メッセージを送り返すために必要なスコープ（ロボットのメッセージ送信権限）を付与します。送信権限がないと、エージェントは動作しても返信を配信できません。

3. AppKey と AppSecret をコピーする

アプリの 凭证与基础信息（認証情報と基本情報）を開き、以下をコピーします。

• AppKey —— これがアプリの client id です
• AppSecret —— これがアプリの client secret です

4. Melso で接続する

1. Agents → あなたのエージェント からそのエージェントを開き、Integrations タブ（または左サイドバーの Integrations 区画）を開きます。
2. Connect DingTalk をクリックします。
3. AppKey と AppSecret を貼り付け、Connect をクリックします。
4. エージェントに Connected to DingTalk と表示されます。Bot はこれで、自身の Stream 接続を通じて待ち受けています。

この連携でできること

Bot を使う（メンバー）

最初のメッセージ：アカウントを紐づける

初めて Bot を @ メンションするか DM すると、Bot は アカウントを紐づける プロンプトで返信し、それはプロダクト内の /dingtalk/bind ページを指しています。リンクをタップして Melso にサインインすると、あなたの DingTalk アイデンティティがあなたの Melso メンバーシップに紐づきます——これによって、エージェントがあなたとして振る舞えるようになります（たとえば /issue はあなたの名義でイシューを起票します）。このリンクは使い切りで、約 15 分で失効します。新しいものが必要なら、もう一度 Bot にメッセージを送るだけです。

対話とコマンド

• グループで —— Bot をグループに追加してから、@your-bot <あなたのメッセージ> とします。フォローアップのたびに再度メンションしてください（Bot は自分をメンションしたメッセージだけを読みます）。
• 1:1 チャットで —— Bot を開いて直接メッセージを送ります。メンションは不要で、すべてのメッセージが読み取られます。
• 画像を送る —— スクリーンショットや写真を、テキストの有無を問わず送れます。会話に入り、エージェントが参照できます。対応形式は PNG・JPEG・GIF・WebP・BMP、1 メッセージあたり最大 4 枚、1 枚あたり 10 MB までです。
• イシューを起票する —— /issue Safari でログインのリダイレクトが壊れている と送り、必要なら続く行に説明を書きます。Melso は同期的にイシューを作成し、同じメッセージの画像をそのイシューに添付して、ID とタイトルをチャットに返します。
• 新しく始める —— /new <あなたのメッセージ> と送ると、そのメッセージを過去の文脈なしで実行します。/new だけを送れば、fresh-start を次の空でないメッセージに適用できます。どちらも既存の会話履歴は削除しません。

管理と切断

ワークスペース全体の管理は Settings → Integrations にあります。

• Connected bots は、ワークスペース内のすべての Bot と、それぞれが紐づくエージェントを一覧表示します（すべてのメンバーから見えます）。
• グループルーティングは Bot が検出したすべてのグループを表示します。owner と admin はグループごとに固定のエージェントを選べ、全メンバーが現在のルートを確認できます。
• ルートを変更するたびに、選択したエージェント用の新しい Chat セッションが作成されます。エージェント A → B → A と戻しても、A の以前のセッションは再開されません。割り当てたエージェントをアーカイブするとルートは保持されますが、そのエージェントを復元するかグループを再割り当てするまで、処理は停止して利用不可の通知が返ります。
• Disconnect は owner / admin 専用 です。切断すると Bot は DingTalk メッセージの受信を停止し、その接続が破棄されます。インストール記録は監査のために保持され、あとで再接続できます。

権限

• 接続 / 切断 にはワークスペースの owner または admin が必要です。
• Bot との対話 には、DingTalk アイデンティティを紐づけたワークスペースメンバーであることが必要です。それ以外の人は一律に破棄されます。
• 破棄されたメッセージの本文が保存されることはありません——監査のために破棄理由だけが記録されます。

セルフホストのセットアップ

Melso Cloud では連携はすでに利用可能です——このセクションは飛ばしてください。

セルフホストの場合、DingTalk は保存時の暗号化キーを設定するまでオフです。このキーは各アプリの AppSecret をデータベース保存前に暗号化します。AppKey は機密情報ではないインストールのルーティング識別子として平文で保存されます。BYO にはデプロイレベルの OAuth の client id/secret は不要です——各インストールは admin が貼り付けた認証情報を使います。

1. 32 バイトのキーを生成し、API サーバーに設定します。

   MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>

   たとえば: openssl rand -base64 32。

2. API を再起動します。キーを設定するまで、Settings → Integrations には「DingTalk integration not enabled」という通知が表示され、Connect DingTalk のエントリポイントは非表示のままになります。

次に

• Chat 連携 — チャンネルエンジン、セッション、認可の仕組み
• エージェント · Chat · イシュー
• 環境変数 — セルフホスト構成の完全なリファレンス