Trabalhar com eventos do Google Chat

Nesta página, explicamos 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 de chat pode usar eventos para entender o que aconteceu e agir ou responder de maneira significativa para os usuários.

Confira alguns exemplos de como usar os 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 do Chat de forma eficaz.
• Acompanhe e analise a atividade no Chat. Por exemplo, para enviar um relatório mensal sobre novos membros ou as mensagens que recebem mais reações ou respostas.
• Interaja em várias plataformas de mensagens. Por exemplo, os usuários podem enviar e receber mensagens de usuários de uma plataforma diferente sem sair do Chat.

Como os eventos funcionam

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

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 eventos por tipo. Os tipos de evento ajudam a filtrar e receber apenas o tipo de informação necessária e permitem que você processe 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 do 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 foi 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

Observação :seu app do Chat também pode receber eventos de interação. Esses eventos ajudam você a responder a interações diretas do usuário, como quando um usuário adiciona o app do Chat a um espaço ou @menciona o app do Chat. Para configurar e receber eventos de interação, consulte Receber e responder a interações com seu app do Google Chat.

Receber eventos do Google Chat

Para receber eventos, seu app de chat pode realizar uma das seguintes ações:

• Inscreva-se em eventos usando a API Google Workspace Events para receber os 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 se inscrever em eventos:

	Inscrever-se em eventos	Consultar eventos
Casos de uso	Processe ou responda a eventos em tempo real. Monitore a atividade dos participantes e descubra novos espaços para monitorar.	Processe ou responda a eventos periodicamente ou com um gatilho. Buscar eventos perdidos de uma assinatura (devido a uma falha temporária ou assinatura inativa).
API	API Google Workspace Events	Chat API
Origem dos eventos	Espaços e usuários	Somente espaços
Eventos aceitos	Mensagens Clubes dos canais Reações Espaço Para conferir uma lista dos tipos de evento compatíveis, consulte Tipos de evento para criar assinaturas na documentação da API Google Workspace Events.	Mensagens Clubes dos canais Reações Espaço Para conferir uma lista dos 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 de eventos.	Payload JSON que contém dados de recursos. Alguns tipos de eventos incluem apenas determinados campos de recursos. Para ver exemplos de payloads, consulte a documentação de referência.

Exemplo: consultar ou se inscrever em eventos sobre os participantes de um espaço

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

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

Inscrever-se em eventos da assinatura

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

Figura 2. Um app do Chat recebe eventos de assinatura por meio de uma assinatura usando a API Google Workspace Events.

Na Figura 2, o app do Chat tem uma assinatura ativa no espaço, de modo que ele recebe um evento sempre que uma associação no espaço muda. O app do Chat poderá processar ou responder em tempo real a qualquer uma das atividades, como postar uma mensagem privada de boas-vindas 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 de assinatura recentes

Em vez de receber os eventos dos participantes à medida que eles ocorrem, um app do Chat pode chamar a API Chat para listar eventos recentes do espaço relacionados à atividade dos participantes.

Figura 3. Um app do Chat recebe eventos de assinatura recentes consultando eventos do espaço usando a API Chat.

Na Figura 3, um app do 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. Depois disso, o app do Chat poderá processar ou responder com base na atividade recente, como postar uma mensagem semanal com um resumo da atividade dos participantes do espaço nos últimos sete dias.

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

Limitações

• No caso de assinaturas de usuários, os eventos sobre novos participantes em mensagens diretas ou chats em grupo sem nome (google.workspace.chat.membership.v1.created) são acionados somente depois que a primeira mensagem é postada.
• As mudanças no histórico do espaço não acionam eventos atualizados do espaço (tipo de evento: google.workspace.chat.spaces.v1.updated).
• Para receber esses eventos, o usuário precisa ser participante direto do espaço. Se um usuário for adicionado, atualizado ou removido indiretamente em um espaço por um Grupo do Google, a assinatura não vai receber esses eventos. Para entender como funcionam as associações 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
• Conferir detalhes sobre um evento do espaço do Google Chat
• Listar eventos de um espaço do Google Chat
• Para ver um exemplo de como usar eventos, consulte o tutorial Responder perguntas com base em conversas do Chat com um app Gemini AI Chat.