你已經有一個訓練好的聊天機器人，現在需要把它放上你的網站。Agentkit 支援四種嵌入方式，選哪一種取決於你的平台、技術環境，以及你需要多少控制權。本指南會涵蓋所有四種選項，附上程式碼範例、設定細節，以及各平台專屬的操作說明。
嵌入方式總覽
| 方法 | 最適合 | 技術門檻 | 客製化程度 | 適用於 |
|---|---|---|---|---|
| JS 小工具 | 大多數網站 | 極低（一段指令碼標籤） | 儀表板設定＋資料屬性 | 任何支援自訂指令碼的網站 |
| React 元件 | React／Next.js 應用程式 | 低（npm install＋元件） | Props＋事件處理常式＋CSS | React、Next.js、Remix、Gatsby |
| iframe | 受限平台、沙盒環境 | 極低（一段 HTML 標籤） | URL 參數 | 任何允許 iframe 的網站 |
| WordPress 外掛程式 | WordPress 網站 | 極低（安裝＋啟用） | 外掛程式設定面板 | 僅限 WordPress |
大多數使用者應該從 JS 小工具開始。它適用於任何平台，以非同步方式載入，不到五分鐘就能完成設定。
開始之前
每一種嵌入方式都需要一個已訓練好的聊天機器人。如果你還沒有：
- 註冊 Agentkit（免費）。
- 建立聊天機器人，並用網站網址、文件、問與答配對或文字來訓練它。
- 在 Playground 中測試，直到回應準確為止。
- 從儀表板的設定進入發布，取得你的嵌入程式碼。
訓練指引請參閱如何用你的網站內容訓練聊天機器人。
方法一：JavaScript 小工具
JS 小工具是最通用的嵌入方式。一段指令碼標籤，放在結尾的 </body> 標籤之前，就能在你的網站上載入一個聊天氣泡。它適用於任何允許自訂 JavaScript 的平台：靜態 HTML 網站、CMS 平台、到達頁建構工具，以及網頁應用程式。
基本安裝
複製這段指令碼標籤，並將它放在頁面結尾的 </body> 標籤之前：
<script src="https://cdn.agentkit.ai/widget.js" data-chatbot="your-chatbot-id" async> </script>
把 your-chatbot-id 換成你 Agentkit 儀表板中的實際 ID。async 屬性能確保指令碼載入時不會阻擋你的頁面。
這樣就足以讓聊天機器人正常運作。小工具會以聊天氣泡的形式出現在畫面右下角，訪客點選即可展開對話。
透過資料屬性進行設定
你可以在指令碼標籤中加入資料屬性，來自訂小工具的行為：
<script src="https://cdn.agentkit.ai/widget.js" data-chatbot="your-chatbot-id" data-position="bottom-right" data-theme="light" async> </script>
可用的資料屬性
| 屬性 | 可用值 | 預設值 | 說明 |
|---|---|---|---|
data-chatbot | 你的聊天機器人 ID | 必填 | 指定要載入哪一個聊天機器人 |
data-position | bottom-right、bottom-left | bottom-right | 小工具氣泡的位置 |
data-theme | light、dark | light | 色彩主題 |
大多數視覺客製化（顏色、歡迎訊息、品牌標示）是透過 Agentkit 儀表板控制，而非資料屬性。這能讓你的嵌入程式碼保持簡潔，並能在不更動網站程式碼的情況下更新設定。
小工具如何載入
小工具指令碼相當輕量，並以非同步方式載入。以下是實際發生的流程：
- 你的頁面正常載入。
async屬性代表指令碼不會阻擋頁面轉譯。 - 指令碼從我們的 CDN 下載並初始化。
- 頁面上出現聊天氣泡。
- 訪客點選氣泡時，完整的聊天介面才會載入。
- 訊息會送到 Agentkit API，並以即時串流方式回傳。
初始指令碼非常小，完整的聊天介面只會在訪客與氣泡互動時才載入，因此對你的頁面速度影響極小。
各平台專屬的小工具安裝方式
JS 小工具能在所有平台上運作，但加入指令碼的步驟會因平台而異。以下是各平台專屬指南的快速連結：
| 平台 | 在哪裡加入指令碼 | 詳細指南 |
|---|---|---|
| WordPress | 佈景主題頁尾、WPCode 外掛程式，或 Custom HTML 區塊 | WordPress 聊天機器人指南 |
| Shopify | theme.liquid 中，</body> 之前 | Shopify 聊天機器人指南 |
| Squarespace | Settings > Advanced > Code Injection > Footer | Squarespace 聊天機器人指南 |
| Wix | HTML 嵌入元素或 Velo | Wix 聊天機器人指南 |
| Webflow | Project Settings > Custom Code > Footer | Webflow 聊天機器人指南 |
| 靜態 HTML | HTML 檔案中的 </body> 之前 | 本指南（上方） |
| Next.js／React | 請見下方方法二 | 本指南（下方） |
方法二：React 元件
如果你使用 React、Next.js、Remix 或 Gatsby 進行開發，React 元件能提供比原始指令碼標籤更緊密的整合。你可以取得以 Props 進行的設定、TypeScript 型別，以及掛接聊天機器人事件的能力。
安裝
安裝 Agentkit 的 React 套件：
npm install @agentkit/react
基本用法
import { AgentitkChat } from '@agentkit/react';
function App() {
return (
<AgentitkChat chatbotId="your-chatbot-id" />
);
}
這會呈現與 JS 小工具相同的聊天氣泡，但會以 React 元件的形式，存在於你應用程式的元件樹中。
Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
chatbotId | string | 必填 | 你的聊天機器人 ID |
position | 'bottom-right' | 'bottom-left' | 'bottom-right' | 小工具位置 |
theme | 'light' | 'dark' | 'light' | 色彩主題 |
Next.js 整合
在 Next.js App Router 專案中，將聊天機器人加入根版面配置，讓它出現在所有頁面上：
// app/layout.tsx
import { AgentitkChat } from '@agentkit/react';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<AgentitkChat chatbotId="your-chatbot-id" />
</body>
</html>
);
}
若使用 Pages Router，則改為將元件加入 _app.tsx。
何時該用 React 元件，何時該用 JS 小工具
| 考量項目 | React 元件 | JS 小工具 |
|---|---|---|
| React／Next.js 專案 | 建議使用 | 可運作，但整合度較低 |
| 非 React 專案 | 不適用 | 使用這個 |
| 需要事件處理常式 | 是 | 有限 |
| TypeScript 支援 | 完整型別 | 無 |
| 伺服器端轉譯 | 能正確處理 Hydration | 指令碼標籤（無 SSR 疑慮） |
| 在意套件大小 | 會加進你的套件 | 從 CDN 另外載入 |
如果你使用 React，就用 React 元件；其他情況一律使用 JS 小工具。
方法三：iframe
iframe 方法會將聊天機器人以獨立頁面的形式，嵌入你網站上的一個框架中。這在 JavaScript 注入受限，或你想以行內元素而非浮動氣泡的方式顯示聊天機器人的環境中很有用。
基本 iframe 嵌入
<iframe src="https://cdn.agentkit.ai/embed/your-chatbot-id" style="width: 100%; height: 600px; border: none;" allow="clipboard-write"> </iframe>
這會在你的頁面上以行內方式顯示完整的聊天介面，而不是浮動氣泡。
何時該用 iframe
| 情境 | 為什麼適合用 iframe |
|---|---|
| 平台限制 JavaScript | Wix、部分 LMS 平台與企業內部網路會封鎖自訂指令碼，但允許 iframe |
| 行內聊天體驗 | 你想將聊天機器人嵌入頁面的某個區塊，而不是浮動氣泡 |
| 沙盒環境 | 會將第三方內容沙盒化的內部工具或平台 |
| Kiosk 或嵌入式顯示 | 數位看板、店內平板，或嵌入式網頁畫面 |
iframe 設定
透過 URL 參數自訂 iframe：
<iframe src="https://cdn.agentkit.ai/embed/your-chatbot-id?theme=dark" style="width: 400px; height: 600px; border: none; border-radius: 12px;" allow="clipboard-write"> </iframe>
| 參數 | 可用值 | 預設值 | 說明 |
|---|---|---|---|
theme | light、dark | light | 色彩主題 |
設定 iframe 尺寸
iframe 不會自動調整大小，你需要透過 CSS 控制它的尺寸：
- 全寬嵌入式聊天：
width: 100%; height: 600px; - 側欄聊天：
width: 400px; height: 100vh;，置於側欄版面配置中。 - 精簡小工具：
width: 350px; height: 500px;，適合較小的行內區域。
iframe 嵌入的限制
| 限制 | 說明 |
|---|---|
| 沒有浮動氣泡 | iframe 以行內方式顯示，而非可切換開關的氣泡 |
| 尺寸固定 | 你必須手動設定寬高，無法自動調整大小 |
| 跨來源限制 | 部分進階功能可能受瀏覽器沙盒機制限制 |
| SEO | iframe 內的內容不會被搜尋引擎索引（與聊天功能無關，但值得留意） |
對大多數網站而言，JS 小工具是更好的選擇。只有在 JS 小工具無法使用，或你明確想要行內聊天體驗時，才使用 iframe。
方法四：WordPress 外掛程式
WordPress 網站可以透過上述任一方法使用 JS 小工具，但也有一種專為非技術使用者簡化流程的做法，也就是使用程式碼片段外掛程式。
使用 WPCode 快速設定
- 從 Plugins（外掛） 進入 Add New（新增），安裝 WPCode 外掛程式（免費，安裝次數超過 200 萬）。
- 前往 Code Snippets（程式碼片段），再進入 Header & Footer（標頭與頁尾）。
- 將 Agentkit 指令碼標籤貼到 Footer（頁尾） 區段中。
- 儲存。
聊天機器人現在會出現在每一個頁面上。WPCode 也支援條件邏輯，讓你能只在特定頁面顯示聊天機器人。
其他 WordPress 方法
| 方法 | 最適合 | 佈景主題更新後是否仍有效 |
|---|---|---|
| WPCode 外掛程式（頁尾） | 大多數使用者，全站嵌入 | 是 |
| Custom HTML 區塊 | 逐頁設定聊天機器人 | 是 |
佈景主題 footer.php 編輯 | 使用子佈景主題的開發人員 | 僅子佈景主題可以 |
完整的 WordPress 操作說明與疑難排解，請參閱如何在 WordPress 網站上加入聊天機器人。
客製化選項
不論你使用哪一種嵌入方式，大多數客製化都是在 Agentkit 儀表板中完成的。這代表你可以在不更動嵌入程式碼的情況下變更設定。
視覺客製化
| 設定項目 | 設定位置 | 控制內容 |
|---|---|---|
| 主色 | 設定 | 小工具的重點色、按鈕顏色、標頭顏色 |
| 位置 | 設定或資料屬性 | 右下角或左下角的擺放位置 |
| 主題 | 設定或資料屬性 | 淺色或深色模式 |
| 歡迎訊息 | 設定 | 聊天開啟時顯示的初始問候語 |
| 品牌標示 | 設定 | 顯示／隱藏「Powered by Agentkit」（Standard 以上方案） |
行為客製化
| 設定項目 | 設定位置 | 控制內容 |
|---|---|---|
| 自訂指示 | 設定 | 引導 AI 的語氣、個性與規則 |
| 建議訊息 | 動作 | 顯示給訪客的預寫提示 |
| 潛在客戶收集 | 動作 | 在對話過程中收集姓名、電子郵件、電話 |
| 自訂表單 | 動作 | 觸發自訂資料收集表單 |
| 速率限制 | 設定 | 每位訪客每個工作階段的最大訊息數 |
| 網域限制 | 設定 | 哪些網域可以載入聊天機器人 |
安全性考量
在網站上嵌入聊天機器人時，請留意以下安全性設定。
網域限制
請務必在聊天機器人設定中設定網域限制，確保聊天機器人只會在你授權的網域上載入。如果沒有設定，任何找到你聊天機器人 ID 的人，都能把你的聊天機器人嵌入他們自己的網站，並占用你的訊息額度。
前往 Agentkit 儀表板的 Settings（設定），新增每一個聊天機器人應該運作的網域：
- 你的主要網域（例如
yourbusiness.com） - 任何子網域（例如
support.yourbusiness.com） - 如果需要測試，加入開發或預備環境網域
速率限制
速率限制會限制單一訪客每個工作階段能傳送的訊息數量，這能防止濫用，並協助你管理訊息額度。對大多數網站而言，每個工作階段 15 到 25 則訊息是合理的上限。
Content Security Policy
如果你的網站使用 Content Security Policy 標頭，你需要將 Agentkit 的網域加入白名單。請在你的 CSP 中加入以下項目：
script-src：cdn.agentkit.aiframe-src：cdn.agentkit.ai（若使用 iframe 方法）connect-src：*.agentkit.com（供 API 呼叫使用）
常見嵌入問題排解
聊天機器人沒有出現
| 可能原因 | 解決方式 |
|---|---|
| 瀏覽器快取 | 在無痕視窗中開啟，或清除快取 |
| 指令碼位置 | 確認指令碼位於 <body> 內，而不是 <head> |
| 缺少聊天機器人 ID | 確認 data-chatbot 與你儀表板中的 ID 相符 |
| 平台限制 | 部分平台會移除指令碼，可嘗試 iframe 方法 |
| Content Security Policy | 將 cdn.agentkit.ai 加入你的 CSP 標頭白名單 |
| 伺服器端快取 | 清除你的 CDN、主機或 CMS 快取 |
聊天機器人有出現，但沒有回應
- **檢查訓練資料。**尚未訓練的聊天機器人沒有任何內容可供運用。
- **確認聊天機器人 ID。**ID 錯誤會導致小工具載入，卻找不到對應的聊天機器人。
- **檢查網域限制。**如果你的網域不在允許清單中，聊天機器人就不會回應。
- **檢查方案額度。**如果你已用完當月的訊息額度，聊天機器人會停止回應，直到下一個計費週期開始。
聊天機器人與其他小工具衝突
如果其他聊天小工具（Intercom、Crisp、Drift）與你的重疊，可以移除另一個小工具、將 Agentkit 的位置改為 bottom-left，或使用 iframe 方法，以行內方式放置聊天機器人，而不是浮動氣泡。
為你的嵌入選擇合適的方案
| 網站流量 | 建議方案 | 每月費用 | 包含訊息數 |
|---|---|---|---|
| 測試或個人網站 | Free | $0 | 50 則訊息，1 個聊天機器人 |
| 小型企業網站 | Hobby | $29.99 | 2,000 則訊息，1 個聊天機器人 |
| 成長中企業或多個網站 | Standard | $119.99 | 12,000 則訊息，2 個聊天機器人，3 個團隊席次 |
| 高流量網站或代理商 | Pro | $399.99 | 40,000 則訊息，3 個聊天機器人，5 個團隊席次 |
年繳能為所有付費方案節省約 20% 的費用。先用 Free 方案測試嵌入效果，等流量成長需要更多訊息時再升級。
後續步驟
聊天機器人嵌入完成後，接下來的重點會從安裝轉為最佳化：
- 監控對話：第一週在 Agentkit 儀表板中觀察對話，找出聊天機器人答得不好的問題。
- 針對弱點新增訓練資料：問與答是修正特定回應問題最快的方式。
- 啟用潛在客戶收集：在對話過程中收集訪客的電子郵件，詳見潛在客戶開發指南。
- 連接你的工具：透過 Zapier、Webhook 或 REST API 連接，詳見整合指南。
- 設定網域限制與速率限制：確保安全性與額度管理。
如需各平台專屬的操作說明，請參閱以下詳細指南：
不需信用卡。
