Apri finestre di dialogo interattive

In questa pagina viene descritto come l'app Chat può aprire le finestre di dialogo per rispondere agli utenti.

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

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

Prerequisiti

Node.js

  • Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un un'app di chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Python

  • Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un un'app di chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Apps Script

  • Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un app di Chat interattiva in Apps Script, completa questa guida rapida.

Apri una finestra di dialogo

Una finestra di dialogo con una serie di widget diversi.
Figura 1: una finestra di dialogo che raccoglie le informazioni di contatto.

In questa sezione viene spiegato come rispondere e impostare una finestra di dialogo:

  1. Attiva la richiesta di finestra di dialogo da un'interazione utente.
  2. Per gestire la richiesta, restituisci e apri una finestra di dialogo.
  3. Dopo che gli utenti avranno inviato le informazioni, elaborale chiudendo finestra di dialogo o la restituzione di un'altra finestra di dialogo.

Attiva una richiesta di finestra di dialogo

Un'app di Chat può aprire le finestre di dialogo solo per rispondere a un utente un'interazione, come un comando slash 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 crea un'interazione che attivi la richiesta di dialogo, ad esempio:

  • Rispondi a un comando slash. Per attivare la richiesta da un comando slash, devi selezionare la casella di controllo Apre una finestra di dialogo durante la configurazione del comando.
  • Rispondere a un clic su un pulsante in una messaggio, all'interno di una scheda o in fondo al messaggio. Per attivare il parametro richiesta da un pulsante in un messaggio, configuri onClick del pulsante impostando interaction su OPEN_DIALOG.
  • Rispondere a un clic su un pulsante nella home page di un'app di Chat. Per ulteriori informazioni sull'apertura di finestre di dialogo dalle home page, consulta: Crea una home page per l'app Google Chat.
di Gemini Advanced.
Pulsante che attiva una finestra di dialogo
Figura 2: un'app di Chat invia un messaggio che richiede agli utenti di utilizzare il comando /addContact slash.
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, utilizza il button.interaction è impostato su OPEN_DIALOG:

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

Dove BUTTON_TEXT è il testo visualizzato nel pulsante e FUNCTION_NAME è la funzione che esegue per aprire l'iniziale .

Apri la finestra di dialogo iniziale

Quando un utente attiva una richiesta di dialogo, la tua app Chat riceve un evento di interazione, rappresentato come event digita API Chat. Se l'interazione attiva una richiesta di dialogo, l'evento Il campo dialogEventType è impostato su REQUEST_DIALOG.

Per aprire una finestra di dialogo, l'app Chat può rispondere al restituendo una richiesta actionResponse con type impostato su DIALOG e Message . Per specificare i contenuti della finestra di dialogo, includi quanto segue oggetti:

  • Un actionResponse con il valore type impostato su DIALOG.
  • Un dialogAction . Il campo body contiene gli elementi dell'interfaccia utente (UI) per visualizzare nella scheda, inclusi uno o più sections di widget. Per raccogliere informazioni dagli utenti, puoi specificare widget di input del modulo e un widget del pulsante. Per scoprire di più sulla progettazione degli input di modulo, consulta Raccogliere ed elaborare informazioni dagli utenti.

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

{ "actionResponse": {
  "type": "DIALOG",
  "dialogAction": { "dialog": { "body": { "sections": [{
    "widgets": [{
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "BUTTON_TEXT",
        "onClick": {
          "action": {"function": "FUNCTION_NAME"}
        }
      }]}}
    }]
  }]}}}
}}

Dove BUTTON_TEXT è il testo visualizzato nel pulsante (ad esempio Next o Submit), WIDGETS rappresenta uno o più widget di input del modulo e FUNCTION_NAME è la funzione 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, L'app di chat riceve un'interazione con CARD_CLICKED evento in cui dialogEventType è SUBMIT_DIALOG.

L'app Chat deve gestire l'evento di interazione nel effettuando 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 restituire una o più finestre di dialogo aggiuntive per aiutare gli utenti a rivedere le informazioni prima l'invio, la compilazione di moduli con più passaggi o la compilazione dinamica dei contenuti.

Per caricare i dati inseriti dagli utenti dalla finestra di dialogo iniziale, devi aggiungere parametri al pulsante che apre la finestra di dialogo successiva o trasmettere l'originale CARD_CLICKED evento di interazione dalla finestra di dialogo iniziale. Per maggiori dettagli, vedi Trasferire i dati su un'altra carta.

In questo esempio, un'app di Chat apre una finestra di dialogo restituisce una seconda finestra di dialogo prima dell'invio. Per caricare i dati di input, L'app di Chat supera l'evento di interazione CARD_CLICKED come parametro per la funzione che apre la finestra di dialogo successiva:

Node.js

// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {

  // Open the first dialog.
  if (event.common.invokedFunction === "openDialog") {
    openDialog(event);
  }

  // Open the second dialog.
  if (event.common.invokedFunction === "openNextDialog") {
    openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }});
};

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }});
}

Python

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat that includes the /createContact
     slash command by opening a dialog.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """

  if req.method == 'GET':
    return 'Sorry, this function must be called from a Google Chat.'

  request = req.get_json(silent=True)

  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_dialog':
        return open_dialog(request)

      elif invoked_function == 'open_next_dialog':
        return open_dialog(request)

def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a dialog in Google Chat.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "open_next_dialog"
        }}
      }]}}
    ]}]}}}
  }}

def open_next_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a second dialog that lets users add more contact details.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submit_dialog"
          }}
        }]}
      }
    ]}]}}}
  }}

Apps Script

Questo esempio invia un messaggio di una scheda restituendo JSON card. Puoi utilizzare anche Servizio di schede Apps Script. 

/**
* Responds to a CARD_CLICKED event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onCardClick(event) {

  // When a user clicks a card, the Chat app checks to see which function to run.
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  }

  if (event.common.invokedFunction === "openNextDialog") {
    return openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }};
}

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }};
}

Dove WIDGETS rappresenta uno o più widget di input modulo.

Chiudi la finestra di dialogo

Quando gli utenti fanno clic su un pulsante in una finestra di dialogo, L'app Chat riceve un evento di interazione con le seguenti informazioni:

Le seguenti sezioni spiegano come convalidare i dati inseriti e chiudi la finestra di dialogo.

Convalida i dati di input dell'utente e chiudi la finestra di dialogo

Per elaborare i dati inseriti dagli utenti, l'app Chat utilizza event.common.formInputs . Per ulteriori informazioni sul recupero dei valori dai widget di input, consulta Raccogliere ed elaborare informazioni dagli utenti.

Se l'utente omette un campo obbligatorio o inserisce valori errati, la L'app di chat può rispondere con un errore restituendo un ActionResponse con "actionStatus": "ERROR MESSAGE".

L'esempio seguente verifica che un utente abbia inserito un valore per un widget che accetta stringhe (stringInputs), come un widget textInput. Se non è presente, L'app Chat restituisce un errore. Se presente, l'app Chat conferma l'invio della finestra di dialogo e chiude la finestra di dialogo:

Node.js

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {Object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] === "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    });

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'ERROR_MESSAGE'
                }
              }
            }

Apps Script

Questo esempio invia un messaggio di una scheda restituendo JSON card. Puoi utilizzare anche Servizio di schede Apps Script. 

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] === "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    };

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

In questo esempio, WIDGET_NAME rappresenta il campo name del widget (come contactName) e ERROR_MESSAGE rappresenta il contenuti del messaggio di errore (ad esempio Don't forget to name your contact). Per informazioni dettagliate sull'elaborazione dei dati di input dai widget, vedi Ricevi dati dai widget interattivi.

(Facoltativo) Inviare un messaggio di conferma

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

Per inviare un nuovo messaggio, restituisci ActionResponse con type impostato su NEW_MESSAGE. Ad esempio, per chiudere la finestra di dialogo e invia un SMS, restituisci quanto segue:

  {
    "actionResponse": {
      "type": "NEW_MESSAGE",
    },
    "text": "Your information has been submitted."
  }

Per aggiornare un messaggio, restituisci un oggetto actionResponse che contiene il ha aggiornato il messaggio e imposta type su uno dei seguenti valori:

Risoluzione dei problemi

Quando un'app Google Chat o card restituisce un errore, L'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte, l'UI di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda restituisce un risultato inaspettato; Ad esempio, il messaggio di una scheda potrebbe non vengono visualizzate.

Anche se un messaggio di errore potrebbe non essere visualizzato nella UI di Chat, messaggi di errore descrittivi e dati di log che ti aiuteranno a correggere gli errori quando il logging degli errori per le app di chat è attivo. Per assistenza con la visualizzazione, il debug e la correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.