Lavorare con gli eventi di Google Chat

Questa pagina spiega in che modo le app Google Chat possono ricevere e rispondere agli eventi in Google Chat.

Un evento di Google Chat rappresenta un'attività o una modifica in Chat, come un nuovo messaggio in uno spazio. L'app Chat può utilizzare gli eventi per capire cosa è successo e intervenire o rispondere in modo significativo per gli utenti.

Ecco alcuni esempi di utilizzo degli eventi:

  • Monitorare e rispondere ai nuovi messaggi in uno spazio, ad esempio controllando la presenza di parole o frasi chiave.
  • Invia un messaggio di benvenuto agli utenti quando entrano nello spazio per spiegare le linee guida dello spazio o condividere suggerimenti su come utilizzare al meglio l'app Chat.
  • Monitorare e analizzare l'attività di Chat. Ad esempio, per inviare un report mensile sui nuovi membri o sui messaggi che ricevono più reazioni o risposte.
  • Comunicare su piattaforme di messaggistica. Ad esempio, gli utenti possono inviare e ricevere messaggi da utenti su una piattaforma di messaggistica diversa senza uscire da Chat.

Come funzionano gli eventi

Ogni volta che accade qualcosa in Google Chat, viene creata, aggiornata o eliminata una risorsa dell'API Google Chat. Chat utilizza gli eventi per fornire informazioni all'app Chat sul tipo di attività che si è verificata e sulla risorsa dell'API Chat interessata.

Esempio di come un messaggio pubblicato in uno spazio di Google Chat attiva un evento.
Figura 1. Un utente pubblica un messaggio in uno spazio di Chat, creando una risorsa Message. Chat crea quindi un evento contenente i dati del nuovo messaggio.

Chat classifica gli eventi in base al tipo. I tipi di eventi ti consentono di filtrare e ricevere solo il tipo di informazioni di cui hai bisogno e di gestire nello stesso modo attività simili.

La tabella seguente mostra in che modo un'attività in Chat influisce su una risorsa dell'API Chat correlata e il tipo di evento ricevuto dalla tua app Chat:

Attività Risorsa API Chat Tipo di evento
Un utente pubblica un messaggio in uno spazio di Chat Viene creata una risorsa Message. Nuovo messaggio
Un utente diventa un gestore dello spazio. Una risorsa Membership viene aggiornata. Abbonamento aggiornato
Un utente reagisce a un messaggio. Viene creata una risorsa Reaction. Nuova reazione
Un utente esce da uno spazio. Una risorsa Membership viene eliminata. Abbonamento eliminato

Ricevere eventi da Google Chat

Per ricevere eventi, l'app Chat può eseguire una delle seguenti operazioni:

  • Abbonati agli eventi utilizzando l'API Google Workspace Events per riceverli man mano che si verificano.
  • Esegui una query sugli eventi recenti chiamando l'API Chat.

La tabella seguente spiega la differenza e i motivi per eseguire query o eseguire l'iscrizione agli eventi:

Iscriversi agli eventi Esegui query sugli eventi
Casi d'uso
  • Elabora o rispondi agli eventi in tempo reale.
  • Monitora l'attività degli abbonati e scopri nuovi spazi da monitorare.
  • Elabora o rispondi agli eventi periodicamente o tramite un attivatore.
  • Recuperare gli eventi persi da un abbonamento (a causa di un'interruzione o di un abbonamento inattivo).
API API Google Workspace Events Chat API
Origine degli eventi Spazi e utenti Solo spazi
Eventi supportati
  • Messaggi
  • Abbonamenti
  • Reazioni
  • Spazio

Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi per la creazione di iscrizioni nella documentazione dell'API Google Workspace Events.
  • Messaggi
  • Abbonamenti
  • Reazioni
  • Spazio

Per un elenco dei tipi di eventi supportati, consulta la risorsa spaceEvents nella documentazione di riferimento dell'API Chat.
Formato degli eventi Un messaggio Google Cloud Pub/Sub, formattato in base alla specifica CloudEvent. Per informazioni dettagliate, consulta Struttura degli eventi di Google Workspace. Una risorsa API Chat ( spaces.spaceEvent)
Dati sugli eventi Stringa con codifica Base64 con o senza dati della risorsa. Per esempi di payload, vedi Dati sugli eventi. Payload JSON contenente i dati della risorsa. Alcuni tipi di eventi includono solo determinati campi delle risorse. Per esempi di payload, consulta la documentazione di riferimento.

Esempio: eseguire query o iscriversi a eventi relativi agli abbonamenti in uno spazio

In questo esempio, un'app Chat vuole ricevere informazioni sulle modifiche apportate ai membri di uno spazio di Chat. Nel lo spazio si verificano le seguenti attività relative all'abbonamento:

  • Un utente entra a far parte dello spazio, creando una risorsa Membership e attivando un nuovo evento membro.
  • Un utente diventa un gestore dello spazio, aggiorna la risorsa Membership per l'utente e attiva un evento di aggiornamento dei membri.
  • Un utente lascia lo spazio, il che comporta l'eliminazione della risorsa Membership per l'utente e l'attivazione di un evento di eliminazione del membro.

Iscriversi agli eventi per gli abbonati

Per ricevere gli eventi in tempo reale, l'app Chat chiama il metodo subscriptions.create() della API Google Workspace Events per iscriversi allo spazio per tutti i tipi di eventi di adesione. Dopo aver creato l'abbonamento, l'app Chat può iniziare a ricevere eventi di adesione.

App di chat che si iscrive agli eventi utilizzando l'API Google Workspace Events.
Figura 2. Un'app Chat riceve eventi di adesione tramite un abbonamento che utilizza l'API Google Workspace Events.

Nella figura 2, l'app Chat ha un abbonamento attivo allo spazio, pertanto riceve un evento ogni volta che un abbonamento allo spazio cambia. L'app Chat può quindi elaborare o rispondere in tempo reale a qualsiasi attività, ad esempio pubblicando un messaggio di benvenuto privato per il membro che si è unito allo spazio.

Per informazioni sulla creazione di iscrizioni utilizzando l'API Google Workspace Events, consulta la documentazione dell'API Google Workspace Events.

Esegui query sugli eventi relativi all'abbonamento recenti

Anziché ricevere gli eventi di adesione man mano che si verificano, un'app Chat può chiamare l'API Chat per elencare gli eventi recenti dello spazio correlati all'attività di adesione.

App di Chat che esegue query sugli eventi utilizzando l'API Chat.
Figura 3. Un'app Chat riceve gli eventi di adesione recenti eseguendo query sugli eventi dello spazio utilizzando l'API Chat.

Nella figura 3, un'app Chat chiama il metodo spaces.spaceEvents.list() dell'API Chat dopo che sono state eseguite tutte le attività di adesione e filtra la query per gli eventi di adesione nuovi, aggiornati ed eliminati. L'API Chat restituisce un elenco di risorse spaceEvent che rappresentano ciascuna delle modifiche all'appartenenza. L'app Chat può quindi elaborare o rispondere in base all'attività recente, ad esempio pubblicando un messaggio settimanale con un riepilogo dell'attività degli abbonati dello spazio negli ultimi 7 giorni.

Per eseguire query sugli eventi utilizzando l'API Chat, consulta Elenca gli eventi da uno spazio di Google Chat.

Limitazioni
  • Per le iscrizioni degli utenti, gli eventi relativi ai nuovi membri nei messaggi diretti o nelle chat di gruppo senza nome (google.workspace.chat.membership.v1.created) vengono attivati solo dopo la pubblicazione del primo messaggio.
  • Per ricevere eventi di adesione, l'utente deve essere un membro diretto dello spazio. Se un utente è stato aggiunto, aggiornato o rimosso indirettamente in uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di appartenenza. Per capire come funzionano le iscrizioni ai gruppi Google, consulta Aggiungere un gruppo Google a uno spazio.