Creare finestre di dialogo interattive

Questa pagina descrive come un'app Google Chat può aprire finestre di dialogo per visualizzare interfacce utente e rispondere agli utenti.

I dialoghi sono interfacce basate su schede e finestre che si aprono da un messaggio o uno spazio 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 del modulo, vedi Raccogliere ed elaborare le informazioni degli utenti.

Prerequisiti

Aprire una finestra di dialogo

Questa sezione spiega come rispondere e impostare una finestra di dialogo procedendo nel seguente modo:

1. Attiva la richiesta di dialogo da un'interazione dell'utente.
2. Gestisci la richiesta restituendo 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 o un clic su un pulsante da un messaggio in una scheda.

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

• Rispondere a un comando. Per attivare la richiesta da un comando, devi selezionare la casella di controllo Apre una finestra di dialogo quando configuri il comando.
• Rispondere 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.

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 eseguita per aprire la finestra di dialogo iniziale.

Apri la finestra di dialogo iniziale

Quando un utente attiva una richiesta di dialogo, la tua app Chat riceve un oggetto evento con un payload che specifica un oggetto dialogEventType come REQUEST_DIALOG.

Per aprire una finestra di dialogo, l'app Chat può rispondere alla richiesta restituendo un oggetto RenderActions con la navigazione pushCard per visualizzare una scheda. La scheda deve contenere elementi dell'interfaccia utente, inclusi uno o più sections[] widget. Per raccogliere informazioni dagli utenti, puoi specificare widget di input del modulo e un widget pulsante. Per saperne di più sulla progettazione degli input dei moduli, consulta Raccogliere ed elaborare le informazioni degli 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 esempio 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 Chat riceve un oggetto evento con un oggetto ButtonClickedPayload. Nel payload, dialogEventType è impostato su SUBMIT_DIALOG. Per capire come raccogliere ed elaborare le informazioni nella finestra di dialogo, consulta Raccogliere ed elaborare le informazioni degli utenti di Google Chat.

La tua app di chat deve rispondere all'oggetto evento eseguendo una delle seguenti operazioni:

• Restituisci un altro dialogo per compilare un'altra scheda o un altro modulo.
• Chiudi la finestra di dialogo dopo aver convalidato i dati inviati dall'utente e, se vuoi, invia un messaggio di conferma.

(Facoltativo) Restituisci un altro dialogo

Dopo che gli utenti inviano la finestra di dialogo iniziale, le app di chat possono restituire una o più finestre di dialogo aggiuntive per aiutare gli utenti a rivedere le informazioni prima dell'invio, completare moduli in più passaggi o compilare dinamicamente i contenuti dei moduli.

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, vedi Raccogliere ed elaborare le informazioni degli utenti.

Per tenere traccia di tutti i dati inseriti dagli utenti nella finestra di dialogo iniziale, devi aggiungere parametri al pulsante che apre la finestra di dialogo successiva. Per maggiori dettagli, vedi Trasferire dati a un'altra carta.

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:

/**
 * 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
        }]
      }}
    }]}}]
  }]}}]}};
}

/**
 * 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, l'app di chat esegue l'azione associata e fornisce l'oggetto evento con buttonClickedPayload impostato su:

• isDialogEvent è true.
• dialogEventType è SUBMIT_DIALOG.

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

(Facoltativo) Visualizzare una notifica temporanea

Quando chiudi la finestra di dialogo, puoi anche visualizzare una notifica di testo temporanea per l'utente che interagisce con l'app.

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

Il seguente esempio verifica che i parametri siano validi e chiude la finestra di dialogo con una notifica di testo a seconda del risultato:

/**
 * 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!" }
  }};
}

/**
 * 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 di parametri tra le finestre di dialogo, vedi Trasferire dati a un'altra scheda.

(Facoltativo) Invia un messaggio di chat di conferma

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

Per inviare un nuovo messaggio, restituisci un DataActions oggetto 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 contiene una delle seguenti azioni:

• UpdateMessageAction: Aggiorna un messaggio inviato dall'app Chat, ad esempio il messaggio da cui l'utente ha richiesto la finestra di dialogo.
• UpdateInlinePreviewAction: aggiorna la carta da un' anteprima del link.

Risoluzione dei problemi

Quando un'app Google Chat o una scheda 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 o la scheda Chat produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Anche se nell'interfaccia utente di Chat potrebbe non essere visualizzato un messaggio di errore, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app di chat è attivata. Per assistenza nella visualizzazione, nel debug e nella correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.