Identificare e specificare gli utenti di Google Chat

Questa pagina spiega in che modo le app Google Chat e gli sviluppatori possono identificare e specificare gli utenti di Chat.

Per eseguire una delle seguenti operazioni, un'app di chat o uno sviluppatore deve specificare un utente:

Come Chat identifica gli utenti

L'API Google Chat genera una risorsa User per ogni persona e app che utilizza Chat. Una risorsa User contiene i seguenti campi:

  • name: il nome della risorsa, formattato come users/{user}, dove {user} rappresenta un identificatore univoco e stabile. Puoi utilizzare users/app come alias dell'app di chat per le chiamate.
  • displayName: Solo output. Il nome visualizzato dell'utente.
  • avatarUrl: Solo output. L'URL dell'immagine dell'avatar dell'utente.
  • email: Solo output. L'indirizzo email dell'utente.
  • domainId: identificatore univoco del dominio Google Workspace dell'utente.
  • type: il tipo di utente. Indica se l'utente è un'app di chat (BOT) o una persona (HUMAN).
  • isAnonymous: Solo output. Quando true, indica che l'utente è stato eliminato o che il suo profilo non è visibile.

Dettagli del profilo utente e regole di visibilità

Quando chiami le API Messages e Memberships utilizzando l'autenticazione utente, l'API Google Chat compila la risorsa User con i dettagli del profilo. L'API compila displayName, email e avatarUrl sia per gli utenti interni (nella tua organizzazione Google Workspace) sia per gli utenti esterni (in organizzazioni esterne o Account Google personali).

Esempi di posizioni in cui l'API compila i profili utente:

  • Il sender di un Message.
  • Utenti all'interno del messaggio annotations, ad esempio l'utente @mentions.
  • Il member all'interno di una risorsa Membership.

Regole di privacy e visibilità

Per proteggere la privacy degli utenti, l'API Google Chat applica regole di visibilità specifiche per determinare se compilare i dettagli del profilo di un utente:

  • Profilo compilato: l'API compila i dettagli del profilo (displayName, email e avatarUrl sono presenti e isAnonymous è false) se l'utente ha accettato un invito allo spazio (è membro dello spazio) o ha un'affinità precedente (ad esempio una cronologia di interazioni di messaggi diretti) con l'utente chiamante.
  • Profilo anonimo: se un utente viene menzionato in uno spazio senza essere un membro e senza affinità precedente con l'utente che chiama, il suo profilo rimane anonimo. Per un utente anonimo, isAnonymous è true e vengono omessi dettagli come displayName, email e avatarUrl. Tuttavia, per le richieste API effettuate con l'autenticazione dell'app, il campo displayName viene sempre compilato.

Il seguente esempio JSON mostra una risorsa User con i dettagli del profilo compilati restituiti in una risposta API o in un evento di interazione:

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

Il seguente esempio JSON mostra una risorsa User anonima in cui i dettagli del profilo utente non sono visibili al chiamante:

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

Specificare un utente in una chiamata all'API Google Chat

Per specificare un utente, utilizza i seguenti valori per il valore {user}:

  • Per gli utenti della tua organizzazione Google Workspace, utilizza uno dei seguenti approcci:

    • name della risorsa User nell'API Chat, ad esempio users/123456789.
    • Il {person_id} per il nome di una risorsa Person nell'API People, dove resourceName è people/{person_id}, ad esempio, users/123456789 nell'API Chat rappresenta la stessa persona di people/123456789 nell'API People.
    • L'id per una risorsa User nell'API Directory, ad esempio users/123456789 nell'API Chat, rappresenta la stessa persona di users/123456789 nell'API Directory.
    • Per le richieste API effettuate con autenticazione utente, l'indirizzo email dell'utente come alias, ad esempio users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Per un utente di un'organizzazione Google Workspace esterna o un utente che utilizza un Account Google, utilizza uno dei seguenti metodi:

    • Un alias email, ad esempio, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com o users/EMAIL_USERNAME@gmail.com.
    • L'name canonico della risorsa User (ad esempio users/12345678901234567890) ottenuto da una precedente chiamata API o evento di interazione.

Identificare un utente da una risposta API o da un evento di interazione

Puoi identificare gli utenti restituiti dalle chiamate API o dagli eventi in entrata in diversi modi:

Poiché l'API Google Chat compila i profili per gli utenti interni ed esterni quando utilizza l'autenticazione utente, gli sviluppatori non devono chiamare l'API Directory per risolvere i nomi o le email di membri e mittenti dei messaggi.