# 串接對話平台：Microsoft Teams

## 串接前確認

* 已在 [MaiAgent 平台](https://admin.maiagent.ai/)上建立好一個「AI 助理」
* 擁有 Microsoft 365 帳號（企業版或教育版）
* 擁有 [Microsoft Azure Portal](https://portal.azure.com/) 帳號與管理權限
* 擁有 Microsoft Entra ID（舊稱 Azure AD）的應用程式註冊權限

{% hint style="warning" %}
Teams Bot 需要組織等級的 Microsoft 365 帳號，個人帳號無法使用。
{% endhint %}

***

## 步驟一：在 Azure 建立 Bot 資源

### 1. 建立 Azure Bot

登入 [Azure Portal](https://portal.azure.com/)，搜尋 <mark style="color:blue;">AI Foundry</mark>（或 Bot Services），找到 <mark style="color:blue;">Azure Bot</mark> 並點擊 <mark style="color:blue;">建立</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a6b8201b7559370de56135b5eddb0f5f35677dc5%2Fteams-azure-ai-foundry.png?alt=media" alt=""><figcaption><p>AI Foundry 中選擇 Azure Bot</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-dfa3dd51c9524c7d938ca175db404d0c01957511%2Fteams-azure-bot-create.png?alt=media" alt=""><figcaption><p>選擇訂閱方案並建立 Azure Bot</p></figcaption></figure>

### 2. 填寫 Bot 建立表單

| 欄位                   | 說明                                  |
| -------------------- | ----------------------------------- |
| **Bot 控制代碼**         | 輸入唯一的 Bot 名稱（例如 `MaiAgentTeamsBot`） |
| **訂用帳戶**             | 選擇您的 Azure 訂用帳戶                     |
| **資源群組**             | 選擇現有或建立新的資源群組                       |
| **定價層**              | 建議選擇 F0（免費）                         |
| **Microsoft App ID** | 選擇「建立新的 Microsoft App ID」或使用現有的     |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-44e925d412f43e2dc52e50698203c4a8dcd5d775%2Fteams-azure-bot-create-form.png?alt=media" alt=""><figcaption><p>填寫 Azure Bot 建立表單</p></figcaption></figure>

點擊 <mark style="color:blue;">檢閱 + 建立</mark>，確認後點擊 <mark style="color:blue;">建立</mark>。

***

## 步驟二：取得 App ID 與密碼

### 1. 取得 Microsoft App ID

建立完成後，進入 Azure Bot 資源，點選 <mark style="color:blue;">組態</mark>，可看到 **Microsoft App ID**，複製備用。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-65746c32cdcbed8f0cba98794cee1c41b234b31f%2Fteams-azure-bot-overview.png?alt=media" alt=""><figcaption><p>Azure Bot 組態 — 取得 Microsoft App ID</p></figcaption></figure>

### 2. 建立用戶端密碼

點選 <mark style="color:blue;">憑證及祕密</mark>（或在 Microsoft Entra ID → 應用程式註冊中找到對應的 App），點擊 <mark style="color:blue;">新增用戶端密碼</mark>，設定描述和到期時間後點擊 <mark style="color:blue;">新增</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a681dddbb5cf7b0c957254f6ac3dcf84e82e24f0%2Fteams-azure-bot-secret.png?alt=media" alt=""><figcaption><p>建立用戶端密碼（Signing Secret）</p></figcaption></figure>

{% hint style="danger" %}
用戶端密碼的「值」只會顯示一次，請務必立即複製並妥善保存。
{% endhint %}

***

## 步驟三：設定 API 權限

### 1. 進入應用程式註冊

在 Azure Portal 搜尋 <mark style="color:blue;">Microsoft Entra ID</mark>，進入 <mark style="color:blue;">應用程式註冊</mark>，找到與 Bot 對應的應用程式。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0b6d5b3a95f88bbb1e65168287a928243f9b3847%2Fteams-app-registration.png?alt=media" alt=""><figcaption><p>Microsoft Entra ID — 應用程式註冊</p></figcaption></figure>

### 2. 新增 API 權限

點選左側選單 <mark style="color:blue;">API 權限</mark>，點擊 <mark style="color:blue;">新增權限</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-36a68f1e4814ea8a7855fa6465790c7d8f52f218%2Fteams-api-permissions.png?alt=media" alt=""><figcaption><p>API 權限頁面</p></figcaption></figure>

### 3. 選擇 Microsoft Graph

選擇 <mark style="color:blue;">Microsoft Graph</mark> → <mark style="color:blue;">應用程式權限</mark>，搜尋 `User.Read.All` 並勾選，點擊 <mark style="color:blue;">新增權限</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ad2728808d2ea3f029fef43b87186fbef7aa9a86%2Fteams-api-graph-app.png?alt=media" alt=""><figcaption><p>選擇應用程式權限</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6d332047c7c35032e743206f31070197fe7ea3b2%2Fteams-api-user-read.png?alt=media" alt=""><figcaption><p>新增 User.Read.All 權限</p></figcaption></figure>

### 4. 授與管理員同意

回到 API 權限頁面，點擊 <mark style="color:blue;">代表 {組織名稱} 授與管理員同意</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-48ebb223a764ac528d656543644ac81ae1da5556%2Fteams-api-admin-consent.png?alt=media" alt=""><figcaption><p>授與管理員同意後，狀態顯示綠色勾號</p></figcaption></figure>

***

## 步驟四：在 MaiAgent 建立 Teams 對話平台

### 1. 進入串接對話平台

在 MaiAgent 左側選單點選 <mark style="color:blue;">對話平台</mark>，點擊 <mark style="color:blue;">串接對話平台</mark>，選擇 <mark style="color:blue;">Azure Bot</mark>（即 Microsoft Teams）。

### 2. 填寫基本設定

| 欄位                         | 說明                  |
| -------------------------- | ------------------- |
| **名稱**                     | 為此串接取一個名稱（必填）       |
| **AI 助理**                  | 選擇要綁定的 AI 助理        |
| **Microsoft App ID**       | 貼上步驟二取得的應用程式 ID（必填） |
| **Microsoft App Password** | 貼上步驟二取得的用戶端密碼（必填）   |

### 3. 儲存並取得 Webhook URL

點擊 <mark style="color:blue;">串接對話平台</mark> 完成建立。系統會產生 **Webhook URL**，複製備用。

***

## 步驟五：回到 Azure 設定訊息端點與頻道

### 1. 設定訊息端點

回到 Azure Bot 資源，進入 <mark style="color:blue;">Bot 設定檔</mark>（組態），將 MaiAgent 產生的 **Webhook URL** 貼入 <mark style="color:blue;">訊息端點</mark> 欄位，點擊 <mark style="color:blue;">套用</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-992d6759f4e7c83a6db8537b15f2c5f152c6e5af%2Fteams-azure-bot-config.png?alt=media" alt=""><figcaption><p>Bot 設定檔 — 填入訊息端點（Webhook URL）</p></figcaption></figure>

### 2. 啟用 Microsoft Teams 頻道

在左側選單點選 <mark style="color:blue;">頻道</mark>，確認 <mark style="color:blue;">Microsoft Teams</mark> 頻道已啟用且狀態為 Healthy。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f26de3e067c7179a269a80a17a6feb3d60c55f03%2Fteams-azure-bot-channels.png?alt=media" alt=""><figcaption><p>頻道設定 — Microsoft Teams 頻道已連接</p></figcaption></figure>

***

## 步驟六：在 Teams 中安裝 Bot

### 方法一：透過 Teams Admin Center 上傳

如果需要讓組織內的所有使用者使用，可透過 [Teams Admin Center](https://admin.teams.microsoft.com/) 上傳 App Manifest：

1. 登入 [Teams Admin Center](https://admin.teams.microsoft.com/)，進入 <mark style="color:blue;">Manage apps</mark>
2. 點擊 <mark style="color:blue;">Upload new app</mark>，上傳 Teams App Manifest（.zip 檔案）

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-37ca47c8942e8477fb60e6cc35760ab1a09bc684%2Fteams-admin-manage-apps.png?alt=media" alt=""><figcaption><p>Teams Admin Center — 管理應用程式</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2eaf92950341522717338b112937ced5f6d22dbb%2Fteams-admin-app-detail.png?alt=media" alt=""><figcaption><p>上傳的 App 詳細資訊</p></figcaption></figure>

{% hint style="info" %}
Teams App Manifest 範本可從 [Google Drive](https://drive.google.com/drive/folders/1E2i3y15oC65xu_5zFIXN7yG9KBgp34KB) 下載，需修改其中的 Bot ID 為您的 Microsoft App ID。
{% endhint %}

### 方法二：透過 Teams 應用程式搜尋

1. 開啟 Microsoft Teams，點選左側 <mark style="color:blue;">應用程式</mark>
2. 搜尋您的 Bot 名稱
3. 點擊 <mark style="color:blue;">開啟</mark> 或 <mark style="color:blue;">新增</mark> 安裝 Bot

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3f22113647406122ab40971cbff5446a4b0d363b%2Fteams-bot-add-app.png?alt=media" alt=""><figcaption><p>在 Teams 應用程式中搜尋並安裝 Bot</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d2d152d29c9716353afc60ff408523a9bdd9e225%2Fteams-bot-install.png?alt=media" alt=""><figcaption><p>確認安裝 Bot 並查看權限</p></figcaption></figure>

***

## 開始使用

安裝完成後，在 Teams 聊天列表中可找到 Bot，直接傳送訊息即可與 AI 助理互動。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ce7c42ac63d5209f50b094f2ca0c2e1d6e04974b%2Fteams-bot-chat-start.png?alt=media" alt=""><figcaption><p>在 Teams 中與 MaiAgent Bot 開始對話</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b03c42f1963159064dc5abc8b1e3ffbf85ce8a3a%2Fteams-bot-chat-demo.png?alt=media" alt=""><figcaption><p>Teams 對話示範 — AI 助理自動回覆</p></figcaption></figure>

***

## 重要注意事項

{% hint style="warning" %}
**安全性**

* 用戶端密碼請妥善保管，切勿公開分享
* 建議定期更新用戶端密碼

**限制說明**

* Bot 在團隊頻道中須被 @ 提及才會回應（一對一私訊不需要）
* Azure Bot Service 免費層（F0）每月可處理 10,000 則訊息

**疑難排解**

* **Bot 無法回應**：確認 Webhook URL（訊息端點）設定正確
* **無法在 Teams 找到 Bot**：確認已在 Teams Admin Center 上傳 Manifest 並核准
* **權限錯誤**：確認 API 權限已授與管理員同意
  {% endhint %}