대화형 기능에서 설정이 앱의 기능에 적합한지 확인합니다. Chat 앱이 사용자와 상호작용하는 경우 대화형 기능 사용 설정을 사용 설정해야 합니다.
기본적으로 앱은 사용자의 채팅 메시지에 응답할 수 있습니다.
앱이 스페이스 및 그룹 채팅의 메시지에 응답하는 경우 스페이스 및 그룹 대화 참여를 선택합니다.
연결 설정에서 HTTP 엔드포인트 URL, Apps Script 프로젝트 배포 ID, Cloud Pub/Sub 주제 이름 또는 Dialogflow 에이전트가 올바르게 설정되어 있고 배포되었는지 확인합니다.
공개 상태에서 적절한 사용자가 Google Workspace 도메인의 이메일 주소 또는 그룹을 사용하여 앱에 액세스할 수 있는지 확인합니다. 앱이 Google Workspace Marketplace SDK로 배포된 경우 Google Workspace Marketplace 설정이 우선하므로 공개 상태 설정이 필요하지 않습니다.
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는 멤버십을 만들 수 없거나 사용자 인증으로 메시지를 만들면 충돌하는 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 관리자가 https://www.googleapis.com/auth/chat.app.* 이름으로 시작하는 승인 범위를 사용하도록 Chat 앱에 일회성 승인을 아직 부여하지 않았음을 의미합니다.
오류를 해결하려면 다음 단계를 따르세요.
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 함수 오류 문제 해결
채팅 앱이 Cloud Functions로 구현되었는데 작동하지 않는 경우 다음 섹션에서 문제를 해결하는 데 도움이 됩니다.
Cloud Functions로 Chat 앱을 빌드할 때 다음 오류가 발생하는 경우가 있습니다.
프로젝트 PROJECT_NAME의 REGION_NAME 리전에 함수 ChatApp이 이미 있습니다.
Cloud Function을 배포할 때 Function
ChatApp in region REGION_NAME in project PROJECT_NAME already
exists 오류가 표시될 수 있습니다. 이 메시지는 다른 Cloud 함수가 배포 중인 함수와 이름이 동일하다는 의미입니다. 이름을 변경하고 함수를 다시 배포합니다. Chat 앱이 기존 Cloud 함수의 트리거 URL이 아닌 Cloud 함수의 트리거 URL을 사용하는지 확인합니다.
정책에 지정된 사용자 중 하나 이상이 허용된 고객에 속하지 않습니다.
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 함수를 호출할 권한이 없음을 의미합니다.
'allUsers'에 'Cloud Functions 호출자' 역할을 부여하면 앱을 지원하는 Cloud Functions를 공개적으로 사용할 수 있으며 인증 없이 액세스할 수 있습니다. 역할 할당 방법을 알아보려면 단일 역할 부여를 참고하세요.
이 오류는 Google Cloud 프로젝트가 도메인으로 제한되어 있음을 의미할 수 있습니다. 도메인 제한 제약 조건에 대한 자세한 내용은 도메인별 ID 제한을 참고하세요.
이 문제를 해결하려면 Cloud 함수가 인증되지 않은 호출을 허용하는지 확인하세요. 기존 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"]],["최종 업데이트: 2025-08-04(UTC)"],[[["\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)."]]
