Google Chat 的 app 必須建在某個 Google Cloud 專案底下，而且誰找得到它、能不能在 你的網域外使用，都由那個專案的設定決定。所以 Chat app 建在你自己的專案裡， OakXgen 只拿一把用來發訊息的金鑰——網域的管理權一直在你手上。

需要：一個 Google Workspace 帳號，以及可以建立 Google Cloud 專案的權限。

1. 啟用 Google Chat API

到 Google Cloud Console 選一個專案（或新建一個）， 搜尋並啟用 Google Chat API。

2. 建立 service account 金鑰

IAM 與管理 → 服務帳戶 → 建立服務帳戶。名稱隨意，不用給任何角色—— Chat app 發訊息只需要它的身分，不需要專案權限。

建好之後點進去 → 金鑰 → 新增金鑰 → JSON，會下載一個 JSON 檔。

3. 在 OakXgen 串接

到 AI 代理的串接分頁，按新增串接 → Google Chat，上傳剛剛的 JSON 檔（或把內容 貼進去），按連線。

成功後畫面會顯示一條 HTTP 端點網址，格式是 https://webhook.oakxgen.ai/agent/<webhook_id>/，下一步要用。

一個 Google Cloud 專案只能對應一個 Chat app，所以同一把專案的金鑰接到另一個 AI 上， 原本那個 AI 的 Google Chat 串接會被取代。

4. 回到 Chat API 設定頁

Google Chat API → 設定（Configuration）：

• 應用程式名稱、頭像網址、說明：客人在 Google Chat 看到的樣子。
• 互動功能：開啟。AI 只回私訊，聊天室相關的選項勾不勾都可以。
• 連線設定：選 HTTP 端點網址，貼上第 3 步的網址。
• Authentication Audience：選 HTTP endpoint URL。 如果這個專案是以 Google Workspace 外掛程式建構的，會看到的是 所有觸發條件使用同一個 HTTP 端點網址，選它並貼上同一條網址。
• 瀏覽權限：指定哪些人或群組可以找到這個 app。

儲存。

5. 測試

在 Google Chat 搜尋 app 名稱並私訊它。第一次打開私訊時 AI 會先打招呼；列表上出現 最後收到的時間就代表串好了。

支援範圍

• 只回私訊。 在聊天室裡被提及時，app 會回一句「目前只在私訊裡回覆，請直接私訊我喔。」
• 輸入 /start 或 重新開始 會重新開始對話。
• 附件（圖片、檔案）目前只會被當成「傳了一張圖片」之類的文字，AI 看不到內容—— 附件要用客人本人的授權才下載得到。
• AI 回覆的卡片會轉成 Google Chat 卡片，網址按鈕可以點；快速回覆會列成文字。

轉真人：已讀不回

Google Chat 沒有真人客服後台，轉真人觸發時不會通知任何人，也不會傳任何話給客人。 AI 對這位客人暫停 30 分鐘，之後自動恢復；客人輸入 /start 也會立刻恢復。細節見 轉真人怎麼觸發。

常見錯誤

串接列表上的紅字是我們向 Google 確認 app 狀態時得到的錯誤：

• 這個專案還沒設定好 Chat app（Google Cloud Console → Google Chat API → 設定）—— 第 4 步還沒儲存，或 Chat API 沒啟用。剛串接完、還沒做第 4 步時出現這行是正常的。
• Service account 金鑰解不開，請重新串接——解除這筆串接，重新上傳金鑰。
• 金鑰在 Google Cloud 被刪除或停用後，也會出現 Google 回報的授權錯誤，同樣要重新產生金鑰再串接一次。

私訊 app 之後最後收到一直沒有時間：通常是第 4 步的網址貼錯，或 Authentication Audience 沒有選 HTTP endpoint URL——我們收到的請求驗不過身分，會直接擋掉。