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:
TextInputfür die Eingabe im freien Format, die auch Vorschläge unterstütztSelectionInputfür Listenelemente und Menüs wie Kästchen, Optionsfelder und Drop-down-Menüs.DateTimePickerfür Datums- und Uhrzeiteinträge
Mit dem Card Builder kannst du JSON-Kartennachrichten für Chat-Apps entwerfen und als Vorschau ansehen:
Den Card Builder öffnenDurch 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:
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:
EventTypeistCARD_CLICKED.DialogEventTypeistSUBMIT_DIALOG(nur für Dialogfelder).
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
In diesem Beispiel wird eine Kartennachricht durch Rückgabe von Karten-JSON gesendet. Sie können auch den Apps Script-Kartendienst verwenden.
/**
* 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.