Ricevere e rispondere alle interazioni degli utenti

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

Questa pagina descrive come:

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

Creare un'app Chat interattiva come componente aggiuntivo di Google Workspace

Per creare un'app di Chat che interagisca con gli utenti di Chat, puoi creare un componente aggiuntivo di Google Workspace che espanda Chat. Anziché ricevere eventi di interazione dall'API Chat, l'app Chat riceve e risponde a oggetti evento dei componenti aggiuntivi. Per saperne di più, consulta Estendere Google Chat nella documentazione del componente aggiuntivo di Google Workspace.

Prerequisiti

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app Chat interattiva, completa una delle seguenti guide introduttive 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 un evento di interazione, rappresentato come 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 tipo diverso di evento di interazione che aiuta la tua app di Chat a 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 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 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 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 di un'app di chat
Un utente richiama un'app di Chat tramite @menzione o utilizzando un comando con barra. 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 Chat da uno spazio. REMOVED_FROM_SPACE L'app Chat rimuove le notifiche in arrivo configurate per lo spazio (ad esempio l'eliminazione di un webhook) e libera la memoria interna.
Un utente fa clic su un pulsante di 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.
  • DialogEventType specifica se l'interazione attiva l'apertura di una finestra di dialogo, invia informazioni da una finestra di dialogo o la chiude.

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 di dialogo Risposta tipica
Un utente attiva una richiesta di dialogo. Ad esempio, utilizzano un comando con barra diagonale o fanno clic su un pulsante di un messaggio. REQUEST_DIALOG La finestra di dialogo si apre nell'app Chat.
Un utente invia informazioni nella finestra di dialogo facendo clic su un pulsante. SUBMIT_DIALOG L'app Chat passa a un'altra finestra di dialogo o la chiude 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 ulteriori informazioni, vedi Aprire finestre di dialogo interattive.

Ricevere eventi di interazione con l'app Chat

Questa sezione descrive come ricevere ed elaborare gli eventi di interazione per la tua app di chat.

Configurare l'app Chat per ricevere eventi di interazione

Non tutte le app di chat sono interattive. Ad esempio, i webhook in arrivo possono inviare solo 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, rivedi le impostazioni e aggiornale in base alle funzionalità che vuoi creare:

    Campo Descrizione
    Funzionalità Obbligatorio. Un insieme di campi che determinano il modo in cui 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 Chat si iscrive come endpoint.
    • Dialogflow: registra l'app Chat con un'integrazione di Dialogflow. Per ulteriori informazioni, vedi Creare un'app Google Chat Dialogflow che comprenda il linguaggio naturale.
    Comandi slash Facoltativo. Comandi che possono essere mostrati agli utenti all'interno di Google Chat. Consente agli utenti di vedere le azioni di base per la tua app di chat in Google Chat e di scegliere un'azione specifica con cui interagire. Per ulteriori informazioni, vedi Rispondi ai comandi con barra come app di Chat.
    Anteprime link Facoltativo. Pattern URL riconosciuti dall'app di chat che forniscono contenuti aggiuntivi quando gli utenti inviano link. Per ulteriori informazioni, consulta Anteprime dei link.
    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, l'app è 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 in caso di timeout, guasto temporaneo della rete o codice di stato HTTPS diverso da 2xx), Google Chat potrebbe riprovare a inviare il messaggio alcune volte entro pochi minuti (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 messaggio non valido, Google Chat non riprova a inviare la richiesta.

Elaborare o rispondere 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 è essenzialmente 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 si è verificata 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 di come 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 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 ADDED_TO_SPACE evento di interazione. 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:

Messaggio di onboarding di esempio.

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à che richiede molto tempo. 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, consulta Creare un messaggio. Per guide sull'utilizzo di metodi aggiuntivi dell'API Chat, consulta la Panoramica dell'API Chat.