配置 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 管理员禁止用户开启或关闭聊天记录，那么有时用户可能无法加入聊天室或可能会被移出聊天室，这是因为强制开启或关闭聊天记录的用户级设置与继承组织级强制设置的聊天室之间存在冲突。
<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>.
部署 Cloud Functions 函数时，您可能会收到 Function
ChatApp in region REGION_NAME in project PROJECT_NAME already
exists 错误。此消息表示，另一个 Cloud Functions 函数与您要部署的函数具有相同的名称。更改名称，然后重新部署函数。验证 Chat 应用使用的是 Cloud Functions 函数的触发网址，而不是预先存在的 Cloud Functions 函数的触发网址。
政策中指定的一个或多个用户不属于许可客户
部署 Cloud Functions 函数时，您可能会收到 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 Functions 函数的服务器。此消息表示名为“allUsers”的用户无权调用 Cloud Function 函数。为“allUsers”授予“Cloud Functions Invoker”角色意味着，为应用提供支持的 Cloud Functions 函数是公开的，并且无需身份验证即可访问。如需了解如何分配角色，请参阅授予单个角色。
此错误可能意味着 Google Cloud 项目受到网域限制。如需详细了解网域限制条件，请参阅按网域限制身份。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-04。"],[[["\u003cp\u003eThis guide addresses common problems encountered while building and testing Google Chat apps, such as cards not rendering, apps not responding, and user access issues.\u003c/p\u003e\n"],["\u003cp\u003eTroubleshooting steps include verifying the Chat app's configuration in the Google Cloud console, ensuring the app is live and interactive features are enabled.\u003c/p\u003e\n"],["\u003cp\u003eUsers encountering access issues should check if the Chat app is allowed by their organization's administrator and has the necessary OAuth authorization scopes.\u003c/p\u003e\n"],["\u003cp\u003eFor Cloud Function-based apps, detailed guidance on checking logs, identifying errors, and fixing common Cloud Function errors like naming conflicts and permission issues is provided.\u003c/p\u003e\n"],["\u003cp\u003eUsers may be excluded from spaces due to conflicting Chat history settings between user-level and space-level configurations.\u003c/p\u003e\n"]]],["This document outlines common issues and troubleshooting steps for Chat apps. Key actions include: verifying app configurations in the Google Cloud Console, ensuring appropriate interactive features are enabled, and confirming correct connection settings. It highlights the necessity of a Google Workspace account for Chat API use and addresses user exclusion from spaces due to conflicting history settings. Other fixes include checking Cloud Function logs, resolving deployment errors, and ensuring proper user permissions for app access. Lastly, it also details on how to solve administrator OAuth errors.\n"],null,["This section describes common issues that you can encounter while building and testing Chat apps.\n\nA card message, dialog, or link preview doesn't render or work as expected\n\nFor help troubleshooting card errors, see [Troubleshoot and fix cards](/workspace/chat/troubleshoot-cards).\n\nApp is not responding\n\nIf you message the Chat app and it responds \"App is not responding,\"\nverify the Chat app's configuration:\n\n1. In the Google Cloud console, click **Menu**\n menu\n \\\u003e **More products**\n \\\u003e **Google Workspace**\n \\\u003e **Product Library**\n \\\u003e **Google Chat API**\n \\\u003e **Manage**\n \\\u003e **Configuration**.\n\n [Go to Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)\n2. Under **App status** , make sure that you selected **Live - available to users**.\n\n3. Under **Interactive features** , make sure that settings are appropriate for your app's functionality. If your Chat app interacts with users, make sure you turn on **Enable interactive features**:\n\n 1. By default, apps can respond to direct messages from users.\n 2. If your app responds to messages in spaces and group chats, select **Join spaces and group conversations**.\n 3. Under **Connection settings** , make sure the **HTTP endpoint URL** , Apps Script project **Deployment ID** , Cloud Pub/Sub **Topic Name**, or Dialogflow agent is set correctly and that it is deployed.\n 4. Under **Visibility** , make sure the appropriate users have access to the app with email address or a group in the Google Workspace domain. If the app is deployed with [Google Workspace Marketplace SDK](/workspace/marketplace/overview), visibility settings aren't necessary because Google Workspace Marketplace settings take precedence.\n4. If the app is published with [Google Workspace Marketplace SDK](/workspace/marketplace/overview), review Google Workspace Marketplace settings.\n\n5. Click **Save**.\n\n6. Try messaging the app again.\n\nGoogle Chat API is only available to Google Workspace users\n\nWhen configuring the Chat app, you might receive the\nerror `Google Chat API is only available to Google Workspace users`. This message\nmeans that the Google Account that you've used to configure the\nChat API isn't part of a Google Workspace organization. To build a\nChat app or use the Chat API, you must use a\n[Google Workspace\naccount](https://workspace.google.com/features/).\n\nNote that Google Chat users can use Chat apps without a\nGoogle Workspace account. To learn more about how users discover and install\nChat apps, see\n[Build interactive Google Chat apps](/workspace/chat/interact-users-overview).\n\nUsers can be excluded from spaces\n\nIf a Google Workspace administrator [disallows users to turn Chat history on or off](https://support.google.com/a/answer/7664184), then there might be times when users can't join or stay in a space due to a conflict between a user-level setting that forces chat history on or off and a space that inherits the organization-level forced setting.\n\nFor example, if a user has a Chat history setting forced \"on\" and a space has a Chat history setting forced \"off\", then that user might not be able to join the space. Additionally, that user might be removed from the space if they joined prior to the conflict and then they post a message in the space after the conflict.\n\nIn this scenario, and other scenarios where there are conflicts between history settings, Chat API might not be able to create a membership, or creating a message with user authentication might remove the authenticated user with a conflicting Chat history setting from the space.\n\nTo learn more, see [Users can be excluded from spaces](https://support.google.com/a/answer/9948515#zippy=%2Cmy-top-level-setting-is-chat-preferred) in the Google Workspace Admin Help center.\n\nTroubleshoot the Advanced Chat service in Google Apps Script\n\nSee the Apps Script page about the\n[Advanced Chat Service](/apps-script/advanced/chat#troubleshoot).\n\nUsers are unable to add a Chat app to a space\n\nIf users encounter the error message\n`This organization's administrator must allow users to install this Chat app`\nwhen trying to add a Chat app to a space, this error\nmight be caused by one of the following reasons:\n\n- The organization has disabled Chat apps.\n- The organization hasn't added this specific Chat app to the organization's allowlist.\n\nIf a user encounters this error message when trying to interact with a\nChat app, it might be caused by the organization\ngranting access to a sub-organizational unit, without enabling it for the\nparent organizational unit.\n\nFor information about how to resolve this issue, see\n[Allow users to install Chat apps](https://support.google.com/a/answer/7651360).\n\nThe administrator must grant the app the required OAuth authorization scope for this action\n\nWhen\n[authenticating as a Chat app](/workspace/chat/authenticate-authorize-chat-user),\nyou might receive the following error: \n\n \u003cHttpError 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.\"\u003e\n\nThis error message means that a Google Workspace administrator hasn't\nyet granted one-time approval to the Chat app to use\nauthorization scopes that begin with the name\n`https://www.googleapis.com/auth/chat.app.*`.\n\nTo resolve the error:\n\n- Ask the Google Workspace administrator to [grant approval to your Chat app](https://support.google.com/a?p=chat-app-auth). When handling this error in your Chat app logic, consider [sending a message](/workspace/chat/create-messages) announcing that the Chat app needs administrator approval to perform the requested action, perhaps: `To perform this action, I need approval.\n \u003chttps://support.google.com/a?p=chat-app-auth|Learn more\u003e.`\n- If the Chat API method supports the `https://www.googleapis.com/auth/chat.bot` authorization scope, which doesn't require administrator approval, consider using it instead. To check which authorization scopes a method supports, see the [Authenticate and authorize Google Chat apps and Google Chat API requests](/workspace/chat/authenticate-authorize#asynchronous-chat-calls).\n\nTroubleshoot Cloud Function errors\n\nIf the Chat app is implemented with Cloud Functions and\nit isn't working, the following sections help troubleshoot and fix the issue.\n\nCheck Cloud Function logs\n\nAs a first step, check the Cloud Functions logs for errors.\n\n1. In the Google Cloud console, go to the Cloud Functions page:\n\n [Go to Cloud Functions](https://console.cloud.google.com/functions)\n2. To open the logs, find your Chat app's Cloud\n Function, then click\n **Show actions** more_vert\n \\\u003e **View logs**.\n\nThe Logs Explorer opens and runs a query showing Cloud Function logs, including\nerrors.\n\nIf the default information logged is not enough to debug your app, you can add\nadditional logging from your Cloud Function code. See [View and write Cloud\nFunction logs](https://cloud.google.com/functions/docs/monitoring/logging).\n\nCheck Cloud Function errors\n\nApart from the logs, Cloud Function might also report errors encountered while\nrunning.\n\n1. In the Google Cloud console, go to the Cloud Functions page:\n\n [Go to Cloud Functions](https://console.cloud.google.com/functions)\n2. Click your Chat app's Cloud Function.\n\n3. On the Function details page, errors are listed under **Errors**.\n\n4. To further troubleshoot an error, click it.\n\nFix common Cloud Function errors\n\nThe following errors are sometimes encountered when building a\nChat app with Cloud Functions.\n\nFunction ChatApp in region \u003cvar translate=\"no\"\u003eREGION_NAME\u003c/var\u003e in project \u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e already exists\n\nWhen deploying a Cloud Function, you might receive the error `Function\nChatApp in region `\u003cvar translate=\"no\"\u003eREGION_NAME\u003c/var\u003e` in project `\u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e` already\nexists`. This message means that another Cloud Function has the same name as the\none you're deploying. Change the name, and\ndeploy the function again. Verify that the Chat app uses the Trigger URL for\nyour Cloud Function, not the Trigger URL of the preexisting Cloud Function.\n\nOne or more users named in the policy do not belong to a permitted customer\n\nWhen deploying a Cloud Function, you might receive the error `The operation\ncannot be completed on the function: \"One or more users named in the policy do\nnot belong to a permitted customer.\"` If you get this error and then message the\nChat app, you get an error saying that the app isn't responding because Google\nChat can't reach the server hosting the Cloud Function. This message means that\na user named \"allUsers\" doesn't have permission to call the Cloud Function.\nGiving \"allUsers\" the \"Cloud Functions Invoker\" role means that the Cloud\nFunction that powers the app is publicly available and accessible without\nauthentication. To learn how to assign a role, see\n[Grant a single role](https://cloud.google.com/iam/docs/granting-changing-revoking-access#grant-single-role).\n\nThis error might mean that the Google Cloud project is domain restricted. For\nmore information about domain restriction constraints, refer to\n[Restricting identities by domain](https://cloud.google.com/resource-manager/docs/organization-policy/restricting-domains#console_1).\n\nTo resolve this issue, verify that your Cloud Function allows unauthenticated\ninvocations. To learn how to allow unauthenticated invocations for an existing\nCloud Function, refer to\n[Allowing public (unauthenticated) access](https://cloud.google.com/run/docs/authenticating/public)."]]
