Cómo suscribirse a eventos de Google Chat

En esta página, se describen los eventos de Google Chat a los que se puede suscribir una app de Google Chat con la API de Google Workspace Events. Después de decidir qué tipos de eventos necesitas, crea una suscripción para comenzar a recibir eventos de Google Chat.

Además de suscribirte a eventos, también puedes llamar a la API de Chat para buscar eventos. Llamar a la API de Chat te permite recuperar eventos de forma periódica o ponerte al día con los eventos que podrías haber pasado por alto en una suscripción debido a una interrupción. Para obtener información sobre las formas en que puedes recibir y responder eventos de Chat, consulta Trabaja con eventos desde Google Chat en la documentación de Chat.

Recursos de destino de Chat admitidos

La API de Google Workspace Events admite suscripciones para lo siguiente:

  • Espacios, representados como recursos space
  • Usuarios, representados como recursos user de la API de Cloud Identity

Eventos de Chat compatibles

Las suscripciones a Google Workspace te permiten recibir eventos sobre los siguientes tipos de cambios en Chat:

  • mensajes nuevos, actualizados o borrados en el espacio.
  • Reacciones nuevas o quitadas a un mensaje
  • Miembros nuevos, actualizados o quitados del espacio
  • Cambios en el espacio al que te suscribiste, como una descripción o el nombre de un espacio actualizados

Tipos de eventos para crear suscripciones

Cuando creas una suscripción, usa el campo eventTypes[] para especificar qué tipos de eventos deseas recibir. Los tipos de eventos tienen el formato de la especificación de CloudEvents, como google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Por ejemplo, para recibir eventos sobre usuarios que se unen a un espacio de Chat, debes especificar el espacio como recurso de destino y el tipo de evento como google.workspace.chat.membership.v1.created. Para recibir eventos sobre un usuario determinado que se una a un espacio, especifica el usuario como recurso de destino y el tipo de evento como google.workspace.chat.membership.v1.created. Para obtener más información sobre cómo funcionan los eventos, consulta Estructura de los eventos de Google Workspace.

En la siguiente tabla, se muestran los tipos de eventos que se admiten para suscripciones a espacios y a usuarios. Para obtener información sobre las excepciones sobre lo que activa un evento, consulta Limitaciones.

Tipo de evento Formato Datos de recursos
Suscripciones a espacios  
Se publicó un mensaje.

google.workspace.chat.message.v1.created

space.message

Se actualiza un mensaje.

google.workspace.chat.message.v1.updated

space.message

Si se borra un mensaje

google.workspace.chat.message.v1.deleted

space.message

Se crea una reacción.

google.workspace.chat.reaction.v1.created

space.message.reaction

Se borra una reacción.

google.workspace.chat.reaction.v1.deleted

space.message.reaction

Se agregará un miembro al espacio.

google.workspace.chat.membership.v1.created

space.membership

Se actualiza un miembro en el espacio.

google.workspace.chat.membership.v1.updated

space.membership

Se quita a un miembro del espacio.

google.workspace.chat.membership.v1.deleted

space.membership

El espacio se actualiza.

google.workspace.chat.space.v1.updated

space

Se borrará el espacio.

google.workspace.chat.space.v1.deleted

space

Suscripciones a usuarios  
El usuario se convierte en miembro de un espacio.

No todos los miembros nuevos activan eventos. Para obtener más información, consulta Limitaciones.

google.workspace.chat.membership.v1.created

space.membership

Se actualiza la membresía del usuario a un espacio.

google.workspace.chat.membership.v1.updated

space.membership

Se quitará al usuario como miembro directo de un espacio.

google.workspace.chat.membership.v1.deleted

space.membership

Tipos de eventos por lotes (solo salida)

Además de recibir los tipos de eventos a los que te suscribes, la app de Chat también puede recibir eventos por lotes. Un evento por lotes es un evento que representa muchos eventos del mismo tipo que ocurren en un período corto. La carga útil de un evento por lotes contiene una lista de todos los recursos modificados.

Por ejemplo, si un usuario agrega 20 usuarios a un espacio al mismo tiempo, tu app de Chat podría recibir un evento por lotes (google.workspace.chat.membership.v1.batchCreated). La carga útil del evento contiene una lista de todos los recursos Membership nuevos que se crearon cuando el usuario agregó a los miembros al espacio.

Recibirás un evento por lotes para cualquier tipo de evento al que te suscribas, por lo que no necesitas especificar eventos por lotes cuando crees una suscripción. Por ejemplo, si te suscribes a reacciones nuevas (google.workspace.chat.reaction.v1.created), la app de Chat se configurará automáticamente para recibir eventos de reacción por lotes (google.workspace.chat.reaction.v1.batchCreated).

En la siguiente tabla, se muestran los posibles eventos por lotes para una suscripción:

Tipo de evento por lotes Formato
Se publican varios mensajes.

google.workspace.chat.message.v1.batchCreated

Se actualizan varios mensajes.

google.workspace.chat.message.v1.batchUpdated

Se borrarán varios mensajes.

google.workspace.chat.message.v1.batchDeleted

Se crean varias reacciones.

google.workspace.chat.reaction.v1.batchCreated

Se borrarán varias reacciones.

google.workspace.chat.reaction.v1.batchDeleted

Se agregan varios miembros al espacio suscrito o el usuario suscripto se agregó a varios espacios.

google.workspace.chat.membership.v1.batchCreated

Las membresías múltiples se actualizan en el espacio suscrito o para el usuario suscrito.

google.workspace.chat.membership.v1.batchUpdated

Se quitan varios miembros del espacio suscrito o se quita al usuario suscrito de múltiples espacios.

google.workspace.chat.membership.v1.batchDeleted

El espacio tiene varias actualizaciones.

google.workspace.chat.space.v1.batchUpdated

Datos de eventos

En esta sección, se describen los datos de eventos y las cargas útiles de ejemplo para los eventos en Chat.

Cuando tu suscripción a Google Workspace recibe un evento de Chat, el campo data contiene la carga útil del evento. Esta carga útil tiene información sobre el recurso de Google Workspace que cambió. Por ejemplo, si te suscribiste a eventos de membresía en un espacio, la carga útil de esos eventos contiene información sobre el recurso spaces.membership que cambió.

Datos de recursos en la carga útil del evento

Cuando creas una suscripción, puedes especificar si deseas que la carga útil incluya detalles sobre el recurso o solo el nombre. Por ejemplo, si deseas recibir eventos sobre los miembros de un espacio de Chat, puedes especificar qué campos de un recurso de membresía deseas recibir en la carga útil del evento.

En la siguiente tabla, se proporcionan ejemplos de cargas útiles de JSON para una suscripción al espacio de Chat spaces/AAAABBBBBB. Para cada evento que recibe la suscripción, la carga útil aparece en el campo data del evento:

Ejemplo Tipo de evento Carga útil de JSON

Un usuario publica un mensaje en el espacio que dice “Hello World”.

google.workspace.chat.message.v1.created

Incluye datos 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"
    }
}
      
Excluye los datos de recursos.
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
      
Un usuario se convierte en administrador del espacio.

google.workspace.chat.membership.v1.updated

Incluye datos 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"
    }
}
      
Excluye los datos de recursos.
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
      
Un usuario actualiza la descripción del espacio a “Equipo de ventas de Cymbal Labs”. google.workspace.chat.space.v1.updated
Incluye datos de recursos
{
    "space":
    {
        "name": "spaces/AAAABBBBBB",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      
Excluye los datos de recursos.
{
    "space":
    {
        "name": "spaces/AAAABBBBBB"
    }
}
      
Se agregaron dos usuarios de Chat al espacio al mismo tiempo. google.workspace.chat.membership.v1.batchCreated
Incluye datos 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"
          }
        }
    ]
}
      
Excluye los datos de recursos.
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
      
Un usuario reacciona a un mensaje con el emoji 😊. google.workspace.chat.reaction.v1.created
Incluye datos de recursos
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
        "user":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      
Omite datos de recursos
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
      
Los usuarios reaccionan a un mensaje con el emoji 😊 y el emoji Así. google.workspace.chat.reaction.v1.batchCreated
Incluye datos 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 datos de recursos
{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}
      

Limitaciones

  • En el caso de los eventos sobre miembros nuevos (google.workspace.chat.membership.v1.created), si el tipo de espacio es un mensaje directo o un mensaje grupal, los eventos se activan después de que se publica el primer mensaje en el espacio.
  • En el caso de los eventos sobre miembros nuevos, los eventos solo se activan cuando se agregan miembros después de que se crea el espacio. El usuario que crea el espacio no activa un evento de miembro nuevo.
  • Los cambios en el historial del espacio no activan eventos de espacio actualizados (Tipo de evento: google.workspace.chat.spaces.v1.updated).
  • Para recibir eventos de membresía, el usuario debe ser miembro directo del espacio. Si se agregó, actualizó o quitó indirectamente un usuario de un espacio a través de un Grupo de Google, la suscripción no recibirá esos eventos de membresía. Para comprender cómo funcionan las membresías de Grupos de Google, consulta Agrega un Grupo de Google a un espacio.