Ricevere e rispondere alle interazioni degli utenti

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

Un evento di interazione con l'app di Google Chat rappresenta qualsiasi azione intrapresa da un utente per richiamare o interagire con un'app di Chat, ad esempio @menzionare un'app di Chat o aggiungerla 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:

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 l'app di Chat può fare.
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 la memoria interna.
Un utente fa clic su un pulsante in una scheda o una finestra di dialogo inviata dall'app Chat. L'app Chat elabora e memorizza 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 diverso tipo di evento di interazione che consente all'app Chat di gestire ogni tipo di evento di conseguenza. Ad esempio, Google Chat utilizza il tipo di evento ADDED_TO_SPACE per qualsiasi interazione in cui un utente aggiunge l'app Chat a uno spazio, in modo che l'app Chat possa gestire una risposta, come la pubblicazione di un messaggio di benvenuto nello spazio. Per visualizzare tutti gli eventi di interazione supportati, consulta la documentazione di riferimento di EventType.

In questa pagina viene descritto come effettuare le seguenti operazioni:

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

Ricevi eventi di interazione con l'app di Chat

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

Configura l'app Chat per ricevere eventi di interazione

Non tutte le app di chat sono interattive. Ad esempio, i webhook 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 della tua app di Chat, vedi Architetture di implementazione delle app di Chat.

Se hai creato un'app di 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 di attivazione/disattivazione Attiva le funzionalità interattive per attivare le funzionalità.
  4. In Funzionalità, seleziona una o entrambe le caselle di controllo seguenti:
    1. Ricevere messaggi 1:1: consente agli utenti di interagire con la tua app di Chat negli spazi di messaggi diretti. L'app Chat riceve eventi di interazione ogni volta che un utente invia un messaggio nello spazio dei 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 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 deve inviare gli eventi di interazione con l'app di Chat.
  6. (Facoltativo) In Comandi slash, aggiungi e configura uno o più comandi slash. Per ulteriori informazioni, consulta la sezione Impostare i comandi slash.
  7. (Facoltativo) In Anteprime link, aggiungi e configura uno o più pattern URL visualizzati in anteprima dalla tua app di Chat. Per ulteriori informazioni, consulta la sezione Link di anteprima.
  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 al servizio

Se una richiesta HTTPS al tuo servizio non va a buon fine (ad esempio un timeout, un guasto temporaneo di rete o un codice di stato HTTPS non 2xx), Google Chat potrebbe riprovare l'invio alcune volte entro pochi minuti (ma non è garantito). Di conseguenza, un'app Chat potrebbe ricevere lo stesso messaggio alcune volte in determinate situazioni. Se la richiesta viene completata correttamente, ma restituisce un payload di messaggi non valido, Google Chat non reinvia la richiesta.

Elabora o rispondi agli eventi di interazione

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

Dopo che 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 sull'evento di interazione o praticamente qualsiasi altra cosa. Questo comportamento di elaborazione è ciò che definisce l'app Google Chat.

Per ogni evento di interazione, le app di chat ricevono un corpo della richiesta, ovvero il payload JSON che rappresenta l'evento. Puoi utilizzare le informazioni per elaborare una risposta. Per esempi di payload di eventi, vedi 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 l'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 è avvenuta 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à di lunga durata. 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 guide sull'utilizzo dei metodi aggiuntivi dell'API Chat, consulta la panoramica dell'API Chat.