Identify and specify Google Chat users (original) (raw)

This page explains the ways Google Chat apps can identify or specify Chat users.

To do any of the following, a Chat app must specify a user:

• Create a message that@ mentions a user.
• Invite or add a user to anexisting space, or add a user to anew space.
• Find direct messagesbetween the Chat app and a specified user, or between two users.
• Get a user's membership details in a space.
• Send a private message to a user.
• Subscribe to a user using the Google Workspace Events API to get events about their membership changes.

How Chat identifies users

The Google Chat API generates aUser resourcefor each person that uses Chat. The following are two importantUser fields:

• name is the resource name for the resource, formatted as users/{user}, where {user} represents a unique and stable identifier. users/app can be used as an alias for the calling Chat app.
• type is the type of user. This type tells Chat whether the user is a Chat app or a person. For Chat apps, the value is BOT. For people, the value isHUMAN.

Specify a user in a call to the Google Chat API

To specify a user, use the following values for the {user} value:

• For users in your Google Workspace organization, use one of the following approaches:
  • The name of theUser resourcein the Chat API, such as users/123456789.
  • The {person_id} for the name of aPerson resource in the People API, where the resourceName is people/{person_id}—for example,users/123456789 in the Chat API represents the same person as people/123456789 in the People API.
  • The id for a User resource in the Directory API—for example,users/123456789 in the Chat API represents the same person as users/123456789 in the Directory API.
• For a user in an external Google Workspace organization, or a user who uses a Google Account, use an email alias—for example,users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com or users/EMAIL_USERNAME@gmail.com.

Identify a user from an interaction event

Every time a user interacts with a Chat app, Chat sends aninteraction event with information about the interaction and the user. For example, when a user mentions a Chat app in a message, the Chat app receives information about the interaction, including what the message says, and who sent it. Chat apps reference users when retrieving information about Chat resources.

To identify the user who interacted with a Chat app, get the value of the name property on theUser resource, which you can get fromEvent.user.name.

The following JSON example shows the expected format of the user identity in an interaction with a Chat app:

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

A message is a specific type of interaction. To identify a user who sent a message to a Chat app, get the value of the name property on theUser resource, using either of the following:

• spaces.messages.sender.name
• Event.user.name
• Add a user to a space.
• Manage members in a space.
• @ mention a user in a message.