> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/conversation-settings/platform-settings/basic-settings.md).

# 基本設定

網頁對話平台的基本設定：平台名稱、綁定的 Agent、返回地址、自訂域名、允許嵌入的網域、公開訪問 URL 與三種嵌入方式，以及 API 平台的 Web Chat ID 在哪裡。

<mark style="color:blue;">基本設定</mark> 是對話平台設定頁「一般」群組的第一個分類，決定這個平台「叫什麼、接哪個 Agent、從哪個網址提供服務」。本頁說明網頁平台的所有欄位；LINE、Microsoft Teams 等通訊平台的基本設定是該平台的憑證欄位，請見對應的「串接對話平台」頁面。設定頁的整體結構與進入方式請見[對話平台設定總覽](/build/conversation-settings/platform-settings.md)。

{% hint style="info" %}
**方案導覽**：本頁是對話平台設定的其中一步，文字客服的完整上線流程見 [文字客服：從零到上線](/serve/text-service.md)；語音客服見 [語音客服：從零到上線](/serve/voice.md)。
{% endhint %}

## 一、什麼時候會用到 <a href="#when-to-use" id="when-to-use"></a>

行銷人員要把公司的 AI 客服掛上官網。她進入網頁平台的 <mark style="color:blue;">基本設定</mark>，把名稱改成「客服小幫手」、確認綁定的是「產品諮詢助理」，在 <mark style="color:blue;">返回地址</mark> 填上官網首頁，再到 <mark style="color:blue;">允許嵌入的網域</mark> 加入 `*.my-company.com`，儲存後點 <mark style="color:blue;">嵌入</mark> 複製 JavaScript 程式碼交給網站工程師。上線後只有公司自己的網站能載入這個客服，其他人複製程式碼也無法使用。

## 二、欄位說明 <a href="#fields" id="fields"></a>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8b1e203abe16f045412157499f71caf17674cb29%2Fplatform-basic-settings.png?alt=media" alt="網頁平台的基本設定：名稱、Agent、返回地址、自訂域名、允許嵌入的網域、公開訪問 URL"><figcaption><p>網頁平台的基本設定</p></figcaption></figure>

| 欄位               | 說明                                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **名稱**           | 對話視窗標題列顯示的名稱，例如「客服小幫手」；必填                                                                                                                     |
| **描述**           | 簡短介紹這個 Agent 能幫什麼忙（最多 100 字），會顯示在 [Agent 市集](/work/built-in-agents/management.md)「組織自建」分頁的 Agent 卡片與分享連結預覽；留空時卡片顯示預設文案。網站與內部對話平台有此欄位，API 平台沒有 |
| **AI 助理**        | 這個平台由哪一個 Agent 回答；同一個 Agent 可以接多個平台                                                                                                           |
| **返回地址**         | 使用者在對話視窗點返回時前往的網址，通常填官網首頁                                                                                                                     |
| **自訂域名 (CNAME)** | 用您自己的網域提供對話頁面，見[第三節](#custom-domain)                                                                                                          |
| **允許嵌入的網域**      | 嵌入白名單，見[第四節](#allowed-embed-origins)                                                                                                          |
| **公開訪問URL**      | 系統自動產生的對話頁網址，可直接分享或嵌入，見[第五節](#public-url-and-embed)                                                                                           |

### 名稱與 Agent <a href="#name-and-agent" id="name-and-agent"></a>

在 <mark style="color:blue;">名稱</mark> 輸入您希望在網站上顯示的名稱，在 <mark style="color:blue;">AI 助理</mark> 下拉選單選擇要回答問題的 Agent。切換 Agent 後立即生效，對話視窗不需要重新嵌入。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b51d95e2e16cbd042aa3b0b1c86f72f8923b0439%2F%E5%90%8D%E7%A8%B1display.png?alt=media" alt="對話視窗標題列顯示平台名稱"><figcaption><p>平台名稱顯示在對話視窗的標題列</p></figcaption></figure>

### 返回地址 <a href="#return-url" id="return-url"></a>

填入公司網站網址後，使用者在全螢幕的對話頁點返回時會跳到這個網址；嵌入預覽時也會以這個網址當作背景。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-63ec964871ee05c4285511fbc4b922d35405803b%2F%E5%9F%BA%E6%9C%AC%E8%A8%AD%E5%AE%9A%20-%20%E5%B5%8C%E5%85%A5%E9%A0%90%E8%A6%BD%20%E8%BF%94%E5%9B%9E%E7%B6%B2%E5%9D%80%20(1)%20(1).png?alt=media" alt="嵌入預覽以返回地址的網站當背景"><figcaption><p>加入返回地址後，嵌入預覽會以該網站作為背景</p></figcaption></figure>

## 三、自訂域名 (CNAME) <a href="#custom-domain" id="custom-domain"></a>

預設的公開訪問網址在 `chat.maiagent.ai` 底下。若希望對話頁改用您自己的網域（例如 `chat.my-company.com`），在 <mark style="color:blue;">自訂域名 (CNAME)</mark> 填入該網域並儲存，系統會為它申請憑證並建立分流。儲存後欄位旁會顯示 <mark style="color:blue;">域名狀態</mark>：

| 狀態           | 意思                       | 要做什麼                 |
| ------------ | ------------------------ | -------------------- |
| **檢查中**      | 系統正在建立分流與憑證              | 等待幾分鐘後重新整理           |
| **DNS 未就緒**  | 您的 DNS 尚未把該網域指向 MaiAgent | 到 DNS 服務商新增 CNAME 紀錄 |
| **憑證未就緒**    | DNS 已指向，憑證仍在簽發           | 等待，通常數分鐘內完成          |
| **DNS 設定異常** | 曾經啟用，但 DNS 紀錄已被改掉或移除     | 檢查 DNS 服務商的 CNAME 紀錄 |
| **已啟用**      | 對話頁已可用您的網域開啟             | 公開訪問網址與嵌入程式碼會改用您的網域  |

{% hint style="info" %}
CNAME 紀錄要指向的目標位址依環境不同，請向[支援中心](https://helpdesk.maiagent.ai/)索取。清空欄位並儲存即可移除自訂域名，對話頁回到預設網址。
{% endhint %}

## 四、允許嵌入的網域 <a href="#allowed-embed-origins" id="allowed-embed-origins"></a>

### 這是什麼？ <a href="#embed-origins-overview" id="embed-origins-overview"></a>

<mark style="color:blue;">允許嵌入的網域</mark> 是一份「嵌入白名單」：填入後，只有清單上的網站能嵌入此網頁聊天，其他網站放置的嵌入程式碼會失效。

適合啟用的情境：

* **防止盜嵌**：擔心第三方網站複製您的嵌入程式碼、把您的客服機器人嵌到他們的頁面上，消耗您的對話額度
* **資安合規**：公司或客戶的資安政策要求列管「哪些網站可以載入此客服元件」

{% hint style="info" %}
這是進階安全設定，**沒有上述需求時，維持空清單即可**。清單為空：任何網站都可以嵌入此網頁聊天。
{% endhint %}

### 運作方式 <a href="#embed-origins-behavior" id="embed-origins-behavior"></a>

| 清單狀態  | 行為                                     |
| ----- | -------------------------------------- |
| 空（預設） | 不限制，任何網站都可以嵌入此網頁聊天                     |
| 非空    | 白名單模式：瀏覽器會擋掉其他網域的嵌入，SDK 也會拒絕其 setup 呼叫 |

* **被擋的網域嵌入時**：該頁面上的聊天元件不會完成初始化，訪客無法開始對話
* **直接開啟公開訪問 URL 的訪客**：此設定只限制「嵌入」，透過公開網址直接開啟聊天頁的訪客不受影響
* **安全機制採「無法驗證即拒絕」**：清單非空時，凡是無法通過來源驗證的嵌入一律被拒，包括網域打錯字、或嵌入頁使用了不支援來源驗證的舊版嵌入腳本

### 設定步驟 <a href="#embed-origins-setup" id="embed-origins-setup"></a>

{% stepper %}
{% step %}

### 找到欄位 <a href="#embed-origins-step-navigate" id="embed-origins-step-navigate"></a>

在 <mark style="color:blue;">基本設定</mark> 找到 <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-2c6dc13d0e37a07d6f539d493f1e1493d018dcfb%2Fwebchat-basic-allowed-origins.png?alt=media" alt="基本設定中的「允許嵌入的網域」欄位"><figcaption><p>基本設定中的「允許嵌入的網域」欄位</p></figcaption></figure>
{% endstep %}

{% step %}

### 新增網域 <a href="#embed-origins-step-add" id="embed-origins-step-add"></a>

每一筆可以是精確來源（`https://example.com`），或萬用網域（`*.example.com`，同時比對 example.com 及其所有子網域）。

| 寫法                          | 說明                                            |
| --------------------------- | --------------------------------------------- |
| ✅ `https://www.example.com` | 精確來源：只允許這個網址（含通訊協定）的頁面嵌入                      |
| ✅ `*.example.com`           | 萬用網域：允許 example.com 及其所有子網域（www、shop、blog⋯）嵌入 |
| ❌ `example.com`             | 精確來源必須包含通訊協定，缺少 `https://` 不會生效               |
| ❌ `*.com`                   | 範圍過寬，等於對所有 .com 網站開放，失去白名單意義                  |
| {% endstep %}               |                                               |

{% step %}

### 儲存並確認 <a href="#embed-origins-step-save" id="embed-origins-step-save"></a>

儲存設定後等待約一分鐘，再到清單上的網站重新整理嵌入頁，確認聊天視窗仍可正常開啟對話。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-856c495d2fb9896943ac455178eed55a38f15a0e%2Fembed-origins-01-filled-list.png?alt=media" alt="已填入網域清單的「允許嵌入的網域」欄位"><figcaption><p>已填入精確來源與萬用網域的清單範例</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 啟用前檢查清單 <a href="#embed-origins-checklist" id="embed-origins-checklist"></a>

{% hint style="warning" %}
清單一旦非空，就會擋掉所有不在清單上的嵌入。為避免「一填就全部被擋」，啟用前請依序確認：

1. **列出所有會嵌入此網頁聊天的網域**：包含正式站、測試環境、預覽環境，一個都不能漏
2. **重新取得最新的嵌入程式碼**：較早期取得的嵌入腳本可能不支援來源驗證，啟用清單後會一律被拒絕；建議先到 <mark style="color:blue;">嵌入</mark> 重新複製一份，更新到您的網站
3. **先加不刪**：第一次啟用時把所有網域加齊，不要邊啟用邊清理
4. **逐一驗證**：儲存後到每個嵌入頁實際開啟一次對話，確認都正常
5. **保留退路**：若啟用後嵌入端無法建立對話，清空清單並儲存；等待約一分鐘後，即可恢復為不限制
   {% endhint %}

### 常見問題 <a href="#embed-origins-faq" id="embed-origins-faq"></a>

**Q：設定後多久生效？**

儲存後通常約一分鐘內生效；之後重新整理已開啟的嵌入頁面，即會套用新設定。

**Q：子網域很多，要逐一列出嗎？**

不用。一筆 `*.example.com` 就會同時比對 example.com 及其所有子網域。

**Q：這個設定能防住什麼、防不住什麼？**

這是「嵌入層」的防護：能防止其他網站把此網頁聊天嵌入他們的頁面。它不是身分驗證，知道公開訪問 URL 的人仍然可以直接開啟聊天頁對話；若需要控管「誰能對話」，請搭配[登入設定](/build/choose-channel/web-chat/website.md#login-settings)使用。

**Q：設定錯了，所有嵌入端都無法對話怎麼辦？**

清空 <mark style="color:blue;">允許嵌入的網域</mark> 清單並儲存；等待約一分鐘後即可恢復為不限制，再重新檢查網域寫法。

## 五、公開訪問 URL 與嵌入 <a href="#public-url-and-embed" id="public-url-and-embed"></a>

頁面下方的 <mark style="color:blue;">公開訪問URL</mark> 是系統自動產生的對話頁網址，旁邊的動作按鈕：

| 動作       | 用途                                                                                                     |
| -------- | ------------------------------------------------------------------------------------------------------ |
| **複製**   | 複製網址，可直接分享給使用者或放在 QR Code                                                                              |
| **訪問**   | 在新分頁開啟對話頁，測試設定效果                                                                                       |
| **語音模式** | 在新分頁開啟語音對話頁；只有綁定的 Agent 已啟用[語音助理](/build/agent/voice-agent.md)時才會出現，上線流程見[語音客服：從零到上線](/serve/voice.md) |
| **嵌入**   | 取得嵌入程式碼，見下方三種嵌入方式                                                                                      |
| **嵌入預覽** | 以返回地址的網站為背景，預覽嵌入後的樣子                                                                                   |

### 三種嵌入方式 <a href="#embed-methods" id="embed-methods"></a>

點 <mark style="color:blue;">嵌入</mark> 後，可在視窗上方切換：

* **JavaScript**：以 `<script>` 載入，最常用，會自動處理載入與相容性
* **Iframe**：以 `<iframe>` 直接嵌入，適合無法插入腳本的環境
* **MaiGPT**：ChatGPT 風格的完整對話介面（左側對話歷史＋右側主對話區），可常駐嵌入頁面，或以右下角浮動按鈕點擊後全螢幕展開

選擇 <mark style="color:blue;">MaiGPT</mark> 後，可在左側調整 <mark style="color:blue;">嵌入容器（targetElement）</mark>、<mark style="color:blue;">語系（locale）</mark>、<mark style="color:blue;">標題（maigptTitle）</mark>，右側 <mark style="color:blue;">程式碼預覽</mark> 會即時更新，點 <mark style="color:blue;">複製</mark> 即可貼到您的網站。完整參數說明請見 [MaiGPT 視窗模式嵌入](/build/choose-channel/web-chat/maigpt-embed.md)。

### 嵌入腳本的特性 <a href="#embed-script" id="embed-script"></a>

JavaScript 嵌入提供的 embed.js 腳本具備：

* **防重複執行**：即使腳本被多次載入，也只會初始化一次
* **清楚的錯誤訊息**：載入失敗時提供錯誤訊息方便除錯
* **不影響網站載入速度**：腳本經過最佳化
* **相容各種網站環境與框架**

嵌入時建議：

1. 將嵌入腳本放在 `</body>` 標籤之前，確保頁面主要內容先載入
2. 只在頁面中加入一次嵌入腳本，避免重複
3. 在 SPA（Single Page Application）中使用時，請參考技術文件的進階設定

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5c896d7bb75574c434d11ef560612d20a61eba48%2F%E5%9F%BA%E6%9C%AC%E8%A8%AD%E5%AE%9A%20-%20%E9%81%B7%E5%85%A5%E8%A8%AD%E5%AE%9A%E9%A0%90%E8%A6%BD.png?alt=media" alt="嵌入預覽畫面"><figcaption><p>嵌入預覽</p></figcaption></figure>

## 六、API 平台的 Web Chat ID <a href="#web-chat-id" id="web-chat-id"></a>

工程師用 API 建立對話時，必填欄位 `webChat` 要填的是 **API 平台的 Web Chat ID**。它不在 Agent 詳細頁，而是在 API 平台的設定頁：

1. 前往 <mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">對話平台</mark>，找到該 Agent 的 <mark style="color:blue;">API</mark> 平台（建立 Agent 時自動產生），點選 <mark style="color:blue;">編輯</mark>。
2. 在左側分類導覽的「串接與登入」群組點選 <mark style="color:blue;">Webhook 設定</mark>。
3. 頁面下方的 <mark style="color:blue;">API 資訊</mark> 卡顯示 <mark style="color:blue;">Web Chat ID</mark>（唯讀），點右側的複製按鈕即可複製。

這張卡只有 API 平台才有；網頁、內部平台沒有 Web Chat ID 欄位。要查整個組織的 Web Chat 清單與 ID，工程師也可以呼叫 `GET /api/v1/web-chats/`，詳見技術手冊 [建立對話與訊息](https://docs.maiagent.ai/tech/api-integration/conversations-and-messages)。

## 七、常見問題 <a href="#faq" id="faq"></a>

### Q：改了名稱或 Agent，要重新嵌入嗎？ <a href="#faq-resave" id="faq-resave"></a>

不用。按 <mark style="color:blue;">儲存</mark> 後立即生效，嵌入程式碼不變。

### Q：同一個 Agent 可以接多個網頁平台嗎？ <a href="#faq-multi-platform" id="faq-multi-platform"></a>

可以。每個平台有自己的名稱、外觀與功能開關，適合同一個 Agent 在不同網站呈現不同樣貌。從 <mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">對話平台</mark> 點 <mark style="color:blue;">串接對話平台</mark> 新增即可。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/conversation-settings/platform-settings/basic-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.