# 串接對話平台：Email

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

* 已在 [MaiAgent 平台](https://admin.maiagent.ai/)上建立好一個「AI 助理」
* 已準備好要串接的電子郵件帳號（Gmail、Outlook、Yahoo 或自訂郵件伺服器）
* 若使用 Gmail 或 Outlook，需先產生**應用程式專用密碼**（非帳號密碼）

{% hint style="warning" %}
Gmail 必須使用 16 位數的應用程式專用密碼，無法使用 Google 帳號密碼登入。請先至 [Google 帳號安全性](https://myaccount.google.com/apppasswords) 產生專用密碼。
{% endhint %}

## 開始串接 <a href="#start-integration" id="start-integration"></a>

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

在左側選單點選 <mark style="color:blue;">對話平台</mark>，點擊右上角 <mark style="color:blue;">串接對話平台</mark> 按鈕。

### 2. 選擇 Email <a href="#step-select-email" id="step-select-email"></a>

在平台選擇頁面中，點擊 <mark style="color:blue;">Email</mark>。

<figure><img src="/files/faGajEvGgIr4Or7yUsGD" alt=""><figcaption><p>Email 串接設定畫面</p></figcaption></figure>

### 3. 選擇郵件服務商 <a href="#step-select-email-provider" id="step-select-email-provider"></a>

從 <mark style="color:blue;">郵件服務商</mark> 下拉選單中選擇：

| 服務商                      | 說明                               |
| ------------------------ | -------------------------------- |
| **Gmail**                | Google 信箱，需使用應用程式專用密碼            |
| **Outlook / Office 365** | Microsoft 信箱，啟用兩步驟驗證時需使用應用程式專用密碼 |
| **Yahoo Mail**           | Yahoo 信箱，需使用應用程式專用密碼             |
| **自訂**                   | 自行設定 IMAP/SMTP 伺服器參數             |

選擇服務商後，系統會自動填入對應的 IMAP 和 SMTP 伺服器設定。

### 4. 填寫連線資訊 <a href="#step-fill-connection-info" id="step-fill-connection-info"></a>

#### 電子郵件地址 <a href="#email-address" id="email-address"></a>

輸入要串接的完整郵件地址，例如 `support@yourcompany.com`。

#### IMAP 設定（收信） <a href="#imap-settings" id="imap-settings"></a>

| 欄位            | 說明                                |
| ------------- | --------------------------------- |
| **IMAP 伺服器**  | 收信伺服器位址（Gmail 為 `imap.gmail.com`） |
| **IMAP Port** | 連接埠號（通常為 993）                     |
| **使用 SSL**    | 建議開啟以確保傳輸安全                       |

#### SMTP 設定（寄信） <a href="#smtp-settings" id="smtp-settings"></a>

| 欄位            | 說明                                |
| ------------- | --------------------------------- |
| **SMTP 伺服器**  | 寄信伺服器位址（Gmail 為 `smtp.gmail.com`） |
| **SMTP Port** | 連接埠號（通常為 587）                     |
| **使用 TLS**    | 建議開啟以確保傳輸安全                       |

#### 認證設定 <a href="#authentication-settings" id="authentication-settings"></a>

| 欄位        | 說明              |
| --------- | --------------- |
| **使用者名稱** | 通常為電子郵件地址       |
| **密碼**    | 應用程式專用密碼（非帳號密碼） |

### 5. 測試連線 <a href="#step-test-connection" id="step-test-connection"></a>

填寫完成後，點擊 <mark style="color:blue;">測試連線</mark> 按鈕。系統會同時測試 IMAP（收信）和 SMTP（寄信）的連線狀況。

* **連線成功**：顯示「連線成功！IMAP 和 SMTP 伺服器連線測試通過」
* **連線失敗**：系統會顯示具體的錯誤原因（認證失敗、伺服器無法連線等），請根據提示修正設定

{% hint style="danger" %}
請務必在儲存前完成連線測試，確認 IMAP 和 SMTP 均可正常連線。
{% endhint %}

### 6. 基本設定與儲存 <a href="#step-basic-settings-and-save" id="step-basic-settings-and-save"></a>

| 欄位         | 說明                |
| ---------- | ----------------- |
| **對話平台名稱** | 為此串接取一個名稱         |
| **AI 助理**  | 選擇要綁定的 AI 助理      |
| **輪詢間隔**   | （選填）系統檢查新郵件的頻率（秒） |
| **重置指令**   | （選填）讓使用者重新開始對話的指令 |

確認設定無誤後，點擊 <mark style="color:blue;">儲存</mark> 完成串接。

串接完成後，當有人寄信至該郵件地址時，AI 助理會自動讀取郵件內容並回覆。

{% hint style="info" %}
串接成功後，您可以在對話平台列表中找到此串接，點擊編輯可進一步設定功能選項（時段回覆、寄件人名稱感知、權限控管等）。
{% 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/email.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.