This section describes common issues that you can encounter while building and testing Chat apps. ## A card message, dialog, or link preview doesn't render or work as expected For help troubleshooting card errors, see [Troubleshoot and fix cards](https://developers.google.com/workspace/chat/troubleshoot-cards). ## App is not responding If you message the Chat app and it responds "App is not responding," verify the Chat app's configuration: 1. In the Google API Console, click **Menu** \> **APIs \& Services** \> **Enabled APIs \& Services** \> **Google Chat API** \> **Configuration**. [Go to Chat API configuration](https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat) 2. 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**: 1. By default, apps can respond to direct messages from users. 2. If your app responds to messages in spaces and group chats, select **Join spaces and group conversations**. 3. Under **Connection settings** , make sure your architecture and **Triggers** (such as the **HTTP endpoint URL** , Apps Script project **Deployment ID** and function name, Cloud Pub/Sub **Topic Name**, or Dialogflow agent) are set correctly and that your app is deployed. 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](https://developers.google.com/workspace/marketplace/overview), visibility settings aren't necessary because Google Workspace Marketplace settings take precedence. 3. If the app is published with [Google Workspace Marketplace SDK](https://developers.google.com/workspace/marketplace/overview), review Google Workspace Marketplace settings. 4. Click **Save**. 5. Try messaging the app again. ## Google Chat API is only available to Google Workspace users When configuring the Chat app, you might receive the error `Google Chat API is only available to Google Workspace users`. This message means that the Google Account that you've used to configure the Chat API isn't part of a Google Workspace organization. To build a Chat app or use the Chat API, you must use a [Google Workspace account](https://workspace.google.com/features/). Note that Google Chat users can use Chat apps without a Google Workspace account. To learn more about how users discover and install Chat apps, see [Build interactive Google Chat apps](https://developers.google.com/workspace/chat/interact-users-overview). ## Users can be excluded from spaces If 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. For 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. In 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. To 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. ## Troubleshoot the Advanced Chat service in Google Apps Script See the Apps Script page about the [Advanced Chat Service](https://developers.google.com/apps-script/advanced/chat#troubleshoot). ## Users are unable to add a Chat app to a space If users encounter the error message `This organization's administrator must allow users to install this Chat app` when trying to add a Chat app to a space, this error might be caused by one of the following reasons: - The organization has disabled Chat apps. - The organization hasn't added this specific Chat app to the organization's allowlist. If a user encounters this error message when trying to interact with a Chat app, it might be caused by the organization granting access to a sub-organizational unit, without enabling it for the parent organizational unit. For information about how to resolve this issue, see [Allow users to install Chat apps](https://support.google.com/a/answer/7651360). ## The administrator must grant the app the required OAuth authorization scope for this action When authenticating with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app), you might receive the following error: This error message means that a Google Workspace administrator hasn't yet granted one-time approval to the Chat app to use authorization scopes that begin with the name `https://www.googleapis.com/auth/chat.app.*`. To resolve the error: - Verify that you completed the **Store Listing** page and [published your app](https://developers.google.com/workspace/marketplace/create-listing#publish-app) to the Google Workspace Marketplace. Unpublished drafts don't appear in the Google Admin console for administrator installation. - Ask the Google Workspace administrator to grant approval to your Chat app by following [Set up app authorization for Chat](https://support.google.com/a?p=chat-app-auth). Trusting an OAuth client ID in **App access control** doesn't grant `chat.app.*` scopes. When handling this error in your Chat app logic, consider [sending a message](https://developers.google.com/workspace/chat/create-messages) announcing that the Chat app needs administrator approval: `To perform this action, I need approval. .` - 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 [Authenticate and authorize Chat apps and Chat API requests](https://developers.google.com/workspace/chat/authenticate-authorize#asynchronous-chat-calls). ## Email aliases aren't supported with app authentication When calling methods such as `spaces.findDirectMessage` with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app), passing an email alias like `users/sasha@example.com` returns an HTTP `403` error: Service account authentication doesn't support access to user information using email aliases. To get user information using email aliases, authenticate as a user. With service account authentication, specify a numeric user ID in the format `users/{user}` instead of an email address. You can get this numeric ID from the `User.name` field in a Chat interaction event, the People API, or the Directory API. For details, see [Specify a user in a call to the Chat API](https://developers.google.com/workspace/chat/identify-reference-users#specify-user). ## Troubleshoot Cloud Function errors If the Chat app is implemented with Cloud Functions and it isn't working, the following sections help troubleshoot and fix the issue. ### Check Cloud Function logs As a first step, check the Cloud Functions logs for errors. 1. In the Google API Console, go to the Cloud Functions page: [Go to Cloud Functions](https://console.developers.google.com/functions) 2. To open the logs, find your Chat app's Cloud Function, then click **Show actions** \> **View logs**. The Logs Explorer opens and runs a query showing Cloud Function logs, including errors. If the default information logged is not enough to debug your app, you can add additional logging from your Cloud Function code. See [View and write Cloud Function logs](https://cloud.google.com/functions/docs/monitoring/logging). ### Check Cloud Function errors Apart from the logs, Cloud Function might also report errors encountered while running. 1. In the Google API Console, go to the Cloud Functions page: [Go to Cloud Functions](https://console.developers.google.com/functions) 2. Click your Chat app's Cloud Function. 3. On the Function details page, errors are listed under **Errors**. 4. To further troubleshoot an error, click it. ### Fix common Cloud Function errors The following errors are sometimes encountered when building a Chat app with Cloud Functions. #### Function ChatApp in region `REGION_NAME` in project `PROJECT_NAME` already exists When deploying a Cloud Function, you might receive the error `Function ChatApp in region REGION_NAME in project PROJECT_NAME already exists`. This message means that another Cloud Function has the same name as the one you're deploying. Change the name, and deploy the function again. Verify that the Chat app uses the Trigger URL for your Cloud Function, not the Trigger URL of the preexisting Cloud Function. #### One or more users named in the policy do not belong to a permitted customer When deploying a Cloud Function, you might receive the error `The operation cannot be completed on the function: "One or more users named in the policy do not belong to a permitted customer."` If you get this error and then message the Chat app, you get an error saying that the app isn't responding because Google Chat can't reach the server hosting the Cloud Function. This message means that a user named "allUsers" doesn't have permission to call the Cloud Function. Giving "allUsers" the "Cloud Functions Invoker" role means that the Cloud Function that powers the app is publicly available and accessible without authentication. To learn how to assign a role, see [Grant a single role](https://cloud.google.com/iam/docs/granting-changing-revoking-access#grant-single-role). This error might mean that the Google Cloud project is domain restricted. For more information about domain restriction constraints, refer to [Restricting identities by domain](https://cloud.google.com/resource-manager/docs/organization-policy/restricting-domains#console_1). To resolve this issue, verify that your Cloud Function allows unauthenticated invocations. To learn how to allow unauthenticated invocations for an existing Cloud Function, refer to [Allowing public (unauthenticated) access](https://cloud.google.com/run/docs/authenticating/public). ## Chat apps that aren't add-ons: Troubleshoot and fix Google Chat app errors The following documentation applies to Chat apps that aren't Google Workspace add-ons. To migrate a Chat app that isn't an add-on, see [Convert a Chat app to a Google Workspace add-on](https://developers.google.com/workspace/chat/convert). If a Chat app that isn't an add-on responds with "App is not responding," check the following settings on the Chat API **Configuration** tab in the Google API Console: - Under **App status** , make sure that you selected **Live - available to users**. - Under **Interactive features** \> **Connection settings** , make sure that your **HTTP endpoint URL** , Apps Script **Deployment ID** , Cloud Pub/Sub **Topic Name**, or Dialogflow agent is configured and deployed.