Ricevere e rispondere agli eventi di interazione

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

Questa pagina descrive come eseguire le seguenti operazioni:

Configurare l'app Chat per ricevere eventi di interazione.
Elaborare l'evento di interazione nella tua infrastruttura.
Se necessario, rispondere agli eventi di interazione.

Prerequisiti

Un account Google Workspace Business o Enterprise con accesso a Google Chat.
Crea un progetto Google Cloud.
Configura la schermata per il consenso OAuth.
Abilita l'API Google Chat.

Tipi di eventi di interazione

Un evento di interazione dell'app 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 di Chat un evento di interazione, rappresentato come tipo Event nell' API Chat. L'app di 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 utilizzando l' eventType oggetto.

Ad esempio, Google Chat utilizza il tipo di evento ADDED_TO_SPACE per qualsiasi interazione in cui un utente aggiunge l' app di Chat a uno spazio, in modo che l' app di Chat possa immediatamente rispondere 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 di Chat riceve un evento di interazione `ADDED_TO_SPACE` che l'app di Chat gestisce 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 di Chat e il modo in cui le app di Chat rispondono in genere:

Interazione utente	`eventType`	Risposta tipica di un'app di Chat
Un utente invia un messaggio a un'app di Chat. Ad esempio, @menziona l'app di Chat o utilizza un comando slash.	`MESSAGE`	L'app di Chat risponde in base al contenuto del messaggio. Ad esempio, un'app di Chat risponde a il comando slash `/about` con un messaggio che spiega le attività che l'app di Chat può svolgere.
Un utente aggiunge un'app di Chat a uno spazio.	`ADDED_TO_SPACE`	L'app di 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 di Chat rimuove tutte le notifiche in arrivo configurate per lo spazio (ad esempio, elimina un webhook) e cancella qualsiasi memoria interna.
Un utente fa clic su un pulsante di una scheda da un messaggio dell'app di Chat, una finestra di dialogo o una home page.	`CARD_CLICKED`	L'app di Chat elabora e memorizza tutti i dati inviati dall'utente oppure restituisce un'altra scheda.
Un utente apre la home page dell' app di Chat facendo clic sulla scheda Home in un messaggio 1:1.	`APP_HOME`	L'app di Chat restituisce una scheda statica o interattiva card dalla home page.
Un utente invia un modulo dalla home page dell'app di Chat.	`SUBMIT_FORM`	L'app di Chat elabora e memorizza tutti i dati inviati dall'utente oppure restituisce un'altra scheda.
Un utente richiama un comando utilizzando un comando rapido.	`APP_COMMAND`	L'app di Chat risponde in base al comando che è stato 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 EventType documentazione di riferimento.

Eventi di interazione dalle finestre di dialogo

Se l'app di 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.
The 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 le app di Chat rispondono in genere:

Interazione utente con una finestra di dialogo	Tipo di evento di dialogo	Risposta tipica
Un utente attiva una richiesta di finestra di dialogo. Ad esempio, utilizza un comando slash o fa clic su un pulsante di un messaggio.	`REQUEST_DIALOG`	L'app di Chat apre la finestra di dialogo.
Un utente invia informazioni nella finestra di dialogo facendo clic su un pulsante.	`SUBMIT_DIALOG`	L'app di 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`	Facoltativamente, l'app di 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 finestre di dialogo interattive.

Ricevere eventi di interazione dell'app di Chat

Questa sezione descrive come ricevere ed elaborare gli eventi di interazione per la tua app di 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 ogni funzionalità interattiva che vuoi creare, devi aggiornare la configurazione nell'API Chat in modo che Google Chat possa inviare gli eventi di interazione correlati alla tua app di Chat:

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

Vai alla pagina di configurazione dell'API Chat

In Funzionalità interattive, esamina le impostazioni e aggiornale in base a lle 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 e inviare messaggi all'app di Chat direttamente in Google Chat. Partecipa a spazi e conversazioni di gruppo: gli utenti possono aggiungere l'app di Chat a spazi e conversazioni di gruppo.
Impostazioni di connessione	Obbligatorio. L'endpoint dell'app di Chat, che è uno dei seguenti: URL dell'endpoint HTTP: un endpoint HTTPS che ospita l'implementazione dell'app di Chat. Apps Script: un ID di 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 di Chat con un'integrazione di Dialogflow. Per saperne di più, vedi Creare un'app Google Chat di Dialogflow che comprende 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 saperne di più, vedi Rispondere ai comandi dell'app Google Chat.
Anteprime link	Facoltativo. Pattern di URL che l'app di Chat riconosce e per cui fornisce contenuti aggiuntivi quando gli utenti inviano link. Per saperne di più, vedi Visualizzare l'anteprima dei link.
Visibilità	Facoltativo. Fino a cinque persone o uno o più Gruppi Google che possono visualizzare e installare l'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.

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

L'app di 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, timeout, errore di rete temporaneo o 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 alcune situazioni un'app di Chat potrebbe ricevere lo stesso messaggio più volte. Se la richiesta viene completata correttamente, ma restituisce un payload di 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 di 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 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 di 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 di eventi, vedi Tipi di eventi di interazione dell'app di Chat.

Il seguente diagramma mostra come le app Google Chat elaborano o rispondono in genere 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 Message oggetto. Per rispondere con un messaggio nello spazio, l'oggetto Message può contenere text, cardsV2 e accessoryWidgets oggetti. Per l'utilizzo con altri tipi di risposte, consulta le seguenti guide:

Rispondi con un messaggio

In questo esempio, l'app di 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, vedi Presentare agli utenti la tua app di Chat.

Per inviare un messaggio di testo quando un utente aggiunge la tua app di Chat a uno spazio, l'app di 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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.
 */
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 di testo:

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à a lunga esecuzione. 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 le guide sull'utilizzo di altri metodi dell'API Chat, vedi la panoramica dell'API Chat.