Import data to Google Chat

With the Google Chat API, you can import data from your other messaging platforms into Google Chat. You can import existing messages, attachments, reactions, memberships, and space entities from your other messaging platforms to corresponding Chat API resources. You can import this data by creating Chat spaces in import mode and importing data into those spaces.

The following is an overview of the steps involved in importing data by using an import mode space:

Review API usage limits and plan ahead.
Configure authorization for the Chat app.
Create a space in import mode.
Import resources.
Validate imported resources.
Reconcile imported resource differences from source data.
Complete import mode.
Create membership resources.

Prerequisites

Apps Script

A Google Workspace account with access to Google Chat.
A published Chat app. To build a Chat app, follow this quickstart.

Python

Python 3.6 or greater
The pip package management tool
The latest Google client libraries for Python. To install or update them, run the following command in your command-line interface:
```
pip3 install --upgrade google-api-python-client google-auth
```
A published Chat app. To create and publish a Chat app, see Build a Google Chat app.
Authorization configured for the Chat app. The Chat app must be delegated domain-wide authority in any domains that the app imports content in, see Authorize Chat apps.

Review API usage limits and plan ahead

The time required to import data into Chat can vary greatly depending on the quantity of Chat resources to import. Plan ahead by reviewing your Chat app's usage limits and the amount of data scheduled for import from the source messaging platform, to determine an estimated timeline.

Create a space in import mode

To create a space in import mode, call the create method on the Space resource and set importMode to true. In order to preserve the creation time of the equivalent space entity from the source messaging platform, you can set the createTime of the space. This createTime must be set to a value between January 1, 2000 and present time.

Make note of the name of the space that you create so you can reference it in later steps when importing content into the space.

From the time that the create method is called, Chat apps have 30 days to import resources into the space, to complete import mode, and to create membership resources using the chat.import scope. Chat apps can still create memberships after 30 days with standard Chat API membership scopes. After 30 days, if the space is still in import mode, it's automatically deleted and will be inaccessible, and unrecoverable by the Chat app. Plan ahead by reviewing your Chat app's usage limits to ensure that all scheduled resources can be imported into Chat within this timeframe.

The following example shows how to create a space in import mode:

Apps Script

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'Import Mode Space',
      importMode: true,
      createTime: (new Date('January 1, 2000')).toJSON()
  });
  console.log(space.name);
}

Python

"""Create a space in import mode."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

result = (
    service.spaces()
    .create(
        body={
            'spaceType': 'SPACE',
            'displayName': 'Import Mode Space',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

Replace the following:

EMAIL: the email address of the user account that you're impersonating with domain-wide authority.

Import resources

To import resources from other messaging platforms, you create Google Chat resources (such as messages, reactions, attachments) in the import mode space. When you create a resource in the space, you specify data from the related resource from the message platform that you're migrating from.

Messages

Your Chat apps can import messages using their own authority, or on behalf of a user through impersonation. (The message author is set to the impersonated user account.) For more information, see Authorize Chat apps. To import a message in an import mode space, call the create method on the Message resource. In order to preserve the creation time of the original message from the source messaging platform, you can set the createTime of the message. This createTime must be set to a value between the space creation time that you previously set and present time.

Messages in the same space cannot contain the same createTime, even if previous messages with that time are deleted.

Messages containing third-party URLs in import mode spaces can't render link previews within Google Chat.

When you create the messages in import mode, spaces don't notify or send email to any users, including messages which contain user mentions.

The following example shows how to create a message in an import mode space:

Python

"""Create a message in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = (
    service.spaces()
    .messages()
    .create(
        parent=NAME,
        body={
            'text': 'Hello, world!',
            'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
        },
    )
    .execute()
)

print(result)

Replace the following:

EMAIL: the email address of the user account that you're impersonating with domain-wide authority.
SPACE_NAME: the name for the space created in import mode.

Reactions

Your Chat app can import reactions for messages by using the Chat API. For information about the resource methods and types of authentication support in import mode spaces, see Authorize Chat apps.

Attachments

Your Chat app can upload attachments using the Chat API. For information about the resource methods and types of authentication support in import mode spaces, see Authorize Chat apps.

Historical memberships

Historical memberships are memberships created for users who had already left the original space entity from the source messaging platform, but you want to retain their data in Chat. For information about adding new members after the space is no longer in import mode, see Create membership resource.

In many cases, when those historical members are subject to a data retention policy in Google, you want to preserve the data (such as Messages and reactions) created by historical memberships in a space before importing them to Chat. While the space is in import mode, you can import those historical memberships into the space, using the create method on the Membership resource. In order to preserve the leave time of the historical membership, you must set the deleteTime of the membership. This leave time must be accurate because it impacts which data to retain for those memberships. Moreover, this deleteTime must be after the space creation timestamp and must not be a future timestamp.

In addition to deleteTime, you can also set createTime to preserve the original join time of the historical membership. Unlike deleteTime, the createTime is optional. If unset, createTime is automatically calculated by subtracting 1 microsecond from deleteTime. If set, createTime must be before deleteTime and must be on or after the space creation time. This createTime information isn't used to determine data retention and isn't visible in admin tools such as the Google Admin console and Google Vault.

While there might be multiple ways that a user can join and leave a space in the source messaging platform (through invites, joining by themselves, being added by another user), in Chat those actions are all represented by the historical membership createTime and deleteTime fields as being added or removed.

The following example shows how to create a historical membership in an import mode space:

Python

"""Create a historical membership in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
    service.spaces()
    .members()
    .create(
        parent=NAME,
        body={
            'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
            'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
            'member': {'name': USER, 'type': 'HUMAN'},
        },
    )
    .execute()
)

print(result)

Replace the following:

EMAIL: the email address of the user account that you're impersonating with domain-wide authority.
SPACE_NAME: the name for the space created in import mode.
USER_ID: the unique ID for the user.

Validate imported resources

Your Chat app can read back and validate the contents of an import mode space by calling the list method on the Message resource. You can read Reaction and Attachment resources from any returned message's emojiReactionSummaries and attachment fields. Chat apps can only call this method on behalf of a user through impersonation. For more information, see Authorize Chat apps.

Your Chat app can also read individual messages for validation by calling the get method on the Message resource. Chat apps can only call this method to read their own messages by using their own authority. For more information, see Authorize Chat apps.

Chat apps can also list historical memberships by calling the list method on the Membership resource. After the space exits import mode, the list method doesn't expose historical memberships anymore. Chat apps can only call this method on behalf of a user through impersonation. For more information, see Authorize Chat apps.

You can read an import mode space's properties by calling the get method on the Space resource. Chat apps can only call this method using their own authority. For more information, see Authorize Chat apps.

Reconcile imported resource differences from source data

If any imported resource no longer matches the original entity from the source messaging platform due to changes in the original entity during import, Chat apps can call the Chat API to modify the imported chat resource. For example, if a user edits a message in the source messaging platform after that message was created in Chat, Chat apps can update the imported message so that it reflects the current content of the original message.

Messages

To update supported fields on a message in an import mode space, call the update method on the Message resource. Chat apps can only call this method using the same authority that was used during the initial message creation. If you used user impersonation during the initial message creation, you must use the same impersonated user to update that message.

To delete a message in an import mode space, call the delete method on the Message resource. Messages in an import mode space don't need to be deleted by the original message creator and can be deleted by impersonating any user in the domain. Chat apps can only delete their own messages using their own authority. For more information, see Authorize Chat apps.

Reactions

To delete a reaction for a message in an import mode space, use the delete method on the reactions resource. For information about the resource methods and types of authentication support in import mode spaces, see Authorize Chat apps.

Attachments

To update attachments for a message in an import mode space, use the upload method on the media resource. For information about the resource methods and types of authentication support in import mode spaces, see Authorize Chat apps.

Historical memberships

To delete a historical membership in an import mode space, use the delete method on the Membership resource. After a space exits import mode, the delete method doesn't let you delete historical memberships anymore.

You can't update a historical membership in an import mode space. If you want to correct an incorrectly imported historical membership, you need to delete it first and then recreate it while the space is still in import mode.

Spaces

To update supported fields in an import mode space, use the patch method on the spaces resource.

To delete an import mode space, use the delete method on the spaces resource.

For information about the resource methods and types of authentication support in import mode spaces, and see Authorize Chat apps.

Complete import mode

Before calling the completeImport method, you should ensure that validation and reconciliation of resource differences are completed. Exiting a space out of import mode is an irreversible process and converts the import mode space into a regular space. There's no indicator in Chat that attributes these spaces to a data import.

To complete import mode and make the space accessible to users, the Chat app can call the completeImport method on the Space resource. Chat apps can only call this method on behalf of a user through impersonation. For more information, see Authorize Chat apps. The impersonated user is added to the space as a space manager once this method completes. This method must be called within 30 days of the initial create.space method call. If you attempt to call this method after the 30 day duration has elapsed, the call results in failures because the import mode space is deleted and is no longer accessible to the Chat app.

The impersonated user in the completeImport method doesn't need to be the space creator.

The following example shows how to complete the import mode:

Python

"""Complete import."""

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()

print(result)

Replace the following:

EMAIL: the email address of the user account that you're impersonating with domain-wide authority.
SPACE_NAME: the name for the space created in import mode.

Create membership resources

To add user memberships for a space that has completed import mode, call the create method on the Membership resource. Chat apps can continue to use the chat.import scope and user impersonation to call this method within 30 days of the initial create.space method call. The impersonated user must be a space manager.

After the 30-day duration has elapsed, Chat apps require additional membership scopes to call this method.

We recommend that Chat apps create membership resources immediately after the import is completed, so that Chat apps can continue to use the chat.import scope for membership creation, and to provide all members with access to the imported space.