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.
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 |
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 |
|
|
API | API Google Workspace Events | Chat API |
Origine degli eventi | Spazi e utenti | Solo spazi |
Eventi supportati |
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. |
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.
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.
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.