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, ad esempio 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 come 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 si uniscono allo 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 di risposte.
• Comunicare su più piattaforme di messaggistica. Ad esempio, gli utenti possono inviare e ricevere messaggi dagli utenti su una piattaforma di messaggistica diversa senza abbandonare 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 alla tua app Chat informazioni sul tipo di attività che si è verificata e sulla risorsa dell'API Chat interessata.

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 per tipo. I tipi di eventi ti consentono di filtrare e ricevere solo il tipo di 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	Viene creata una risorsa Message.	Nuovo messaggio
Un utente diventa un gestore dello spazio.	Una risorsa Membership è stata aggiornata.	Abbonamento aggiornato
Un utente reagisce a un messaggio.	Viene creata una risorsa Reaction.	Nuova reazione
Un utente abbandona uno spazio.	Una risorsa Membership viene eliminata.	Abbonamento eliminato

Nota: l'app Chat può anche ricevere eventi di interazione. Questi eventi ti aiutano a rispondere alle interazioni dirette degli utenti, ad esempio quando un utente aggiunge la tua app Chat a uno spazio o @menzioni la tua app Chat. Per configurare e ricevere eventi di interazione, consulta Ricevere e rispondere alle interazioni con l'app Google Chat.

Ricevi eventi da Google Chat

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

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

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

	Iscriviti agli eventi	Query sugli eventi
Casi d'uso	Elabora o rispondi agli eventi in tempo reale. Monitora l'attività di appartenenza degli utenti e scopri nuovi spazi da monitorare.	Elabora o rispondi 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 pagina relativa ai 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 Google Cloud Pub/Sub, formattato in base alla specifica CloudEvent. Per maggiori dettagli, consulta Struttura degli eventi di Google Workspace.	Una risorsa API Chat ( spaces.spaceEvent)
Dati sugli eventi	Stringa con codifica Base64 con o senza dati delle risorse. Ad esempio, vedi Dati sugli eventi.	Payload JSON che contiene i dati delle risorse. Alcuni tipi di eventi includono solo determinati campi delle risorse. Ad esempio, consulta la documentazione di riferimento.

Esempio: eseguire una query o iscriversi a eventi sulle iscrizioni 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 a far parte dello 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 attiva un evento di eliminazione dei membri.

Iscriviti agli eventi di abbonamento

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

Figura 2. Un'app di Chat riceve gli 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 un'iscrizione allo spazio cambia. L'app Chat può quindi elaborare o rispondere in tempo reale a qualsiasi attività, come la pubblicazione di un messaggio di benvenuto privato per il membro che si è unito allo spazio.

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

Query sugli eventi di appartenenza recenti

Anziché ricevere gli eventi di appartenenza al momento in cui si verificano, un'app Chat può chiamare l'API Chat per elencare gli eventi dello spazio recenti relativi alle attività di appartenenza.

Figura 3. Un'app di Chat riceve gli eventi di appartenenza recenti tramite 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 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 spaceEvent risorse che rappresentano ogni modifica dell'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 adesione allo 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) vengono attivati solo dopo la pubblicazione del primo messaggio.
• Per ricevere eventi di iscrizione, l'utente deve essere un membro diretto dello spazio. Se un utente è stato aggiunto, aggiornato o rimosso indirettamente a uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di appartenenza. Per capire come funzionano le iscrizioni a gruppi Google, vedi Aggiungere un gruppo Google a uno spazio.

Argomenti correlati

• Panoramica dell'API Google Workspace Events
• Creare un abbonamento
• Visualizzare i dettagli su un evento dello spazio di Google Chat
• Elencare gli eventi da uno spazio di Google Chat
• Per esempi di come utilizzare gli eventi, consulta il tutorial Rispondere a domande basate sulle conversazioni di Chat con un'app Gemini AI Chat o sulla funzionalità di guida per l'inclusività dell'app Chat di gestione dei problemi nel codelab Creare app per Google Chat con Gemini.