# 串接對話平台：Slack

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

* 已在 [MaiAgent 平台](https://admin.maiagent.ai/)上建立好一個「AI 助理」
* 已擁有 Slack 工作空間（Workspace）的管理員權限

## 步驟一：建立 Slack App <a href="#step-create-slack-app" id="step-create-slack-app"></a>

### 1. 前往 Slack API 建立 App <a href="#step-go-to-slack-api" id="step-go-to-slack-api"></a>

前往 <https://api.slack.com/apps>，點擊 <mark style="color:blue;">Create an App</mark>。

<figure><img src="/files/OtWhptIOuToUQpPJ7r0v" alt=""><figcaption><p>Slack API — Your Apps 頁面</p></figcaption></figure>

### 2. 選擇 From scratch <a href="#step-create-from-scratch" id="step-create-from-scratch"></a>

選擇 <mark style="color:blue;">From scratch</mark>，使用圖形介面手動設定。

<figure><img src="/files/h5EuFoXByb1Nfm1OSvI2" alt=""><figcaption><p>選擇 From scratch 建立方式</p></figcaption></figure>

### 3. 填寫 App 名稱與工作空間 <a href="#step-fill-app-name-and-workspace" id="step-fill-app-name-and-workspace"></a>

輸入 App 名稱（例如 `MaiAgentBot`），並選擇要安裝的 Slack 工作空間，點擊 <mark style="color:blue;">Create App</mark>。

<figure><img src="/files/XJdeBhecufsSmBSkCJ00" alt=""><figcaption><p>填寫 App 名稱並選擇工作空間</p></figcaption></figure>

### 4. 取得 Signing Secret <a href="#step-get-signing-secret" id="step-get-signing-secret"></a>

建立完成後，進入 <mark style="color:blue;">Basic Information</mark> 頁面，在 **App Credentials** 區塊找到 <mark style="color:blue;">Signing Secret</mark>，點擊 <mark style="color:blue;">Show</mark> 後複製備用。

<figure><img src="/files/XrzMKOLPs5STFsQ1Ez3e" alt=""><figcaption><p>App Credentials — 複製 Signing Secret</p></figcaption></figure>

***

## 步驟二：設定 Bot 權限 <a href="#step-configure-bot-permissions" id="step-configure-bot-permissions"></a>

### 1. 進入 OAuth & Permissions <a href="#step-go-to-oauth-permissions" id="step-go-to-oauth-permissions"></a>

在左側選單點選 <mark style="color:blue;">OAuth & Permissions</mark>。

<figure><img src="/files/eyyIQ5hssiitk30SOSYq" alt=""><figcaption><p>OAuth &#x26; Permissions 頁面</p></figcaption></figure>

### 2. 新增 Bot Token Scopes <a href="#step-add-bot-token-scopes" id="step-add-bot-token-scopes"></a>

往下捲動到 **Bot Token Scopes** 區塊，點擊 <mark style="color:blue;">Add an OAuth Scope</mark>，依序新增以下權限：

| Scope               | 說明            |
| ------------------- | ------------- |
| `app_mentions:read` | 讀取 @ 提及機器人的訊息 |
| `channels:history`  | 讀取公開頻道的訊息歷史   |
| `chat:write`        | 發送訊息          |
| `files:read`        | 讀取檔案（圖片/文件）   |
| `groups:history`    | 讀取私人頻道的訊息歷史   |
| `im:history`        | 讀取私訊的訊息歷史     |
| `mpim:history`      | 讀取群組私訊的歷史     |

<figure><img src="/files/0XjjZqNkt3QweYWLISKS" alt=""><figcaption><p>Bot Token Scopes 權限設定</p></figcaption></figure>

### 3. 安裝 App 到工作空間 <a href="#step-install-app-to-workspace" id="step-install-app-to-workspace"></a>

捲動回頁面上方，點擊 <mark style="color:blue;">Install to Workspace</mark>（或 Reinstall to Workspace）。

<figure><img src="/files/7HphyVLDwszjarlW6uQk" alt=""><figcaption><p>Install App 頁面</p></figcaption></figure>

Slack 會跳轉至授權頁面，確認權限後點擊 <mark style="color:blue;">允許</mark>。

<figure><img src="/files/FBSzPld0kCNFUQoAeSeG" alt=""><figcaption><p>授權 App 存取工作空間</p></figcaption></figure>

### 4. 複製 Bot User OAuth Token <a href="#step-copy-bot-user-oauth-token" id="step-copy-bot-user-oauth-token"></a>

安裝完成後，回到 <mark style="color:blue;">OAuth & Permissions</mark> 頁面，複製 <mark style="color:blue;">Bot User OAuth Token</mark>（格式為 `xoxb-...`）。

<figure><img src="/files/L8lcpbgarZ7pmDOdXsVa" alt=""><figcaption><p>複製 Bot User OAuth Token</p></figcaption></figure>

***

## 步驟三：設定 App Home（啟用私訊） <a href="#step-configure-app-home" id="step-configure-app-home"></a>

進入左側選單 <mark style="color:blue;">App Home</mark> 頁面，在 **Show Tabs** 區塊中：

1. 開啟 <mark style="color:blue;">Messages Tab</mark>
2. 勾選 <mark style="color:blue;">Allow users to send Slash commands and messages from the messages tab</mark>

<figure><img src="/files/VHs96ZqZOlgTDGSba3E3" alt=""><figcaption><p>啟用 Messages Tab 讓使用者能私訊 Bot</p></figcaption></figure>

{% hint style="warning" %}
此步驟必須完成，否則使用者無法透過私訊與 Bot 互動。
{% endhint %}

***

## 步驟四：在 MaiAgent 建立 Slack 對話平台 <a href="#step-create-slack-channel-in-maiagent" id="step-create-slack-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;">Slack</mark>。

<figure><img src="/files/LRwWtpDmRfe2b3Egf8yE" alt=""><figcaption><p>MaiAgent Slack 串接設定畫面</p></figcaption></figure>

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

| 欄位                       | 說明                          |
| ------------------------ | --------------------------- |
| **名稱**                   | 為此串接取一個名稱（必填）               |
| **AI 助理**                | 選擇要綁定的 AI 助理                |
| **Bot User OAuth Token** | 貼上步驟二取得的 Bot Token（必填）      |
| **Signing Secret**       | 貼上步驟一取得的 Signing Secret（必填） |

### 3. 驗證憑證 <a href="#step-verify-credentials" id="step-verify-credentials"></a>

點擊 <mark style="color:blue;">驗證憑證</mark> 按鈕，確認 Token 和 Secret 正確無誤。

### 4. 聊天室設定 <a href="#step-chat-room-settings" id="step-chat-room-settings"></a>

| 設定                 | 說明                         |
| ------------------ | -------------------------- |
| **群組中僅在被 @ 提及時回應** | 開啟後，Bot 在群組頻道中只有被 @ 提及時才回應 |
| **啟用重置命令**         | 開啟後，使用者可透過指令重新開始對話         |

### 5. 儲存並取得 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**，請複製備用。

***

## 步驟五：回到 Slack App 設定 Event Subscriptions <a href="#step-configure-event-subscriptions" id="step-configure-event-subscriptions"></a>

### 1. 啟用 Events <a href="#step-enable-events" id="step-enable-events"></a>

在 Slack App 左側選單點選 <mark style="color:blue;">Event Subscriptions</mark>，開啟 <mark style="color:blue;">Enable Events</mark>。

<figure><img src="/files/IJ7wErG7rVNlsCh4BzIa" alt=""><figcaption><p>Event Subscriptions 設定頁面</p></figcaption></figure>

### 2. 貼上 Request URL <a href="#step-paste-request-url" id="step-paste-request-url"></a>

將 MaiAgent 產生的 **Webhook URL** 貼入 <mark style="color:blue;">Request URL</mark> 欄位。Slack 會自動驗證，顯示 <mark style="color:green;">Verified ✓</mark> 表示設定成功。

<figure><img src="/files/JyRV5R42WRJvAHzqna8l" alt=""><figcaption><p>Request URL 驗證成功</p></figcaption></figure>

### 3. 訂閱 Bot Events <a href="#step-subscribe-bot-events" id="step-subscribe-bot-events"></a>

展開 **Subscribe to bot events** 區塊，點擊 <mark style="color:blue;">Add Bot User Event</mark>，新增以下事件：

| Event              | 說明         |
| ------------------ | ---------- |
| `message.im`       | 私訊中的新訊息    |
| `message.channels` | 公開頻道中的新訊息  |
| `message.groups`   | 私人頻道中的新訊息  |
| `message.mpim`     | 群組私訊中的新訊息  |
| `app_mention`      | 在頻道中被 @ 提及 |

<figure><img src="/files/cIm3usZ6B00B449BBXm6" alt=""><figcaption><p>訂閱 Bot Events</p></figcaption></figure>

### 4. 儲存變更 <a href="#step-save-changes" id="step-save-changes"></a>

點擊 <mark style="color:blue;">Save Changes</mark> 完成設定。

{% hint style="warning" %}
儲存後 Slack 可能會要求重新安裝 App，請點擊頁面頂部提示重新安裝以套用新權限。
{% endhint %}

***

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

串接完成後，您可以透過以下方式與 AI 助理互動：

### 私訊對話 <a href="#direct-message-conversation" id="direct-message-conversation"></a>

直接在 Slack 中私訊 Bot，AI 助理會自動回覆。支援傳送文字、圖片和檔案。

<figure><img src="/files/nagFOZ75qZx0OH8nuVbP" alt=""><figcaption><p>Slack 私訊對話 — AI 助理自動回覆（支援圖片辨識）</p></figcaption></figure>

### 檔案上傳與分析 <a href="#file-upload-and-analysis" id="file-upload-and-analysis"></a>

使用者可在對話中上傳 Excel、PDF 等檔案，AI 助理能讀取檔案內容並回答相關問題。

<figure><img src="/files/3uYSCkHnWd56xhcfV1pq" alt=""><figcaption><p>上傳 Excel 檔案，AI 助理自動分析內容</p></figcaption></figure>

### 頻道 @ 提及 <a href="#channel-mention" id="channel-mention"></a>

在頻道中 `@Bot名稱 你的問題`，AI 助理會在頻道中回覆。

{% hint style="info" %}
如需將 Bot 加入特定頻道，請在該頻道中輸入 `/invite @Bot名稱`，或在頻道設定 → 整合 → 新增應用程式中加入。
{% 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/slack.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.