Lavorare con gli eventi di Google Chat

Questa pagina spiega come 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. 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:

  • Monitorare e rispondere ai nuovi messaggi in uno spazio, ad esempio controllando parole o frasi chiave.
  • Inviare 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 di 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 una piattaforma di messaggistica diversa senza uscire da Chat.

Come funzionano gli eventi

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

Esempio di come un messaggio pubblicato in uno spazio 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 dati sul 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 dell'API Chat correlata e sul tipo di evento che riceve la tua app di Chat:

Attività Risorsa dell'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 lascia uno spazio. Viene eliminata una risorsa Membership. Abbonamento eliminato

Ricevere eventi da Google Chat

Per ricevere eventi, la tua app di Chat può eseguire una delle seguenti operazioni:

  • Iscriversi agli eventi utilizzando l'API Google Workspace Events per ricevere gli eventi man mano che si verificano.
  • Eseguire 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 Esegui una query per gli eventi
Casi d'uso
  • Elaborare o rispondere agli eventi in tempo reale.
  • Monitorare l'attività di abbonamento degli utenti e scoprire nuovi spazi da monitorare.
  • Elaborare o rispondere agli eventi periodicamente o tramite un trigger.
  • Recuperare gli eventi persi da un abbonamento (a causa di un'interruzione o abbonamento inattivo).
API API Google Workspace Events API Chat
Origine degli eventi Spazi, utenti e organizzazioni Google Workspace ( Anteprima per gli sviluppatori) Solo spazi
Eventi supportati
  • Messaggi
  • Abbonamenti
  • Reazioni
  • Spazio

Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi per la creazione di abbonamenti 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 di Google Cloud Pub/Sub, formattato in base alla specifica CloudEvent. Per maggiori dettagli, vedi 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. 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: eseguire una query o iscriversi agli eventi relativi agli abbonamenti in uno spazio

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

  • Un utente entra nello spazio, creando una risorsa Membership e attivando un nuovo evento membro.
  • Un utente diventa gestore dello spazio, aggiornando la risorsa Membership per l'utente e attivando un evento membro aggiornato.
  • Un utente lascia lo spazio, eliminando la risorsa Membership per l'utente e attivando un evento membro eliminato.

Iscriversi agli eventi di abbonamento

Per ricevere gli eventi in tempo reale, l' app di Chat chiama il metodo subscriptions.create() dell'API Google Workspace Events per iscriversi allo spazio per tutti i tipi di eventi di abbonamento. Dopo aver creato l'abbonamento, l'app di 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 di Chat ha un abbonamento attivo allo spazio, quindi l'app riceve un evento ogni volta che viene modificato un abbonamento nello spazio. L'app di Chat può quindi elaborare o rispondere in tempo reale a una qualsiasi delle attività, ad esempio pubblicando un messaggio di benvenuto privato al membro che ha aderito allo spazio.

Per scoprire come creare abbonamenti utilizzando l'API Google Workspace Events, consulta la documentazione dell'API Google Workspace Events.

Eseguire una query per gli eventi di abbonamento recenti

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

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 una query per gli eventi di spazio utilizzando l'API Chat.

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

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

Limitazioni e comportamenti di pubblicazione

Limitazioni generali

  • Per ricevere gli eventi di abbonamento, l'utente o l'app di Chat deve essere un membro diretto dello spazio. Se sono stati aggiunti, aggiornati o rimossi indirettamente da uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di abbonamento. Per capire come funzionano gli abbonamenti ai gruppi Google, vedi Aggiungere un gruppo Google a uno spazio.

Abbonamenti utente

  • 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.

Abbonamenti cliente ( Anteprima per gli sviluppatori)

Per gli abbonamenti cliente si applicano le seguenti limitazioni:

  • L'organizzazione Google Workspace deve avere almeno una licenza SKU Enterprise. Tieni presente che questo requisito non viene applicato rigorosamente durante la fase del Programma Anteprima per gli sviluppatori, ma verrà applicato in futuro (verrà annunciato separatamente).
  • Un'app di Chat può creare un solo abbonamento cliente per una determinata organizzazione Google Workspace. Un'organizzazione Google Workspace può avere un massimo di cinque abbonamenti cliente in totale (creati da diverse app di Chat).

Per gli abbonamenti cliente, la pubblicazione degli eventi segue queste regole generali:

  • Eventi di spazio: pubblicati solo se l'evento si verifica in uno spazio gestito dalla tua organizzazione Google Workspace.
  • Eventi utente: pubblicati solo se l'evento si verifica per un utente che appartiene alla tua organizzazione Google Workspace.

L'unica eccezione a queste regole riguarda gli eventi di abbonamento. Il tuo abbonamento può ricevere eventi di abbonamento sia da spazi gestiti dalla tua organizzazione sia da spazi gestiti da organizzazioni esterne, ma la modalità di pubblicazione dipende dall'organizzazione che gestisce lo spazio:

Spazi gestiti dalla tua organizzazione Google Workspace

Se si verifica una modifica all'abbonamento in uno spazio gestito dall'organizzazione Google Workspace, viene pubblicata come evento di spazio.

Il nome della risorsa di un evento di spazio utilizza il seguente formato:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Spazi gestiti da organizzazioni esterne

Se l'abbonamento di un utente gestito dalla tua organizzazione Google Workspace cambia in uno spazio gestito da un'organizzazione esterna (ad esempio, uno spazio denominato esterno o un messaggio diretto creato da un utente esterno), il tuo abbonamento riceve questo evento come evento utente.

Il nome della risorsa di un evento utente utilizza il seguente formato:

users/{userId}/userEvents/{userEventId}