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 an existing space, or add a user to a new space.
- Find direct messages between 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 a
User
resource
for each person that uses Chat. The following are two important
User
fields:
name
is the resource name for the resource, formatted asusers/{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 isBOT
. 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
resource in the Chat API, such asusers/123456789
. - The
{person_id}
for the name of aPerson
resource in the People API, where theresourceName
ispeople/{person_id}
—for example,users/123456789
in the Chat API represents the same person aspeople/123456789
in the People API. - The
id
for aUser
resource in the Directory API—for example,users/123456789
in the Chat API represents the same person asusers/123456789
in the Directory API.
- The
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
orusers/EMAIL_USERNAME@gmail.com
.
Identify a user from an interaction event
Every time a user interacts with a Chat app, Chat sends an interaction 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 the
User
resource,
which you can get from
Event.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 the
User
resource, using either of the
following: