Trabalhar com eventos do Google Chat

Esta página explica como os apps do Google Chat podem receber e responder a eventos no Google Chat.

Um evento do Google Chat representa uma atividade ou mudança no Chat, como uma nova mensagem em um espaço. Seu app do Chat pode usar eventos para entender o que aconteceu e tomar medidas ou responder de uma forma significativa para os usuários.

Confira alguns exemplos de como usar eventos:

  • Monitore e responda a novas mensagens em um espaço, como verificar palavras-chave ou frases.
  • Envie uma mensagem de boas-vindas aos usuários quando eles entrarem no espaço para explicar as diretrizes ou compartilhar dicas sobre como usar o app Chat de maneira eficaz.
  • Acompanhar e analisar a atividade do Chat. Por exemplo, para enviar um relatório mensal sobre novos membros ou as mensagens que recebem mais reações ou respostas.
  • Comunicação em várias plataformas de mensagens. Por exemplo, os usuários podem enviar e receber mensagens de pessoas em outra plataforma de mensagens sem sair do Chat.

Como os eventos funcionam

Sempre que algo acontece no Google Chat, um recurso da API Google Chat é criado, atualizado ou excluído. O Chat usa eventos para fornecer informações ao seu app sobre o tipo de atividade que ocorreu e o recurso da API Chat afetado.

Exemplo de como uma mensagem postada em um espaço do Google Chat aciona um evento.
Figura 1. Um usuário posta uma mensagem em um espaço do Chat, o que cria um recurso Message. Em seguida, o chat cria um evento que contém dados sobre a nova mensagem.

O Chat categoriza os eventos por tipo. Os tipos de eventos ajudam a filtrar e receber apenas as informações necessárias, além de permitir que você lide com atividades semelhantes da mesma forma.

A tabela a seguir mostra como uma atividade no Chat afeta um recurso relacionado da API Chat e o tipo de evento que seu app do Chat recebe:

Atividade Recurso da API Chat Tipo de evento
Um usuário posta uma mensagem em um espaço do Chat Um recurso Message é criado. Nova mensagem
Um usuário se torna administrador de um espaço. Um recurso Membership é atualizado. Assinatura atualizada
Um usuário reage a uma mensagem. Um recurso Reaction é criado. Nova reação
Um usuário sai de um espaço. Um recurso Membership é excluído. Assinatura excluída

Receber eventos do Google Chat

Para receber eventos, seu app do Chat pode fazer o seguinte:

  • Inscreva-se em eventos usando a API Google Workspace Events para receber eventos à medida que eles acontecem.
  • Consulte eventos recentes chamando a API Chat.

A tabela a seguir explica a diferença e os motivos para consultar ou inscrever-se em eventos:

Inscrever-se em eventos Consultar eventos
Casos de uso
  • Processar ou responder a eventos em tempo real.
  • Monitore a atividade de associação dos usuários e descubra novos espaços para monitorar.
  • Processar ou responder a eventos periodicamente ou por um gatilho.
  • Extrair eventos perdidos de uma assinatura (devido a uma interrupção ou assinatura inativa).
API API Google Workspace Events Chat API
Origem dos eventos Espaços e usuários Somente espaços
Eventos aceitos
  • Mensagens
  • Assinaturas
  • Reações
  • Espaço

Para conferir uma lista de tipos de eventos compatíveis, consulte Tipos de eventos para criar assinaturas na documentação da API Google Workspace Events.
  • Mensagens
  • Assinaturas
  • Reações
  • Espaço

Para conferir uma lista de tipos de eventos compatíveis, consulte o recurso spaceEvents na documentação de referência da API Chat.
Formato de eventos Uma mensagem do Google Cloud Pub/Sub, formatada de acordo com a especificação CloudEvent. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace. Um recurso da API Chat ( spaces.spaceEvent)
Dados do evento String codificada em base64 com ou sem dados de recursos. Para exemplos de payloads, consulte Dados de eventos. Payload JSON que contém dados de recursos. Alguns tipos de eventos incluem apenas determinados campos de recursos. Para exemplos de payloads, consulte a documentação de referência.

Exemplo: consultar ou se inscrever em eventos sobre assinaturas em um espaço

Neste exemplo, um app do Chat quer receber informações sobre mudanças nos participantes de um espaço do Chat. Na sala, ocorre a seguinte atividade de participação:

  • Um usuário entra no espaço, o que cria um recurso Membership e aciona um evento de novo membro.
  • Um usuário se torna administrador de um espaço, o que atualiza o recurso Membership para o usuário e aciona um evento de membro atualizado.
  • Um usuário sai do espaço, o que exclui o recurso Membership para o usuário e aciona um evento de membro excluído.

Inscrever-se em eventos de assinatura

Para receber eventos em tempo real, o app Chat chama o método subscriptions.create() da API Google Workspace Events para assinar o espaço e receber todos os tipos de eventos de associação. Depois de criar a assinatura, o app Chat pode começar a receber eventos de associação.

App do Chat que se inscreve em eventos usando a API Google Workspace Events.
Figura 2. Um app do Chat recebe eventos de associação por uma assinatura usando a API Google Workspace Events.

Na figura 2, o app Chat tem uma assinatura ativa do espaço. Por isso, ele recebe um evento sempre que uma participação no espaço muda. O app Chat pode processar ou responder em tempo real a qualquer uma das atividades, como postar uma mensagem de boas-vindas particular para o membro que entrou no espaço.

Para saber como criar assinaturas usando a API Google Workspace Events, consulte a documentação da API Google Workspace Events.

Consultar eventos recentes de assinatura

Em vez de receber os eventos de participação conforme eles ocorrem, um app do Chat pode chamar a API Chat para listar eventos recentes do espaço relacionados à atividade de participação.

App de chat que consulta eventos usando a API Chat.
Figura 3. Um app do Chat recebe eventos recentes de associação ao consultar eventos de espaço usando a API Chat.

Na figura 3, um app Chat chama o método spaces.spaceEvents.list() da API Chat depois que todas as atividades de associação são concluídas e filtra a consulta para eventos de associação novos, atualizados e excluídos. A API Chat retorna uma lista de recursos spaceEvent que representam cada uma das mudanças de associação. Em seguida, o app Chat pode processar ou responder com base na atividade recente, como postar uma mensagem semanal com um resumo da atividade de participação no espaço nos últimos sete dias.

Para consultar eventos usando a API Chat, consulte Listar eventos de um espaço do Google Chat.

Limitações
  • Para assinaturas de usuários, os eventos sobre novos membros em mensagens diretas ou chats em grupo sem nome (google.workspace.chat.membership.v1.created) só são acionados após a postagem da primeira mensagem.
  • Para receber eventos de participação, o usuário precisa ser um membro direto do espaço. Se um usuário foi adicionado, atualizado ou removido indiretamente de um espaço por um Grupo do Google, a assinatura não vai receber esses eventos de participação. Para entender como funcionam as associações a grupos do Google, consulte Adicionar um grupo do Google a um espaço.