Identify and specify Google Chat users

  • Google Chat apps can identify users through a unique User resource with a name and type field to distinguish between bots and humans.

  • You can specify a user in API calls using their resource name, Person resource ID, Directory API ID, or email alias depending on their location and account type.

  • Chat apps receive user information during interactions through the User resource within the event data, allowing identification and actions based on user details.

  • User identification enables features like mentioning users in messages, adding them to spaces, managing memberships, sending private messages, and subscribing to events.

  • Resources such as the User and Person objects, along with API guides, are available for further understanding and implementing user management in Chat apps.

This page explains how Google Chat apps and developers can identify and specify Chat users.

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

How Chat identifies users

The Google Chat API generates a User resource for each person and app that uses Chat. A User resource contains the following fields:

  • name: The resource name, formatted as users/{user}, where {user} represents a unique and stable identifier. You can use users/app as an alias for the calling Chat app.
  • displayName: Output only. The user's display name.
  • avatarUrl: Output only. The user's avatar image URL.
  • email: Output only. The user's email address.
  • domainId: Unique identifier of the user's Google Workspace domain.
  • type: The type of user. This indicates whether the user is a Chat app (BOT) or a person (HUMAN).
  • isAnonymous: Output only. When true, indicates that the user is deleted or their profile is not visible.

User profile details and visibility rules

When calling the Messages and Memberships APIs using user authentication, the Google Chat API populates the User resource with profile details. The API populates displayName, email, and avatarUrl for both internal users (in your Google Workspace organization) and external users (in external organizations or personal Google Accounts).

Examples of where the API populates user profiles include the following locations:

Privacy and visibility rules

To protect user privacy, the Google Chat API applies specific visibility rules when determining whether to populate a user's profile details:

  • Populated profile: The API populates profile details (displayName, email, and avatarUrl are present, and isAnonymous is false) if the user has accepted a space invitation (is a member of the space) or has a prior affinity (such as a direct message interaction history) with the calling user.
  • Anonymous profile: If a user is mentioned in a space without being a member and without prior affinity with the calling user, their profile remains anonymous. For an anonymous user, isAnonymous is true, and details like displayName, email, and avatarUrl are omitted. However, for API requests made with app authentication, the displayName field always populates.

The following JSON example shows a User resource with populated profile details returned in an API response or interaction event:

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

The following JSON example shows an anonymous User resource where the user profile details are not visible to the caller:

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

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 the User resource in the Chat API, such as users/123456789.
    • The {person_id} for the name of a Person 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 API requests made with user authentication, the user's email address as an alias—for example, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • For a user in an external Google Workspace organization, or a user who uses a Google Account, use one of the following:

    • An email alias—for example, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com or users/EMAIL_USERNAME@gmail.com.
    • The canonical name of the User resource (such as users/12345678901234567890) obtained from a prior API call or interaction event.

Identify a user from an API response or interaction event

You can identify users returned from API calls or incoming events in several ways:

Because the Google Chat API populates profiles for both internal and external users when using user authentication, developers don't need to call the Directory API to resolve names or emails for members and message senders.