Cómo suscribirse a eventos de Google Chat

En esta página, se describen los eventos de Chat a los que una app de Chat puede suscribirse 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 Chat.

Además de suscribirte a los eventos, también puedes consultar los eventos llamando a la API de Google Chat. 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 perdido de una suscripción debido a una interrupción. Para obtener información sobre las formas en que puedes recibir eventos de Chat y responder a ellos, consulta Trabaja con eventos de Chat en la documentación de Chat.

Eventos de Chat admitidos

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 de un mensaje
• Miembros nuevos, actualizados o que se quitaron del espacio.
• Cambios en el espacio al que te suscribiste, como un nombre o una descripción actualizados
• Cambios en la disponibilidad del usuario
• Cambios en el spaceReadState o el threadReadState del usuario.

Recursos que puedes supervisar para detectar eventos

Para recibir eventos, debes especificar un recurso de Chat para supervisar, que se denomina recurso de destino de la suscripción.

La API de Google Workspace Events admite los siguientes recursos de destino para Chat:

Tipos de eventos para crear suscripciones

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

Por ejemplo, para recibir eventos sobre los usuarios que se unen a un espacio de Chat, especifica el espacio como el recurso de destino y el tipo de evento como google.workspace.chat.membership.v1.created. Para recibir eventos sobre un usuario determinado que se une a cualquier espacio, especifica al usuario como el 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 admitidos para las suscripciones a espacios y a usuarios. Para obtener información sobre las excepciones relacionadas con lo que activa un evento, consulta Limitaciones.

Tipos de eventos por lotes (solo salida)

Además de recibir los tipos de eventos a los que te suscribas, es posible que tu app de Chat también reciba 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, es posible que tu app de Chat reciba 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 es necesario que especifiques eventos por lotes cuando crees una suscripción. Por ejemplo, si te suscribes a reacciones nuevas (google.workspace.chat.reaction.v1.created), tu app de Chat se configura automáticamente para recibir eventos de reacciones por lotes (google.workspace.chat.reaction.v1.batchCreated).

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

Datos de eventos

En esta sección, se describen los datos de eventos y los ejemplos de cargas útiles 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 contiene información sobre el recurso de Google Workspace que cambió. Por ejemplo, si te suscribiste a los eventos de membresía en un espacio, la carga útil de estos 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 su nombre. Por ejemplo, si deseas recibir eventos sobre los miembros de un espacio de Chat, especifica 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:

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

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

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
      

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

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
      

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

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

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

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

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

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

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

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

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

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

Limitaciones generales

• Para recibir eventos de membresía, el usuario o la app de Chat deben ser miembros directos del espacio. Si se agregaron, actualizaron o quitaron indirectamente 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 los Grupos de Google, consulta Cómo agregar un Grupo de Google a un espacio.

Suscripciones de usuarios

• En el caso de las suscripciones a usuarios, los eventos sobre miembros nuevos en mensajes directos o chats en grupo sin nombre (google.workspace.chat.membership.v1.created) solo se activan después de que se publica el primer mensaje.

Suscripciones de clientes (science Versión preliminar para desarrolladores)

En el caso de las suscripciones de clientes, se aplican las siguientes limitaciones:

• La organización de Google Workspace debe tener al menos una licencia de SKU de Enterprise. Ten en cuenta que este requisito no se aplica estrictamente durante la etapa del Programa de versión preliminar para desarrolladores, pero se aplicará en el futuro (se anunciará por separado).
• Una app de Chat solo puede crear una suscripción del cliente para una organización de Google Workspace determinada. Una organización de Google Workspace puede tener hasta cinco suscripciones de clientes en total (creadas por diferentes apps de Chat).

En el caso de las suscripciones de clientes, la entrega de eventos sigue estas reglas generales:

• Eventos de espacios: Se entregan solo si el evento ocurre en un espacio administrado por tu organización de Google Workspace.
• Eventos de usuario: Se entregan solo si el evento ocurre para un usuario que pertenece a tu organización de Google Workspace.

La única excepción a estas reglas son los eventos de membresía. Tu suscripción puede recibir eventos de membresía de espacios administrados por tu organización y de espacios administrados por organizaciones externas, pero la forma en que se entregan depende de qué organización administre el espacio:

Espacios administrados por tu organización de Google Workspace

Si se produce un cambio en la membresía de un espacio administrado por la organización de Google Workspace, se entrega como un evento del espacio.

El nombre del recurso de un evento de espacio usa el siguiente formato:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Espacios administrados por organizaciones externas

Si la membresía de un usuario administrado por tu organización de Google Workspace cambia en un espacio administrado por una organización externa (por ejemplo, un espacio externo con nombre o un mensaje directo creado por un usuario externo), tu suscripción recibe este evento como un evento de usuario.

El nombre del recurso de un evento de usuario usa el siguiente formato:

users/{userId}/userEvents/{userEventId}

Temas relacionados

• Estructura de los eventos de Google Workspace
• Elige permisos de OAuth
• Crea una suscripción para recibir eventos de Chat