Lavorare con gli eventi di Google Chat

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

Un evento Google Chat rappresenta un'attività o una modifica in Chat, ad esempio un nuovo messaggio in uno spazio. La tua app di chat può utilizzare gli eventi per capire cosa è successo e intraprendere azioni o rispondere in modo significativo per i tuoi utenti.

Ecco alcuni esempi di come puoi utilizzare gli eventi:

  • Monitora e rispondi ai nuovi messaggi in uno spazio, ad esempio controllando 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 in modo efficace 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 il maggior numero di reazioni o risposte.
  • Comunicare su diverse piattaforme di messaggistica. Ad esempio, gli utenti possono inviare e ricevere messaggi da utenti su un'altra piattaforma di messaggistica senza uscire da Chat.

Come funzionano gli eventi

Ogni volta che succede qualcosa in Google Chat, una risorsa dell'API Google Chat viene creata, aggiornata o eliminata. Chat utilizza gli eventi per fornire informazioni alla tua app Chat sul tipo di attività che si è verificata e sulla risorsa 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, che crea una risorsa Message. Chat crea quindi un evento contenente i dati del nuovo messaggio.

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

La tabella seguente mostra in che modo un'attività in Chat influisce su una risorsa API Chat correlata e il tipo di evento che riceve la tua app di 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 gestore dello spazio. Viene aggiornata una risorsa Membership. 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, la tua app di Chat può eseguire una delle seguenti operazioni:

  • Iscriviti agli eventi utilizzando l'API Google Workspace Events per ricevere gli eventi man mano che si verificano.
  • Esegui una query per gli eventi recenti chiamando l'API Chat.

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

Iscriviti agli eventi Query per gli eventi
Casi d'uso
  • Elabora o rispondi agli eventi in tempo reale.
  • Monitora l'attività di abbonamento degli utenti e scopri nuovi spazi da monitorare.
  • Elaborare o rispondere agli eventi periodicamente o tramite un trigger.
  • Recupera gli eventi mancanti 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 maggiori dettagli, vedi Struttura degli eventi Google Workspace. Una risorsa API Chat ( spaces.spaceEvent)
Dati sugli eventi Stringa con codifica Base64 con o senza dati delle risorse. Per esempi di payload, vedi Dati sugli eventi. Payload JSON contenente i dati delle risorse. Alcuni tipi di eventi includono solo determinati campi delle risorse. Per esempi di payload, consulta la documentazione di riferimento.

Esempio: query o iscrizione a eventi relativi alle iscrizioni in uno spazio

In questo esempio, un'app Chat vuole ricevere informazioni sulle modifiche ai membri di uno spazio Chat. Nello spazio si verifica la seguente attività di abbonamento:

  • Un utente entra nello spazio, il che crea una risorsa Membership e attiva un evento di nuovo membro.
  • Un utente diventa un gestore dello spazio, il che aggiorna la risorsa Membership per l'utente e attiva un evento di aggiornamento dei membri.
  • Un utente esce dallo spazio, il che elimina la risorsa Membership per l'utente e attiva un evento di eliminazione di un membro.

Iscriviti agli eventi relativi agli abbonamenti

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

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

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

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

Query per gli eventi di abbonamento recenti

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

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

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

Per eseguire query sugli eventi utilizzando l'API Chat, vedi Elencare gli eventi di uno spazio Google Chat.

Limitazioni
  • Per gli abbonamenti agli 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 relativi all'appartenenza, l'utente deve essere un membro diretto dello spazio. Se un utente è stato aggiunto, aggiornato o rimosso indirettamente da uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di appartenenza. Per capire come funzionano le iscrizioni ai gruppi Google, consulta la sezione Aggiungere un gruppo Google a uno spazio.