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.

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.

Prerequisiti

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

• Servizio HTTP con Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

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:

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 le finestre di dialogo, l'evento di interazione contiene le seguenti informazioni aggiuntive che puoi utilizzare per elaborare una risposta:

• Il valore 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:

Per ulteriori informazioni, vedi Aprire finestre di dialogo interattive.

Ricevi 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 di 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, 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 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 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 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 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 saperne di più, vedi 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 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 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 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 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:

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:

• Apri finestre di dialogo interattive
• Anteprime dei link
• Elaborare le informazioni inviate dagli utenti

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:

/**
 * 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`.'
    });
  }
};

/**
 * 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:

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

Argomenti correlati

• Invia un messaggio
• Aprire finestre di dialogo interattive
• Anteprime dei link
• Leggere i dati dei moduli inseriti dagli utenti sulle schede
• Rispondere ai comandi slash
• Creare una home page per un'app di Chat
• Verificare le richieste da Chat
• Testare le funzionalità interattive per le app Google Chat