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:

- Create a message that [@ mentions a user](https://developers.google.com/workspace/chat/format-messages#messages-@mention).
- Invite or add a user to an [existing space](https://developers.google.com/workspace/chat/create-members), or add a user to a [new space](https://developers.google.com/workspace/chat/set-up-spaces).
- [Find direct messages](https://developers.google.com/workspace/chat/find-direct-message-in-spaces) between the Chat app and a specified user, or between two users.
- [Get a user's membership details in a space](https://developers.google.com/workspace/chat/get-members).
- [Send a private message](https://developers.google.com/workspace/chat/private-messages) to a user.
- [Subscribe to a user](https://developers.google.com/workspace/chat/events-overview) using the Google Workspace Events API to get events about their membership changes.

## How Chat identifies users

The Google Chat API generates a
[`User` resource](https://developers.google.com/workspace/chat/api/reference/rest/v1/User)
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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
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:

- The `sender` of a [`Message`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages).
- Users within message `annotations`, such as user [`@mentions`](https://developers.google.com/workspace/chat/format-messages#messages-@mention).
- The `member` within a [`Membership`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.members) resource.

### 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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app), 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](https://developers.google.com/workspace/chat/api/reference/rest/v1/User) in the Chat API, such as `users/123456789`.
  - The `{person_id}` for the name of a [`Person` resource](https://developers.google.com/people/api/rest/v1/people) 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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), the user's email address as an alias, such as `users/EMAIL_ADDRESS`.
- For a user in an external Google Workspace organization, or a user
  who uses a Google Account, use one of the following:

  - For API requests made with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), an email alias such as `users/EMAIL_ADDRESS`.
  - The canonical `name` of the `User` resource, such as `users/12345678901234567890`, obtained from a prior API call or interaction event.

> [!IMPORTANT]
> **Important:** With [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app), service accounts don't support email aliases such as `users/sasha@example.com` when looking up user information with `spaces.findDirectMessage` or mentioning users with `<users/{user}>` syntax. Passing an email alias to `spaces.findDirectMessage` with app authentication returns an HTTP `403` error. Specify a numeric ID in `users/{user}` from a Chat `User` resource, the People API, or the Directory API instead.

## Identify a user from an API response or interaction event

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

- **Messages API** : Get the sender's identity from [`Message.sender`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages#Message) or mentioned users from [`Message.annotations[].userMention.user`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages#UserMentionMetadata).
- **Memberships API** : Get the member's identity from [`Membership.member`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.members#Membership).
- **Interaction events** : When a user interacts with a Chat app, Chat sends an [interaction event](https://developers.google.com/workspace/chat/receive-respond-interactions) with the user's identity in [`Event.user`](https://developers.google.com/workspace/chat/api/reference/rest/v1/Event).

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.

## Related topics

- [Authenticate and authorize as a Google Chat user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
- [Add a user to a space](https://developers.google.com/workspace/chat/create-members).
- [Manage members in a space](https://developers.google.com/workspace/chat/list-members).
- [@ mention a user in a message](https://developers.google.com/workspace/chat/format-messages#messages-@mention).
- [`User` resource REST API reference](https://developers.google.com/workspace/chat/api/reference/rest/v1/User).