メッセージチャネル連携

​

チャネル認可と Channel Pairing の区別

​

QR コードバインディングのフロー（推奨）

1. Channel を作成する: Channel の作成 API を呼び出し、name、channel_type、および希望する Identity 解決モードを渡します。channel_config.credentials は省略します。fixed モードでは identity_id と template_id も渡します。pairing モードでは identity_resolution.mode=pairing を渡し、identity_id や template_id は渡しません。
2. QR Session を作成する: Channel QR Session の作成 API を呼び出し、qr_code_image_base64（QR コード画像）または qr_code_content（認可 URL）を取得します。poll_interval_seconds はオプションの互換性フィールドであり、安定した返却値として依存すべきではありません。
3. QR コードを表示して認可する: QR コードをユーザーに表示し、対応するチャネルのクライアントで QR コードを読み取り、認可を確認します。
4. 認可状態をポーリングする: Channel QR Session の取得 を呼び出し、status をポーリングします。poll_interval_seconds がある場合はその値を使用し、なければデフォルトの 3 秒間隔でポーリングします。confirmed になるまで継続します（他の状態: waiting、scanned、expired、denied、error）。
5. チャネル認可を完了する: status=confirmed の後に Channel の詳細を再取得すると、binding_status が bound になります。fixed モードの Channel は固定の実行コンテキストで受信メッセージを処理できます。pairing モードの Channel はペアリングされていないメッセージに対してペアリングコードを返します。メッセージが Agent に到達する前に Channel Pairing（下記）を完了してください。

​

Identity 解決モード

​

fixed モード

{
  "identity_id": "idn_019eabc123",
  "identity_resolution": {
    "mode": "fixed"
  },
  "template_id": "tmpl_support",
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}

​

pairing モード

{
  "identity_resolution": {
    "mode": "pairing"
  },
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}

1. ユーザーが実際の IM の個人チャットまたはグループチャットからボットにメッセージを送信します。
2. Channel Gateway はペアリングされていない direct/room スコープにペアリング待ちのレコードを作成し、ペアリングコードの案内を送信します。Session は作成されません。
3. 管理者が Channel のペアリング API を code + identity_id + template_id で呼び出します。認可を自動化する場合は、先にペアリングの一覧を取得し、channel_id + scope_type + scope_external_id を独自のルールと照合してから、channel_pairing_id + identity_id + template_id を送信できます。
4. 以降のメッセージは Pairing を通じて Identity と Template を解決し、Session を作成または再利用します。
5. バインディングを解除するには、Pair レスポンスの id を使用して Channel のペアリング解除 API を呼び出します。

​

直接認証情報による連携（必要に応じて）

​

DingTalk

​

DingTalk アプリを作成する

1. DingTalk 開放プラットフォーム にアクセスします。開発者権限を持つ組織を選択するか、いずれかの組織を選択して開発者権限を取得してください。適切な組織がない場合は、モバイル版 DingTalk で QR コードをスキャンして組織を素早く作成できます。
2. トップナビゲーションの アプリ開発 をクリックし、DingTalk アプリのページで アプリを作成 をクリックします。

​

DingTalk ボットを作成する

1. アプリを作成したら、左側ナビゲーションで アプリ機能を追加 を選択し、右側のボットカード下の 追加 ボタンをクリックします。
2. ボット設定ページで、ボット設定を有効にします。
3. メッセージ受信モード で Stream モード を選択し、公開 をクリックしてボット設定を完了します。

​

権限を設定する

​

アプリを公開する

1. 左側ナビゲーションで バージョン管理と公開 を選択し、新規バージョンを作成 をクリックします。
2. アプリのバージョン番号とバージョン説明を入力し、業務のニーズに応じてアプリの利用可能範囲を選択し、保存 をクリックして公開を完了します。

​

認証情報を取得する

​

Feishu

​

Feishu アプリを作成する

1. Feishu 開放プラットフォーム にアクセスし、右上の 開発者コンソール をクリックします。
2. 企業向けカスタムアプリを作成 をクリックし、必要な情報を入力して 作成 をクリックします。

​

ボットの追加と設定

1. 左側ナビゲーションで アプリ機能を追加 を選択し、ボットカードの 追加 ボタンをクリックします。
2. ボット設定カードの「利用の始め方」の右側にある編集アイコンをクリックします。
3. メッセージカードのコールバックリクエスト方式 領域で 設定へ をクリックし、購読方式として 長時間接続によるコールバック受信 を選択して保存します。
4. イベント設定 をクリックし、購読方式として同様に 長時間接続によるコールバック受信 を選択して保存します。
5. イベント設定ページで、次の 4 つのイベントを追加して保存します:
   • ボットがグループに参加
   • ボットがグループから削除
   • メッセージ既読
   • メッセージ受信

​

権限を設定する

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access",
      "base:app:copy",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:record:create",
      "base:record:delete",
      "base:record:retrieve",
      "base:record:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "base:app:create",
      "base:app:update",
      "base:app:read",
      "board:whiteboard:node:create",
      "board:whiteboard:node:read",
      "calendar:calendar:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user:search",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.media:download",
      "docs:document:copy",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:file:download",
      "drive:file:upload",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly",
      "search:docs:read",
      "search:message",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "task:comment:read",
      "task:comment:write",
      "task:task:read",
      "task:task:write",
      "task:task:writeonly",
      "task:tasklist:read",
      "task:tasklist:write",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only"
    ]
  }
}

​

アプリを公開する

1. 左側ナビゲーションで バージョン管理と公開 を選択します。
2. バージョンを作成 をクリックし、必要な情報を入力して 保存 をクリックします。

​

認証情報を取得する

​

WeCom

​

スマートボットを作成する

1. WeCom 管理コンソール にアクセスし、左側ナビゲーションで セキュリティと管理 > 管理ツール をクリックし、ボットを作成 をクリックしてから 手動で作成 をクリックします。
2. ボットの表示範囲を設定します。
3. ページの下部までスクロールして API モードで作成 をクリックし、接続方法として 長時間接続を使用 を選択します。

​

認証情報を取得する

​

個人 WeChat

​

Microsoft Teams 連携

​

Microsoft Entra アプリケーションを作成する

1. Microsoft Entra 管理センター を開き、対象テナントでアプリ登録を作成します。
2. Supported account types を Single tenant に設定します。
3. Application (client) ID と Directory (tenant) ID を記録し、それぞれ app_id と tenant_id として使用します。
4. Certificates & secrets で Client secret を作成し、その Value を client_secret として記録します。

​

ファイル送受信に必要な Microsoft Graph 権限を設定する

1. Microsoft Entra 管理センターで対象のアプリ登録を開き、API permissions に移動します。
2. Add a permission > Microsoft Graph > Application permissions を選択します。
3. Sites.ReadWrite.All と ChatMember.Read.All を追加します。
4. テナント管理者が Grant admin consent を選択し、両方の権限が付与済みになっていることを確認します。

​

Azure Bot を作成して設定する

1. Azure Portal で Azure Bot を作成し、Microsoft App Type に Single Tenant を選択します。
2. Entra アプリケーションの App ID と Tenant ID を Azure Bot に関連付けます。
3. Configuration で、Messaging endpoint に Global 環境から提供された完全な Teams コールバック URL を設定します。パスは /channels/teams/messages です。
4. Azure Bot で Microsoft Teams チャネルを有効にします。

​

Teams アプリを作成して公開する

1. Developer Portal for Teams を開き、Teams アプリを作成します。
2. Bot capability を追加し、Azure Bot と同じ App ID を関連付けます。
3. 必要な personal、team、groupChat スコープを選択します。
4. Teams アプリの manifest の Bot 設定で supportsFiles: true を指定し、個人チャットでの FileConsent によるファイル送受信を有効にします。
5. manifest v1.12 以降で、グループチャットとチャネルの受信ファイルを解析するための RSC メッセージ読み取り権限を宣言します。グループチャットには ChatMessage.Read.Chat、標準 Team チャネルには ChannelMessage.Read.Group を使用します。
6. アプリパッケージをダウンロードし、顧客の Teams 管理センターまたは組織の App catalog から公開して、対象の個人チャット、グループチャット、または Team にインストールします。manifest の権限を更新した後は、アプリを再公開し、対象のグループチャットまたは Team で再インストールまたは再同意が必要です。

{
  "webApplicationInfo": {
    "id": "<Application (client) ID>",
    "resource": "api://<Application (client) ID>"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "ChatMessage.Read.Chat",
          "type": "Application"
        },
        {
          "name": "ChannelMessage.Read.Group",
          "type": "Application"
        }
      ]
    }
  },
  "bots": [
    {
      "botId": "<Application (client) ID>",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true
    }
  ]
}

​

Teams Channel を作成する

• Microsoft Graph permissions reference
• Send and receive files
• Get chatMessage in a channel or chat
• Grant RSC permissions to an app

​

関連