Inscrever-se em eventos do Google Chat

Esta página descreve os eventos do Chat que um app do 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 Chat.

Além de assinar eventos, também é possível consultar eventos chamando a API Google Chat. A chamada da API Chat permite recuperar eventos periodicamente ou acompanhar eventos que você pode ter perdido de uma assinatura devido a uma interrupção. Para saber mais sobre as maneiras de receber e responder a eventos do Chat, consulte Trabalhar com eventos do Chat na documentação do Chat.

Eventos do Chat aceitos

As assinaturas do Google Workspace permitem receber eventos sobre os seguintes tipos de mudanças no Chat:

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

Recursos que podem ser monitorados para eventos

Para receber eventos, especifique um recurso do Chat a ser monitorado, chamado de recurso de destino da assinatura.

A API Google Workspace Events oferece suporte aos seguintes recursos de destino do Chat:

Tipos de eventos para criar assinaturas

Ao criar uma assinatura, use o eventTypes[] campo para especificar os tipos de eventos que 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 events.

A tabela a seguir mostra quais tipos de eventos são aceitos para assinaturas de espaços e assinaturas de usuários. Para saber mais sobre exceções sobre o que aciona um evento, consulte Limitações.

Tipos de eventos em lote (somente saída)

Além de receber os tipos de eventos que você assina, 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 que foram criados quando o usuário adicionou os participantes ao espaço.

Você recebe um evento em lote para qualquer tipo de evento que assinar. Portanto, não é necessário especificar eventos em lote ao criar uma assinatura. Por exemplo, se você assinar 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 mostra os possíveis eventos em lote para uma assinatura:

Dados de eventos

Esta seção descreve os dados de eventos e exemplos de payloads para eventos no Chat.

Quando a assinatura do Google Workspace recebe um evento de Chat, o data campo contém o payload do evento. Esse payload tem informações sobre o recurso do Google Workspace que foi alterado. Por exemplo, se você assinou eventos de participação em um espaço, o payload desses eventos contém informações sobre o spaces.membership recurso que foi alterado.

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 você quer receber no payload do evento.

A tabela a seguir mostra 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 participantes em mensagens diretas ou chats em grupo sem nome (google.workspace.chat.membership.v1.created), só são acionados após a primeira mensagem ser 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 as participações do Grupo do Google funcionam, consulte Adicionar um Grupo do Google a um espaço.

Temas relacionados

• Estrutura dos eventos do Google Workspace
• Escolher escopos do OAuth
• Criar uma assinatura para receber eventos do Chat