Identificar e especificar usuários do Google Chat

Esta página explica como os apps e desenvolvedores do Google Chat podem identificar e especificar usuários do Chat.

Para fazer qualquer uma das ações a seguir, um app do Chat ou um desenvolvedor precisa especificar um usuário:

Como o Chat identifica usuários

A API Google Chat gera um recurso User para cada pessoa e app que usa o Chat. Um recurso User contém os seguintes campos:

  • name: o nome do recurso, formatado como users/{user}, em que {user} representa um identificador exclusivo e estável. Você pode usar users/app como um alias para o app de chat que está fazendo a chamada.
  • displayName: somente saída. O nome de exibição do usuário.
  • avatarUrl: somente saída. O URL da imagem do avatar do usuário.
  • email: somente saída. O endereço de e-mail do usuário.
  • domainId: identificador exclusivo do domínio do Google Workspace do usuário.
  • type: o tipo de usuário. Isso indica se o usuário é um app de chat (BOT) ou uma pessoa (HUMAN).
  • isAnonymous: somente saída. Quando true, indica que o usuário foi excluído ou que o perfil dele não está visível.

Detalhes do perfil do usuário e regras de visibilidade

Ao chamar as APIs Messages e Memberships usando a autenticação do usuário, a API Google Chat preenche o recurso User com detalhes do perfil. A API preenche displayName, email e avatarUrl para usuários internos (na sua organização do Google Workspace) e externos (em organizações externas ou Contas do Google pessoais).

Exemplos de locais em que a API preenche perfis de usuários:

Regras de privacidade e visibilidade

Para proteger a privacidade do usuário, a API Google Chat aplica regras de visibilidade específicas ao determinar se os detalhes do perfil de um usuário devem ser preenchidos:

  • Perfil preenchido: a API preenche os detalhes do perfil (displayName, email e avatarUrl estão presentes, e isAnonymous é false) se o usuário aceitou um convite para um espaço (é membro dele) ou tem uma afinidade anterior (como um histórico de interações por mensagem direta) com o usuário que fez a chamada.
  • Perfil anônimo: se um usuário for mencionado em um espaço sem ser membro e sem afinidade prévia com o usuário que fez a chamada, o perfil dele vai permanecer anônimo. Para um usuário anônimo, isAnonymous é true, e detalhes como displayName, email e avatarUrl são omitidos. No entanto, para solicitações de API feitas com autenticação de app, o campo displayName sempre é preenchido.

O exemplo JSON a seguir mostra um recurso User com detalhes de perfil preenchidos retornados em uma resposta da API ou um evento de interação:

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

O exemplo de JSON a seguir mostra um recurso User anônimo em que os detalhes do perfil do usuário não estão visíveis para o autor da chamada:

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

Especificar um usuário em uma chamada para a API Google Chat

Para especificar um usuário, use os seguintes valores para o valor {user}:

  • Para usuários na sua organização do Google Workspace, use uma das seguintes abordagens:

    • O name do recurso User na API Chat, como users/123456789.
    • O {person_id} para o nome de um Person recurso na API People, em que o resourceName é people/{person_id}. Por exemplo, users/123456789 na API Chat representa a mesma pessoa que people/123456789 na API People.
    • O id de um recurso User na API Directory. Por exemplo, users/123456789 na API Chat representa a mesma pessoa que users/123456789 na API Directory.
    • Para solicitações de API feitas com autenticação de usuário, o endereço de e-mail do usuário como um alias, por exemplo, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Para um usuário em uma organização externa do Google Workspace ou que usa uma Conta do Google, use uma das seguintes opções:

    • Um alias de e-mail, por exemplo, users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com ou users/EMAIL_USERNAME@gmail.com.
    • O name canônico do recurso User (como users/12345678901234567890) obtido de uma chamada de API ou evento de interação anterior.

Identificar um usuário em uma resposta da API ou um evento de interação

É possível identificar usuários retornados de chamadas de API ou eventos recebidos de várias maneiras:

Como a API Google Chat preenche perfis de usuários internos e externos ao usar a autenticação de usuários, os desenvolvedores não precisam chamar a API Directory para resolver nomes ou e-mails de membros e remetentes de mensagens.