# 串接對話平台：Microsoft Teams

## 串接前確認 <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* 已在 [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 資源 <a href="#step-create-azure-bot-resource" id="step-create-azure-bot-resource"></a>

### 1. 建立 Azure Bot <a href="#step-create-azure-bot" id="step-create-azure-bot"></a>

登入 [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="/files/7VJ3VxkB7kCGl2MmdnaT" alt=""><figcaption><p>AI Foundry 中選擇 Azure Bot</p></figcaption></figure>

<figure><img src="/files/sCXIqaMKSbhGeEJhd8ME" alt=""><figcaption><p>選擇訂閱方案並建立 Azure Bot</p></figcaption></figure>

### 2. 填寫 Bot 建立表單 <a href="#step-fill-bot-creation-form" id="step-fill-bot-creation-form"></a>

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

<figure><img src="/files/cIzQuW2GBxD5qfYTZRPm" alt=""><figcaption><p>填寫 Azure Bot 建立表單</p></figcaption></figure>

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

***

## 步驟二：取得 App ID 與密碼 <a href="#step-get-app-id-and-secret" id="step-get-app-id-and-secret"></a>

### 1. 取得 Microsoft App ID <a href="#step-get-microsoft-app-id" id="step-get-microsoft-app-id"></a>

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

<figure><img src="/files/zh77R210bqbHAuyt5oBQ" alt=""><figcaption><p>Azure Bot 組態 — 取得 Microsoft App ID</p></figcaption></figure>

### 2. 建立用戶端密碼 <a href="#step-create-client-secret" id="step-create-client-secret"></a>

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

<figure><img src="/files/Oi6VayTiB8DF7M5YSkX6" alt=""><figcaption><p>建立用戶端密碼（Signing Secret）</p></figcaption></figure>

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

***

## 步驟三：設定 API 權限 <a href="#step-configure-api-permissions" id="step-configure-api-permissions"></a>

### 1. 進入應用程式註冊 <a href="#step-go-to-app-registration" id="step-go-to-app-registration"></a>

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

<figure><img src="/files/NPH3SfiZQSKow4Onqz9j" alt=""><figcaption><p>Microsoft Entra ID — 應用程式註冊</p></figcaption></figure>

### 2. 新增 API 權限 <a href="#step-add-api-permissions" id="step-add-api-permissions"></a>

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

<figure><img src="/files/0ca6rW8Ri8Hftk1WyJ3c" alt=""><figcaption><p>API 權限頁面</p></figcaption></figure>

### 3. 選擇 Microsoft Graph <a href="#step-select-microsoft-graph" id="step-select-microsoft-graph"></a>

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

<figure><img src="/files/pyTeY4UBk6mUMawtJRmF" alt=""><figcaption><p>選擇應用程式權限</p></figcaption></figure>

<figure><img src="/files/bPdDCjLxOtoPAlO0yF15" alt=""><figcaption><p>新增 User.Read.All 權限</p></figcaption></figure>

### 4. 授與管理員同意 <a href="#step-grant-admin-consent" id="step-grant-admin-consent"></a>

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

<figure><img src="/files/sEQkxpyAeB7mcRZqUTv1" alt=""><figcaption><p>授與管理員同意後，狀態顯示綠色勾號</p></figcaption></figure>

***

## 步驟四：在 MaiAgent 建立 Teams 對話平台 <a href="#step-create-teams-channel-in-maiagent" id="step-create-teams-channel-in-maiagent"></a>

### 1. 進入串接對話平台 <a href="#step-go-to-channel-integration" id="step-go-to-channel-integration"></a>

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

### 2. 填寫基本設定 <a href="#step-fill-basic-settings" id="step-fill-basic-settings"></a>

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

### 3. 儲存並取得 Webhook URL <a href="#step-save-and-get-webhook-url" id="step-save-and-get-webhook-url"></a>

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

***

## 步驟五：回到 Azure 設定訊息端點與頻道 <a href="#step-configure-message-endpoint-and-channel-in-azure" id="step-configure-message-endpoint-and-channel-in-azure"></a>

### 1. 設定訊息端點 <a href="#step-set-message-endpoint" id="step-set-message-endpoint"></a>

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

<figure><img src="/files/Qaz75sns0SAo0nouLt8h" alt=""><figcaption><p>Bot 設定檔 — 填入訊息端點（Webhook URL）</p></figcaption></figure>

### 2. 啟用 Microsoft Teams 頻道 <a href="#step-enable-microsoft-teams-channel" id="step-enable-microsoft-teams-channel"></a>

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

<figure><img src="/files/km3Epeg2AraO4BdZA9HV" alt=""><figcaption><p>頻道設定 — Microsoft Teams 頻道已連接</p></figcaption></figure>

***

## 步驟六：在 Teams 中安裝 Bot <a href="#step-install-bot-in-teams" id="step-install-bot-in-teams"></a>

### 方法一：透過 Teams Admin Center 上傳 <a href="#method-upload-via-teams-admin-center" id="method-upload-via-teams-admin-center"></a>

如果需要讓組織內的所有使用者使用，可透過 [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="/files/WJNCU4tYQH3qAB9gywPs" alt=""><figcaption><p>Teams Admin Center — 管理應用程式</p></figcaption></figure>

<figure><img src="/files/tNMwk8zukAeeokHSSqdg" 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 應用程式搜尋 <a href="#method-search-via-teams-app" id="method-search-via-teams-app"></a>

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="/files/gX5Q5sQqFSzm6rOFEhWa" alt=""><figcaption><p>在 Teams 應用程式中搜尋並安裝 Bot</p></figcaption></figure>

<figure><img src="/files/f69ORqMO6pIp0NVmR4mm" alt=""><figcaption><p>確認安裝 Bot 並查看權限</p></figcaption></figure>

***

## 開始使用 <a href="#getting-started" id="getting-started"></a>

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

<figure><img src="/files/hwXf7Lk6OPmTT0LBxbDX" alt=""><figcaption><p>在 Teams 中與 MaiAgent Bot 開始對話</p></figcaption></figure>

<figure><img src="/files/POMWdES7sVrtOkoVcf7y" alt=""><figcaption><p>Teams 對話示範 — AI 助理自動回覆</p></figcaption></figure>

***

## 重要注意事項 <a href="#important-notes" id="important-notes"></a>

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

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

**限制說明**

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

**疑難排解**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/conversations/teams.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.