Lavorare con gli eventi di Google Chat

In questa pagina viene spiegato in che modo le app di Google Chat possono ricevere e rispondere agli eventi in Google Chat.

Un evento di Google Chat rappresenta un'attività o una modifica in Chat, ad esempio un nuovo messaggio in uno spazio. L'app di chat può utilizzare gli eventi per capire cosa è successo e intervenire o rispondere in modo significativo per gli 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 mentre entrano nello spazio per spiegare le linee guida dello spazio o per 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 tra 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 succede 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 è verificato 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 che contiene i dati relativi al nuovo messaggio.

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

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 dall'app Chat:

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

Ricevere eventi da Google Chat

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

  • Iscriviti agli eventi utilizzando l'API Google Workspace Eventi per ricevere gli eventi non appena si verificano.
  • Query sugli eventi recenti chiamando l'API Chat.

La seguente tabella spiega la differenza e i motivi dell'esecuzione di query o della sottoscrizione agli eventi:

Iscriviti agli eventi Query sugli eventi
casi d'uso
  • Elabora gli eventi o rispondi in tempo reale.
  • Monitora l'attività di appartenenza degli utenti e scopri nuovi spazi da monitorare.
  • Elaborare o rispondere agli eventi periodicamente o tramite un attivatore.
  • Recupera 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 la sezione Tipi di eventi per la creazione di abbonamenti nella documentazione dell'API Google Workspace Eventi.
  • 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, consulta Struttura degli eventi di Google Workspace. Una risorsa dell'API Chat ( spaces.spaceEvent)
Dati sugli eventi Stringa con codifica Base64 con o senza dati delle risorse. Ad esempio i payload, consulta Dati sugli eventi. Payload JSON che contiene i dati delle risorse. Alcuni tipi di eventi includono solo determinati campi delle risorse. Ad esempio i payload, consulta la documentazione di riferimento.

Esempio: eseguire query o iscriversi a eventi relativi alle adesioni a uno spazio

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

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

Iscriviti agli eventi di abbonamento

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

App di chat che si abbona agli eventi utilizzando l'API Google Workspace Eventi.
Figura 2. Un'app di chat riceve gli eventi di appartenenza tramite un abbonamento utilizzando l'API Google Workspace Eventi.

Nella figura 2, l'app di Chat ha un abbonamento attivo allo spazio, quindi riceve un evento ogni volta che cambia un appartenenza 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 si è unito allo spazio.

Per scoprire di più su come creare abbonamenti utilizzando l'API Google Workspace Eventi, consulta la documentazione relativa all'API Google Workspace Eventi.

Query sugli eventi di appartenenza recenti

Invece di ricevere gli eventi di iscrizione man mano che si verificano, un'app Chat può chiamare l'API Chat per elencare gli eventi recenti dello spazio correlati alle attività relative alle iscrizioni.

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

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

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

Limitazioni
  • Per le iscrizioni agli utenti, gli eventi relativi ai nuovi membri in messaggi diretti o chat di gruppo senza nome (google.workspace.chat.membership.v1.created) si attivano solo dopo la pubblicazione del primo messaggio.
  • Le modifiche alla cronologia dello spazio non attivano gli eventi dello spazio aggiornati (tipo di evento: google.workspace.chat.spaces.v1.updated).
  • Per ricevere eventi di appartenenza, 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 informazioni su come funzionano le iscrizioni ai gruppi Google, vedi Aggiungere un gruppo Google a uno spazio.