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 do Chat pode usar eventos para entender o que aconteceu e entrar em ação ou responder de maneira significativa para os usuários.

Veja alguns exemplos de como usar eventos:

• Monitorar e responder a novas mensagens em um espaço, como verificar palavras ou frases-chave.
• 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.
• 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.
• Comunique-se em várias 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 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 do 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 que você precisa, além de permitir que você lide com atividades semelhantes 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 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 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 fazer o seguinte:

• Inscreva-se em eventos usando a API Google Workspace Events para receber eventos conforme 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. Monitorar a atividade de participação dos usuários e descobrir novos espaços para monitorar.	Processar ou responder a eventos periodicamente ou por um gatilho. Busque 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, usuários e organizações do Google Workspace (science prévia para desenvolvedores)	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 ver 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 do evento	String codificada em Base64 com ou sem dados de recursos. Para ver exemplos de payloads, consulte Dados de eventos.	Payload JSON que contém dados de recursos. Alguns tipos de evento incluem apenas determinados campos de recurso. Para ver exemplos de payloads, consulte a documentação de referência.

Exemplo: consultar ou se inscrever em eventos sobre participações 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. No espaço, 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 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 do usuário e aciona um evento de exclusão de participante.

Inscrever-se em eventos de assinatura

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 participação. Depois de criar a assinatura, o app do Chat pode começar a receber eventos de assinatura.

Na figura 2, o app do Chat tem uma assinatura ativa do espaço, então 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 participante 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 associação recentes

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.

Na figura 3, um app do Chat chama o método spaces.spaceEvents.list() da API Chat depois que todas as atividades de participação ocorrem e filtra a consulta para eventos de participação novos, atualizados e excluídos. A API Chat retorna uma lista de recursos spaceEvent que representam cada uma das mudanças de participaçã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 e comportamentos de entrega

Limitações gerais

• Para receber eventos de participação, o usuário ou o app do Chat precisa ser um participante direto do espaço. Se eles forem adicionados, atualizados ou removidos indiretamente de um espaço por um Grupo do Google, a assinatura não receberá esses eventos de associação. Para entender como funcionam as associações aos Grupos do Google, consulte Adicionar um Grupo do Google a um espaço.

Assinaturas do usuário

• Para assinaturas de usuários, os eventos sobre novos membros em mensagens diretas ou grupos de chat sem nome (google.workspace.chat.membership.v1.created) só são acionados depois que a primeira mensagem é postada.

Assinaturas de clientes

Para assinaturas de clientes, as seguintes limitações se aplicam:

• A organização do Google Workspace precisa ter pelo menos uma licença de SKU Enterprise.
• Um app do Chat só pode criar uma assinatura de cliente para uma determinada organização do Google Workspace. Uma organização do Google Workspace pode ter até cinco assinaturas de cliente no total (criadas por diferentes apps do Chat).

Para assinaturas de clientes, a entrega de eventos segue estas regras gerais:

• Eventos de espaço: entregues apenas se o evento ocorrer em um espaço gerenciado pela sua organização do Google Workspace.
• Eventos do usuário: entregues apenas se o evento ocorrer para um usuário que pertence à sua organização do Google Workspace.

A única exceção a essas regras são os eventos de assinatura. Sua assinatura pode receber eventos de associação de espaços gerenciados pela sua organização e por organizações externas, mas a forma como eles são entregues depende de qual organização gerencia o espaço:

Espaços gerenciados pela sua organização do Google Workspace

Se ocorrer uma mudança na participação em um espaço gerenciado pela organização do Google Workspace, ela será entregue como um evento de espaço.

O nome do recurso de um evento de espaço usa o seguinte formato:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Espaços gerenciados por organizações externas

Se a participação de um usuário gerenciado pela sua organização do Google Workspace mudar em um espaço gerenciado por uma organização externa (por exemplo, um espaço externo nomeado ou uma mensagem direta criada por um usuário externo), sua assinatura vai receber esse evento como um evento de usuário.

O nome do recurso de um evento de usuário usa o seguinte formato:

users/{userId}/userEvents/{userEventId}

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