En esta página, se explica cómo las apps de Google Chat pueden recibir eventos en Google Chat y responder a ellos.
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 manera significativa para tus usuarios.
Estos son algunos ejemplos de cómo puedes usar eventos:
- Supervisar y responder a mensajes nuevos en un espacio, como buscar palabras o frases clave
- Enviar un mensaje de bienvenida a los usuarios cuando se unen al espacio para explicar los lineamientos del espacio o compartir sugerencias sobre cómo usar la app de Chat de manera eficaz
- 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, actualiza o borra un recurso de la API de Google Chat. Chat usa eventos para entregar información a tu app de Chat sobre el tipo de actividad que ocurrió y el recurso de la API de Chat que se vio afectado.
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 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. |
Reacción nueva |
| Un usuario abandona un espacio. | Se borra un recurso Membership. |
Membresía borrada |
Recibe eventos de Google Chat
Para recibir eventos, tu app de Chat puede hacer lo siguiente:
- Suscribirse a eventos con la API de Google Workspace Events para recibirlos a medida que ocurren
- Consultar eventos recientes llamando a la API de Chat
En la siguiente tabla, se explica la diferencia y los motivos para consultar eventos o suscribirse a ellos:
| Suscríbete a eventos | Consulta eventos | |
|---|---|---|
| Casos de uso |
|
|
| API | API de Google Workspace Events | API de Chat |
| Fuente de eventos | Espacios, usuarios y organizaciones de Google Workspace ( Versión preliminar para desarrolladores) | Solo espacios |
| Eventos admitidos |
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. |
Para obtener una lista de los tipos de eventos compatibles, 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 detalles, consulta Estructura de los eventos de Google Workspace) |
Un recurso de la API de Chat
(
spaces.spaceEvent)
|
| Datos de eventos | String codificada en Base64 con o sin datos de recursos (para ver cargas útiles de ejemplo, consulta Datos de eventos) | Carga útil de JSON que contiene datos de recursos (algunos tipos de eventos solo incluyen ciertos campos de recursos) (para ver cargas útiles de ejemplo, 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
Membershipy activa un evento de miembro nuevo. - Un usuario se convierte en administrador del espacio, lo que actualiza el recurso
Membershippara el usuario y activa un evento de miembro actualizado. - Un usuario abandona el espacio, lo que borra el recurso
Membershippara el 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 para 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.
En la figura 2, la app de Chat tiene una suscripción activa al espacio, por lo que la app 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 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 recientes del espacio que están relacionados con la actividad de membresía.
En la figura 3, una app de Chat llama al método de la API de Chat
spaces.spaceEvents.list()
después de que se producen todas las actividades de membresía y filtra la consulta
para obtener 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 en función de 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 Enumera eventos de un espacio de Google Chat.
Limitaciones y comportamientos de entrega
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 de forma indirecta 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 Agrega un Grupo de Google a un espacio.
Suscripciones del usuario
-
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 ( 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 de 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 del espacio: Se entregan solo si el evento ocurre en un espacio administrado por tu organización de Google Workspace.
- Eventos del 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 es para 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 administra el espacio:
Espacios administrados por tu organización de Google Workspace
Si se produce un cambio de membresía en un espacio administrado por la organización de Google Workspace, se entrega como un evento del espacio.
El nombre del recurso de un evento del 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 con nombre externo o un mensaje directo creado por un usuario externo), tu suscripción recibe este evento como un evento del usuario.
El nombre del recurso de un evento del usuario usa el siguiente formato:
users/{userId}/userEvents/{userEventId}
Temas relacionados
- Descripción general de la API de Google Workspace Events
- Crea una suscripción
- Obtén detalles sobre un evento de espacio de Google Chat
- Enumera eventos de un espacio de Google Chat