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.

In questa pagina viene descritto come effettuare le seguenti operazioni:

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

Prerequisiti

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un'app Chat interattiva, completa una delle seguenti guide rapide in base all'architettura dell'app che vuoi utilizzare:

Tipi di eventi di interazione

Un evento di interazione con l'app Google Chat rappresenta qualsiasi azione intrapresa da un utente per richiamare o interagire con un'app Chat, ad esempio menzionare un'app Chat o aggiungerla a uno spazio.

Quando gli utenti interagiscono con un'app di Chat, Google Chat invia all'app Chat un evento di interazione, rappresentato come un tipo Event nell'API Chat. L'app Chat può utilizzare l'evento per elaborare l'interazione e, facoltativamente, rispondere con un messaggio.

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. Il tipo di evento di interazione è rappresentato utilizzando l'oggetto eventType.

Ad esempio, Google Chat utilizza il tipo di eventoADDED_TO_SPACE per qualsiasi interazione in cui un utente aggiunge l'app Chat a uno spazio, in modo che l'app Chat possa rispondere immediatamente con un messaggio di benvenuto nello spazio.

L'app di chat pubblica un messaggio di benvenuto.
Figura 1: quando un utente aggiunge un'app di Chat a uno spazio, l'app Chat riceve un evento di interazione ADDED_TO_SPACE gestito dall'app Chat per inviare un messaggio di benvenuto nello spazio.

La tabella seguente mostra le interazioni utente comuni, il tipo di evento di interazione ricevuto dalle app Chat e la modalità di risposta tipica delle app Chat:

Interazione utente eventType Risposta tipica da un'app di Chat
Un utente richiama un'app di Chat @menzionandola o utilizzando un comando slash. MESSAGE L'app Chat risponde in base ai contenuti del messaggio. 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. ADDED_TO_SPACE L'app Chat invia un messaggio di onboarding che spiega cosa fa e come gli utenti dello spazio possono interagire con essa.
Un utente rimuove un'app di Chat da uno spazio. REMOVED_FROM_SPACE 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 da un messaggio, una finestra di dialogo o la home page dell'app Chat. CARD_CLICKED L'app Chat elabora e archivia i dati inviati dall'utente oppure restituisce un'altra scheda.
Un utente apre la home page dell'app Chat facendo clic sulla scheda Home in un messaggio 1:1. APP_HOME L'app Chat restituisce una scheda statica o interattiva dalla home page.
Un utente invia un modulo dalla home page dell'app Chat. SUBMIT_FORM L'app Chat elabora e archivia i dati inviati dall'utente oppure restituisce un'altra scheda.

Per visualizzare tutti gli eventi di interazione supportati, consulta la EventType documentazione di riferimento.

Eventi di interazione dalle finestre di dialogo

Se l'app Chat apre dialoghi, l'evento di interazione contiene le seguenti informazioni aggiuntive che puoi utilizzare per elaborare una risposta:

  • isDialogEvent è impostato su true.
  • L'DialogEventType chiarisce se l'interazione attiva una finestra di dialogo per l'apertura, invia le informazioni da una finestra di dialogo o chiude una finestra di dialogo.

La tabella seguente mostra le interazioni comuni con le finestre di dialogo, i tipi di eventi di dialogo corrispondenti e una descrizione di come reagiscono in genere le app di chat:

Interazione dell'utente con una finestra di dialogo Tipo di evento della finestra di dialogo Risposta tipica
Un utente attiva una richiesta di dialogo. Ad esempio, utilizzano un comando con barra o fanno clic su un pulsante in un messaggio. REQUEST_DIALOG L'app Chat apre la finestra di dialogo.
Un utente invia le informazioni nella finestra di dialogo facendo clic su un pulsante. SUBMIT_DIALOG L'app Chat passa a un'altra finestra di dialogo o chiude la finestra di dialogo per completare l'interazione.
Un utente esce o chiude la finestra di dialogo prima di inviare le informazioni. CANCEL_DIALOG Se vuoi, l'app Chat può rispondere con un nuovo messaggio o aggiornare il messaggio o la scheda da cui l'utente ha aperto la finestra di dialogo.

Per saperne di più, vedi Aprire le finestre di dialogo interattive.

Ricevere eventi di interazione con l'app 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 di chat interattiva, devi scegliere un endpoint che consenta all'app 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.

Per ogni funzionalità interattiva che vuoi creare, devi aggiornare la configurazione nell'API Chat in modo che Google Chat possa inviare eventi di interazione correlati alla tua app di Chat:

  1. Nella console Google Cloud, vai alla pagina dell'API Chat e fai clic sulla pagina Configurazione:

    Vai alla pagina di configurazione dell'API Chat

  2. In Funzionalità interattive, controlla le impostazioni e aggiornale in base alle funzionalità che vuoi creare:

    Campo Descrizione
    Funzionalità Obbligatorio. Un insieme di campi che determinano in che modo l'app di Chat può interagire con gli utenti:
    • Ricevere messaggi 1:1: gli utenti possono trovare l'app Chat e inviarvi messaggi direttamente in Google Chat.
    • Partecipa a spazi e conversazioni di gruppo: gli utenti possono aggiungere l'app Chat a spazi e conversazioni di gruppo.
    Impostazioni di connessione Obbligatorio. L'endpoint per l'app Chat, che è uno dei seguenti:
    • URL endpoint HTTP: un endpoint HTTPS che ospita l'implementazione dell'app Chat.
    • Apps Script: un ID deployment per un progetto Apps Script che implementa un'app di Chat.
    • Nome argomento Cloud Pub/Sub: un argomento Pub/Sub a cui l'app di Chat si abbona come endpoint.
    • Dialogflow: registra l'app Chat con un'integrazione di Dialogflow. Per saperne di più, consulta Creare un'app Google Chat Dialogflow che capisce il linguaggio naturale.
    Comandi slash (Facoltativo) Comandi che possono essere mostrati agli utenti all'interno di Google Chat. Consente agli utenti di visualizzare le azioni principali della tua app Chat in Google Chat e di scegliere un'azione specifica con cui vogliono interagire. Per ulteriori informazioni, vedi Rispondere ai comandi slash come app di chat.
    Anteprime link (Facoltativo) Pattern URL che l'app Chat riconosce e fornisce contenuti aggiuntivi per quando gli utenti inviano link. Per ulteriori informazioni, consulta la sezione Link di anteprima.
    Visibilità (Facoltativo) Fino a cinque persone o uno o più gruppi Google che possono visualizzare e installare la tua app di chat. Utilizza questo campo per testare l'app di chat o per condividerla con il tuo team. Per ulteriori informazioni, consulta Testare le funzionalità interattive.
  3. Fai clic su Salva. Quando salvi la configurazione dell'app Chat, questa diventa disponibile per gli utenti specificati nella tua organizzazione Google Workspace.

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

Gestire i 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 ha ricevuto 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 data, registrare le informazioni sugli eventi di interazione o qualsiasi altra cosa. Questo comportamento di elaborazione è ciò che definisce l'app Google Chat.

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. In caso contrario, l'app Chat può rispondere in modo asincrono.

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

Il seguente diagramma mostra in che modo solitamente l'app Google Chat 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 rispondere in tempo reale, l'app Chat deve restituire un oggetto Message. Per rispondere con un messaggio nello spazio, l'oggetto Message può contenere oggetti text, cardsV2 e accessoryWidgets. Per l'utilizzo con altri tipi di risposte, consulta le seguenti guide:

Rispondi con un messaggio

In questo esempio, l'app Chat crea e invia un messaggio ogni volta che viene aggiunta a uno spazio. Per scoprire le best practice per l'onboarding degli utenti, consulta Presentare l'app Chat agli utenti.

Per inviare un messaggio quando un utente aggiunge la tua app Chat a uno spazio, l'app Chat risponde a un evento di interazione ADDED_TO_SPACE. Per rispondere agli eventi di interazione ADDED_TO_SPACE con un messaggio, utilizza il seguente codice:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

L'esempio di codice restituisce il seguente messaggio:

Esempio di messaggio di onboarding.

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