In diesem Leitfaden wird beschrieben, wie Sie die von Nutzern in Kartennachrichten und Dialogfelder eingegebenen Informationen abrufen und lesen. Nutzer können Daten eingeben, die Chat-Apps empfangen, lesen und auf die sie antworten. Widgets, über die Nutzer Informationen eingeben können, sind unter anderem:
TextInputfür die Freitexteingabe, die auch Vorschläge unterstütztSelectionInputfür Listenelemente und Menüs wie Kästchen, Optionsfelder und Drop-down-MenüsDateTimePickerfür Datums- und Uhrzeiteinträge
Dadurch können Chat-Apps beispielsweise Folgendes tun:
- Kundenservicefälle aktualisieren
- Aufträge erstellen
- Mit Webdiensten authentifizieren
Funktionsweise des Empfangs von Daten
Eine Chat-App stellt dem Nutzer Informationen in Form eines Dialogfelds oder einer Kartennachricht bereit. In diesem Beispiel wird der Nutzer in einem Dialogfeld aufgefordert, mit den Widgets TextInput und SelectionInput Informationen zu einem Kontakt einzugeben:
Wenn Sie fertig sind, 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).
Daten zu den von Nutzern eingegebenen Daten erhalten Sie mit dem Feld Event.common.formInputs in der Ereignisnutzlast. 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.
Ihre 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 der Chat-App, z. B.:
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 die 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 antworten, die über eine Kartennachricht oder ein Dialogfeld erhoben wurden
Nachdem die Daten aus einer Kartennachricht oder einem Dialogfeld empfangen wurden, antwortet die Chat-App entweder mit der Empfangsbestätigung oder mit einer Fehlermeldung. In beiden Fällen wird ein ActionResponse zurückgegeben:
- Um den erfolgreichen Empfang zu bestätigen, antworten Sie mit einem
ActionResponse-Parameter, 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 das Vorhandensein eines name-Werts geprüft. Ist dies nicht der Fall, gibt die Anwendung einen Fehler zurück. Falls vorhanden, bestätigt die App den Erhalt 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 -Karte einen Fehler zurückgibt, wird in der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ oder „Anfrage kann nicht verarbeitet werden“ angezeigt. Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, die Chat-App oder -Karte aber zu einem unerwarteten Ergebnis führt, z. B. wird keine Kartennachricht angezeigt.
Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, stehen beschreibende Fehlermeldungen und Protokolldaten zur Verfügung, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Weitere Informationen finden Sie im Hilfeartikel Fehler in Google Chat beheben.