DingTalk
1. 前提条件
- DingTalkオープンプラットフォームのアカウントを持っていること（企業内部アプリ、サードパーティアプリのどちらでも可）
- Agentic Engineプラットフォームの管理者権限
2. DingTalkアプリを作成して認証情報を取得する
DingTalkオープンプラットフォームにアクセスしてログインし、次の手順で操作します：
- 「Developer Console」→「App Development」→「Internal Enterprise Apps」に進み、「Create App」をクリックします
- アプリケーション名と説明を入力します
- アプリの作成に成功したら、アプリの詳細ページ →「Credentials & Basic Info」に進み、次の2つの値を控えておきます：
| フィールド名 | 対応するプラットフォームのフィールド | 説明 |
|---|---|---|
| AppKey | Client ID | アプリの一意の識別子。OAuth認証に使用します |
| AppSecret | Client Secret | アプリシークレット。厳重に保管し、漏洩しないようにしてください |
企業CorpIdを取得する
DingTalk開発者プラットフォームを開いてログインします。ホームの右側にある企業情報カードで CorpId を見つけ、値全体をコピーします。DingTalkチャネルを追加する際は、このCorpIdをClient ID、Client Secretと一緒に入力する必要があります。
CorpIdは現在の企業の一意の識別子で、企業ごとに値が異なります。自社のページに表示される値全体を使用し、例やスクリーンショットの値をそのまま写さないでください。
- 「Add App Capabilities」→「Robot」に進み、ロボットの設定でメッセージ受信モードに「Stream Mode」を選択します
- アプリの「Permission Management」で、次の権限を有効にします：
Read personal contact information、Employee mobile number information、DingTalk group basic information management、Read member information、Send messages by enterprise robots、Write interactive card instances、AI card streaming updates、Write intelligent interactive cards。「Enterprise Storage App Read」権限を有効にする必要はありません：この権限は企業ストレージ系のAPIで使用するもので、現在のチャネル実装ではこれらのAPIを呼び出しません。 - 「Security Settings」で、Agentic EngineのサーバーIPをアウトバウンドIPのホワイトリストに追加し、OAuthリダイレクトURL（コールバックドメイン）を次のように設定します：
https://<your-domain>/api/dingtalk-oauth/callback - 設定を変更するたびに、「Version Management and Release」で「View version details」をクリックし、バージョン番号とバージョンの説明を編集してから「Publish」をクリックします
3. プラットフォームでDingTalkチャネルを追加する
管理者がAgentic Engineにログインし、「システム管理」→「エージェント 管理者」→「チャンネル管理」に進みます：
- 「新規チャンネル」をクリックし、チャンネルタイプで DingTalk を選択します
- 次の構成項目を入力します：
| 構成項目 | 必須 | 説明 |
|---|---|---|
| チャンネル名 | 必須 | 表示名。例：「企業DingTalk」。 |
| Corp ID | 必須 | DingTalk企業の一意の識別子。企業の身元を検証し、チャットスペースを作成するために使用します。DingTalk管理コンソールの企業情報からコピーできます。 |
| Client ID | 必須 | DingTalkアプリのAppKeyを入力します。 |
| Client Secret | 必須 | DingTalkアプリのAppSecretを入力します。 |
| 対話式質問カードテンプレート ID | 任意 | DingTalk AI CardテンプレートのIDで、「xxxxxxxx.schema」のような形式です。公開済みで、プロジェクトの変数仕様に準拠したDingTalk AI Cardテンプレートを使用する必要があります。空欄の場合、質問には自動的にテキストで回答する形式になります。 |
| デフォルトモデル | 任意 | 単一Agentのチャネルタスクで使用します。入力しない場合は、システム全体のデフォルトモデルを使用します。Teamは各メンバー自身に設定されたモデルを使用します。 |
| チャネル入力の追加説明 | 任意 | チャネル入力の各ターンに追加する説明として使われ、Agent自身のシステムプロンプトを置き換えるものではありません。 |
- 「保存」をクリックします。チャネルの作成に成功すると、ステータスが「実行中」と表示されます
同じ企業で複数のDingTalkチャネルインスタンスを作成できますが、同じDingTalkロボットのアイデンティティを同じ環境で重複して設定することはできません。Client ID、Client Secret、またはCorp IDを変更した後は、再検証して対応するチャットスペースを再度有効にする必要があります。名前、デフォルトモデル、またはチャネル入力の追加説明のみを変更した場合、検証済みのスペースが無効になることはありません。
4. ユーザーがDingTalkアカウントを連携する
管理者がチャネルの設定を完了すると、一般ユーザーはユーザーメニューの「チャネル連携」で自分のDingTalkアカウントを連携できます：
OAuth認証による連携
- AEのユーザーメニューを開いて「チャネル連携」に進み、「DingTalk」の下で対象のチャネルインスタンスを見つけて、「連携」をクリックします
- DingTalkのOAuth認証ページに移動するので、QRコードをスキャンするか、DingTalkアカウントにログインして認証を完了します
- 認証に成功すると自動的にプラットフォームに戻り、連携ステータスが「連携済み」に変わります
「連携」をクリックした後に連携コードのダイアログが表示された場合は、DingTalkでロボットとのプライベートチャットに、ダイアログ内の完全な連携コマンドを送信してください（連携コードの有効期間は10分です）。詳しくはチャネルの概要と連携をご覧ください。
5. グループチャットのメッセージ振り分け
グループチャットのメッセージ振り分けを使用すると、同じDingTalkロボットがルールに従って、さまざまな質問をそれぞれ異なるAgentまたはTeamに渡すことができます。1つの「チャットスペース」は設定内の企業CorpIdに対応し、ルールはその企業内でこのロボットを使用しているグループチャットに適用されます。Agentic Engineアカウントを連携済みで、グループ内でロボットを明示的に@メンションしたメンバーのみがタスクを開始できます。
管理者による設定
- アプリがStreamモードを使用していること、Client ID、Client Secret、CorpIdがすべて入力されていること、およびグループ基本情報、ロボットによるメッセージ送信、インタラクティブカード、AIカードのストリーミング更新など、本ドキュメントで前述した権限が有効になっていることを確認します。
- 「システム管理 → エージェント 管理者 → チャンネル管理」に進み、対象のDingTalkチャネルで「メッセージ振り分け」を開きます（ダイアログのタイトルは「グループチャットのメッセージ振り分け」）。検証に成功すると、CorpIdごとにチャットスペースが作成されます。
- 「既定の Agent/Team」を選択します。グループチャット振り分けを有効にする前に、既定の対象を設定する必要があります。
- 必要に応じて最大19件のルールを追加します。各ルールでAgent/Teamを1つ選択し、必須の「呼び出しコマンド」を入力します。キーワードも最大10個まで入力できます。その後、有効化スイッチをオンにして保存します。
- グループで
@机器人 /helpを送信して動作を確認します。
| 構成項目 | ルール |
|---|---|
| 既定の Agent/Team | 有効化する前に設定が必要です。呼び出しコマンドが指定されておらず、キーワードにも一致しない場合に使用されます。 |
| 呼び出しコマンド | 必須、1～32文字。英字、数字、-、_ を使用できます。システムの予約コマンドは使用できません。大文字・小文字や全角・半角の違いは、別のコマンドとして扱われません。 |
| キーワード | 入力は任意です。各ルール最大10個、1個あたり2～32文字。複数のキーワードが同時に一致した場合は、長いキーワードが優先されます。同じ長さで一意に判断できない場合は、既定の Agent/Team に戻ります。 |
| 選択可能な範囲 | 有効かつ実行可能なシステム/企業Agent、および現在の企業のTeamを選択できます。個人Agentは候補に表示されません。 |
グループチャットでの使い方
| 用途 | 例 | 説明 |
|---|---|---|
| 利用可能な機能を確認 | @机器人 /help@机器人 能力清单 | 現在のユーザーが使用でき、かつ現在実行可能な機能のみを表示します。 |
| Agent/Teamを指定 | @机器人 /analysis 分析本周数据 | @机器人 @analysis 分析本周数据 と送信することもできます。 |
| キーワードで振り分け | @机器人 帮我检查埋点方案 | キーワードに一致した場合は対応するルールを、一致しない場合は既定の対象を使用します。 |
| タスクを取消 | @机器人 /cancel | メッセージ全体をこのとおり正確に送信する必要があります。出力済みの本文は残り、取消の確認メッセージが別途送信されます。 |
| 旧形式との互換 | @机器人 /agent analysis 分析本周数据 | 引き続き使用できますが、/analysis を直接使用することを推奨します。 |
コマンドの範囲：グループチャット振り分けでは /new は使用できません。プライベートチャットでは引き続き /new、/agent、/cancel を使用できます。通常の新規タスクは、まずロボットを@メンションする必要があります。ユーザーの回答を待っている状態では、ロボットのカードまたはテキストの案内に従って続行します。
公開コンテキストと個人データ：システムが参考にするのは、最近ロボットを明示的に@メンションし、実際に処理されたグループチャットの公開ターンのみです。ロボットを@メンションしていない通常のグループメッセージ、他のグループ、プライベートチャット、ユーザーメモリが混ざることはありません。
6. よくある質問
チャネルのステータス異常 / 接続できない
- Client IDとClient Secretが正しく入力されているか確認します
- DingTalkオープンプラットフォームでのアプリのステータスが「Online」または「In Development」であることを確認します
OAuthコールバックに失敗する
- DingTalkアプリの「Security Settings」で、プラットフォームのサーバーIPがホワイトリストに追加されていることを確認します
- コールバックアドレスが正しく設定され、プラットフォームの実際のデプロイ先ドメインと完全に一致している（プロトコルとパスを含む）ことを確認します
ユーザーがアカウントを連携できない
- DingTalkアプリで関連する権限が有効になっていることを確認します
- アプリのコールバックアドレスが正しく設定されていることを確認します
関連ページと次のステップ
- 他のプラットフォームの接続手順を確認する：チャンネル管理。
- チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
- 使用するAgentを設定する：Agent。
- プラットフォーム内での会話の使い方を確認する：会話。