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. O app do Chat pode usar eventos para entender o que aconteceu e realizar ações ou responder de uma maneira significativa para os usuários.

Confira alguns exemplos de como usar eventos:

• Monitorar e responder a novas mensagens em um espaço, como a verificação de 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.
• Comunicar-se em várias plataformas de mensagens. Por exemplo, os usuários podem enviar e receber mensagens de outras pessoas em uma plataforma de mensagens diferente 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 enviar informações ao app Chat sobre o tipo de atividade que ocorreu e o recurso da API Chat que foi afetado.

O Chat categoriza os eventos por tipo. Os tipos de evento ajudam a filtrar e receber apenas o tipo de informação necessário e a lidar 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 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 foi excluído.	Assinatura excluída

Receber eventos do Google Chat

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

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

A tabela a seguir explica a diferença e os motivos para consultar ou assinar 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 acionador. 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 conferir uma lista de tipos de evento compatíveis, consulte Tipos de evento 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 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 do evento.	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 assinaturas em um espaço

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

• Um usuário entra no espaço, que cria um recurso Membership e aciona um evento de novo membro.
• Um usuário se torna um administrador de 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 associação

Para receber eventos em tempo real, o app do Chat chama o método subscriptions.create() da API Google Workspace Events para se inscrever no espaço para 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.

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 do 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 associação

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

Na Figura 3, um app de chat chama o método spaces.spaceEvents.list() da API Chat depois que todas as atividades de associação ocorreram 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 na atividade recente, como postar uma mensagem semanal com um resumo da atividade de participação do 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, eventos sobre novos membros em mensagens diretas ou chats em grupo sem nome (google.workspace.chat.membership.v1.created), só acione depois que a primeira mensagem for postada.
• Para receber eventos de participação, o usuário precisa ser um participante 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 recebe esses eventos de participação. Para entender como funciona a associação a grupos do Google, consulte Adicionar um grupo do Google a um espaço.

Temas relacionados

• Visão geral da API Google Workspace Events
• Criar uma assinatura
• Receber detalhes sobre um evento de espaço do Google Chat
• Listar eventos de um espaço do Google Chat
• Para conferir exemplos de como usar eventos, consulte o tutorial Responder a perguntas com base em conversas do Chat usando um app do Chat com IA do Gemini ou o recurso de ajuda de inclusão do app do Chat para gerenciamento de problemas no codelab Criar apps para o Google Chat com o Gemini.