Von Nutzern eingegebene Prozessinformationen

In diesem Leitfaden wird beschrieben, wie die von Nutzern in Kartennachrichten und Dialogfelder eingegebenen Informationen abgerufen und gelesen werden. Nutzer können Daten eingeben, die Chat-Apps empfangen, lesen und beantworten. Zu den Widgets, in die Nutzer Informationen eingeben können, gehören:

  • TextInput für die Eingabe im freien Format, die auch Vorschläge unterstützt
  • SelectionInput für Listenelemente und Menüs wie Kästchen, Optionsfelder und Drop-down-Menüs.
  • DateTimePicker für Datums- und Uhrzeiteinträge


Mit dem Card Builder kannst du Karten entwerfen und sie dir als Vorschau ansehen.

Den Card Builder öffnen

Durch den Empfang von Dateneingaben von Nutzern können Chat-Apps beispielsweise Folgendes tun:

  • Supportanfragen für den Kundenservice aktualisieren.
  • Erstellen Sie Arbeitsaufträge.
  • Mit Webdiensten authentifizieren

So funktioniert der Empfang von Daten

Eine Chat-App präsentiert dem Nutzer Informationen in Form eines Dialogfelds oder einer Kartennachricht. In diesem Beispiel wird der Nutzer in einem Dialogfeld aufgefordert, mit den Widgets TextInput und SelectionInput Informationen zu einem Kontakt einzugeben:

Ein Dialogfeld mit verschiedenen Widgets.

Anschließend empfängt die Chat-App die Daten, die Nutzer in das Dialogfeld eingegeben haben, im JSON-Format sowie ein Interaktionsereignis, wobei Folgendes gilt:

Verwenden Sie das Feld Event.common.formInputs in der Ereignisnutzlast, um Daten darüber zu erhalten, was Nutzer eingegeben haben. Das Feld formInputs ist eine Zuordnung, bei der Schlüssel String-IDs sind, die jedem Widget zugewiesen sind, und Werte, die Nutzereingaben für jedes Widget darstellen. Verschiedene Objekte stehen für unterschiedliche Eingabedatentypen. Beispielsweise stellt Event.common.formInputs.stringInputs Stringeingaben dar.

Die Anwendung kann auf den ersten vom Nutzer eingegebenen Wert unter event.common.formInputs.NAME.stringInputs.value[0] zugreifen, wobei NAME das Feld name eines TextInput-Widgets ist.

Daten von Karten erhalten

Wenn ein Nutzer Daten in eine Kartennachricht eingibt, empfängt die Chat-App ein Interaktionsereignis für die Chat-App, z. B. im folgenden Beispiel:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Daten aus Dialogfeldern erhalten

Wenn ein Nutzer Daten in einem Dialogfeld sendet, empfängt Ihre Chat-App ein weiteres Interaktionsereignis der Chat-App, z. B. im folgenden Beispiel:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Auf Daten reagieren, die über eine Kartennachricht oder ein Dialogfeld erhoben wurden

Nachdem die Daten aus einer Kartennachricht oder einem Dialogfeld empfangen wurden, bestätigt die Chat-App entweder den Empfang oder gibt einen Fehler zurück. In beiden Fällen wird ein ActionResponse zurückgegeben:

  • Um den erfolgreichen Empfang zu bestätigen, antworten Sie mit dem Parameter ActionResponse, der "actionStatus": "OK" enthält.
  • Um einen Fehler zurückzugeben, antworten Sie mit dem Parameter ActionResponse, der "actionStatus": "ERROR MESSAGE" enthält.

Beispiel

Im folgenden Beispiel wird geprüft, ob ein name-Wert vorhanden ist. Andernfalls gibt die Anwendung einen Fehler zurück. Falls vorhanden, bestätigt die App den Empfang der Formulardaten und 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 receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

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 receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "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': 'Don\'t forget to name your new contact!'
                }
              }
            }

Fehlerbehebung

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

Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Aufrufen, Debuggen und Beheben von Fehlern finden Sie im Hilfeartikel Google Chat-Fehler beheben.