Google Chat-Nutzer identifizieren und spezifizieren

Auf dieser Seite wird erläutert, wie Google Chat-Apps und Entwickler Chat-Nutzer identifizieren und angeben können.

Für die folgenden Aktionen muss in einer Chat-App oder von einem Entwickler ein Nutzer angegeben werden:

So werden Nutzer in Google Chat identifiziert

Die Google Chat API generiert für jede Person und App, die Chat verwendet, eine User-Ressource. Eine User-Ressource enthält die folgenden Felder:

  • name: Der Ressourcenname im Format users/{user}, wobei {user} eine eindeutige und stabile ID ist. Sie können users/app als Alias für die Chat-App für Anrufe verwenden.
  • displayName: Nur Ausgabe. Der Anzeigename des Nutzers.
  • avatarUrl: Nur Ausgabe. Die URL des Avatarbilds des Nutzers.
  • email: Nur Ausgabe. Die E-Mail-Adresse des Nutzers.
  • domainId: Eindeutige Kennung der Google Workspace-Domain des Nutzers.
  • type: Der Nutzertyp. Gibt an, ob der Nutzer eine Chat-App (BOT) oder eine Person (HUMAN) ist.
  • isAnonymous: Nur Ausgabe. Wenn true angezeigt wird, bedeutet das, dass der Nutzer gelöscht wurde oder sein Profil nicht sichtbar ist.

Details zum Nutzerprofil und Sichtbarkeitsregeln

Wenn Sie die Messages API und die Memberships API mit Nutzerauthentifizierung aufrufen, werden die Profilinformationen in der User-Ressource der Google Chat API eingefügt. Die API füllt displayName, email und avatarUrl sowohl für interne Nutzer (in Ihrer Google Workspace-Organisation) als auch für externe Nutzer (in externen Organisationen oder privaten Google-Konten) aus.

Beispiele dafür, wo die API Nutzerprofile erstellt:

  • Die sender eines Message.
  • Nutzer in der Nachricht annotations, z. B. Nutzer @mentions.
  • Die member in einer Membership-Ressource.

Datenschutz- und Sichtbarkeitsregeln

Zum Schutz der Privatsphäre der Nutzer gelten für die Google Chat API bestimmte Sichtbarkeitsregeln, wenn entschieden wird, ob die Profildetails eines Nutzers ausgefüllt werden:

  • Ausgefülltes Profil: Die API füllt die Profildetails aus (displayName, email und avatarUrl sind vorhanden und isAnonymous ist false), wenn der Nutzer eine Einladung für einen Bereich angenommen hat (Mitglied des Bereichs ist) oder eine frühere Beziehung (z. B. einen Direktnachrichtenaustausch) mit dem anrufenden Nutzer hat.
  • Anonymes Profil: Wenn ein Nutzer in einem Bereich erwähnt wird, ohne Mitglied zu sein und ohne vorherige Affinität zum anrufenden Nutzer, bleibt sein Profil anonym. Bei einem anonymen Nutzer ist isAnonymous gleich true. Details wie displayName, email und avatarUrl werden weggelassen. Bei API-Anfragen, die mit App-Authentifizierung gestellt werden, wird das Feld displayName jedoch immer ausgefüllt.

Das folgende JSON-Beispiel zeigt eine User-Ressource mit ausgefüllten Profildetails, die in einer API-Antwort oder einem Interaktionsereignis zurückgegeben werden:

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

Das folgende JSON-Beispiel zeigt eine anonyme User-Ressource, in der die Details des Nutzerprofils für den Aufrufer nicht sichtbar sind:

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

Nutzer in einem Aufruf der Google Chat API angeben

Verwenden Sie die folgenden Werte für den {user}-Wert, um einen Nutzer anzugeben:

  • Für Nutzer in Ihrer Google Workspace-Organisation haben Sie folgende Möglichkeiten:

    • Die name der User-Ressource in der Chat API, z. B. users/123456789.
    • Die {person_id} für den Namen einer Person-Ressource in der People API, wobei resourceName people/{person_id} ist, z. B. users/123456789 in der Chat API, stellt dieselbe Person wie people/123456789 in der People API dar.
    • Die id für eine User-Ressource in der Directory API, z. B. users/123456789 in der Chat API, stellt dieselbe Person wie users/123456789 in der Directory API dar.
    • Bei API-Anfragen, die mit Nutzerauthentifizierung gestellt werden, die E-Mail-Adresse des Nutzers als Alias, z. B. users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Für einen Nutzer in einer externen Google Workspace-Organisation oder einen Nutzer, der ein Google-Konto verwendet, haben Sie folgende Möglichkeiten:

    • Ein E‑Mail-Alias, z. B. users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com oder users/EMAIL_USERNAME@gmail.com.
    • Der kanonische name der User-Ressource (z. B. users/12345678901234567890), der aus einem vorherigen API-Aufruf oder Interaktionsereignis abgerufen wurde.

Nutzer anhand einer API-Antwort oder eines Interaktionsereignisses identifizieren

Es gibt mehrere Möglichkeiten, Nutzer zu identifizieren, die von API-Aufrufen oder eingehenden Ereignissen zurückgegeben werden:

Da die Google Chat API Profile für interne und externe Nutzer erstellt, wenn die Nutzerauthentifizierung verwendet wird, müssen Entwickler die Directory API nicht aufrufen, um Namen oder E-Mail-Adressen für Mitglieder und Absender von Nachrichten aufzulösen.