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 os eventos para entender o que aconteceu e realizar ações ou responder de maneira significativa para os usuários.
Confira alguns exemplos de como usar eventos:
- Monitore e responda 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 conforme eles entram no espaço, explicando as diretrizes ou compartilhando dicas sobre como usar o app Chat.
- Monitore e analise 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 entre plataformas de mensagens. Por exemplo, os usuários podem enviar e receber mensagens de usuários em 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 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 necessário e permitem processar atividades semelhantes da mesma maneira.
A tabela a seguir mostra como uma atividade no Chat afeta um recurso da API Chat relacionado 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:
- Faça sua inscrição em eventos usando a API Google Workspace Events para receber os eventos à medida que eles ocorrerem.
- Consulte 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 |
|
|
API | API Google Workspace Events | Chat API |
Origem dos eventos | Espaços e usuários | Somente espaços |
Eventos aceitos |
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. |
Para conferir uma lista de tipos de evento 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 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 do Chat quer receber informações sobre alterações 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 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 excluído de membro.
Inscrever-se em eventos para membros
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 em todos os tipos de eventos de associação. Depois
de criar a assinatura, o app do Chat pode começar a
receber eventos de associação.
Na Figura 2, o app do Chat tem uma assinatura ativa no espaço, de modo que o app recebe um evento sempre que uma associação ao espaço muda. O app do Chat poderá processar ou responder em tempo real a qualquer uma das atividades, como postar uma mensagem particular de boas-vindas 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 recentes de associação
Em vez de receber os eventos de associação à medida que eles ocorrem, um app do Chat pode chamar a API Chat para listar eventos recentes do espaço relacionados à atividade dos participantes.
Na Figura 3, um app do Chat chama o método
spaces.spaceEvents.list()
da API Chat após a ocorrência de todas as atividades de associação e filtra a consulta
para eventos 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 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
-
No caso de assinaturas de usuários, eventos sobre novos participantes em mensagens diretas ou chats em grupo sem nome (
google.workspace.chat.membership.v1.created
), são acionados depois que a primeira mensagem é postada. - Para receber eventos de associação, o usuário precisa ser participante direto do espaço. Se um usuário tiver sido adicionado, atualizado ou removido 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.
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 conferir exemplos de como usar eventos, consulte o tutorial Responder perguntas com base em conversas do Chat com um app Gemini AI Chat ou o recurso de ajuda de inclusão do app de gerenciamento de problemas Chat no codelab Criar apps para o Google Chat com o Gemini.