Nesta página, descrevemos os eventos do Google Chat em que um app do Google Chat pode assinar usando a API Google Workspace Events. Depois de decidir de quais tipos de eventos você precisa, crie uma assinatura para começar a receber eventos do Google Chat.
Além de se inscrever em eventos, também é possível consultar eventos chamando a API Chat. Chamar a API Chat permite recuperar eventos periodicamente ou acompanhar aqueles que você pode ter perdido em uma assinatura devido a uma interrupção. Para saber mais sobre as formas de receber e responder a eventos do Chat, consulte Trabalhar com eventos do Google Chat na documentação do Chat.
Recursos de destino do Chat compatíveis
A API Google Workspace Events é compatível com assinaturas destes produtos:
- Espaços, representados como recursos
space
- Usuários, representados como recursos
user
da API Cloud Identity
Eventos do Chat compatíveis
Com as assinaturas do Google Workspace, é possível receber eventos sobre os seguintes tipos de alterações no Chat:
- Mensagens novas, atualizadas ou excluídas no espaço.
- reações novas ou removidas a uma mensagem
- Participantes novos, atualizados ou removidos no espaço.
- Mudanças no espaço em que você se inscreveu, como uma descrição ou um nome atualizado.
Tipos de evento para a criação de assinaturas
Ao criar uma assinatura, você usa o campo
eventTypes[]
para especificar quais tipos de eventos quer receber. Os tipos de evento são formatados de acordo com a especificação do CloudEvents, como google.workspace.APPLICATION.RESOURCE.VERSION.ACTION
.
Por exemplo, para receber eventos sobre usuários que participam de um espaço do Chat,
especifique o espaço como o recurso de destino e o tipo de evento como
google.workspace.chat.membership.v1.created
. Para receber eventos sobre um determinado
usuário que entrou em qualquer espaço, especifique o usuário como o recurso de destino e o
tipo de evento como google.workspace.chat.membership.v1.created
. Para saber mais sobre
como os eventos funcionam, consulte Estrutura dos eventos do
Google Workspace.
A tabela a seguir mostra quais tipos de evento são compatíveis com assinaturas de espaços e assinaturas de usuários. Para saber mais sobre exceções sobre o que aciona um evento, consulte Limitações.
Tipo de evento | Formato | Dados do recurso | ||
---|---|---|---|---|
Inscrições em espaços | ||||
Uma mensagem foi postada. |
|
|
||
Uma mensagem foi atualizada. |
|
|
||
Uma mensagem foi excluída. |
|
|
||
Uma reação será criada. |
|
|
||
Uma reação foi excluída. |
|
|
||
Um participante é adicionado ao espaço. |
|
|
||
Um participante foi atualizado no espaço. |
|
|
||
Um participante é removido do espaço. |
|
|
||
O espaço foi atualizado. |
|
|
||
O espaço foi excluído. |
|
|
||
Assinaturas para usuários | ||||
O usuário se torna participante de um espaço.
Nem todos os novos participantes acionam eventos. Para detalhes, consulte Limitações |
|
|
||
A associação do usuário a um espaço é atualizada. |
|
|
||
O usuário é removido como participante direto de um espaço. |
|
|
Tipos de eventos em lote (somente saída)
Além de receber os tipos de eventos em que você se inscreveu, o app do Chat também pode receber eventos em lote. Um evento em lote representa muitos eventos do mesmo tipo que ocorrem em um curto período. O payload de um evento em lote contém uma lista de todos os recursos alterados.
Por exemplo, se um usuário adicionar 20 usuários a um espaço ao mesmo tempo, o
app do Chat poderá receber um evento em lote
(google.workspace.chat.membership.v1.batchCreated
). O payload do evento contém
uma lista de todos os novos recursos Membership
criados quando o usuário
adicionou os membros ao espaço.
Como você recebe um evento em lote para qualquer tipo de evento em que se inscreveu, não precisa especificar eventos em lote ao criar uma assinatura. Por
exemplo, se você se inscrever para receber novas reações
(google.workspace.chat.reaction.v1.created
), o
app do Chat será configurado automaticamente para receber eventos
de reação em lote (google.workspace.chat.reaction.v1.batchCreated
).
A tabela a seguir exibe os possíveis eventos em lote para uma assinatura:
Tipo de evento em lote | Formato |
---|---|
Várias mensagens foram postadas. |
|
Várias mensagens foram atualizadas. |
|
Várias mensagens foram excluídas. |
|
Várias reações são criadas. |
|
Várias reações são excluídas. |
|
Vários participantes são adicionados ao espaço inscrito ou o usuário inscrito foi adicionado a vários espaços. |
|
Várias associações são atualizadas no espaço inscrito ou para o usuário inscrito. |
|
Vários participantes são removidos do espaço em que você se inscreveu ou o usuário inscrito foi removido de diversos espaços. |
|
O espaço tem várias atualizações. |
|
Dados de eventos
Esta seção descreve dados de eventos e exemplos de payloads para eventos no Chat.
Quando sua assinatura do Google Workspace recebe um evento do
Chat, o campo
data
contém o payload do evento. Esse payload tem informações sobre o
recurso do Google Workspace que foi alterado. Por exemplo, se você se inscreveu em eventos de associação em um espaço, o payload desses eventos conterá informações sobre o recurso spaces.membership
que mudou.
Dados de recursos no payload do evento
Ao criar uma assinatura, você pode especificar se quer que o payload inclua detalhes sobre o recurso ou apenas o nome dele. Por exemplo, se você quiser receber eventos sobre membros em um espaço do Chat, especifique quais campos de um recurso de associação quer receber no payload do evento.
A tabela a seguir fornece exemplos de payloads JSON para uma assinatura do
espaço do Chat spaces/AAAABBBBBB
. Para cada evento que a
assinatura recebe, o payload aparece no campo data
do evento:
Exemplo | Tipo de evento | Payload do JSON |
---|---|---|
Um usuário posta uma mensagem no espaço dizendo "Hello world". |
|
Inclui dados de recursos
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD", "sender": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "2023-09-07T21:37:36.260127Z", "text": "Hello world", "thread": { "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE" }, "space": { "name": "spaces/AAAABBBBBB" }, "argumentText": "Hello world" } } Exclui dados de recursos
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD" } } |
Um usuário se torna administrador do espaço. |
|
Inclui dados de recursos
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MANAGER" } } Exclui dados de recursos
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } } |
Um usuário atualiza a descrição do espaço para "Equipe de vendas da Cymbal Labs". | google.workspace.chat.space.v1.updated |
Inclui dados de recursos
{ "space": { "name": "spaces/AAAABBBBBB", "displayName": "Cymbal Sales", "spaceThreadingState": "THREADED_MESSAGES", "spaceType": "SPACE", "spaceDetails": { "description": "Sales team for Cymbal Labs." }, "spaceHistoryState": "HISTORY_ON" } } Exclui dados de recursos
{ "space": { "name": "spaces/AAAABBBBBB" } } |
Dois usuários do Chat foram adicionados ao espaço ao mesmo tempo. | google.workspace.chat.membership.v1.batchCreated |
Inclui dados de recursos
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/987654321234567890", "state": "JOINED", "member": { "name": "users/987654321234567890", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } } ] } Exclui dados de recursos
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/98765432123456789019" } } ] } |
Um usuário reage a uma mensagem com o emoji 😊. | google.workspace.chat.reaction.v1.created |
Inclui dados de recursos
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } } Omite dados de recursos
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" } } |
Os usuários reagem a uma mensagem com os emojis 😊 e 🎃 | google.workspace.chat.reaction.v1.batchCreated |
Inclui dados de recursos
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } }, { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", "user": { "name": "users/98765431234564321", "type": "HUMAN" }, "emoji": { "unicode": "😸" } } } ] } Omite dados de recursos
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" }, "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", } } ] } |
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. - As mudanças no histórico do espaço não acionam eventos atualizados no espaço (tipo de evento:
google.workspace.chat.spaces.v1.updated
). - 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
- Estrutura dos eventos do Google Workspace
- Escolher escopos do OAuth
- Crie uma assinatura para receber eventos do Chat.