Each Google Chat app that you create requires its own Google Cloud project with the Chat API enabled and configured. To perform read-only API calls with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), like getting spaces and listing messages, you only need to [enable the API](https://developers.google.com/workspace/guides/enable-apis) and [create an OAuth client](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#step-2:). To perform create, update, and delete API calls, or to deploy and test an interactive Chat app (built as a Google Workspace add-on that extends Chat), you must also configure the Chat API. The Chat API configuration settings are where you specify all the details about the Chat app, including its display name, avatar, deployment endpoints, and interactive features. ## Prerequisites - A Business or Enterprise [Google Workspace](https://support.google.com/a/answer/6043576) account with access to [Google Chat](https://workspace.google.com/products/chat/). - [Create a Google Cloud project](https://developers.google.com/workspace/guides/create-project). - [Configure the OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent). - [Enable the Google Chat API](https://developers.google.com/workspace/guides/enable-apis). ## Choose a display name, avatar, and description for your Chat app When you enable the Chat API, you configure the details about your Chat app that appear to users in Chat, including a display name, avatar, and description. These details only appear in Chat. To publish your Chat app to the Marketplace, you must also specify the details that appear in your Chat app's [Marketplace listing](https://developers.google.com/workspace/marketplace/create-listing). Before you configure a Chat app, prepare the following information: | Field | Description | Format | |---|---|---| | App name | The display name for the Chat app. | Up to 25 alphanumeric characters | | Avatar URL | The image that displays as your Chat app's avatar. | An HTTPS URL pointing to a square graphics image (PNG or JPEG). Recommended size is 256 by 256 pixels or more. | | Description | A brief description of the purpose of the Chat app. | Up to 40 alphanumeric characters | The Chat app's name, avatar, and description are displayed to users in the Chat UI. For some Chat API write requests, Chat uses this information to attribute the actions that a Chat app takes in Chat. For example, if you call the `spaces.create()` method, Chat includes the name of the Chat app in the description of who created the space, as shown in the following image: ![Google Chat app creates a space for a user.](https://developers.google.com/static/workspace/chat/images/auth-user-create-space.png) **Figure 1** . The attribution message that Chat displays when the `spaces.create()` method is used to create a space on behalf of a user. ![](https://developers.google.com/static/workspace/chat/images/auth-user-create-space.png) To interact with Chat apps, users also see or use this information in the following ways: - @mention the Chat app to add it to a space or send it a message. - Find and start a direct message with the Chat app. In the **Apps** menu, direct messages display the Chat app's name and avatar. - From the compose bar, users can browse Chat apps and see their name, avatar, and description. ## Configure your Chat app in the Google Cloud console When you have your Chat app details, open your Cloud project and configure the Chat API: 1. In the Google Cloud console, go to the Chat API page and click the **Configuration** page: [Go to the Chat API Configuration page](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 2. Under **Application info** , fill out the **App name** , **Avatar URL** , and **Description** fields. 3. Optional: From the **Markup syntax** menu, select the default markup syntax (**Markdown** or **Chat** ) for your Chat app's messages. To learn more about text formatting and how Chat determines the markup syntax for API requests, see [Format messages](https://developers.google.com/workspace/chat/format-messages#format-texts). 4. Under **Interactive features**, configure whether your Chat app responds to user interactions: > [!NOTE] > **Note:** If your Chat app only calls the Chat API and doesn't receive or respond to user interactions, leave **Enable interactive features** turned off and skip to the next step. To build an interactive Chat app, turn on **Enable interactive features** and complete the following: 1. Under **Functionality** : - Optional: Select **Support App Home** to display a [homepage card](https://developers.google.com/workspace/chat/send-app-home-card-message) in the **Home** tab of 1:1 direct messages with the Chat app. - Select **Join spaces and group conversations** to make your Chat app available to install and use. By default, users can install and message with the Chat app in a dedicated space between the user and Chat app. Users can also add and interact with the Chat app in spaces with multiple people. 2. Under **Connection settings** , select the architecture that you want to use to receive [event objects from Chat](https://developers.google.com/workspace/chat/receive-respond-interactions#event-objects): - To use an HTTP service, select **HTTP endpoint URL** and provide a URL. - To use a Google Apps Script project, select **Apps Script** and provide a [deployment ID](https://developers.google.com/apps-script/concepts/deployments) for the project. - To use a Dialogflow agent, select **Dialogflow** , select **Dialogflow CX** or **Dialogflow ES**, and provide the agent's resource name. - To use Pub/Sub, select **Cloud Pub/Sub** and enter the topic name. > [!WARNING] > **Warning:** If an Apps Script deployment ID is already populated, the Cloud project is connected to an existing Google Workspace add-on. If you update the deployment ID in the Chat API, the deployment ID is updated for your add-on and could affect your listing in the Google Workspace Marketplace. To review your add-on configuration, see [Configure your app in the Google Workspace Marketplace SDK](https://developers.google.com/workspace/marketplace/enable-configure-sdk). 3. Optional: To route event objects to specific endpoints or functions, go to **Connection settings** \> **Triggers** and provide or update the callback endpoints or functions for the following [Chat triggers](https://developers.google.com/workspace/chat/receive-respond-interactions#triggers): > [!NOTE] > **Note:** For Apps Script, if you don't update the triggers, you must implement the default callback functions that are populated in this section (such as `onMessage`, `onAddedToSpace`, `onRemovedFromSpace`, `onAppCommand`, and `onAppHome`). - **App home** (if **Support App Home** is enabled): A user opens the **Home** tab in a 1:1 direct message with the Chat app. - **Added to space**: A user adds the Chat app to a group conversation or space, or installs the Chat app for 1:1 messages. - **Message**: A user sends a message to the Chat app. For example, a user sends a direct message to the Chat app or @mentions the Chat app in a space with multiple people. - **Removed from space**: A user uninstalls or removes the Chat app from a space. - **App command**: A user invokes a quick command, slash command, or message action from the Chat app. 4. Optional: Add other interactive features such as [sessions](https://developers.google.com/workspace/chat/sessions), [starter prompts](https://developers.google.com/workspace/chat/receive-respond-interactions#starter-prompts), [commands](https://developers.google.com/workspace/chat/commands) (quick commands, slash commands, and message actions), or [link previews](https://developers.google.com/workspace/chat/preview-links). 5. Under **Visibility** , select **Make this Chat app available to specific people and groups** and enter the email addresses of individuals or Google Groups in your Google Workspace organization: - To [install and test your app](https://developers.google.com/workspace/chat/test-interactive-features) yourself, enter your own email address. - To share an internal Chat app across a team or your entire organization without publishing to the Marketplace, enter one or more Google Groups. Groups don't have a member limit. If your app requests `chat.app.*` scopes, you must still [publish the app](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app#publish-gwm) for administrator approval. - If your administrator restricts Marketplace installs to apps on an allowlist, Google Cloud console limits this field to five individual user email addresses for development. Group visibility applies only after an administrator adds the app to the allowlist. 5. Optional: Under **Logs** , select the **Log errors to Logging** checkbox to use Google Cloud Logging. For more information, see [Query error logs for Chat apps](https://developers.google.com/workspace/chat/query-logs). 6. Click **Save**. After you save the configuration, anyone that you specified in the Chat API's **Visibility** setting can install, test, or use the Chat app. To start testing and debugging your Chat app, see [Test interactive features for Google Chat apps](https://developers.google.com/workspace/chat/test-interactive-features). ## Configure your Chat app using the Google Workspace add-ons API > [!WARNING] > **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features. Instead of configuring your Chat app manually in the Google Cloud console, you can use your Google Cloud project enrolled in the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview) to programmatically read and update the configuration for a Chat app built as a Google Workspace add-on using the `chatAppConfig` resource in the [`Google Workspace add-ons API`](https://developers.google.com/workspace/add-ons/reference). `chatAppConfig` is a singleton resource that always exists for each Cloud project. Before you save a configuration for the first time, the resource contains an empty configuration (which is also what [`GetChatAppConfig`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig/get) returns if you read the resource before the first save). Because the resource already exists, you don't need to create it separately---use [`UpdateChatAppConfig`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig/patch) both to save the initial configuration and to update an existing configuration. > [!NOTE] > **Note:** The `chatAppConfig` methods only support Chat apps built as Google Workspace add-ons. To upgrade an existing Chat app, see [Convert a Google Chat app to a Google Workspace add-on](https://developers.google.com/workspace/chat/convert). ### Prerequisites and authentication Before calling `GetChatAppConfig` or `UpdateChatAppConfig`, complete the following prerequisites: 1. Enroll your Google Cloud project in the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview). 2. [Enable](https://developers.google.com/workspace/guides/enable-apis) the Google Workspace add-ons API (`gsuiteaddons.googleapis.com`) in your Cloud project. Optionally, you can enable the Google Chat API (`chat.googleapis.com`) if you want to view or update the Chat app configuration in the Google Cloud console or call the Chat API. 3. Authenticate as a human user with an OAuth 2.0 credential that includes the `https://www.googleapis.com/auth/cloud-platform` scope. Service account authentication isn't supported for `chatAppConfig` methods. 4. Ensure the authenticated user has the required Identity and Access Management (IAM) permissions on the target Cloud project: - `gsuiteaddons.chatAppConfigs.get` and `chat.bots.get` to read the configuration (`GetChatAppConfig`). - `gsuiteaddons.chatAppConfigs.update` and `chat.bots.update` to update the configuration (`UpdateChatAppConfig`). 5. If you use a client library, [download the Developer Preview client library](https://drive.google.com/corp/drive/u/0/folders/1dEMGAAfvJesVVkBWMWGhTg0lXsyfCFDP?resourcekey=0-KsqjW2D8rN89ZIfC8X8LFw) with your registered Developer Preview account. ### Update a Chat app configuration To configure a Chat app for the first time or update an existing configuration, send a `PATCH` request ([`UpdateChatAppConfig`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig/patch)) to the singleton [`chatAppConfig`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig) resource for your Cloud project: - For the initial save on a Cloud project with an empty `chatAppConfig`, `displayName` (3 to 25 characters) and `description` (1 to 40 characters) are required. If you omit `interactiveFeatureConfig` on the initial save, the Chat app is configured as non-interactive. - For subsequent updates, use the optional `updateMask` query parameter to specify the comma-separated fields to update (or omit `updateMask` to update all provided fields). Updating a repeated field (`appCommands`, `urlPatterns`, or `allowlistedTestingPrincipals`) replaces the entire list. PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig Authorization: Bearer ACCESS_TOKEN Content-Type: application/json { "name": "projects/PROJECT_NUMBER/chatAppConfig", "displayName": "Cymbal Assistant", "description": "Helps manage tasks and schedules", "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png", "state": "ACTIVE", "errorLoggingEnabled": true, "markupSyntax": "MARKUP_SYNTAX_MARKDOWN", "interactiveFeatureConfig": { "supportsMultiuserSpaces": false, "connectionConfig": { "httpEndpointConfig": { "commonUrl": "https://example.com/chat" } }, "appCommands": [ { "commandType": "SLASH_COMMAND", "commandId": 1, "command": "/help", "description": "Show available commands", "dialogEnabled": false } ], "urlPatterns": [ { "hostPattern": "example.com", "pathPrefix": "tasks/" } ], "allowlistedTestingPrincipals": [ "USER_EMAIL" ] } } Replace the following in the request URL, header, and body: - `PROJECT_NUMBER`: The numeric project number of the Cloud project hosting your Chat app. - `ACCESS_TOKEN`: A user OAuth 2.0 access token authorized with the `https://www.googleapis.com/auth/cloud-platform` scope. - `USER_EMAIL`: An email address or Google Group from your Google Workspace organization to allowlist for testing the Chat app (for example, your own email address). - The example configuration fields in the request body (such as `displayName`, `description`, `avatarUri`, and `interactiveFeatureConfig`, including your endpoint configuration, commands, link preview URL patterns, and testing principals) with the values for your Chat app. For details on all supported fields and endpoint options, see the [`projects.chatAppConfig` REST reference](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig) and [`projects.chatAppConfig.patch`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig/patch). ### Get a Chat app configuration To read the current Chat app configuration for a Cloud project, call [`GetChatAppConfig`](https://developers.google.com/workspace/add-ons/reference/rest/v1/projects.chatAppConfig/get). You can pass the optional `view` query parameter (`ChatAppConfigView`): - `BASIC` (default): Returns basic metadata without `interactiveFeatureConfig`. - `FULL`: Returns all configuration fields, including `interactiveFeatureConfig`. If the Chat app configuration hasn't been saved for the Cloud project yet, the method returns an empty `ChatAppConfig` object. ### HTTP GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL Authorization: Bearer ACCESS_TOKEN ### Node.js const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1; const client = new GSuiteAddOnsClient(); async function getChatAppConfig() { const [response] = await client.getChatAppConfig({ name: 'projects/PROJECT_NUMBER/chatAppConfig', view: 'FULL', }); console.log(JSON.stringify(response, null, 2)); } getChatAppConfig(); ### Python from google.cloud import gsuiteaddons_v1 client = gsuiteaddons_v1.GSuiteAddOnsClient() request = gsuiteaddons_v1.GetChatAppConfigRequest( name="projects/PROJECT_NUMBER/chatAppConfig", view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL, ) response = client.get_chat_app_config(request=request) print(response) ## Considerations for existing Google Workspace add-ons Chat apps require a different configuration compared to Google Workspace add-ons that extend other Google Workspace applications. If your add-on extends other Google Workspace applications, consider the following requirements for configuring the Chat app: - Both individuals and Google Workspace administrators must be able to install your add-on from the Marketplace. You configure these installation settings in the Marketplace SDK. - Chat apps don't use the name and logo that you configure for other Google Workspace applications in the `addons.common` object of the [manifest](https://developers.google.com/workspace/add-ons/concepts/workspace-manifests). - For add-ons that are published to the Google Workspace Marketplace, you can't save a draft of any changes to the Google Chat API configuration settings. After you update and save the Chat API configuration settings, the updated Chat app is immediately available to all existing users. To update your Marketplace listing, you can [create a draft](https://developers.google.com/workspace/marketplace/manage-app-listing#draft-app-listing) before submitting any changes. - If you built your add-on using Apps Script: - You must use the same Apps Script deployment ID that you use for the rest of your add-on configuration. - You can't use the Apps Script editor to install [test deployments](https://developers.google.com/workspace/add-ons/how-tos/testing-workspace-addons#install_an_unpublished) in Chat. Instead, you must [install them directly from the Chat UI](https://developers.google.com/workspace/chat/test-interactive-features). - If you built your add-on using an HTTP service, omit any Chat app configuration details in the `projects.deployments` manifest that you create using the Google Workspace add-ons API. The HTTP deployments that you specify in the Google Workspace Marketplace SDK are only used for other Google Workspace applications. Instead, configure your Chat app in the [Google Cloud console](https://developers.google.com/workspace/chat/configure-chat-api#configure-console) or using the `chatAppConfig` resource in the [Google Workspace add-ons API](https://developers.google.com/workspace/chat/configure-chat-api#configure-api). ## Grant other people permission to configure the Chat API You can [give specific users access](https://cloud.google.com/iam/docs/granting-changing-revoking-access#single-role) to the Chat app configuration page by granting them the **Chat apps Owner** or **Chat apps Viewer** [Google Cloud Identity Access Management (IAM) role](https://cloud.google.com/iam/docs/roles-permissions/chat). Users with these roles can't navigate to the Chat apps configuration page by using the **APIs \& Services** dashboard, but can access the configuration page by navigating to the Google Cloud console for the Chat app's host Cloud project as follows: ``` https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID ``` Where `PROJECT_ID` is the project ID of the Google Cloud project hosting the Chat app. > [!NOTE] > Users with **Project** roles can also access the app configuration page. > > > Users with custom roles containing the > `resourcemanager.projects.(get|update)` permissions cannot access > the Chat app configuration. For custom roles, use > the `chat.bots.(get|update)` permissions (and > `gsuiteaddons.chatAppConfigs.(get|update)` when calling the > [Google Workspace add-ons API](https://developers.google.com/workspace/chat/configure-chat-api#configure-api)) instead. ## Related topics - [Choose a Chat app architecture](https://developers.google.com/workspace/chat/structure) - [Receive and respond to user interactions](https://developers.google.com/workspace/chat/receive-respond-interactions) - [Test interactive features for Google Chat apps](https://developers.google.com/workspace/chat/test-interactive-features) ## Chat apps that aren't add-ons: Configure the Google Chat API If you maintain a Chat app that isn't a Google Workspace add-on, your configuration uses a single endpoint for all interaction events rather than per-event triggers: 1. In the Google Cloud console, go to the Chat API **Configuration** page: [Go to Chat API Configuration page](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 2. Under **Interactive features** , turn on **Enable interactive features**. 3. Clear **Build this Chat app as a Google Workspace add-on** . A dialog opens asking you to confirm. In the dialog, click **Disable**. 4. Under **Functionality** , select **Support App Home** or **Join spaces and group conversations** as needed. 5. Under **Connection settings** , specify a single endpoint for your Chat app (**HTTP endpoint URL** , **Apps Script** deployment ID, **Cloud Pub/Sub topic name** , or **Dialogflow**). 6. Configure optional **Commands** , **Link previews** , **Visibility** , and **Logs** , then click **Save**. To upgrade a Chat app that isn't an add-on to a Google Workspace add-on that extends Google Chat, see [Convert a Google Chat app to a Google Workspace add-on](https://developers.google.com/workspace/chat/convert).