Migrate Chat bots shared in your domain after merging Google Workspace organizations

If your Google Workspace organization or domain merges with another one, your Google Chat bot might stop responding, disappear from direct messages and Chat rooms, or otherwise stop working as expected. Mergers don't always affect Chat bots, and your Chat bot might remain fully functional, especially if you published it on the Google Workspace Marketplace or created it as a member of the destination environment; the Google Workspace organization or domain that other organizations or domains merge into. If your Chat bot is affected by the merge, then to ensure a fully functional Chat bot, migrate it to a new Google Cloud project.

Does your Chat bot require migration?

If any of the following conditions are true, then your Chat bot might remain fully functional with no need to migrate:

  • Your Chat bot is published on the Google Workspace Marketplace.
  • You, the Chat bot developer, were a member of the destination environment when you first saved your Chat bot configuration.
  • Your Chat bot is only shared with specific users via their email addresses, and users' email addresses remain the same after the merge.

Whether or not you have to migrate your Chat bot is determined by how you publish your Chat bot and by administrative settings in the merged Google Workspace organization that might cause your Chat bot to stop working. For example, the administrator of the merged Google Workspace organization might have to add your Chat bot to an allowlist, or might have to allow users to install Chat bots. For more information, see Allow users to install bots in the Google Workspace admin help.

Before migrating your Chat bot, check with your organization’s admin to see if administrative settings are affecting it. Changing an administrative setting might restore full functionality to your Chat bot and make migration unnecessary.

What happens to Chat bots after the merge?

To ensure that your Chat bot does not respond to users who shouldn't have permission to message it, access to your bot remains limited to the domain or organization under which it was created.

If you were a member of the destination environment when you first saved your Chat bot configuration, then your Chat bot continues to work as expected.

If you were a member of a source environment when you first saved your Chat bot, then whether people retain or lose access to your Chat bot is determined by how the Chat bot is shared:

  • If your Chat bot is shared with Everyone in your domain, then after merging, users who are now part of the destination environment lose access to your Chat bot.
  • If your Chat bot is shared with both specific users and groups, then after merging, the specific users retain access to the Chat bot, but the groups lose access.

To allow groups or the entire domain to message your Chat bot, migrate the Chat bot and set the appropriate permissions on the Google Chat API Configuration page in Google Cloud Console.

Migrate your Chat bot

Migrating your Chat bot is a three-step process.

  1. Create a Google Cloud project in the destination environment and enable APIs.
  2. Redeploy your Chat bot from the new Google Platform project.
  3. Add the recreated Chat bot to Chat rooms or conversations, and disable the original bot.

Step 1: Create a Google Cloud project in the destination environment and enable APIs

Creating a new Google Cloud project for the migrated Chat bot in the merged Google Workspace organization ensures that users and groups who you let access the Chat bot can do so without error.

  1. Open the Google Cloud Console.
  2. Next to "Google Cloud Platform," click the Down arrow . A dialog listing current projects appears.
  3. Click New Project. The New Project screen appears.
  4. In the Project Name field, enter a descriptive name for your project.
  5. (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.
  6. Click Organization and select your organization.
  7. In the Location field, click Browse to display potential locations for your project.
  8. Click a location and click Select.
  9. Click Create. The console navigates to the Dashboard page and your project is created within a few minutes.

After creating the project, you’re ready to enable the APIs your Chat bot uses to run. All Chat bots require “Google Chat API”. Depending on how your Chat bot is built, you might need to enable other APIs. For example, if your Chat bot uses Google Cloud Functions, enable “Cloud Functions API” and “Cloud Build API”. As a best practice, to ensure that the migrated bot works without error, enable the same APIs in the new project that are enabled in the old project.

To enable an API:

  1. Open the Google Cloud Console.
  2. Next to "Google Cloud Platform," click the Down arrow and select your new project.
  3. In the top-left corner, click Menu > APIs & Services.
  4. Click Enable APIs and Services. The Welcome to API Library page appears.
  5. In the search field, enter the name of the API you want to enable. For example, type “Google Chat API” to find the Google Chat API.
  6. Click the API to enable. The API page appears.
  7. Click Enable. The Overview page appears.
  8. To enable an additional API, repeat steps 3 - 7.

It might be necessary to configure the OAuth consent screen for your Google Cloud project. To configure the OAuth consent screen, refer to Setting up OAuth 2.0. If your Chat bot uses a service account, it might be helpful to refer to Use service accounts.

For further information on Google Cloud projects, refer to Creating and managing projects.

Step 2: Redeploy your Chat bot from the new Google Platform project

Depending on whether your Chat bot is built with Apps Script or another language, like Python or Java, redeploying your Chat bot differs a little. In either case, you don’t need to recreate all of your code.

Redeploy a Chat bot

To redeploy your Chat bot, specify the correct configuration in your new Google Cloud project.

  1. Open the Google Cloud Console.
  2. Next to "Google Cloud Platform," click the Down arrow and select your new project.
  3. In the search field, enter the name of the API you want to enable. For example, type “Google Chat API” to find the Google Chat API.
  4. Click Manage.
  5. Click Configuration.
  6. Complete the configuration form. For help completing the configuration form, refer to About bot configuration.
  7. Click Save.

Redeploy an Apps Script Chat bot

To redeploy your Apps Script Chat bot, change the Google Cloud project number its Apps Script project is associated with to the one belonging to your new Google Cloud project. Then, copy your Apps Script deployment ID and paste it into the Chat bot configuration page in Google Cloud Console.

Copy your Google Cloud project number
  1. Open the Google Cloud Console.
  2. Next to "Google Cloud Platform," click the Down arrow and select your new project.
  3. In the top-left corner, click Menu > IAM & Admin > Manage Resources.
  4. Find your new project in the listed projects. In the filter bar, enter the name of your new project and press enter.
  5. Next to your project, click More options > Settings.
  6. Under “Project number”, copy the project number.
Switch your Apps Script project's Google Cloud project

New editor

  1. Go to script.google.com.
  2. In the search bar, search for your Chat bot’s Apps Script project.
  3. Click the Apps Script project.
  4. Click Project Settings .
  5. Under Google Cloud Platform (GCP) Project, click Change project.
  6. In GCP project number, enter the Google Cloud project number.
  7. Click Set project.

Legacy editor

  1. Go to script.google.com.
  2. In the search bar, search for your Chat bot’s Apps Script project.
  3. Click the Apps Script project.
  4. Click Resources > Cloud Platform project.
  5. In the Change Project section, paste the project number you copied into the text field, then click Set Project.
  6. A warning screen explains the effects of changing the Cloud Platform project. Read the notice carefully, and click Confirm.
Copy your Apps Script project's deployment ID

New editor

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

Legacy editor

  1. Click Publish > Deploy from manifest.
  2. Next to the version you want to deploy, click Get ID.
  3. Copy the Deployment ID.
  4. Click Close, then click Close again.
Reconfigure and redploy your Chat bot
  1. Open the Google Cloud Console.
  2. Next to "Google Cloud Platform," click the Down arrow and select your new project.
  3. In the search field, search for “Google Chat API” and click Google Chat API.
  4. Click Manage.
  5. Click Configuration.
  6. Under Connection settings, select Apps Script project.
  7. In the Deployment ID field, paste the deployment id.
  8. Complete the configuration form. For help completing the configuration form, refer to About bot configuration.
  9. Click Save.

Before your Chat bot becomes available to users in the destination environment, your administrator might have to manually allow the Chat bot. For more information, refer to Share your bot only in your domain.

Step 3: Add the recreated Chat bot to Chat rooms or conversations, and disable the original bot

Now that the Chat bot is migrated to the destination environment, it's time to publicize it. Add it into Chat rooms or conversations and remove the old bot from them so that people only message the migrated bot.

First, add the migrated bot to rooms or conversations:

  1. Go to Chat or Gmail.
  2. Select a conversation or room.
    • If the conversation window is expanded, at the top, click the drop-down next to the name of the room or person.
    • If the conversation window is minimized, click More options .
  3. Click Add people & bots.
  4. Choose an option:
    • Enter the name of the bot.
    • Search to find the bot.
  5. Click Send.
  6. Repeat steps 2 - 5 for multiple Chat conversations and rooms, as necessary.

Next, remove the old bot from rooms or conversations:

  1. Go to Chat or your Gmail account.
  2. Select a conversation or room.
    • If the conversation window is expanded, at the top, click the drop-down next to the name of the room or person.
    • If the conversation window is minimized, click More options .
  3. Click View members.
  4. Point to the old, un-migrated Chat bot and click More options > Remove from room.
  5. Repeat steps 2 - 4 for multiple Chat conversations and rooms, as necessary.

For further information about adding and removing bots, refer to Get started with bots in Google Chat.

Finally, disable the original bot to encourage people to replace it with the new one:

  1. Open the Google Cloud Console.
  2. If necessary, select the Google Cloud project that hosts the original, non-migrated Chat bot.
    1. Next to "Google Cloud Platform," click the Down arrow . A dialog listing current projects appears.
    2. Select the project that hosts the migrated Chat bot.
    3. Click Open.
  3. In the search field, enter "Google Chat API" and click Google Chat API.
  4. Click Manage.
  5. Click Configuration.
  6. In the "Bot status" section, select Disabled.
  7. Click Save.

Further reading

As you migrate your Chat bot, it may be helpful to refer to the following: