Cómo suscribirse a eventos de Google Chat (original) (raw)
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 eventos, también puedes consultarlos 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 haberte 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, consultaCómo trabajar 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 messagesen el espacio.
- Reacciones nuevas a un mensaje o reacciones que se quitaron de un mensaje
- Miembros nuevos, actualizados o que se quitarondel espacio.
- Cambios en el espacioal que te suscribiste, como un nombre o una descripción actualizados.
Recursos que puedes supervisar para obtener eventos
Para recibir eventos, debes especificar un recurso de Chat para supervisar, que se denomina recurso objetivo de la suscripción.
La API de Google Workspace Events admite los siguientes recursos objetivos para Chat:
| Recurso objetivo | Formato | Limitaciones |
|---|---|---|
| Espacio | //chat.googleapis.com/spaces/SPACE donde SPACE es el ID en el nombre del recurso del recurso space de la API de Chat. Puedes obtener el ID de la URL del espacio o con el spaces.list() método. | El usuario o la app de Chat que autoriza la suscripción debe ser miembro del espacio a través de su cuenta de Google Workspace o de Google Admite lo siguiente: Autenticación de usuarios Autenticación de apps con aprobación del administrador |
| Todos los espacios de un usuario | //chat.googleapis.com/spaces/- | La suscripción solo recibe eventos de los espacios en los que el usuario es miembro a través de su cuenta de Google Workspace o de Google. Solo admite la autenticación de usuarios. |
| Usuario | //cloudidentity.googleapis.com/users/USER donde USER es el ID en el nombre del recurso de la API de Chat user resource. Para obtener más información, consultaCómo identificar y especificar usuarios de Google Chat. | La suscripción solo recibe eventos sobre el usuario que autorizó la suscripción. Un usuario no puede autorizar una suscripción en nombre de otros usuarios. Solo admite la autenticación de usuarios. |
Tipos de eventos para crear suscripciones
Cuando crees una suscripción, usa eleventTypes[]campo para especificar qué tipos de eventos deseas recibir. Los tipos de eventos se formatean según la especificación de CloudEvents, comogoogle.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 objetivo 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 el usuario como el recurso objetivo 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 muestra qué tipos de eventos se admiten para las 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 publica un mensaje. | google.workspace.chat.message.v1.created | space.message |
| Se actualiza un mensaje. | google.workspace.chat.message.v1.updated | space.message |
| 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 agrega 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 un miembro del espacio. | google.workspace.chat.membership.v1.deleted | space.membership |
| Se actualiza el espacio. | google.workspace.chat.space.v1.updated | space |
| Se borra 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 quita 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, tu 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 breve. 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ó 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 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 borran varios mensajes. | google.workspace.chat.message.v1.batchDeleted |
| Se crean varias reacciones. | google.workspace.chat.reaction.v1.batchCreated |
| Se borran varias reacciones. | google.workspace.chat.reaction.v1.batchDeleted |
| Se agregan varios miembros al espacio suscrito, o el usuario suscrito se agregó a varios espacios. | google.workspace.chat.membership.v1.batchCreated |
| Se actualizan varias membresías en el espacio suscrito o para el usuario suscrito. | google.workspace.chat.membership.v1.batchUpdated |
| Se quitan varios miembros del espacio suscrito, o el usuario suscrito se quitó de varios 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, eldatacampo 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 estos eventos contiene información sobre elspaces.membership recurso 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 del recurso. 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:
| 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/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" } } Excluye datos de recursos: { "message": { "name": "spaces/SPACE_ID/messages/MESSAGE_ID" } } |
| Un usuario se convierte en administrador del espacio. | google.workspace.chat.membership.v1.updated | Incluye datos 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" } } Excluye datos de recursos: { "membership": { "name": "spaces/SPACE_ID/members/MEMBER_ID" } } |
| 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/SPACE_ID", "displayName": "Cymbal Sales", "spaceThreadingState": "THREADED_MESSAGES", "spaceType": "SPACE", "spaceDetails": { "description": "Sales team for Cymbal Labs." }, "spaceHistoryState": "HISTORY_ON" } } Excluye datos de recursos: { "space": { "name": "spaces/SPACE_ID" } } |
| 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/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" } } ] } Excluye datos de recursos: { "memberships": [ { "membership": { "name": "spaces/SPACE_ID/members/MEMBER_ID" } }, { "membership": { "name": "spaces/SPACE_ID/members/MEMBER_ID" } } ] } |
| Un usuario reacciona a un mensaje con el emoji 😊. | google.workspace.chat.reaction.v1.created | Incluye datos de recursos: { "reaction": { "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID", "user": { "name": "users/USER_ID", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } } Excluye datos de recursos: { "reaction": { "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID" } } |
| Los usuarios reaccionan a un mensaje con los emojis 😊 y 😸. | google.workspace.chat.reaction.v1.batchCreated | Incluye datos 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": "😸" } } } ] } Excluye datos 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", } } ] } |
Limitaciones
- Para las suscripciones a usuarios, los eventos sobre los 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 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, consultaCómo agregar un Grupo de Google a un espacio.
- Estructura de los eventos de Google Workspace
- Elige alcances de OAuth
- Crea una suscripción para recibir eventos de Chat