Trabaja con eventos de Google Chat

En esta página, se explica cómo las apps de Google Chat pueden recibir y responder a eventos en Google Chat.

Un evento de Google Chat representa una actividad o un cambio en Chat, como un mensaje nuevo en un espacio. Tu app de Chat puede usar eventos para comprender lo que sucedió y tomar medidas o responder de una manera significativa para tus usuarios.

Estos son algunos ejemplos de cómo puedes usar los eventos:

  • Supervisar y responder mensajes nuevos en un espacio, como buscar palabras o frases clave
  • Envía un mensaje de bienvenida a los usuarios cuando se unan al espacio para explicarles los lineamientos del espacio o compartir sugerencias sobre cómo usar de forma eficaz la app de Chat.
  • Hacer un seguimiento y analizar la actividad de Chat Por ejemplo, para enviar un informe mensual sobre los miembros nuevos o los mensajes que reciben más reacciones o respuestas.
  • Comunicarse en diferentes plataformas de mensajería Por ejemplo, los usuarios pueden enviar y recibir mensajes de usuarios en una plataforma de mensajería diferente sin salir de Chat.

Cómo funcionan los eventos

Cada vez que sucede algo en Google Chat, se crea, se actualiza o se borra un recurso de la API de Google Chat. Chat usa eventos para enviar información a tu app de Chat sobre el tipo de actividad que se produjo y el recurso de la API de Chat que se vio afectado.

Ejemplo de cómo un mensaje publicado en un espacio de Google Chat activa un evento.
Figura 1. Un usuario publica un mensaje en un espacio de Chat, lo que crea un recurso Message. Luego, Chat crea un evento que contiene datos sobre el mensaje nuevo.

Chat clasifica los eventos por tipo. Los tipos de eventos te ayudan a filtrar y recibir solo el tipo de información que necesitas, y te permiten controlar actividades similares de la misma manera.

En la siguiente tabla, se muestra cómo una actividad en Chat afecta a un recurso relacionado de la API de Chat y el tipo de evento que recibe tu app de Chat:

Actividad Recurso de la API de Chat Tipo de evento
Un usuario publica un mensaje en un espacio de Chat Se crea un recurso Message. Mensaje nuevo
Un usuario se convierte en administrador del espacio. Se actualiza un recurso Membership. Membresía actualizada
Un usuario reacciona a un mensaje. Se crea un recurso Reaction. Nueva reacción
Un usuario abandona un espacio. Se borra un recurso Membership. Se borró la membresía

Cómo recibir eventos de Google Chat

Para recibir eventos, tu app de Chat puede hacer lo siguiente:

  • Suscríbete a eventos con la API de Google Workspace Events para recibirlos a medida que ocurren.
  • Llama a la API de Chat para consultar los eventos recientes.

En la siguiente tabla, se explica la diferencia y los motivos para consultar o suscribirse a eventos:

Suscríbete a eventos Cómo consultar eventos
Casos de uso
  • Procesar o responder eventos en tiempo real
  • Supervisa la actividad de membresía de los usuarios y descubre nuevos espacios para supervisar.
  • Procesar o responder eventos de forma periódica o a través de un activador
  • Recupera eventos perdidos de una suscripción (debido a una interrupción o a una suscripción inactiva).
API API de Google Workspace Events Chat API
Fuente de eventos Espacios y usuarios Solo espacios
Eventos admitidos
  • Mensajes
  • Membresías
  • Reacciones
  • Espacio

Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos para crear suscripciones en la documentación de la API de Google Workspace Events.
  • Mensajes
  • Membresías
  • Reacciones
  • Espacio

Para obtener una lista de los tipos de eventos admitidos, consulta el recurso spaceEvents en la documentación de referencia de la API de Chat.
Formato del evento Un mensaje de Google Cloud Pub/Sub con el formato según la especificación de CloudEvent. Para obtener más información, consulta Estructura de los eventos de Google Workspace. Un recurso de la API de Chat ( spaces.spaceEvent)
Datos de eventos Es una cadena codificada en base64 con o sin datos de recursos. Para ver ejemplos de cargas útiles, consulta Datos de eventos. Carga útil JSON que contiene datos de recursos. Algunos tipos de eventos solo incluyen ciertos campos de recursos. Para ver ejemplos de cargas útiles, consulta la documentación de referencia.

Ejemplo: Consulta o suscríbete a eventos sobre membresías en un espacio

En este ejemplo, una app de Chat quiere recibir información sobre los cambios en los miembros de un espacio de Chat. En el espacio, se produce la siguiente actividad de membresía:

  • Un usuario se une al espacio, lo que crea un recurso Membership y activa un evento de miembro nuevo.
  • Un usuario se convierte en administrador de un espacio, lo que actualiza el recurso Membership del usuario y activa un evento de miembro actualizado.
  • Un usuario abandona el espacio, lo que borra el recurso Membership del usuario y activa un evento de miembro borrado.

Suscríbete a eventos de membresía

Para recibir eventos en tiempo real, la app de Chat llama al método subscriptions.create() de la API de Google Workspace Events para suscribirse al espacio de todos los tipos de eventos de membresía. Después de crear la suscripción, la app de Chat puede comenzar a recibir eventos de membresía.

App de chat que se suscribe a eventos con la API de Google Workspace Events
Figura 2: Una app de Chat recibe eventos de membresía a través de una suscripción con la API de Google Workspace Events.

En la figura 2, la app de Chat tiene una suscripción activa al espacio, por lo que recibe un evento cada vez que cambia una membresía en el espacio. Luego, la app de Chat puede procesar o responder en tiempo real a cualquiera de las actividades, como publicar un mensaje de bienvenida privado para el miembro que se unió al espacio.

Para obtener información sobre cómo crear suscripciones con la API de Google Workspace Events, consulta la documentación de la API de Google Workspace Events.

Consulta los eventos de membresía recientes

En lugar de recibir los eventos de membresía a medida que ocurren, una app de Chat puede llamar a la API de Chat para enumerar los eventos de espacio recientes que se relacionan con la actividad de membresía.

App de chat que consulta eventos con la API de Chat
Figura 3: Una app de Chat recibe eventos de membresía recientes mediante una consulta de eventos de espacio con la API de Chat.

En la Figura 3, una app de Chat llama al método spaces.spaceEvents.list() de la API de Chat después de que se hayan producido todas las actividades de membresía y filtra la búsqueda de eventos de membresía nuevos, actualizados y borrados. La API de Chat muestra una lista de recursos spaceEvent que representan cada uno de los cambios de membresía. Luego, la app de Chat puede procesar o responder según la actividad reciente, como publicar un mensaje semanal con un resumen de la actividad de membresía del espacio en los últimos 7 días.

Para consultar eventos con la API de Chat, consulta Cómo crear una lista de eventos de un espacio de Google Chat.

Limitaciones
  • 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.
  • Para recibir eventos de membresía, el usuario debe ser miembro directo del espacio. Si un usuario se agregó, se actualizó o se quitó indirectamente a un espacio a través de un Grupo de Google, la suscripción no recibe esos eventos de membresía. Para comprender cómo funcionan las membresías de Grupos de Google, consulta Cómo agregar un Grupo de Google a un espacio.