Inscrever-se em eventos do Google Chat

Nesta página, descrevemos os eventos do Google Chat que um app do Google Chat pode assinar usando a API Google Workspace Events. Depois de decidir 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, você também pode consultar eventos chamando a API Chat. Ao chamar a API Chat, você pode recuperar eventos periodicamente ou acompanhar eventos que perdeu de uma assinatura devido a uma interrupção. Para saber como receber e responder a eventos do Chat, consulte Trabalhar com eventos do Google Chat na documentação do Chat.

Eventos do Chat aceitos

Com as assinaturas do Google Workspace, você recebe eventos sobre os seguintes tipos de mudanças no Chat:

• Mensagens novas, atualizadas ou excluídas no espaço.
• Reações novas ou removidas de uma mensagem.
• Participantes novos, atualizados ou removidos do espaço.
• Mudanças no espaço a que você se inscreveu, como um nome ou uma descrição atualizada.

Recursos que podem ser monitorados para eventos

Para receber eventos, especifique um recurso do Chat para monitorar, que é chamado de recurso de destino da assinatura.

A API Google Workspace Events é compatível com os seguintes recursos de destino para o Chat:

Tipos de eventos para criar assinaturas

Ao criar uma assinatura, use o campo eventTypes[] para especificar quais tipos de eventos você quer receber. Os tipos de eventos 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 entram em 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 entra 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 eventos são compatíveis com assinaturas de espaços e de usuários. Para saber mais sobre exceções de o que aciona um evento, consulte Limitações.

Tipos de eventos em lote (somente saída)

Além de receber os tipos de eventos a que você se inscreveu, seu app de 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 pessoas a um espaço ao mesmo tempo, seu app de chat poderá receber um evento em lote (google.workspace.chat.membership.v1.batchCreated). A carga útil do evento contém uma lista de todos os novos recursos Membership criados quando o usuário adicionou os membros ao espaço.

Você recebe um evento em lote para qualquer tipo de evento a que se inscrever. Portanto, não é necessário 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), seu app Chat será configurado automaticamente para receber eventos de reação em lote (google.workspace.chat.reaction.v1.batchCreated).

A tabela a seguir mostra os possíveis eventos em lote para uma assinatura:

Dados do evento

Esta seção descreve os 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 a carga útil do evento. Esse payload tem informações sobre o recurso do Google Workspace que mudou. Por exemplo, se você se inscreveu para receber eventos de assinatura em um espaço, o payload desses eventos contém 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 participantes em um espaço do Chat, especifique quais campos de um recurso de participaçã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:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}
      

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
      

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      

• 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ó são acionados depois que a primeira mensagem é postada.
• Para receber eventos de participação, o usuário ou app do Chat precisa ser um participante direto do espaço. Se eles foram adicionados, atualizados ou removidos indiretamente de um espaço por um Grupo do Google, a assinatura não vai receber esses eventos de participaçã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