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:
- Configure authorization for the Chat app.
- Create a space in import mode.
- Import resources excluding memberships.
- Validate imported resources.
- Reconcile imported resource differences from source data.
- Complete import mode.
- Create membership resources.
Prerequisites
- A Chat app. To create a Chat app, see Create Chat apps.
- 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.
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 excluding memberships
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.
Import resources (excluding memberships)
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.
You cannot create membership resources in a space that is in import mode. To migrate members, you must create the membership resources after the space has imported the other resources.
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.
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.
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.
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.
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.
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.
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.