疑難排解並修正 Google Chat 應用程式錯誤

本節說明建構及測試 Chat 應用程式時可能遇到的常見問題。

資訊卡訊息、對話方塊或連結預覽畫面無法正常顯示或運作

如需排解卡片錯誤的相關說明，請參閱「排解及修正卡片問題」。

應用程式沒有回應

如果傳送訊息給 Chat 應用程式後，系統回覆「應用程式未回應」，請確認 Chat 應用程式的設定：

  1. 在 Google API 控制台中，依序點選「選單」「API 和服務」「已啟用的 API 和服務」「Google Chat API」「設定」。

    前往 Chat API 設定

  2. 在「互動功能」下方，確認設定是否符合應用程式功能。如果 Chat 應用程式會與使用者互動，請務必開啟「啟用互動功能」：

    1. 根據預設，應用程式可以回覆使用者的即時訊息。
    2. 如果應用程式會回覆聊天室和群組對話中的訊息，請選取「加入聊天室和群組對話」。
    3. 在「連線設定」下方，確認架構和「觸發條件」 (例如 HTTP 端點網址、Apps Script 專案部署 ID 和函式名稱、Cloud Pub/Sub 主題名稱或 Dialogflow 代理程式) 設定正確無誤，且應用程式已部署。
    4. 在「可見度」下方，確認適當使用者可透過電子郵件地址或 Google Workspace 網域中的群組存取應用程式。如果應用程式是透過 Google Workspace Marketplace SDK 部署，則不需要設定瀏覽權限，因為 Google Workspace Marketplace 設定的優先順序較高。

  3. 如果應用程式是透過 Google Workspace Marketplace SDK 發布，請檢查 Google Workspace Marketplace 設定。

  4. 按一下 [儲存]。

  5. 請再次傳送訊息給應用程式。

Google Chat API 僅適用於 Google Workspace 使用者

設定 Chat 應用程式時，您可能會收到 Google Chat API is only available to Google Workspace users 錯誤。這則訊息表示您用來設定 Chat API 的 Google 帳戶不屬於 Google Workspace 機構。如要建構 Chat 應用程式或使用 Chat API，請務必使用 Google Workspace 帳戶。

請注意，Google Chat 使用者不需 Google Workspace 帳戶，即可使用 Chat 應用程式。如要進一步瞭解使用者如何探索及安裝 Chat 擴充應用程式，請參閱「建構互動式 Google Chat 擴充應用程式」。

使用者可能無法加入聊天室或被移出聊天室

如果 Google Workspace 管理員禁止使用者開啟或關閉即時通訊記錄，當使用者層級的設定強制開啟或關閉即時通訊記錄，而聊天室沿用機構層級的強制設定時，使用者可能會因為設定衝突而無法加入或留在聊天室。

舉例來說，如果使用者強制開啟即時通訊記錄，但聊天室強制關閉即時通訊記錄，使用者可能就無法加入該聊天室。此外，如果使用者在發生衝突前加入聊天室，並在發生衝突後於聊天室中發布訊息，系統可能會將該使用者移出聊天室。

在這種情況下，以及其他即時通訊記錄設定發生衝突的情況，Chat API 可能無法建立成員資格，或者建立訊息時，如果使用者驗證的即時通訊記錄設定與聊天室的設定衝突，系統可能會將該使用者從聊天室中移除。

詳情請參閱 Google Workspace 管理員說明中心的「使用者可能無法加入聊天室或被移出聊天室」一文。

排解 Google Apps Script 中 Advanced Chat 服務的問題

請參閱 Apps Script 頁面，瞭解進階即時通訊服務。

使用者無法在聊天室中新增 Chat 擴充應用程式

如果使用者嘗試將 Chat 應用程式新增至空間時，遇到以下錯誤訊息： This organization's administrator must allow users to install this Chat app 可能是因為下列原因：

  • 貴機構已停用 Chat 應用程式。
  • 機構尚未將這個特定的 Chat 應用程式加入機構的許可清單。

如果使用者嘗試與 Chat 應用程式互動時收到這則錯誤訊息，可能是因為貴機構授予子組織單位存取權，但未為上層組織單位啟用這項功能。

如要瞭解如何解決這個問題，請參閱「允許使用者安裝 Chat 應用程式」。

管理員必須授予應用程式執行這項操作所需的 OAuth 授權範圍

以 Chat 應用程式身分進行驗證時，可能會收到下列錯誤訊息：

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">

這則錯誤訊息表示 Google Workspace 管理員尚未一次性核准 Chat 應用程式，使用以 https://www.googleapis.com/auth/chat.app.* 開頭的授權範圍。

如要解決這項錯誤，請按照下列步驟操作：

  • 請 Google Workspace 管理員核准您的 Chat 應用程式。在 Chat 應用程式邏輯中處理這項錯誤時，請考慮傳送訊息，宣布 Chat 應用程式需要管理員核准才能執行要求的操作，例如：To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
  • 如果 Chat API 方法支援 https://www.googleapis.com/auth/chat.bot 授權範圍 (不需要管理員核准)，請考慮改用該方法。如要查看方法支援哪些授權範圍，請參閱「驗證及授權 Google Chat 擴充應用程式和 Google Chat API 要求」。

排解 Cloud Functions 錯誤

如果 Chat 應用程式是透過 Cloud Functions 實作，且無法正常運作，請參閱下列章節，瞭解如何排解及修正問題。

查看 Cloud Functions 記錄

首先，請檢查 Cloud Functions 記錄是否有錯誤。

  1. 前往 Google API 控制台的 Cloud Functions 頁面：

    前往 Cloud Functions 頁面

  2. 如要開啟記錄，請找出 Chat 應用程式的 Cloud 函式，然後依序點選「顯示動作」「>」「查看記錄」。

Logs Explorer 隨即開啟並執行查詢，顯示 Cloud Functions 記錄，包括錯誤。

如果記錄的預設資訊不足以偵錯應用程式，可以從 Cloud Functions 程式碼新增其他記錄。請參閱「查看及寫入 Cloud Functions 記錄檔」。

檢查 Cloud 函式錯誤

除了記錄檔，Cloud Functions 也可能會回報執行時發生的錯誤。

  1. 前往 Google API 控制台的 Cloud Functions 頁面：

    前往 Cloud Functions 頁面

  2. 按一下 Chat 應用程式的 Cloud Function。

  3. 在「Function details」(函式詳細資料) 頁面中，錯誤會列在「Errors」(錯誤) 下方。

  4. 如要進一步排解錯誤，請按一下錯誤。

修正常見的 Cloud Functions 錯誤

使用 Cloud Functions 建構 Chat 應用程式時，有時會遇到下列錯誤。

專案 PROJECT_NAME 的區域 REGION_NAME 中已有函式 ChatApp

部署 Cloud 函式時，您可能會收到 Function ChatApp in region REGION_NAME in project PROJECT_NAME already exists 錯誤。這則訊息表示另一個 Cloud 函式與您要部署的函式同名。變更名稱，然後重新部署函式。確認 Chat 應用程式使用的是 Cloud 函式的觸發網址，而非現有 Cloud 函式的觸發網址。

政策中提及的一或多位使用者不屬於獲准的客戶

部署 Cloud Function 時，您可能會收到 The operation cannot be completed on the function: "One or more users named in the policy do not belong to a permitted customer." 錯誤。如果收到這項錯誤，然後傳送訊息給 Chat 應用程式，系統會顯示應用程式沒有回應的錯誤訊息，因為 Google Chat 無法連上代管 Cloud Function 的伺服器。這則訊息表示名為「allUsers」的使用者沒有權限呼叫 Cloud 函式。將「Cloud Functions 叫用者」角色授予「allUsers」，表示應用程式使用的 Cloud Function 可公開存取，且不需要驗證。如要瞭解如何指派角色，請參閱「授予單一角色」。

這項錯誤可能表示 Google Cloud 專案受到網域限制。如要進一步瞭解網域限制條件，請參閱「依照網域設定身分限制」。

如要解決這個問題，請確認 Cloud Function 允許未經驗證的叫用。如要瞭解如何允許未經驗證叫用現有的 Cloud Function，請參閱「允許公開 (未經驗證) 存取」。

非外掛程式的 Chat 擴充應用程式：排解及修正 Google Chat 擴充應用程式錯誤

下列說明文件適用於非 Google Workspace 外掛程式的 Chat 擴充應用程式。如要遷移非外掛程式的 Chat 擴充應用程式，請參閱「將 Chat 擴充應用程式轉換為 Google Workspace 外掛程式」。

如果 Chat 應用程式 (非外掛程式) 回應「應用程式沒有回應」，請在 Google API 控制台的 Chat API「設定」分頁中，檢查下列設定：

  • 在「應用程式狀態」下方，確認已選取「已發布 - 使用者可存取」。
  • 依序前往「互動式功能」 >「連線設定」，確認已設定並部署 HTTP 端點 URL、Apps Script 部署 ID、Cloud Pub/Sub 主題名稱或 Dialogflow 代理程式。