Publish Google Chat apps

After you've created a Chat app, you can publish it so that it's available to select people or groups, everyone in your Google Workspace organization, or any Google Chat user that has a Google Workspace account.

How users discover and use Google Chat apps

Users can discover and start using Chat apps in a few different ways:

  • Searching for apps in Google Chat
  • Interacting with an app that's been added to a Chat space
  • Discovering the app in their direct messages panel after a Google Workspace administrator installed the app on their behalf.

To start using an app, Google Chat users can start a direct message with the app or add it to a space by choosing it from the proposed recipient list as shown below:

Adding an app to a space by typing @ in a message.

Users can also narrow the proposed recipient list by @mentioning the app by name. For example, if you publish an app called "Scheduler Bot" and a user in your organization types "@sch", then Google Chat suggests your app as one of the autocomplete options.

Alternatively, Google Workspace administrators can find Chat apps on the Google Workspace Marketplace and install the apps for users in their organization. When administrators install a Chat app, the app appears in the users' direct messages panel.

Google Workspace administrators can also manage and allowlist the use of Chat apps in their Google Workspace organization. If you're developing a Chat app for an organization that uses allowlists, you must request that an administrator adds your Chat app to the allowlist so that users can find and use the app. For more information see Google Workspace Admin Help's documentation, Allow users to install Chat apps.

Configure and publish your Chat app using the Google Cloud console

To publish your Chat app and make it available to others, you generally need to follow these steps:

  1. Enable and configure the Google Chat API. When you configure the API, you grant other Google Chat users access to your Chat app for testing.
  2. Publish your app with the Google Workspace Marketplace SDK. You can configure your Chat app to be available to users in your Google Workspace organization, or to all Google Chat users.
  3. If your Google Workspace organization manages access to Chat apps, request that your Google Workspace administrator adds the app to the organization's allowlist.

Visibility and publishing settings for your Chat app

The following table explains how to configure the settings for the Google Chat API and Google Workspace Marketplace SDK based on the audience of your Chat app:

. . . .
I'm building a Chat app... Authentication method Google Chat API settings Google Workspace Marketplace SDK settings Where is my Chat app published?
...For my small team Authenticate as a user or an app.In the Visibility setting, specify people and/or Google Groups that can access the app.

If your Google Workspace account requires apps to be allowlisted, you can only specify up to 5 individual email addresses (You can't specify Google Groups).

 You don't need to configure the Google Workspace Marketplace SDK for your Chat app. Team members can find and use your Chat app from Google Chat.
...For my large team Authenticate as a user or an app.In the Visibility setting, specify people and/or Google Groups to test your Chat app.

After testing, publish your Chat app to your Google Workspace organization using the settings in the Google Workspace Marketplace SDK.

Set App visibility to Private.

Set Installation settings to Individual + Admin.

If your Google Workspace account requires apps to be allowlisted, request that an administrator add your Chat app to the allowlist so that users can find and use the app. For more information see Google Workspace Admin Help's documentation, Allow users to install Chat apps.

Anyone in your Google Workspace organization can find and install your Chat app in Google Chat, and view your app in the Google Workspace Marketplace. Users and Google Workspace administrators can install your app from the Marketplace.
...For my Google Workspace organization Authenticate as a user or an app.In the Visibility setting, specify people and/or Google Groups to test your Chat app.

After testing, publish your Chat app to your Google Workspace organization using the settings in the Google Workspace Marketplace SDK.

Set App visibility to Private.

Set Installation settings to Individual + Admin.

Anyone in your Google Workspace organization can find and install your Chat app in Google Chat, and view your app in the Google Workspace Marketplace. Only Google Workspace administrators can install your app from the Marketplace.
...For everyone (public Chat app) Authenticate as an app.In the Visibility setting, specify people and/or Google Groups to test your Chat app.

After testing, publish your Chat app publicly using the settings in the Google Workspace Marketplace.

Set App visibility to Public.

Set Installation settings to Individual + Admin

Any Google Workspace user can find and install your Chat app in Google Chat, and view your app in the Google Workspace Marketplace. Only Google Workspace administrators can install your app from the Marketplace.

Enable and configure the Google Chat API

Set up a project for your app in the Google API Console and enable the Google Chat API.

  1. Use the button below to create a new project (or select an existing one) and add a service account to it. Give the service account the Project Owner role.
    Enable the API
  2. Save the downloaded JSON key. Your app can use this key to authenticate messages that it sends to spaces asynchronously.
  3. Open your project in the API Console. In the list of APIs, click Google Chat API.
  4. Select the Configuration tab and enter the information for the app, as described in the following table.

When you save the app configuration, your app becomes available to the specified users in your Google Workspace organization.

Google Chat API configuration settings

Field Description
App name The name that people use when interacting with your app.
Avatar URL An HTTPS URL pointing to a square graphics image (e.g. PNG or JPEG), at least 128x128, that will appear as the avatar for your app.
Description A description of the app's functionality which appears below your app's name.
Functionality A set of fields that determine what events can trigger the app:
  • Receive 1:1 messages: Users can find and message the app directly in Google Chat.
  • Receive events from admin installation: Receive ADDED_TO_SPACE or REMOVED_FROM_SPACE events from Chat when a Google Workspace admin installs or uninstalls the app in their organization. By default, the app doesn't receive these events unless you opt-in to receive them because it might result in higher queries per second.
  • Join spaces and group conversations: The app can join spaces and group conversations when it's added to them.
Connection settings The endpoint for the app, which is one of the following:
  • App URL: An HTTPS endpoint where the app implementation is hosted.
  • Apps Script project: A deployment ID for an Apps Script project that implements an app.
  • Cloud Pub/Sub topic name: A Cloud Pub/Sub topic that the app subscribes to as an endpoint.
  • Dialogflow: Registers the app with a Dialogflow integration. For more information, see the Dialogflow documentation on integration with Google Chat.
Slash commands Commands that can be surfaced to users within Google Chat. Allows users to see core actions for your app within Google Chat, and choose a specific action they wish to interact with.
Link unfurling URL patterns that the app recognizes and provides additional content for when users send links. For more information, refer to Unfurl links.
Visibility Up to 5 individuals or one or more Google Groups that can view and install your Chat app. Use this field to test your app, or to share the app with your team. To learn more see Visibility and publishing settings for your Chat app.

Grant app configuration permissions

You can grant specific users access to the app configuration page. To do this, use the Chat apps Owner and Chat apps Viewer IAM roles. Users with these roles can't navigate to the app configuration page via the APIs & Services dashboard, but can access the configuration page by navigating to the console for their project as follows:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=your-project-id

Publish your app with the Google Workspace Marketplace SDK

Use the Google Workspace Marketplace SDK to:

  • Publish your app publicly and let any Google Chat user add your Chat app to a space.
  • Publish your app to your domain.
  • Make your app visible to Google Workspace administrators so that they can install the app for users in their organization. To be visible to Google Workspace administrators, your app must feature direct messaging.

Before you publish your app using the Google Workspace Marketplace SDK, follow these steps:

  1. Test your Chat app by installing it from Chat. Make sure your app is fully functional and not a work in progress.
  2. Review the publication requirements and verify that your app satisfies all of them. See Areas of review.
  3. Record your app’s version number--you need this to configure the Google Workspace Marketplace SDK.

When you're ready to publish, see Overview: Publish an app.

Disable your Chat app

After you save the configuration page, an App Status field appears. This field lets you control whether the app is Live or Disabled.

To disable a Chat app:

  1. Open the Google Cloud console.
  2. If necessary, select the Google Cloud project that hosts the Chat app:
    1. Next to "Google Cloud," click the Down arrow . A dialog listing current projects appears.
    2. Select the project that hosts the migrated Chat app.
    3. Click Open.
  3. Search for "Google Chat API" and click Google Chat API.
  4. Click Manage.
  5. Click Configuration.
  6. In the "App status" section, select Disabled.
  7. Click Save.