Apri finestre di dialogo interattive

Questa pagina descrive in che modo un'app Google Chat può aprire finestre di dialogo per visualizzare interfacce utente (UI) e rispondere agli utenti.

In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di Google Chat.

Le finestre di dialogo sono interfacce basate su schede con finestre che si aprono da uno spazio o un messaggio di Chat. La finestra di dialogo e i relativi contenuti sono visibili solo all'utente che l'ha aperta.

Le app di chat possono utilizzare le finestre di dialogo per richiedere e raccogliere informazioni dagli utenti di Chat, inclusi i moduli in più passaggi. Per maggiori dettagli sulla creazione di input dei moduli, consulta Raccogliere ed elaborare informazioni dagli utenti.

Prerequisiti

Node.js

Un componente aggiuntivo di Google Workspace che espande Google Chat. Per crearne uno, compila la guida rapida HTTP.

Apps Script

Un componente aggiuntivo di Google Workspace che espande Google Chat. Per crearne uno, compila la guida rapida di Apps Script.

Aprire una finestra di dialogo

Una finestra di dialogo con una serie di widget diversi.
Figura 1: un'app di Chat che apre una finestra di dialogo per raccogliere i dati di contatto.

Questa sezione spiega come rispondere e configurare un dialogo nel seguente modo:

  1. Attiva la richiesta di dialogo da un'interazione dell'utente.
  2. Gestisci la richiesta restituendo un valore e aprendo una finestra di dialogo.
  3. Dopo che gli utenti hanno inviato le informazioni, elabora l'invio chiudendo la finestra di dialogo o restituendo un'altra finestra di dialogo.

Attivare una richiesta di dialogo

Un'app di chat può aprire finestre di dialogo solo per rispondere a un'interazione dell'utente, ad esempio un comando con barra o un clic su un pulsante da un messaggio in una scheda.

Per rispondere agli utenti con una finestra di dialogo, un'app di chat deve creare un'interazione che attivi la richiesta di dialogo, ad esempio:

  • Rispondere a un comando slash. Per attivare la richiesta da un comando con barra, devi selezionare la casella di controllo Apre una finestra di dialogo durante la configurazione del comando.
  • Rispondi a un clic sul pulsante in un messaggio, all'interno di una scheda o nella parte inferiore del messaggio. Per attivare la richiesta da un pulsante in un messaggio, configura l'azione onClick del pulsante impostando interaction su OPEN_DIALOG.
Pulsante che attiva una finestra di dialogo
Figura 2: un'app di Chat invia un messaggio che chiede agli utenti di utilizzare il comando barra /addContact.
Il messaggio include anche un pulsante su cui gli utenti possono fare clic per attivare il comando.

Il seguente JSON mostra come attivare una richiesta di dialogo da un pulsante in un messaggio della scheda. Per aprire la finestra di dialogo, imposta il campo onClick.action.interaction del pulsante su OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

dove BUTTON_TEXT è il testo visualizzato nel pulsante e ACTION_FUNCTION è la funzione che viene eseguita per aprire la dialogo iniziale.

Apri la finestra di dialogo iniziale

Quando un utente attiva una richiesta di dialogo, l'app Chat riceve un oggetto evento con un payload che specifica che un oggetto dialogEventType è REQUEST_DIALOG.

Per aprire una finestra di dialogo, l'app Chat può rispondere alla richiesta restituendo un oggetto RenderActions con il comando di navigazione pushCard per visualizzare una scheda. La scheda deve contenere qualsiasi elemento dell'interfaccia utente (UI), inclusi uno o più sections[] di widget. Per raccogliere informazioni dagli utenti, puoi specificare i widget di input del modulo e un widget di pulsante. Per scoprire di più sulla progettazione degli input dei moduli, consulta Raccogliere ed elaborare informazioni dagli utenti.

Il seguente JSON mostra come un'app di Chat restituisce una risposta che apre una finestra di dialogo:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

Dove BUTTON_TEXT è il testo visualizzato nel pulsante (ad es. Next o Submit), WIDGETS rappresenta uno o più widget di input del modulo, e ACTION_FUNCTION è la funzione di callback dell'azione che viene eseguita quando gli utenti fanno clic su un pulsante.

Gestire l'invio della finestra di dialogo

Quando gli utenti fanno clic su un pulsante che invia una finestra di dialogo, la tua app di chat riceve un oggetto evento con un oggetto ButtonClickedPayload. Nel payload, dialogEventType è impostato su SUBMIT_DIALOG.

L'app Chat deve gestire l'oggetto evento eseguendo una delle seguenti operazioni:

(Facoltativo) Restituire un'altra finestra di dialogo

Dopo che gli utenti hanno inviato la finestra di dialogo iniziale, le app di chat possono mostrare una o più finestre di dialogo aggiuntive per aiutare gli utenti a rivedere le informazioni prima di inviarle, completare moduli in più passaggi o compilare i contenuti dei moduli in modo dinamico.

Per elaborare i dati inseriti dagli utenti, l'app Chat gestisce i dati nell'oggetto commonEventObject.formInputs dell'evento. Per scoprire di più sul recupero dei valori dai widget di input, consulta Raccogliere ed elaborare le informazioni degli utenti.

Per tenere traccia dei dati inseriti dagli utenti dalla finestra di dialogo iniziale, devi aggiungere parametri al pulsante che apre la finestra di dialogo successiva. Per maggiori dettagli, consulta Trasferire i dati su un'altra scheda.

In questo esempio, un'app di chat apre una finestra di dialogo iniziale che porta a una seconda finestra di dialogo per la conferma prima dell'invio:

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

Questo esempio invia un messaggio della scheda restituendo JSON della scheda. Puoi anche utilizzare il servizio di schede di Apps Script. 

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

dove WIDGETS rappresenta qualsiasi altro widget di input del modulo.

Chiudi la finestra di dialogo

Quando gli utenti fanno clic su un pulsante di invio in una finestra di dialogo, la tua app Chat esegue l'azione associata e fornisce all'oggetto evento buttonClickedPayload impostato su quanto segue:

  • isDialogEvent è true.
  • dialogEventType è SUBMIT_DIALOG.

L'app Chat dovrebbe restituire un oggetto RenderActions con EndNavigation impostato su CLOSE_DIALOG.

(Facoltativo) Mostra una notifica

Quando chiudi la finestra di dialogo, puoi anche visualizzare una notifica di testo.

Per visualizzare una notifica, restituisci l'oggetto RenderActions con il campo notification impostato.

L'esempio seguente verifica che i parametri siano validi e chiude la finestra di dialogo con una notifica di testo in base al risultato:

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Per informazioni dettagliate sul passaggio dei parametri tra le finestre di dialogo, consulta Trasferire i dati a un'altra scheda.

(Facoltativo) Invia un messaggio di conferma

Quando chiudi la finestra di dialogo, puoi anche inviare un nuovo messaggio o aggiornarne uno esistente.

Per inviare un nuovo messaggio, restituisci un oggetto DataActions con il campo CreateMessageAction impostato con il nuovo messaggio. Ad esempio, per chiudere la finestra di dialogo e inviare un messaggio, restituisci quanto segue:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Per aggiornare un messaggio dopo che l'utente ha inviato una finestra di dialogo, restituisci un oggetto DataActions che contenga una delle seguenti azioni:

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.