Interaktive Dialogfelder öffnen

Auf dieser Seite wird beschrieben, wie eine Google Chat-App Dialoge öffnen kann, um Benutzeroberflächen (User Interfaces, UIs) anzuzeigen und auf Nutzer zu reagieren.

In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.

Dialogfelder sind kartenbasierte Benutzeroberflächen, die über einen Chatbereich oder eine Nachricht geöffnet werden. Das Dialogfeld und sein Inhalt sind nur für den Nutzer sichtbar, der es geöffnet hat.

Chat-Apps können Dialogfelder verwenden, um Informationen von Google Chat-Nutzern anzufordern und zu erheben, einschließlich mehrstufiger Formulare. Weitere Informationen zum Erstellen von Formularinputs finden Sie unter Informationen von Nutzern erheben und verarbeiten.

Vorbereitung

Dialogfeld öffnen

In diesem Abschnitt wird beschrieben, wie Sie antworten und einen Dialog einrichten:

1. Auslösen der Dialoganfrage durch eine Nutzerinteraktion
2. Bearbeiten Sie die Anfrage, indem Sie ein Dialogfeld zurückgeben und öffnen.
3. Nachdem Nutzer Informationen gesendet haben, verarbeiten Sie die Einreichung, indem Sie entweder das Dialogfeld schließen oder ein anderes Dialogfeld zurückgeben.

Dialoganfrage auslösen

Eine Chat-App kann nur Dialogfelder öffnen, um auf eine Nutzerinteraktion zu reagieren, z. B. einen Schrägstrichbefehl oder einen Klick auf eine Schaltfläche in einer Nachricht auf einer Karte.

Damit eine Chat-App Nutzern mit einem Dialog antworten kann, muss sie eine Interaktion erstellen, die die Dialoganfrage auslöst. Beispiele:

• Auf einen Slash-Befehl reagieren Wenn du die Anfrage über einen Befehl mit einem Schrägstrich auslösen möchtest, musst du beim Konfigurieren des Befehls das Kästchen Öffnet ein Dialogfeld aktivieren.
• Reagieren Sie auf einen Schaltflächenklick in einer Nachricht, entweder als Teil einer Karte oder unten in der Nachricht. Wenn Sie die Anfrage über eine Schaltfläche in einer Nachricht auslösen möchten, konfigurieren Sie die onClick-Aktion der Schaltfläche, indem Sie ihre interaction auf OPEN_DIALOG festlegen.

In der folgenden JSON-Datei wird gezeigt, wie eine Dialoganfrage über eine Schaltfläche in einer Kartennachricht ausgelöst wird. Um das Dialogfeld zu öffnen, legen Sie das Feld onClick.action.interaction der Schaltfläche auf OPEN_DIALOG fest:

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

Dabei ist BUTTON_TEXT der Text, der in der Schaltfläche angezeigt wird, und ACTION_FUNCTION die Funktion, die ausgeführt wird, um den ersten Dialogfeld zu öffnen.

Erstes Dialogfeld öffnen

Wenn ein Nutzer eine Dialoganfrage auslöst, empfängt Ihre Chat-App ein Ereignisobjekt mit einer Nutzlast, in der ein dialogEventType-Objekt als REQUEST_DIALOG angegeben ist.

Wenn Sie ein Dialogfeld öffnen möchten, kann Ihre Chat-App auf die Anfrage antworten, indem sie ein RenderActions-Objekt mit der Navigation pushCard zurückgibt, um eine Karte anzuzeigen. Die Karte sollte alle Elemente der Benutzeroberfläche enthalten, einschließlich eines oder mehrerer sections[]-Widgets. Wenn Sie Informationen von Nutzern erfassen möchten, können Sie Formulareingabe-Widgets und ein Schaltflächen-Widget angeben. Weitere Informationen zum Entwerfen von Formularinputs finden Sie unter Informationen von Nutzern erheben und verarbeiten.

Im folgenden JSON-Code wird gezeigt, wie eine Chat-App eine Antwort zurückgibt, die ein Dialogfeld öffnet:

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

Dabei ist BUTTON_TEXT der Text, der in der Schaltfläche angezeigt wird (z. B. Next oder Submit), WIDGETS steht für ein oder mehrere Formular-Eingabe-Widgets und ACTION_FUNCTION ist die Callback-Funktion der Aktion, die ausgeführt wird, wenn Nutzer auf eine Schaltfläche klicken.

Dialogfeld einreichen

Wenn Nutzer auf eine Schaltfläche klicken, über die ein Dialogfeld gesendet wird, erhält Ihre Chat-App ein Ereignisobjekt mit einem ButtonClickedPayload-Objekt. In der Nutzlast ist dialogEventType auf SUBMIT_DIALOG festgelegt.

Ihre Chat-App muss das Ereignisobjekt verarbeiten. Dazu haben Sie folgende Möglichkeiten:

• Ein weiteres Dialogfeld zurückgeben, um eine weitere Karte oder ein weiteres Formular auszufüllen.
• Schließen Sie das Dialogfeld, nachdem Sie die von den Nutzern eingereichten Daten überprüft haben, und senden Sie optional eine Bestätigungsnachricht.

Optional: Ein anderes Dialogfeld zurückgeben

Nachdem Nutzer den ersten Dialog gesendet haben, können Chat-Apps einen oder mehrere zusätzliche Dialoge zurückgeben, damit Nutzer Informationen vor dem Senden prüfen, mehrstufige Formulare ausfüllen oder Formularinhalte dynamisch ausfüllen können.

Um die von Nutzern eingegebenen Daten zu verarbeiten, verarbeitet die Chat-App die Daten im commonEventObject.formInputs-Objekt des Ereignisses. Weitere Informationen zum Abrufen von Werten aus Eingabe-Widgets finden Sie unter Informationen von Nutzern erheben und verarbeiten.

Wenn Sie alle Daten im Blick behalten möchten, die Nutzer im ersten Dialogfeld eingeben, müssen Sie der Schaltfläche, über die das nächste Dialogfeld geöffnet wird, Parameter hinzufügen. Weitere Informationen finden Sie unter Daten auf eine andere Karte übertragen.

In diesem Beispiel öffnet eine Chat-App ein erstes Dialogfeld, das zu einem zweiten Dialogfeld zur Bestätigung führt, bevor die Eingabe gesendet wird:

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

Dabei steht WIDGETS für alle anderen Formulareingaben-Widgets.

Dialogfeld schließen

Wenn Nutzer in einem Dialogfeld auf eine Schaltfläche zum Senden klicken, führt Ihre Chat-App die zugehörige Aktion aus und gibt für das Ereignisobjekt buttonClickedPayload mit folgendem Wert an:

• isDialogEvent liegt bei true.
• dialogEventType liegt bei SUBMIT_DIALOG.

Die Chat-App sollte ein RenderActions-Objekt zurückgeben, bei dem EndNavigation auf CLOSE_DIALOG festgelegt ist.

Optional: Benachrichtigung anzeigen

Wenn Sie das Dialogfeld schließen, können Sie auch eine Textbenachrichtigung anzeigen lassen.

Wenn du eine Benachrichtigung anzeigen möchtest, gib das RenderActions-Objekt mit dem festgelegten Feld notification zurück.

Im folgenden Beispiel wird geprüft, ob die Parameter gültig sind, und das Dialogfeld wird je nach Ergebnis mit einer Textbenachrichtigung geschlossen:

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

Weitere Informationen zum Übergeben von Parametern zwischen Dialogfeldern finden Sie unter Daten auf eine andere Karte übertragen.

Optional: Bestätigungsnachricht senden

Wenn Sie das Dialogfeld schließen, können Sie auch eine neue Nachricht senden oder eine vorhandene aktualisieren.

Wenn Sie eine neue Nachricht senden möchten, geben Sie ein DataActions-Objekt zurück, das das Feld CreateMessageAction mit der neuen Nachricht enthält. Wenn Sie beispielsweise das Dialogfeld schließen und eine SMS senden möchten, geben Sie Folgendes zurück:

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

Wenn Sie eine Nachricht aktualisieren möchten, nachdem der Nutzer einen Dialog gesendet hat, geben Sie ein DataActions-Objekt zurück, das eine der folgenden Aktionen enthält:

• UpdateMessageAction: Aktualisiert eine Nachricht, die von der Chat-App gesendet wurde, z. B. die Nachricht, über die der Nutzer den Dialog angefordert hat.
• UpdateInlinePreviewAction: Aktualisiert die Karte anhand einer Linkvorschau.

Fehlerbehebung

Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird in der Chat-Benutzeroberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage konnte nicht verarbeitet werden“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte führt zu einem unerwarteten Ergebnis. Beispielsweise wird eine Kartennachricht möglicherweise nicht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, die Ihnen bei der Fehlerbehebung helfen, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Ansehen, Entfernen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.