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 para entender o que aconteceu e agir ou reagir de maneira para seus usuários.

Confira alguns exemplos de como usar eventos:

  • Monitorar e responder a novas mensagens em um espaço, como a verificação de uma chave palavras ou frases.
  • Enviar uma mensagem de boas-vindas aos usuários para explicar como eles entram no espaço ou compartilhar dicas sobre como usar de forma eficaz as App Chat.
  • Monitore e analise a atividade do Chat. Por exemplo, para enviar uma relatório mensal sobre novos membros ou as mensagens que recebem mais reações ou respostas.
  • Comunique-se entre plataformas de mensagens. Por exemplo, os usuários podem enviar e receber mensagens de usuários em uma plataforma de mensagens diferente, sem sair do Chat.

Como os eventos funcionam

Sempre que acontece algo no Google Chat, um recurso dessa API é criados, atualizados ou excluídos. O Chat usa eventos para entregar mensagens informações ao app do Chat sobre o tipo de a atividade que ocorreu e o recurso da API Chat que foi afetado.

Exemplo de como uma mensagem postada em um espaço do Google Chat aciona um evento.
Figura 1. Um usuário publica uma mensagem em um Espaço do Chat, que cria um recurso Message. O Chat cria um evento com dados sobre o novo mensagem.

O Chat categoriza os eventos por tipo. Os tipos de evento ajudam a filtrar e receber apenas o tipo de informação de que precisa e permitir que você lide com informações semelhantes as atividades da mesma maneira.

A tabela a seguir mostra como uma atividade no Chat afeta um recurso relacionado da API Chat e o tipo de evento O 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 do 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, o app do Chat pode realizar uma das seguintes ações: seguintes:

  • Fazer inscrição em eventos usando a API Google Workspace Events para receber eventos à medida que elas ocorrem.
  • Consulte eventos recentes chamando a API Chat.

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

Inscrever-se em eventos Consultar eventos
Casos de uso
  • Processe ou responda a eventos em tempo real.
  • Monitore usuários atividades de assinatura e descobrir novos espaços para monitor
  • Processar ou responder a eventos periodicamente ou com um gatilho.
  • Buscar 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 uma lista de tipos de evento compatíveis, consulte Tipos de evento para a criação de assinaturas no Documentação da API Google Workspace Events.
  • Mensagens
  • Assinaturas
  • Reações
  • Espaço
.
Para obter uma lista de tipos de evento compatíveis, consulte recurso spaceEvents na API Chat documentação de referência.
Formato de eventos Uma mensagem do Google Cloud Pub/Sub, formatada de acordo com o especificação do CloudEvent. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace. Um recurso da API Chat ( spaces.spaceEvent)
Dados de eventos 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 evento 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 a participação em um espaço

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

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

Inscrever-se em eventos para membros

Para receber eventos em tempo real, o O app do Chat chama a API Google Workspace Events subscriptions.create() para se inscrever no espaço para todos os tipos de eventos de associação. Depois criar a assinatura, o app do Chat poderá começar a receber eventos de associação.

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

Na Figura 2, o app Chat tem uma assinatura ativa para o espaço. Assim, o app recebe um evento sempre que alguém participa dele. mudanças. O app do Chat pode processar ou responder em tempo real para qualquer atividade, como postar uma mensagem privada de boas-vindas para a pessoa 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 associação

Em vez de receber os eventos de associação à medida que eles ocorrem, uma O app do Chat pode chamar a API Chat para listar eventos recentes no espaço relacionados às atividades dos participantes.

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

Na Figura 3, um app do Chat chama a API Chat. spaces.spaceEvents.list() depois que todas as atividades de associação ocorrerem, 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. O app do Chat pode processar ou responder com base no atividade recente, como postar uma mensagem semanal com um resumo dos o número de membros do espaço nos últimos 7 dias.

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

Limitações
  • Nas inscrições de usuários, eventos sobre novos participantes em mensagens diretas ou chats em grupo sem nome (google.workspace.chat.membership.v1.created) é acionada somente após a primeira mensagem ser postada.
  • Para receber eventos de associação, o usuário precisa ser participante direto do espaço. Se um usuário foi adicionado, for atualizada ou removida indiretamente em um espaço usando um grupo do Google, a assinatura não receber esses eventos de associação. Para entender como funcionam as associações a grupos do Google, consulte Adicionar um grupo do Google a um espaço.