Ricevi e rispondi alle interazioni con l'app Google Chat

In questa pagina viene descritto in che modo l'app Google Chat può ricevere e rispondere alle interazioni degli utenti, anche note come eventi di interazione con l'app Google Chat.

Un evento di interazione con l'app Google Chat rappresenta qualsiasi azione compiuta da un utente per richiamare o interagire con un'app di chat, ad esempio una @menzione di un'app di chat o l'aggiunta a uno spazio. Quando gli utenti interagiscono con un'app di chat, Google Chat invia all'app un evento di interazione. L'app Chat può utilizzare l'evento per elaborare l'interazione e creare una risposta.

Ad esempio, le app di chat utilizzano gli eventi di interazione per eseguire una delle seguenti operazioni:

Esempio di evento di interazione Risposta tipica da un'app di chat
Un utente richiama un'app di chat @menzionandola o utilizzando un comando slash. L'app Chat elabora ciò che dice il messaggio per crearne uno. Ad esempio, un'app di chat risponde al comando /about con un messaggio che spiega le attività che può svolgere.
Un utente aggiunge un'app di chat a uno spazio. L'app Chat invia un messaggio di onboarding che spiega cosa fa e come gli utenti nello spazio possono interagire con l'app.
Un utente rimuove un'app di chat da uno spazio. L'app Chat rimuove tutte le notifiche in arrivo configurate per lo spazio (ad esempio eliminando un webhook) e libera l'eventuale spazio di archiviazione interno.
Un utente fa clic su un pulsante in una scheda o una finestra di dialogo inviata dall'app Chat. L'app Chat elabora e archivia tutti i dati inviati dall'utente oppure restituisce un'altra scheda o finestra di dialogo.

Per ogni tipo di interazione utente, Google Chat invia un tipo diverso di evento di interazione. Ad esempio, Google Chat utilizza il tipo di evento MESSAGE per qualsiasi interazione in cui un utente richiama l'app Chat in un messaggio. Per maggiori dettagli, consulta Tipi di eventi di interazione con l'app Google Chat.

In questa pagina viene descritto come:

  • Configura l'app Chat per ricevere eventi.
  • Elabora l'evento di interazione sulla tua infrastruttura.
  • Se opportuno, rispondi agli eventi di interazione.

Ricevere eventi di interazione con l'app di Chat

Questa sezione descrive come ricevere ed elaborare gli eventi di interazione per l'app Chat.

Configurare l'app Chat per ricevere eventi di interazione

Non tutte le app di Chat sono interattive. Ad esempio, i hook in arrivo possono solo inviare messaggi in uscita e non possono rispondere agli utenti. Se stai creando un'app Chat interattiva, devi scegliere un endpoint che consenta all'app Chat di ricevere, elaborare e rispondere agli eventi di interazione. Per scoprire di più sulla progettazione dell'app di Chat, consulta Architetture di implementazione delle app di Chat.

Se hai creato un'app Chat interattiva, devi configurare l'API Google Chat in modo che Google Chat possa inviarti eventi di interazione:

  1. Nella console Google Cloud, apri la pagina dell'API Google Chat:

    Vai alla pagina dell'API Google Chat

  2. Fai clic sulla scheda Configurazione.
  3. Nella sezione Funzionalità interattive, fai clic sul pulsante Attiva funzionalità interattive per attivare l'opzione.
  4. In Funzionalità, seleziona una o entrambe le seguenti caselle di controllo:
    1. Ricevere messaggi 1:1: consente agli utenti di interagire con l'app Chat negli spazi di messaggi diretti. L'app di chat riceve eventi di interazione ogni volta che un utente invia un messaggio nello spazio di messaggi diretti.
    2. Partecipare a spazi e conversazioni di gruppo: consente agli utenti di aggiungere e rimuovere l'app Chat negli spazi con più di una persona. L'app di chat riceve eventi di interazione ogni volta che viene aggiunta o rimossa dallo spazio e ogni volta che gli utenti @menzionano o utilizzano un comando slash nello spazio.
  5. In Impostazioni di connessione, specifica dove Google Chat invia gli eventi di interazione dell'app di Chat.
  6. (Facoltativo) In Comandi slash, aggiungi e configura uno o più comandi slash. Per maggiori informazioni, vedi Configurare i comandi slash.
  7. (Facoltativo) In Anteprime link, aggiungi e configura uno o più pattern URL visualizzati in anteprima nell'app Chat. Per saperne di più, consulta la sezione Link alle anteprime.
  8. Fai clic su Salva.

L'app Chat è ora configurata per ricevere eventi di interazione da Google Chat.

Gestire i nuovi tentativi di chiamata HTTP per il servizio

Se una richiesta HTTPS al tuo servizio ha esito negativo (ad esempio un timeout, un errore di rete temporaneo o un codice di stato HTTPS non 2xx), Google Chat potrebbe riprovare a consegnare alcune volte entro qualche minuto (ma non è garantito). Di conseguenza, un'app di Chat potrebbe ricevere lo stesso messaggio più volte in determinate situazioni. Se la richiesta viene completata correttamente, ma restituisce un payload di messaggio non valido, Google Chat non riprova a effettuare la richiesta.

Elaborare o rispondere a eventi di interazione

Questa sezione spiega in che modo le app di Google Chat possono elaborare e rispondere agli eventi di interazione.

Quando l'app Chat riceve un evento di interazione da Google Chat, può rispondere in molti modi. In molti casi, le app di chat interattive rispondono all'utente con un messaggio. L'app Google Chat può anche cercare alcune informazioni da un'origine dati, registrare le informazioni sugli eventi di interazione o quasi qualsiasi altra informazione. Questo comportamento di elaborazione è essenzialmente ciò che definisce l'app Google Chat.

Per ogni evento di interazione, le app di chat ricevono un corpo della richiesta, che è il payload JSON che rappresenta l'evento. Puoi utilizzare le informazioni per elaborare una risposta. Per esempi di payload di eventi, consulta Tipi di eventi di interazione con l'app di Chat.

Il seguente diagramma mostra in che modo l'app Google Chat in genere elabora o risponde a diversi tipi di eventi di interazione:

Architettura del modo in cui le app Google Chat elaborano gli eventi di interazione.

Rispondi in tempo reale

Gli eventi di interazione consentono alle app di chat di rispondere in tempo reale o in modo sincrono. Le risposte sincrone non richiedono autenticazione.

Per creare risposte sincrone agli eventi di interazione, consulta le seguenti guide:

Per rispondere in modo sincrono, un'app di chat deve rispondere entro 30 secondi e la risposta deve essere pubblicata nello spazio in cui si è verificata l'interazione. Altrimenti, l'app Chat può rispondere in modo asincrono.

Rispondi in modo asincrono

A volte le app di chat devono rispondere a un evento di interazione dopo 30 secondi o eseguire attività al di fuori dello spazio in cui è stato generato l'evento di interazione. Ad esempio, un'app di chat potrebbe dover rispondere all'utente dopo aver completato un'attività a lunga esecuzione. In questo caso, le app di Chat possono rispondere in modo asincrono chiamando l'API Google Chat.

Per creare un messaggio utilizzando l'API Chat, vedi Creare un messaggio. Per le guide sull'utilizzo dei metodi aggiuntivi dell'API Chat, consulta la panoramica dell'API Chat.