Identifier et spécifier des utilisateurs Google Chat

Cette page explique comment les applications et les développeurs Google Chat peuvent identifier et spécifier les utilisateurs Chat.

Pour effectuer l'une des opérations suivantes, une application Chat ou un développeur doit spécifier un utilisateur :

Comment Chat identifie-t-il les utilisateurs ?

L'API Google Chat génère une ressource User pour chaque personne et application qui utilise Chat. Une ressource User contient les champs suivants :

  • name : nom de la ressource, au format users/{user}, où {user} représente un identifiant unique et stable. Vous pouvez utiliser users/app comme alias pour l'application Chat pour les appels.
  • displayName : Sortie uniquement. Nom à afficher de l'utilisateur.
  • avatarUrl : Sortie uniquement. URL de l'avatar de l'utilisateur.
  • email : Sortie uniquement. Adresse e-mail de l'utilisateur.
  • domainId : identifiant unique du domaine Google Workspace de l'utilisateur.
  • type : type d'utilisateur. Indique si l'utilisateur est une application de chat (BOT) ou une personne (HUMAN).
  • isAnonymous : Sortie uniquement. Lorsque la valeur est true, cela indique que l'utilisateur est supprimé ou que son profil n'est pas visible.

Détails du profil utilisateur et règles de visibilité

Lorsque vous appelez les API Messages et Memberships à l'aide de l'authentification utilisateur, l'API Google Chat remplit la ressource User avec les détails du profil. L'API remplit displayName, email et avatarUrl pour les utilisateurs internes (dans votre organisation Google Workspace) et externes (dans des organisations externes ou des comptes Google personnels).

Voici quelques exemples d'emplacements où l'API remplit les profils utilisateur :

  • Le sender d'un Message.
  • Utilisateurs du message annotations, tels que l'utilisateur @mentions.
  • member dans une ressource Membership.

Règles de confidentialité et de visibilité

Pour protéger la confidentialité des utilisateurs, l'API Google Chat applique des règles de visibilité spécifiques lorsqu'elle détermine s'il faut renseigner les informations du profil d'un utilisateur :

  • Profil renseigné : l'API renseigne les détails du profil (displayName, email et avatarUrl sont présents, et isAnonymous est false) si l'utilisateur a accepté une invitation à rejoindre un espace (il est membre de l'espace) ou s'il a une affinité préalable (comme un historique d'interactions par message privé) avec l'utilisateur appelant.
  • Profil anonyme : si un utilisateur est mentionné dans un espace sans être membre et sans affinité préalable avec l'utilisateur appelant, son profil reste anonyme. Pour un utilisateur anonyme, isAnonymous est défini sur true, et les détails tels que displayName, email et avatarUrl sont omis. Toutefois, pour les requêtes API effectuées avec l'authentification de l'application, le champ displayName est toujours renseigné.

L'exemple JSON suivant montre une ressource User avec des informations de profil renseignées renvoyées dans une réponse d'API ou un événement d'interaction :

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

L'exemple JSON suivant montre une ressource User anonyme où les informations du profil utilisateur ne sont pas visibles par l'appelant :

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

Spécifier un utilisateur dans un appel à l'API Google Chat

Pour spécifier un utilisateur, utilisez les valeurs suivantes pour la valeur {user} :

  • Pour les utilisateurs de votre organisation Google Workspace, utilisez l'une des approches suivantes :

    • Le name de la ressource User dans l'API Chat, tel que users/123456789.
    • Le {person_id} pour le nom d'une ressource Person dans l'API People, où resourceName est people/{person_id} (par exemple, users/123456789 dans l'API Chat représente la même personne que people/123456789 dans l'API People).
    • Le id d'une ressource User dans l'API Directory (par exemple, users/123456789 dans l'API Chat) représente la même personne que users/123456789 dans l'API Directory.
    • Pour les requêtes API effectuées avec l'authentification de l'utilisateur, l'adresse e-mail de l'utilisateur en tant qu'alias, par exemple users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Pour un utilisateur d'une organisation Google Workspace externe ou un utilisateur qui utilise un compte Google, procédez de l'une des manières suivantes :

    • Un alias d'adresse e-mail, par exemple users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com ou users/EMAIL_USERNAME@gmail.com.
    • name canonique de la ressource User (par exemple, users/12345678901234567890) obtenu à partir d'un appel d'API ou d'un événement d'interaction précédent.

Identifier un utilisateur à partir d'une réponse d'API ou d'un événement d'interaction

Vous pouvez identifier les utilisateurs renvoyés à partir d'appels d'API ou d'événements entrants de plusieurs manières :

Étant donné que l'API Google Chat remplit les profils des utilisateurs internes et externes lors de l'utilisation de l'authentification des utilisateurs, les développeurs n'ont pas besoin d'appeler l'API Directory pour résoudre les noms ou les adresses e-mail des membres et des expéditeurs de messages.