---
url: https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/google-chat-integration.md
description: >-
  讓同事或客人在 Google Chat 私訊 AI。Chat app 建在你自己的 Google Cloud 專案，把 service account
  金鑰交給 OakXgen，再把我們給的網址填回 Chat API 設定頁。這篇逐步說明，以及常見的錯誤訊息。
---

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

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

## 1. 啟用 Google Chat API

到 [Google Cloud Console](https://console.cloud.google.com/) 選一個專案（或新建一個），
搜尋並啟用 **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` 也會立刻恢復。細節見
[轉真人怎麼觸發](./handoff.md)。

## 常見錯誤

串接列表上的紅字是我們向 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**——我們收到的請求驗不過身分，會直接擋掉。