Ricevere e rispondere alle interazioni degli utenti

Questa pagina descrive in che modo l'app di Chat può ricevere e rispondere alle interazioni degli utenti in Google Chat.

Per creare interfacce interattive per le app di Chat, utilizza i seguenti componenti:

  • Trigger: i modi in cui gli utenti di Google Chat possono richiamare un'app di Chat, ad esempio aggiungendola a uno spazio o inviandole un messaggio.
  • Oggetti evento: i dati che le app Chat ricevono dai trigger o dalle interazioni con la UI.
  • Azioni: i modi in cui le app di Chat possono rispondere alle interazioni, ad esempio inviando messaggi o restituendo un'interfaccia utente basata su schede.
L'app di Chat riceve un oggetto evento da un trigger Aggiunta allo spazio
Figura 1: quando un utente aggiunge un'app Chat a uno spazio, viene attivato il trigger Aggiunta allo spazio, che invia un oggetto evento. Per rispondere con un messaggio, l'app di Chat gestisce l'oggetto evento e restituisce un'azione che crea il messaggio.

Le app di Chat possono creare e visualizzare interfacce nei seguenti modi:

  • Messaggi che possono contenere testo, schede statiche o interattive e pulsanti accessori.
  • Home page (Home dell'app) che vengono visualizzate nella scheda Home dei messaggi diretti 1:1 con l'app di Chat.
  • Finestre di dialogo, ovvero schede che si aprono in una nuova finestra e che in genere invitano gli utenti a inviare informazioni.
  • Anteprime link, ovvero schede che mostrano in anteprima informazioni su un servizio esterno.

Prerequisiti

Come funzionano le interazioni degli utenti

Quando un utente interagisce con un'app Chat, Google Chat richiama un trigger configurato e invia un oggetto evento all'endpoint o alla funzione dell'app Chat. L'app di Chat elabora l'oggetto evento e può restituire un'azione in modo sincrono entro 30 secondi o rispondere in modo asincrono utilizzando l'API Chat.

Il seguente diagramma mostra come le app Google Chat elaborano e rispondono alle interazioni degli utenti:

Architettura del modo in cui le app Google Chat elaborano le interazioni degli utenti.

Trigger

I trigger sono i modi specifici in cui gli utenti richiamano un'app di Chat utilizzando la UI di Chat, ad esempio utilizzando le @menzioni o i comandi dell'app.

La tabella seguente mostra i trigger di Chat, una descrizione e il modo in cui le app di Chat in genere rispondono:

Trigger Descrizione Risposta tipica
Aggiunta allo spazio

Un utente aggiunge l'app Chat a uno spazio o un amministratore di Google Workspace installa l'app Chat negli spazi dei messaggi diretti per gli utenti della sua organizzazione. Per informazioni sulle app di Chat installate dagli amministratori, consulta Installa le app del Marketplace per la tua organizzazione nella documentazione della Guida per gli amministratori di Google Workspace.

 L'app di Chat invia un messaggio di onboarding che spiega cosa fa e come gli utenti dello spazio possono interagire con l'app.
Messaggio

Un utente interagisce con l'app di Chat in un messaggio in uno dei seguenti modi:

  • Invia un messaggio in uno spazio di messaggi diretti (DM) con l'app di Chat.
  • @menziona l'app di Chat in qualsiasi tipo di spazio.
  • Invia un messaggio contenente un link che corrisponde al pattern dell'URL per le anteprime dei link.
  • Digita il testo nel menu di selezione multipla di un widget selectionInput.
 L'app di Chat risponde in base ai contenuti del messaggio. Ad esempio, un'app di Chat risponde con un messaggio, allega una scheda di anteprima del link o suggerisce elementi in un menu a selezione multipla.
Rimossa dallo spazio

Un utente rimuove l'app Chat da uno spazio o un amministratore di Google Workspace disinstalla l'app Chat per un utente della sua organizzazione.

Gli utenti non possono rimuovere le app di Chat installate dall'amministratore. Se un utente aveva installato l'app Chat in precedenza, l'app Chat rimane installata indipendentemente dal fatto che un amministratore di Google Workspace tenti di disinstallarla.

 L'app di Chat rimuove tutte le notifiche in arrivo configurate per lo spazio (ad esempio eliminando un webhook) e libera lo spazio di archiviazione interno. Le app di Chat non possono rispondere con messaggi a questo trigger perché non sono più membri dello spazio.
Comando dell'app

Un utente richiama un comando dell'app di Chat (ad esempio un comando slash, un comando rapido o un'azione di messaggio).

 L'app di Chat risponde al comando. Ad esempio, risponde con un messaggio o apre una finestra di dialogo.
App Home

Un utente apre la scheda Home in uno spazio di messaggi diretti 1:1 con l'app Chat o interagisce con un widget nella scheda della home page.

 L'app Chat restituisce un oggetto RenderActions che invia una scheda della home page (pushCard) o aggiorna la scheda della home page visualizzata (updateCard).

Puoi configurare gli endpoint o le funzioni di callback per questi trigger nella console Google Cloud nella pagina Configurazione dell'API Chat. Per istruzioni passo passo, consulta Configura l'API Google Chat.

Configura i prompt iniziali

I prompt iniziali aiutano gli utenti a scoprire le funzionalità della tua app di Chat quando aprono un messaggio diretto 1:1 vuoto con la tua app. Puoi configurare fino a tre prompt iniziali.

Per aggiungere e configurare i prompt iniziali:

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

    Vai alla pagina di configurazione dell'API Chat

  2. Nella sezione Funzionalità interattive, individua Prompt iniziali e fai clic su Aggiungi un prompt.

  3. Nel campo Ranking (1-3), inserisci un numero compreso tra 1 e 3 per specificare l'ordine di visualizzazione.

  4. In Selezione del tipo, scegli il comportamento del prompt:

    • Prompt testuale: compila la barra di scrittura con un testo predefinito quando l'utente fa clic sul chip di prompt.
    • Prompt dei comandi: esegue un comando slash o un comando rapido registrato quando viene selezionato. Non è possibile selezionare i comandi che richiedono argomenti aggiuntivi.

  5. Configura il prompt in base al tipo selezionato:

    • Se hai selezionato Prompt di testo:

      1. In Titolo, inserisci il titolo del prompt visualizzato nel chip (fino a 30 caratteri).
      2. In Testo del prompt, inserisci il testo inserito nella barra di scrittura (fino a 60 caratteri).
      3. (Facoltativo) Aggiungi titoli e testo localizzati per gli utenti in altre lingue:
      4. Nella sezione Prompt localizzati, fai clic su Aggiungi una lingua.
      5. In Lingua, seleziona una lingua supportata dal menu a discesa.
      6. In Titolo localizzato, inserisci il titolo localizzato (fino a 30 caratteri).
      7. In Testo del prompt localizzato, inserisci il testo del prompt localizzato (fino a 60 caratteri).
      8. Ripeti l'operazione per aggiungere altre lingue, se necessario.

    • Se hai selezionato Prompt dei comandi:

      1. In Comando slash/Comando rapido, seleziona il comando dal menu a discesa.

  6. Fai clic su Fine e poi su Salva in fondo alla pagina.

Gestisci i nuovi tentativi di chiamata HTTP al tuo 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 diverso da 2xx), Google Chat potrebbe riprovare a recapitare il messaggio alcune volte nell'arco di alcuni minuti (ma non è garantito). Di conseguenza, un'app di Chat potrebbe ricevere lo stesso evento più volte in determinate situazioni. Se la richiesta viene completata correttamente, ma restituisce un payload di risposta non valido, Google Chat non riprova a inviarla.

Oggetti evento

Le app di Chat ricevono oggetti evento quando viene eseguito un trigger di Chat o quando gli utenti di Chat interagiscono con una UI dell'app di Chat (ad esempio facendo clic su un pulsante o inviando una finestra di dialogo). L'oggetto evento ti consente di utilizzare i dati di interazione per rispondere o aggiornare una UI.

Nel 2025, le app di Google Chat sono state ampliate per supportare gli eventi dei componenti aggiuntivi, che sono diventati l'impostazione predefinita per le nuove app di Chat a partire da luglio 2025. Nella documentazione di Chat, gli eventi dei componenti aggiuntivi sono il tipo di evento standard mostrato nelle guide e negli esempi di codice. La documentazione relativa agli eventi di Chat (per le app di Chat che non sono componenti aggiuntivi di Google Workspace) è suddivisa in sezioni compresse (ad esempio, App di Chat che non sono componenti aggiuntivi: ricevi e rispondi agli eventi di interazione).

Determina i tipi di eventi e risposte

Quando l'app di Chat riceve un oggetto evento, la struttura del payload e il modo in cui rispondi dipendono dal fatto che l'app di Chat sia configurata come componente aggiuntivo di Google Workspace.

Per verificare il tipo di oggetti evento ricevuti dalla tua app e come deve rispondere, controlla la configurazione dell'app utilizzando la seguente tabella:

Tipo di app Riceve gli eventi dei componenti aggiuntivi
(impostazione predefinita per le nuove app create dopo luglio 2025)		 Riceve eventi di Chat
(impostazione predefinita precedente, prima di luglio 2025)
App Apps Script
Controlla il file manifest (appsscript.json)		 L'oggetto chat è configurato all'interno di addOns: 
{
  "addOns": {
    "chat": {}
  }
}
 		L'oggetto chat è configurato nella radice del manifest: 
{
  "chat": {}
}
Altre app
Controlla la pagina Configurazione dell'API Google Chat		 La casella di controllo "Crea questa app di Chat come componente aggiuntivo di Google Workspace" è selezionata. La casella di controllo "Crea questa app di Chat come componente aggiuntivo di Google Workspace" non è selezionata.
Dove trovare la documentazione Nelle guide e negli esempi di codice

Documentazione di riferimento sugli eventi: Oggetti evento dei componenti aggiuntivi		 Sezioni compresse (ad esempio, App di Chat che non sono componenti aggiuntivi: ricevi e rispondi agli eventi di interazione)

Documentazione di riferimento sugli eventi: Eventi di interazione dell'API Chat
Come rispondere Restituisci un'azione, ad esempio DataActions o RenderActions.
Scopri come rispondere con un'azione		 Restituisce una risorsa Message.
Scopri come rispondere con un messaggio

Payload degli oggetti evento

Ogni oggetto evento dei componenti aggiuntivi include un commonEventObject con i dettagli dell'host e della piattaforma (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters e formInputs) e un oggetto chat contenente il contesto specifico di Chat:

  • Per un trigger App Home (quando un utente apre la scheda Home in un messaggio diretto 1:1 con l'app Chat), l'oggetto chat contiene chat.user e chat.eventTime senza un campo payload di unione. Quando un utente fa clic su un pulsante nella scheda della home page, l'oggetto evento include chat.buttonClickedPayload insieme a commonEventObject.parameters (e commonEventObject.formInputs se la scheda contiene input del modulo).
  • Per le interazioni con spazi e messaggi (Aggiunta allo spazio, Messaggio, Rimozione dallo spazio, Comando dell'app o interazioni con pulsanti e widget), l'oggetto chat include chat.user, chat.space, chat.eventTime e il payload di interazione corrispondente:
    • messagePayload: contiene space, message e configCompleteRedirectUri quando un utente invia un messaggio.
    • addedToSpacePayload: contiene space, interactionAdd e configCompleteRedirectUri quando l'app di Chat viene aggiunta a uno spazio.
    • removedFromSpacePayload: contiene space quando l'app Chat viene rimossa da uno spazio.
    • buttonClickedPayload: contiene space, message, isDialogEvent e dialogEventType quando un utente fa clic su un pulsante in una scheda o in una finestra di dialogo.
    • widgetUpdatedPayload: contiene space quando un utente interagisce con un widget, ad esempio digitando in un menu a selezione multipla con un'origine dati esterna.
    • appCommandPayload: contiene space, message, appCommandMetadata, isDialogEvent, dialogEventType e configCompleteRedirectUri quando un utente richiama un comando dell'app.

Per scoprire di più sugli oggetti evento dei componenti aggiuntivi in Chat e in altre applicazioni Google Workspace, consulta Oggetti evento.

Fornire una risposta

Questa sezione spiega in che modo le app di Chat utilizzano le azioni per rispondere in modo sincrono alle interazioni degli utenti.

Per rispondere con un'azione, un'app di Chat deve rispondere entro 30 secondi e la risposta deve essere applicata allo spazio in cui si è verificata l'interazione. Queste risposte sincrone non richiedono l'autenticazione. Se l'app di Chat richiede più di 30 secondi o deve agire al di fuori dello spazio, configura l'autenticazione e rispondi in modo asincrono utilizzando l'API Google Chat.

Per rispondere alle interazioni degli utenti in modo sincrono, l'app di Chat gestisce l'oggetto evento in entrata e restituisce uno dei seguenti oggetti JSON:

La tabella seguente mostra come le app di Chat possono rispondere con azioni. Le app di Chat possono restituire direttamente oggetti JSON o creare la risposta utilizzando AddOnResponseService e CardService di Apps Script.

Risposta dell'app di Chat Azione richiesta da restituire (JSON) Azione richiesta per il ritorno (Apps Script)
Inviare un messaggio o aggiornare un messaggio. DataActions (createMessageAction o updateMessageAction) DataActionsResponse
Visualizzare l'anteprima dei link nei messaggi inviati dagli utenti di Chat in uno spazio. DataActions (updateInlinePreviewAction) DataActionsResponse
Eseguire il rendering o l'aggiornamento di una home page nella scheda Home di un messaggio diretto. RenderActions (pushCard o updateCard) ActionResponse
Aprire, aggiornare o chiudere una finestra di dialogo. RenderActions (pushCard, updateCard o endNavigation: "CLOSE_DIALOG") ActionResponse
Per raccogliere informazioni da una scheda o da una finestra di dialogo, suggerisci elementi di selezione in base a ciò che gli utenti digitano in un menu a selezione multipla. RenderActions (modifyCard) ActionResponse
Richiedi la configurazione o l'autorizzazione per un servizio esterno. AuthorizationError (basic_authorization_prompt) AuthorizationException

Rispondi con un messaggio

Le app di Chat possono rispondere con un messaggio a uno dei seguenti trigger o interazioni:

  • Trigger di messaggio, ad esempio quando gli utenti utilizzano la menzione @o inviano un messaggio diretto a un'app di Chat.
  • Trigger Aggiunta allo spazio, ad esempio quando gli utenti installano l'app Chat da Google Workspace Marketplace o la aggiungono a uno spazio.
  • Trigger di comandi dell'app, ad esempio quando gli utenti richiamano un comando slash o un comando rapido.
  • Clic sui pulsanti delle schede nei messaggi o nelle finestre di dialogo. Ad esempio, quando gli utenti inseriscono informazioni e fanno clic su Invia.

Le app di Chat possono includere uno dei seguenti elementi in un messaggio:

  • Testo che contiene link ipertestuali, @menzioni ed emoji. Consulta Formatta i messaggi.
  • Una o più schede, che possono essere visualizzate in un messaggio o aprirsi in una nuova finestra come finestra di dialogo. Consulta Crea schede per le app Google Chat.
  • Uno o più widget accessori, ovvero pulsanti che vengono visualizzati dopo il testo o le schede di un messaggio.

Per rispondere con un messaggio, restituisci DataActions con un oggetto CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Nell'esempio seguente, un'app di Chat crea e invia un messaggio di testo di onboarding ogni volta che viene aggiunta a uno spazio rispondendo al trigger Aggiunta allo spazio con DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

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 GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", 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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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.

Aggiorna un messaggio

Le app di Chat possono anche aggiornare i messaggi che inviano. Ad esempio, un'app Chat può aggiornare un messaggio dopo che un utente invia una finestra di dialogo o fa clic su un pulsante in una scheda di un messaggio.

Per aggiornare un messaggio dell'app di Chat in risposta a un'interazione, restituisci DataActions con un UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Le app di Chat possono anche aggiornare un messaggio inviato da un utente per allegare una scheda di anteprima del link utilizzando updateInlinePreviewAction. Per maggiori dettagli, consulta Visualizza l'anteprima dei link.

Rispondi in modo asincrono utilizzando l'API Google Chat

Anziché restituire un'azione in modo sincrono, le app di Chat potrebbero dover chiamare l'API Google Chat per rispondere a un'interazione o inviare messaggi proattivi. Ad esempio, le app di Chat devono chiamare l'API Google Chat per eseguire una delle seguenti operazioni:

  • Rispondere a un'interazione dopo 30 secondi (ad esempio dopo aver completato un'attività di lunga durata).
  • Inviare messaggi in base a una pianificazione o inviare notifiche sulle modifiche alle risorse esterne.
  • Eseguire attività al di fuori dello spazio in cui è avvenuta l'interazione.
  • Eseguire attività in Chat che non sono disponibili come azioni sincrone, ad esempio elencare gli spazi o aggiungere membri a uno spazio.
  • Eseguire attività per conto di un utente di Chat (che richiede l'autenticazione dell'utente).

Quando rispondi a un'interazione dopo 30 secondi, per evitare che l'utente visualizzi un messaggio di errore rivolto agli utenti che indica che l'app Chat non risponde, devi confermare la ricezione dell'oggetto evento entro 30 secondi restituendo una risposta vuota:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Per inviare un messaggio utilizzando l'API Chat, configura l'autenticazione e chiama il metodo spaces.messages.create. Per i passaggi, vedi Invia un messaggio. Per guide sull'utilizzo di altri metodi dell'API Chat, consulta la panoramica dell'API Chat.

App di Chat che non sono componenti aggiuntivi: ricevono e rispondono alle interazioni degli utenti

Le app di Chat che non sono componenti aggiuntivi di Google Workspace ricevono eventi di interazione dell'API Chat (Event) anziché oggetti evento dei componenti aggiuntivi di Google Workspace (EventObject), e rispondono restituendo una risorsa Message anziché un'azione.

Per eseguire l'upgrade di un'app di Chat che non è un componente aggiuntivo al framework dei componenti aggiuntivi di Google Workspace, consulta Converti un'app di Google Chat in un componente aggiuntivo di Google Workspace.

Tipi di eventi di interazione

Per ogni tipo di interazione dell'utente, Google Chat invia a un'app Chat che non è un componente aggiuntivo un oggetto Event il cui tipo è rappresentato dal campo eventType:

Interazione utente eventType Risposta tipica di un'app di Chat che non è un componente aggiuntivo
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 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 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 l'app.
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 eliminando un webhook) e libera lo spazio di archiviazione interno.
Un utente fa clic su un pulsante di una scheda di un messaggio, di una finestra di dialogo o della home page di un'app di Chat. CARD_CLICKED L'app di Chat elabora e archivia i dati inviati dall'utente o 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 dalla home page.
Un utente invia un modulo dalla home page dell'app Chat. SUBMIT_FORM L'app di Chat elabora e archivia i dati inviati dall'utente o restituisce un'altra scheda.
Un utente richiama un comando utilizzando un comando rapido. APP_COMMAND L'app di 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 e i payload JSON di esempio, consulta Tipi di eventi di interazione con l'app di Chat e la documentazione di riferimento di EventType.

Eventi di interazione dalle finestre di dialogo

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

  • Il campo isDialogEvent è impostato su true.
  • DialogEventType (REQUEST_DIALOG, SUBMIT_DIALOG o CANCEL_DIALOG) 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.

Configura un'app di Chat che non sia un componente aggiuntivo per ricevere eventi di interazione

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

    Vai alla pagina di configurazione dell'API Chat

  2. In Funzionalità interattive, deseleziona Crea questa app di Chat come componente aggiuntivo di Google Workspace e configura Funzionalità, un singolo endpoint Impostazioni di connessione (URL endpoint HTTP, Apps Script, nome argomento Cloud Pub/Sub o Dialogflow), Comandi, Prompt iniziali, Anteprime link e Visibilità.

  3. Fai clic su Salva.

Rispondi con un messaggio in un'app di Chat che non è un componente aggiuntivo

Per rispondere in modo sincrono in un'app di Chat che non è un componente aggiuntivo, restituisci direttamente un oggetto Message. L'esempio seguente risponde a un evento di interazione ADDED_TO_SPACE con un messaggio:

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