Identifica y especifica los usuarios de Google Chat

En esta página, se explica cómo los desarrolladores y las apps de Google Chat pueden identificar y especificar usuarios de Chat.

Para realizar cualquiera de las siguientes acciones, una app de Chat o un desarrollador deben especificar un usuario:

Cómo identifica Chat a los usuarios

La API de Google Chat genera un recurso User para cada persona y app que usa Chat. Un recurso User contiene los siguientes campos:

  • name: Es el nombre del recurso, con el formato users/{user}, en el que {user} representa un identificador único y estable. Puedes usar users/app como alias de la app de Chat que realiza la llamada.
  • displayName: Solo resultado. Es el nombre visible del usuario.
  • avatarUrl: Solo resultado. Es la URL de la imagen del avatar del usuario.
  • email: Solo resultado. La dirección de correo electrónico del usuario.
  • domainId: Es el identificador único del dominio de Google Workspace del usuario.
  • type: Es el tipo de usuario. Indica si el usuario es una app de chat (BOT) o una persona (HUMAN).
  • isAnonymous: Solo resultado. Cuando es true, indica que se borró al usuario o que su perfil no está visible.

Detalles del perfil del usuario y reglas de visibilidad

Cuando se llama a las APIs de Messages y Memberships con la autenticación del usuario, la API de Google Chat completa el recurso User con detalles del perfil. La API completa los campos displayName, email y avatarUrl para los usuarios internos (en tu organización de Google Workspace) y los usuarios externos (en organizaciones externas o Cuentas de Google personales).

Estos son algunos ejemplos de lugares donde la API completa los perfiles de usuario:

  • El sender de un Message.
  • Usuarios dentro del mensaje annotations, como el usuario @mentions.
  • Es el member dentro de un recurso Membership.

Reglas de privacidad y visibilidad

Para proteger la privacidad del usuario, la API de Google Chat aplica reglas de visibilidad específicas cuando determina si debe completar los detalles del perfil de un usuario:

  • Perfil completado: La API completa los detalles del perfil (displayName, email y avatarUrl están presentes, y isAnonymous es false) si el usuario aceptó una invitación a un espacio (es miembro del espacio) o tiene una afinidad previa (como un historial de interacción de mensajes directos) con el usuario que llama.
  • Perfil anónimo: Si se menciona a un usuario en un espacio sin que sea miembro y sin afinidad previa con el usuario que llama, su perfil permanece anónimo. En el caso de un usuario anónimo, isAnonymous es true, y se omiten detalles como displayName, email y avatarUrl. Sin embargo, para las solicitudes a la API realizadas con autenticación de la app, el campo displayName siempre se completa.

En el siguiente ejemplo en formato JSON, se muestra un recurso User con detalles del perfil completados que se devolvió en un evento de interacción o respuesta de la API:

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

En el siguiente ejemplo en formato JSON, se muestra un recurso User anónimo en el que el llamador no puede ver los detalles del perfil del usuario:

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

Cómo especificar un usuario en una llamada a la API de Google Chat

Para especificar un usuario, usa los siguientes valores para el valor {user}:

  • Para los usuarios de tu organización de Google Workspace, usa uno de los siguientes enfoques:

    • Es el name del recurso User en la API de Chat, como users/123456789.
    • El {person_id} para el nombre de un recurso Person en la API de People, en el que resourceName es people/{person_id}, por ejemplo, users/123456789 en la API de Chat representa a la misma persona que people/123456789 en la API de People.
    • El id para un recurso User en la API de Directory (por ejemplo, users/123456789 en la API de Chat representa a la misma persona que users/123456789 en la API de Directory)
    • Para las solicitudes de API realizadas con autenticación de usuario, la dirección de correo electrónico del usuario como alias, por ejemplo, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Para un usuario de una organización externa de Google Workspace o un usuario que usa una Cuenta de Google, usa una de las siguientes opciones:

    • Un alias de correo electrónico, por ejemplo, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com o users/EMAIL_USERNAME@gmail.com.
    • Es el name canónico del recurso User (como users/12345678901234567890) que se obtiene de una llamada a la API o un evento de interacción anteriores.

Identifica a un usuario a partir de una respuesta de API o un evento de interacción

Puedes identificar a los usuarios que se muestran en las llamadas a la API o en los eventos entrantes de varias maneras:

Dado que la API de Google Chat completa los perfiles de los usuarios internos y externos cuando se usa la autenticación de usuarios, los desarrolladores no necesitan llamar a la API de Directory para resolver los nombres o los correos electrónicos de los miembros y los remitentes de mensajes.