> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pathors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatwoot 整合快速入門指南

> 學習如何在 Pathors 中整合 Chatwoot，包括取得 API Access Token、設定憑證以及建立 Agent Bot。

## 概述

本教學將指導您如何在 Pathors 中整合 Chatwoot。設定完成後，Pathors AI 將透過 Agent Bot 自動回覆 Chatwoot 收件匣中的對話。

## 前置需求

* Chatwoot 帳號（自架或雲端版本）
* Pathors 專案

## 步驟 1：取得 Chatwoot 憑證

您需要從 Chatwoot 取得以下三項資訊：

### Base URL

這是您的 Chatwoot 實例的網址。

* **Chatwoot 雲端版**：`https://app.chatwoot.com`
* **自架版**：您的自訂網域，例如 `https://chatwoot.yourcompany.com`

### 帳號 ID（Account ID）

1. 登入 Chatwoot 後台
2. 前往 **設定** > **帳號設定**
3. 頁面上會顯示您的帳號 ID，點擊 **Copy** 即可複製

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step1-chatwoot-account-id.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=f220794152cc2550d0c91ba9730f177b" alt="在 Chatwoot 帳號設定找到 Account ID" width="804" height="900" data-path="images/chatwoot/step1-chatwoot-account-id.png" />

<Tip>
  您也可以從 Chatwoot 網址中找到帳號 ID。例如在
  `https://app.chatwoot.com/app/accounts/1/dashboard` 中，帳號 ID 就是 `1`。
</Tip>

### API Access Token

API Access Token 是 Pathors 與 Chatwoot API 溝通所需的憑證。

1. 登入 Chatwoot 後台
2. 點擊左下角的**頭像**以開啟個人資料頁面
3. 向下捲動到 **Access Token** 區塊
4. 點擊**眼睛圖示**顯示 Token，再點 **Copy** 複製

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step2-chatwoot-access-token.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=f9c4c0f8a174646def84538c83708a68" alt="從 Chatwoot 個人資料頁複製 API Access Token" width="804" height="900" data-path="images/chatwoot/step2-chatwoot-access-token.png" />

<Warning>
  此 Token 擁有您 Chatwoot 帳號的完整 API 存取權限，請妥善保管，切勿公開分享。
</Warning>

## 步驟 2：在 Pathors 中設定 Chatwoot

1. 登入您的 Pathors 專案
2. 前往**整合**頁面，點擊 **Chatwoot**
3. 使用右上角的開關**啟用**整合

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step3-pathors-integration-page.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=de0a4cf58e7366011e5b7b996a7db816" alt="Pathors 的 Chatwoot 設定頁，整合已啟用" width="1390" height="1114" data-path="images/chatwoot/step3-pathors-integration-page.png" />

4. 填入憑證（輸入後會自動儲存）：
   * **帳號 ID**：步驟 1 取得的 Chatwoot Account ID
   * **API Access Token**：步驟 1 取得的 Token
   * **Base URL**：您的 Chatwoot 實例網址（預設 `https://app.chatwoot.com`）

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step4-pathors-credentials-form.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=b32816d9fd04830020522a73950bc3b6" alt="在 Pathors 整合表單中填入 Chatwoot 憑證" width="1390" height="1114" data-path="images/chatwoot/step4-pathors-credentials-form.png" />

## 步驟 3：自訂真人轉接行為（選擇性）

Pathors 內建 `transfer_to_human` 工具，讓 AI 在必要時把對話轉給真人客服。您可以透過**真人轉接描述**欄位調整觸發時機。

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step5-pathors-handoff-description.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=5d822c88456b735380e3a23db9faac67" alt="自訂描述以告訴 AI 何時應轉接真人客服" width="1390" height="1114" data-path="images/chatwoot/step5-pathors-handoff-description.png" />

<Tip>
  預設描述是安全的起點。建議依您的產品調整 — 例如明確列出 AI 不該處理的主題（法律、退款、VIP 帳號），讓轉接觸發更穩定。
</Tip>

## 步驟 4：建立 Agent Bot

憑證儲存後：

1. 點擊 Chatwoot 設定卡片上方的**建立 Bot** 按鈕
2. Pathors 會自動在您的 Chatwoot 帳號中建立 Agent Bot
   * Bot 名稱與您的 Pathors 專案名稱一致
   * Webhook URL 會自動設定
3. 建立完成後，會顯示 **Agent Bot ID** 的標籤

<Tip>
  如果需要更新 Bot（例如重新命名專案後），點擊**更新 Bot**。這會更新 Bot 名稱和 Webhook URL，不會建立新的 Bot。
</Tip>

## 步驟 5：在 Chatwoot 中將 Bot 指派到收件匣

Agent Bot 需要被指派到 Chatwoot 的收件匣才能開始接收對話。

1. 在 Chatwoot 後台，前往 **設定** > **收件匣**
2. 選擇您希望 Bot 處理的收件匣
3. 點擊 **Bot Configuration** 分頁
4. 在 **Select an agent bot** 下拉選單中選擇剛剛建立的 Bot（名稱會與您的 Pathors 專案名稱一致）
5. 點擊 **Update**

<img src="https://mintcdn.com/pathorstechnology/KdB-f_Xl4XvHDQAi/images/chatwoot/step6-chatwoot-inbox-bot-assignment.png?fit=max&auto=format&n=KdB-f_Xl4XvHDQAi&q=85&s=e919632e7c8a9f5d50bd01878df55d88" alt="在 Chatwoot 收件匣指派 Pathors Agent Bot" width="804" height="900" data-path="images/chatwoot/step6-chatwoot-inbox-bot-assignment.png" />

<Note>
  每個收件匣同一時間只能指派一個 Agent Bot。如果您有多個收件匣，可以將同一個 Bot 指派給每一個。
</Note>

## 步驟 6：驗證連線

1. 回到 Pathors 的 Chatwoot 設定頁面，點擊**驗證連線**
2. 如果驗證成功，代表整合已完全設定完成
3. 嘗試從聯絡人端傳送訊息到該收件匣，確認 Bot 是否正常回應

## 常見問題

### 出現「Invalid API Access Token」錯誤

* 確認您已完整複製 Chatwoot 個人資料中的 Token
* 確認該 Token 所屬帳號擁有 API 存取權限
* 確認帳號 ID 與 Token 所屬帳號一致

### 出現「Agent bot with this name already exists」錯誤

* 您的 Chatwoot 帳號中已存在同名的 Bot
* 請至 Chatwoot 的**設定** > **Bot**移除重複的 Bot，或重新命名您的 Pathors 專案

### Bot 沒有回應訊息

* 確認 Bot 已指派到正確的收件匣（步驟 5）
* 點擊**驗證連線**確認 Bot 仍然正確設定
* 確認 Pathors 整合已開啟

### 驗證時出現「Agent bot not found」錯誤

* Bot 可能已從 Chatwoot 端被刪除
* 點擊**建立 Bot** 建立新的 Bot，然後重新指派到收件匣

## 相關資源

* [Chatwoot Agent Bot 官方文件](https://www.chatwoot.com/docs/product/others/agent-bots)
* [Chatwoot API 參考文件](https://www.chatwoot.com/developers/api/)