Inscrever-se em eventos do Google Chat

Nesta página, descrevemos os eventos do Chat em que um app do Chat pode se inscrever 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 se inscrever em eventos, você também pode consultar eventos chamando a API Google Chat. Chamar a API Chat permite recuperar eventos periodicamente ou acompanhar eventos que você pode ter perdido de uma assinatura devido a uma interrupção. Para saber como receber e responder a eventos do Chat, consulte Trabalhar com eventos do Chat na documentação do Chat.

Eventos do Chat compatíveis

As assinaturas do Google Workspace permitem que você receba eventos sobre os seguintes tipos de mudanças no Chat:

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 é compatível com os seguintes recursos de destino para o Chat:

Recurso de destino Formato Limitações
Espaço

//chat.googleapis.com/spaces/SPACE

em que SPACE é o ID no nome do recurso do recurso space da API Chat. É possível conseguir o ID no URL do espaço ou usando o método spaces.list().

 O usuário ou app do Chat que autoriza a assinatura precisa ser membro do espaço pela Conta do Google Workspace ou do Google. Compatível com:
Todos os espaços de um usuário

//chat.googleapis.com/spaces/-

 A assinatura só recebe eventos dos espaços em que o usuário é membro com a Conta do Google ou do Google Workspace. Oferece suporte apenas à autenticação do usuário.
Usuário

//cloudidentity.googleapis.com/users/USER

em que USER é o ID no nome do recurso do recurso user da API Chat. Para mais detalhes, consulte Identificar e especificar usuários do Google Chat.

A assinatura só recebe eventos sobre o usuário que autorizou a assinatura. Um usuário não pode autorizar uma assinatura em nome de outros usuários. Oferece suporte apenas à autenticação do usuário.
Cliente

//admin.googleapis.com/customers/CUSTOMER

em que CUSTOMER é o ID de cliente. Também é possível usar o alias my_customer para o domínio personalizado do cliente do app do Chat.

A assinatura recebe eventos de todos os espaços e usuários gerenciados pelo domínio do cliente. Só aceita a autenticação de apps com aprovação do administrador.

Tipos de evento para criar assinaturas

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

Tipo de evento Formato Dados de recursos
Inscrições em espaços  
Uma mensagem é postada.

google.workspace.chat.message.v1.created

space.message
Uma mensagem é atualizada.

google.workspace.chat.message.v1.updated

space.message
Uma mensagem é excluída.

google.workspace.chat.message.v1.deleted

space.message
Uma reação é criada.

google.workspace.chat.reaction.v1.created

space.message.reaction
Uma reação é excluída.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Um participante é adicionado ao espaço.

google.workspace.chat.membership.v1.created

space.membership
Um participante é atualizado no espaço.

google.workspace.chat.membership.v1.updated

space.membership
Um participante é removido do espaço.

google.workspace.chat.membership.v1.deleted

space.membership
O espaço é atualizado.

google.workspace.chat.space.v1.updated

space
O espaço é excluído.

google.workspace.chat.space.v1.deleted

space
Assinaturas de usuários  
O usuário se torna participante de um espaço.

Nem todos os novos membros acionam eventos. Para mais detalhes, consulte Limitações.

google.workspace.chat.membership.v1.created

space.membership
A participação do usuário em um espaço é atualizada.

google.workspace.chat.membership.v1.updated

space.membership
O usuário é removido como participante direto de um espaço.

google.workspace.chat.membership.v1.deleted

space.membership
O estado de leitura do espaço do usuário é atualizado.

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
O estado de leitura da conversa do usuário é atualizado.

google.workspace.chat.threadReadState.v1.updated

threadReadState
Assinaturas para clientes  
Um evento ocorre em qualquer espaço, mensagem, reação, associação ou estado de leitura do usuário na sua organização do Google Workspace.

Oferece suporte a todos os tipos de eventos listados para assinaturas de espaço e de usuário.

Depende do tipo de evento (por exemplo, space, space.message, space.membership ou spaceReadState).

Tipos de evento em lote (somente saída)

Além de receber os tipos de evento em que você se inscreve, seu 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, seu 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 em que se inscrever. Portanto, não é necessário especificar eventos em lote ao criar uma inscrição. Por exemplo, se você se inscrever para receber novas reações (google.workspace.chat.reaction.v1.created), seu 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:

Tipo de evento em lote Formato
Várias mensagens são postadas.

google.workspace.chat.message.v1.batchCreated
Várias mensagens são atualizadas.

google.workspace.chat.message.v1.batchUpdated
Várias mensagens foram excluídas.

google.workspace.chat.message.v1.batchDeleted
Várias reações são criadas.

google.workspace.chat.reaction.v1.batchCreated
Várias reações foram excluídas.

google.workspace.chat.reaction.v1.batchDeleted
Vários participantes são adicionados ao espaço inscrito ou o usuário inscrito foi adicionado a vários espaços.

google.workspace.chat.membership.v1.batchCreated
Várias assinaturas são atualizadas no espaço inscrito ou para o usuário inscrito.

google.workspace.chat.membership.v1.batchUpdated
Vários participantes são removidos do espaço inscrito ou o usuário inscrito foi removido de vários espaços.

google.workspace.chat.membership.v1.batchDeleted
O espaço tem várias atualizações.

google.workspace.chat.space.v1.batchUpdated
Vários estados de leitura de espaço são atualizados para o usuário inscrito.

google.workspace.chat.spaceReadState.v1.batchUpdated
Vários estados de leitura de conversas são atualizados para o usuário inscrito.

google.workspace.chat.threadReadState.v1.batchUpdated

Dados do evento

Nesta seção, descrevemos 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 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 contém informações sobre o recurso spaces.membership que mudou.

Dados de recursos no payload do evento

Ao criar uma assinatura, é possível especificar se você 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 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:

Exemplo Tipo de evento Payload JSON

Um usuário posta uma mensagem no espaço que diz "Hello world".

google.workspace.chat.message.v1.created

Inclui dados de recursos:

{
    "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"
    }
}

Exclui dados de recursos:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
Um usuário se torna administrador do espaço.

google.workspace.chat.membership.v1.updated

Inclui dados de recursos:

{
    "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"
    }
}

Exclui dados de recursos:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
Um usuário atualiza a descrição do espaço para "Equipe de vendas do Cymbal Labs". google.workspace.chat.space.v1.updated

Inclui dados de recursos:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "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/SPACE_ID"
    }
}
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/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"
          }
        }
    ]
}

Exclui dados de recursos:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
Um usuário reage a uma mensagem com o emoji 😊. google.workspace.chat.reaction.v1.created

Inclui dados de recursos:

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

Exclui dados de recursos:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
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/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": "😸"
            }
          }
        }
    ]
}

Exclui dados de recursos:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
Um usuário acessa um espaço não lido, o que atualiza o estado de leitura do espaço. google.workspace.chat.spaceReadState.v1.updated

Inclui dados de recursos:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

Exclui dados de recursos:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
Um usuário lê uma mensagem em uma conversa, o que atualiza o estado de leitura da conversa. google.workspace.chat.threadReadState.v1.updated

Inclui dados de recursos:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

Exclui dados de recursos:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
Um usuário fica disponível no Chat. google.workspace.chat.availability.v1.updated

Inclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}

Exclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Um usuário fica inativo no Chat. google.workspace.chat.availability.v1.updated

Inclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}

Exclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Um usuário define a disponibilidade como Away no Chat. google.workspace.chat.availability.v1.updated

Inclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}

Exclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Um usuário define a disponibilidade como Do not disturb no Chat. google.workspace.chat.availability.v1.updated

Inclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}

Exclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Um usuário define um status personalizado no Chat. google.workspace.chat.availability.v1.updated

Inclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}

Exclui dados de recursos:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}

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}