Migrate your Google Chat app

If you merge Google Workspace organizations, you might need to migrate your Chat app so that it continues working.

Before migrating your Chat app, check with your organization's administrator to see if administrative settings are affecting it. Changing an administrative setting might restore full functionality to your Chat app and make migration unnecessary. For example, your Google Workspace administrator might have to add your Chat app to an allowlist, or might have to let users install Chat apps. For more information, see Determine if Google Chat apps need to migrate after merging Google Workspace organizations.

After you determine that you need to migrate your Chat app complete the following three-step process:

  1. Set up the environment for your Chat app by creating a Google Cloud project in the merged organization, enabling APIs, and potentially configuring the OAuth 2.0 consent screen.
  2. Redeploy your Chat app from the new Cloud project.
  3. Add the recreated Chat app to Chat spaces or conversations, and turn off the original Chat app.

Create a Cloud project in the merged organization and enable APIs

Creating a new Cloud project and enabling APIs for the Chat app in the merged Google Workspace organization makes sure that users and groups who you let access the Chat app can do so without error.

Create a Cloud project

Google Cloud console

  1. In the Google Cloud console, go to Menu > IAM & Admin > Create a Project.

    Go to Create a Project

  2. In the Project Name field, enter a descriptive name for your project.

    Optional: To edit the Project ID, click Edit. The project ID can't be changed after the project is created, so choose an ID that meets your needs for the lifetime of the project.

  3. In the Location field, click Browse to display potential locations for your project. Then, click Select.
  4. Click Create. The Google Cloud console navigates to the Dashboard page and your project is created within a few minutes.

gcloud CLI

In one of the following development environments, access the Google Cloud CLI (gcloud):

  • Cloud Shell: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell.
    Activate Cloud Shell
  • Local Shell: To use a local development environment, install and initialize the gcloud CLI.
    To create a Cloud project, use the gcloud projects create command: 
    gcloud projects create PROJECT_ID
     Replace PROJECT_ID by setting the ID for the project you want to create.

Enable APIs

All Chat apps are required to have the Google Chat API enabled. Depending on how your Chat app is built, you might need to enable other APIs. For example, if you built your Chat app using Google Cloud Functions, enable the Cloud Build API, Cloud Functions API, Pub/Sub API, Cloud Logging API, Artifact Registry API, and Cloud Run API. As a best practice, to ensure that the migrated app works, enable the same APIs in the new Cloud project that are enabled in the old Cloud project.

To enable an API, do the following:

Google Cloud console

  1. In the Google Cloud console, go to Menu > More products > Google Workspace > Product Library.

    Go to Product Library

  2. Click the API that you want to turn on.
  3. Click Enable.
  4. To enable more APIs, repeat these steps.

Google Cloud CLI

  1. Install or open the Google Cloud Command Line Interface (CLI).

  2. Run the services enable command, specifying which API service to enable.

    gcloud services enable API_SERVICE_ID

Configure the Chat API

In your new Cloud project, you must use the Chat API to specify your Chat app's name, description, and icon. To configure these details, see Configure the Chat API

It might be necessary to configure the OAuth consent screen for your Cloud project. If you previously used OAuth 2.0 for authorization, use the same authorization scopes of access.

  1. In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.

    Go to OAuth consent screen

  2. Select the user type for your app, then click Create.
  3. Complete the app registration form, then click Save and Continue.

  4. If you're creating an app for use outside of your Google Workspace organization, click Add or Remove Scopes. We recommend the following best practices when selecting scopes:

    • Select the scopes that provide the minimum level of access required by your app. For a list of available scopes, see OAuth 2.0 Scopes for Google APIs.
    • Review the scopes listed in each of the three sections: non-sensitive scopes, sensitive scopes, and restricted scopes. For any scopes listed in the "Your sensitive scopes" or "Your restricted scopes" sections, try to identify alternative non-sensitive scopes to avoid unnecessary additional reviews.
    • Some scopes require additional reviews by Google. For apps used only internally by your Google Workspace organization, scopes aren't listed on the consent screen and use of restricted or sensitive scopes doesn't require further review by Google. For more information, see Scope categories.
  5. After selecting the scopes required by your app, click Save and Continue.
  6. If you selected External for user type, add test users:
    1. Under Test users, click Add users.
    2. Enter your email address and any other authorized test users, then click Save and Continue.
  7. Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.

Redeploy your Chat app to the new Cloud project

Depending on whether your Chat app is built with Apps Script, AppSheet, or another connection type, like Python or Java, redeploying your Chat app differs a little. In either case, you don't need to recreate all of your code, but you do need to make some changes.

Migrate the Chat app logic

Depending on the architecture of your Chat app, you might need to migrate other services to the new Cloud project:

  • For HTTP apps, you also need to migrate the rest of the app logic that was built using Cloud Functions, Cloud Run, or App Engine.
  • For conversational Chat apps that use natural language, you also need to migrate the Dialogflow agents.
  • For Chat apps that are built behind a firewall, you also need to migrate the Pub/Sub topics.

Configure interactive features in the new Cloud project

To redeploy your Chat app that's built with a language like Python or Java, configure the Chat app in your new Cloud project.

To configure interactive features, see Receive and respond to user interactions.

Redeploy an Apps Script Chat app

To redeploy your Chat app that's built with Apps Script, change the Cloud project number that the Apps Script project is associated with to the project number that belongs to your new Cloud project. Then, copy your Apps Script deployment ID and paste it into the Chat app configuration page in the Google Cloud console.

Copy your Cloud project number

  1. In the Google Cloud console, go to Menu > IAM & Admin > Settings.

    Go to IAM & Admin Settings

  2. In the Project number field, copy the value.

Set your Google Cloud project number in your Apps Script project

  1. Go to Apps Script.

    Go to Apps Script

  2. In the Chat app Apps Script project, click Project Settings .

  3. Under Google Cloud Platform (GCP) Project, click Change project.

  4. In GCP project number, paste the Google Cloud project number.

  5. Click Set project.

Copy your Apps Script project's deployment ID

  1. In the top-right of Apps Script, click Deploy > Manage deployments.
  2. Under Deployment ID, click Copy.
  3. Click Done.

Reconfigure and redeploy your Chat app

  1. In the Google Cloud console, search for "Google Chat API" and click Google Chat API, then click Manage.

    Go to Chat API

  2. Click the Configuration tab, and enter the following required information:

    • App name: The name that people use when interacting with your Chat app.
    • Avatar URL: An HTTPS URL pointing to a square graphics image (for example, PNG or JPEG), at least 128x128, that appears as the avatar for your Chat app.
    • Description: A description of the Chat app's intended purpose which appears below your Chat app's name.

  3. To turn on interactive features, click the Enable interactive features toggle that let users interact with your Chat app:

  4. Under Connection settings, select Apps Script project.

  5. In the Deployment ID field, paste the deployment ID that you previously copied.

  6. To complete the rest of the configuration, see the table in the Configure the Chat app in the new Cloud project

  7. Click Save.

Redeploy an AppSheet Chat app

To redeploy your Chat app that's built with AppSheet in your new Cloud project, copy the app to the new Cloud project.

Update the service account

If your Chat app authenticates as an app and uses a service account to make calls to Google APIs, update the Chat app's service account details. For more information, see Authenticate as a Chat app.

Share your Chat app

Before your Chat app becomes available to users in the new organization, your administrator might have to manually allow access to the Chat app. For more information, refer to How Google Workspace administrators install Chat apps.

Switch to the new Chat app

Now that the Chat app is migrated to the new organization, it's time to publicize it. Add it into Chat spaces or direct messages, and then remove the old Chat app from them so that people only message the migrated Chat app.

Add the new Chat app to Chat spaces

  1. Go to Chat.

    Go to Chat

  2. Click a direct message or space.

  3. Click the drop-down next to the name of the space or person, and then select Apps & integrations.

  4. Click Add apps.

  5. Enter the name of the app, select the app from the list, and then click Add.

  6. Repeat these steps for every space or direct message that you want to add the Chat app to.

Remove the old Chat app from Chat spaces

  1. Go to Chat.

    Go to Chat

  2. Click a direct message or space.

  3. Click the drop-down next to the name of the space or person, and then select Apps & integrations.

  4. Next to the old, un-migrated Chat app, click More options , and then click Remove from space.

  5. Repeat these steps for every space or direct message that you want to remove the old Chat app from.

Turn off the old Chat app

To prevent users from using the old Chat app and to encourage them to use the new Chat app, turn off the old Chat app and unpublish it from Google Workspace Marketplace.