Ricevere e rispondere agli eventi di interazione

Questa pagina descrive come la tua app Google Chat può ricevere e rispondere alle interazioni utente, note anche come eventi di interazione dell'app Google Chat.

Questa pagina descrive come:

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

Prerequisiti

Tipi di eventi di interazione

Un evento di interazione con l'app Google Chat rappresenta qualsiasi azione che un utente intraprende 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 Chat, Google Chat invia all'app Chat 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 l'app di Chat a gestire ogni tipo di evento di conseguenza. Il tipo di evento di interazione è rappresentato dall'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 che gestisce per inviare un messaggio di benvenuto nello spazio.

La seguente tabella mostra le interazioni comuni degli utenti, il tipo di evento di interazione che ricevono le app Chat e il modo in cui le app Chat rispondono in genere:

Interazione utente eventType Risposta tipica di un'app di chat
Un utente invia un messaggio a un'app Chat. Ad esempio, @menziona l'app Chat o utilizza un comando slash. MESSAGE L'app Chat risponde in base ai contenuti del messaggio. Ad esempio, un'app di chat risponde al comando slash /about con un messaggio che spiega le attività che l'app di chat può svolgere.
Un utente aggiunge un'app 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 l'app.
Un utente rimuove un'app Chat da uno spazio. REMOVED_FROM_SPACE L'app Chat rimuove tutte le notifiche in arrivo configurate per lo spazio (ad esempio l'eliminazione di un webhook) e cancella qualsiasi memoria interna.
Un utente fa clic su un pulsante di una scheda da un messaggio, una finestra di dialogo o una home page dell'app di chat. CARD_CLICKED L'app Chat elabora e archivia i dati inviati dall'utente o 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.
Un utente richiama un comando utilizzando un comando rapido. APP_COMMAND L'app Chat risponde in base al comando richiamato. Ad esempio, un'app di chat risponde al comando Informazioni con un messaggio che spiega le attività che l'app di chat può svolgere.

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

Eventi di interazione dalle finestre di dialogo

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

  • isDialogEvent è impostato su true.
  • DialogEventType chiarisce se l'interazione attiva l'apertura di una finestra di dialogo, invia 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 rispondono 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 slash o fanno clic su un pulsante di un messaggio. REQUEST_DIALOG L'app Chat apre la finestra di dialogo.
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 saperne di più, consulta 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 Chat.

Configurare l'app di chat per ricevere eventi di interazione

Non tutte le app di chat sono interattive. Ad esempio, i webhook in entrata 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 chat di ricevere, elaborare e rispondere agli eventi di interazione. Per saperne di più sulla progettazione dell'app di Chat, vedi Architetture di implementazione delle app di chat.

Per ciascuna delle funzionalità interattive 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. Nella sezione 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. Per impostazione predefinita, 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 dell'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 iscrive come endpoint.
    • Dialogflow: registra l'app di chat con un'integrazione di Dialogflow. Per saperne di più, vedi Creare un'app Google Chat Dialogflow che comprenda il linguaggio naturale.
    Comandi (Facoltativo) Comandi slash e comandi rapidi per l'app di chat. I comandi consentono agli utenti di richiedere un'azione o utilizzare una funzionalità specifica dell'app di chat. Per maggiori informazioni, vedi Rispondere ai comandi dell'app Google Chat.
    Anteprime link (Facoltativo) Pattern URL riconosciuti dall'app di chat che forniscono contenuti aggiuntivi per gli utenti che inviano link. Per ulteriori informazioni, vedi 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 la tua app di chat o per condividerla con il tuo team. Per saperne di più, consulta Testare le funzionalità interattive.

  3. Fai clic su Salva. Quando salvi la configurazione dell'app di chat, questa è disponibile per gli utenti specificati nella tua organizzazione Google Workspace.

La tua 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 errore di rete temporaneo o un codice di stato HTTPS non 2xx), Google Chat potrebbe riprovare a inviare la richiesta alcune volte entro pochi minuti (ma non è garantito). Di conseguenza, in determinate situazioni, un'app di chat potrebbe ricevere lo stesso messaggio più volte. Se la richiesta viene completata correttamente, ma restituisce un payload del messaggio non valido, Google Chat non riprova a inviare la richiesta.

Elaborare o rispondere agli eventi di interazione

Questa sezione spiega come 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 sugli eventi di interazione o qualsiasi altra cosa. Questo comportamento di elaborazione definisce essenzialmente 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 le informazioni per elaborare una risposta. Per esempi di payload degli eventi, vedi Tipi di eventi di interazione dell'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 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 l'autenticazione.

Per rispondere in tempo reale, l'app di chat deve restituire un oggetto Message. Per rispondere con un messaggio nello spazio, l'oggetto Message può contenere gli 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 di testo ogni volta che viene aggiunta a uno spazio. Per scoprire le best practice per l'onboarding degli utenti, consulta Presentare l'app di chat agli utenti.

Per inviare un messaggio di testo quando un utente aggiunge la tua app Chat a uno spazio, la tua app Chat risponde a un ADDED_TO_SPACE evento di interazione. Per rispondere agli eventi di interazione ADDED_TO_SPACE con un messaggio di testo, 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`.'
  }
}

Il codice campione restituisce il seguente messaggio di testo:

Messaggio di onboarding di esempio.

Rispondere in modo asincrono

A volte le app 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, consulta Crea un messaggio. Per guide sull'utilizzo di metodi API Chat aggiuntivi, consulta la panoramica dell'API Chat.