Interaktive Dialogfelder öffnen

Auf dieser Seite wird beschrieben, wie mit der Google Chat App Dialogfelder geöffnet werden können um den Nutzern zu antworten.

Dialoge sind kartenbasierte Oberflächen im Fenstermodus. die in einem Chatbereich oder in einer Nachricht geöffnet werden. Das Dialogfeld und seine Inhalte sind nur für den Nutzer sichtbar, der sie geöffnet hat.

Chat-Apps können über Dialogfelder Informationen von folgenden Personen anfordern und erheben: Chatnutzer, einschließlich mehrstufiger Formulare Weitere Informationen Informationen zum Erstellen von Formulareingaben finden Sie unter Nutzerinformationen erfassen und verarbeiten.

<ph type="x-smartling-placeholder">

Vorbereitung

Node.js

  • Eine Google Chat App mit aktivierten interaktiven Funktionen. So erstellen Sie ein Chat-App mit einem HTTP-Dienst verwenden können, führen Sie diese Kurzanleitung aus.

Python

  • Eine Google Chat App mit aktivierten interaktiven Funktionen. So erstellen Sie ein Chat-App mit einem HTTP-Dienst verwenden können, führen Sie diese Kurzanleitung aus.

Apps Script

  • Eine Google Chat App mit aktivierten interaktiven Funktionen. So erstellen Sie ein Chat-App in Apps Script verwenden, gehen Sie wie in dieser Kurzanleitung beschrieben vor.

Dialogfeld öffnen

<ph type="x-smartling-placeholder">
</ph> Ein Dialogfeld mit einer Vielzahl verschiedener Widgets.
Abbildung 1: Dialogfeld zum Erfassen von Kontaktdaten

In diesem Abschnitt wird erläutert, wie Sie auf die Anfragen reagieren und einen Dialog einrichten:

  1. Dialoganfrage über eine Nutzerinteraktion auslösen
  2. Verarbeiten Sie die Anfrage, indem Sie ein Dialogfeld zurückgeben und öffnen.
  3. Nachdem die Nutzer die Informationen gesendet haben, schließen Sie die oder ein anderes Dialogfeld zurückgegeben wird.

Dialoganfrage auslösen

Eine Chat-App kann nur Dialogfelder öffnen, um einem Nutzer zu antworten Interaktion, z. B. ein Slash-Befehl oder das Klicken auf eine Schaltfläche aus einer Nachricht in einer Karte.

Damit Nutzer mit einem Dialogfeld antworten können, muss eine Chat-App Erstellen Sie eine Interaktion, die die Dialoganfrage auslöst, z. B.:

  • Auf einen Slash-Befehl antworten. Um die Anfrage über einen Slash-Befehl auszulösen, Sie müssen das Kästchen Öffnet ein Dialogfeld anklicken, wenn Sie den Befehl konfigurieren.
  • Auf Schaltflächenklicks in einem message, entweder als Teil einer Karte oder unten in der Nachricht. Um das Ereignis über eine Schaltfläche in einer Nachricht anfordern möchten, konfigurieren Sie onClick der Schaltfläche Aktion ausführen, indem Sie interaction auf OPEN_DIALOG setzen.
  • Auf einen Klick auf eine Schaltfläche auf der Startseite einer Chat-App reagieren: Informationen zum Öffnen von Dialogfeldern auf der Startseite finden Sie unter Startseite für die Google Chat App erstellen
<ph type="x-smartling-placeholder">
</ph> Schaltfläche zum Auslösen eines Dialogfelds
Abbildung 2: Eine Chat-App sendet eine Nachricht, in der die Nutzer aufgefordert werden, den Slash-Befehl /addContact zu verwenden.
Die Meldung enthält auch eine Schaltfläche, auf die Nutzer klicken können, um den Befehl auszulösen.

Die folgende JSON zeigt, wie eine Dialoganfrage über eine Schaltfläche in einem Kartennachricht. Zum Öffnen des Dialogfelds button.interaction auf OPEN_DIALOG festgelegt ist:

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

Dabei ist BUTTON_TEXT der Text, der in der Schaltfläche angezeigt wird. FUNCTION_NAME ist die Funktion, die ausgeführt wird, Dialogfeld.

Erstes Dialogfeld öffnen

Wenn ein Nutzer eine Dialoganfrage auslöst, wird Ihre Chat-App ein Interaktionsereignis empfängt, das als event geben Sie Folgendes ein: Chat API Löst die Interaktion eine Dialoganfrage aus, Das Feld „dialogEventType“ ist auf REQUEST_DIALOG gesetzt.

Zum Öffnen eines Dialogfelds kann Ihre Chat-App auf die durch Zurückgeben eines actionResponse , wobei type auf DIALOG gesetzt ist und Message -Objekt enthält. Fügen Sie Folgendes hinzu, um den Inhalt des Dialogfelds anzugeben: Objekte:

  • Ein actionResponse -Objekt, wobei type auf DIALOG gesetzt ist.
  • Ein dialogAction-Objekt. Das Feld body enthält die UI-Elemente, die auf der Karte angezeigt werden, einschließlich einer oder mehrerer sections von Widgets. Um Informationen von Nutzern zu erfassen, können Sie Formulareingabe-Widgets und ein Schaltflächen-Widget. Weitere Informationen zum Entwerfen von Formulareingaben finden Sie unter Erheben und verarbeiten Sie Daten von Nutzern.

Der folgende JSON-Code zeigt, wie eine Chat-App Daten zurückgibt Antwort, die ein Dialogfeld öffnet:

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

Dabei ist BUTTON_TEXT der in der Schaltfläche angezeigte Text (z. B. Next oder Submit), WIDGETS steht für eine oder mehrere Widgets für die Formulareingabe und FUNCTION_NAME ist die Funktion, die ausgeführt wird, wenn Nutzer auf eine Schaltfläche klicken.

Übermitteln des Dialogfelds verarbeiten

Wenn Nutzer auf eine Schaltfläche klicken, mit der ein Dialogfeld gesendet wird, Chat-App empfängt eine CARD_CLICKED-Interaktion Ereignis, bei dem das dialogEventType-Element ist SUBMIT_DIALOG.

Ihre Chat-App muss das Interaktionsereignis so verarbeiten, einen der folgenden Schritte ausführen:

Optional: Weiteres Dialogfeld zurückgeben

Nachdem Nutzer das erste Dialogfeld gesendet haben, können Chat-Apps ein oder mehrere zusätzliche Dialogfelder zurückgeben, damit Nutzer sich mehrstufige Formulare ausfüllen, mehrstufige Formulare ausfüllen oder Formularinhalte dynamisch ausfüllen.

Wenn Sie Daten laden möchten, die Nutzer im ersten Dialogfeld eingegeben haben, müssen Sie Parameter für die Schaltfläche zum Öffnen des nächsten Dialogfelds oder übergeben Sie das ursprüngliche CARD_CLICKED-Interaktionsereignis aus dem ersten Dialogfeld. Weitere Informationen finden Sie unter Daten auf eine andere Karte übertragen

In diesem Beispiel öffnet eine Chat-App ein Dialogfeld, wird vor dem Senden ein zweites Dialogfeld angezeigt. Zum Laden der Eingabedaten enthält der Die Chat-App besteht das Interaktionsereignis „CARD_CLICKED“ als Parameter für die Funktion, die das nächste Dialogfeld öffnet:

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

In diesem Beispiel wird eine Kartennachricht gesendet, JSON-Karte Sie können auch die Apps Script-Kartendienst 

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

Dabei steht WIDGETS für einen oder mehrere Widgets für die Formulareingabe.

Dialogfeld schließen

Wenn Nutzer in einem Dialogfeld auf eine Schaltfläche klicken, Die Chat-App empfängt ein Interaktionsereignis mit dem folgende Informationen:

In den folgenden Abschnitten wird erläutert, wie Sie die von Nutzenden eingegebenen Daten validieren und Schließen Sie das Dialogfeld.

Nutzereingabedaten validieren und Dialogfeld schließen

Um die von Nutzern eingegebenen Daten zu verarbeiten, verwendet die event.common.formInputs -Objekt enthält. Weitere Informationen zum Abrufen von Werten aus Eingabe-Widgets finden Sie unter Erheben und verarbeiten Sie Daten von Nutzern.

Wenn der Nutzer ein Pflichtfeld auslässt oder falsche Werte eingibt, Die Chat-App kann mit einem Fehler antworten, indem sie Folgendes zurückgibt: ActionResponse mit "actionStatus": "ERROR MESSAGE".

Das folgende Beispiel prüft, ob ein Nutzer einen Wert für ein Widget eingibt, der akzeptiert Strings (stringInputs), z. B. ein textInput-Widget. Fehlt diese Angabe, wird der Die Chat-App gibt einen Fehler zurück. Falls vorhanden, bestätigt die Chat-App das Senden des Dialogfelds Schließt das Dialogfeld:

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

In diesem Beispiel wird eine Kartennachricht gesendet, JSON-Karte Sie können auch die Apps Script-Kartendienst 

/**
* 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 diesem Beispiel steht WIDGET_NAME für das Feld name der (z. B. contactName) und das ERROR_MESSAGE steht für die Inhalt der Fehlermeldung (z. B. Don't forget to name your contact) Weitere Informationen zur Verarbeitung von Eingabedaten aus Widgets finden Sie unter Daten von interaktiven Widgets empfangen

Optional: Bestätigungsnachricht senden

Wenn Sie das Dialogfeld schließen, können Sie auch eine neue Nachricht senden oder eine bereits vorhanden ist.

Um eine neue Nachricht zu senden, geben Sie eine ActionResponse -Objekt mit type auf NEW_MESSAGE gesetzt. Um das Dialogfeld zu schließen, und senden Sie eine SMS, geben Sie Folgendes zurück:

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

Um eine Nachricht zu aktualisieren, geben Sie ein actionResponse-Objekt zurück, das die aktualisierte Nachricht und legt für type einen der folgenden Werte fest:

Fehlerbehebung

Wenn eine Google Chat App oder card gibt einen Fehler zurück. Der Parameter In der Chatoberfläche wird die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal kann die Chat-UI Es wird zwar keine Fehlermeldung angezeigt, aber die Chat-App oder die Karte zu einem unerwarteten Ergebnis führt. z. B. wird eine Kartennachricht angezeigt werden.

Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, beschreibende Fehlermeldungen und Protokolldaten stehen zur Fehlerbehebung zur Verfügung. wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Hilfe bei der Anzeige: Debugging und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben