Ce guide explique comment recevoir et lire les informations que les utilisateurs saisissent dans les messages associés aux fiches et les boîtes de dialogue. Les utilisateurs peuvent saisir les données que les applications Chat reçoivent, lisent et auxquelles elles répondent. Les widgets qui permettent aux utilisateurs de saisir des informations sont les suivants:
TextInput
pour une saisie de texte au format libre qui accepte également les suggestions.SelectionInput
pour les éléments de liste et les menus, comme les cases à cocher, les cases d'option et les menus déroulantsDateTimePicker
pour les entrées de date et d'heure.
Utilisez Card Builder pour concevoir et prévisualiser les messages de fiche JSON pour les applications Chat:
Ouvrez l'outil de création de cartesLa réception de données saisies par les utilisateurs permet aux applications Chat d'effectuer les opérations suivantes:
- Mettre à jour les demandes d'assistance auprès du service client.
- Créer des bons de travail
- Authentifiez-vous avec des services Web.
Fonctionnement de la réception de données
Une application Chat présente des informations à l'utilisateur sous forme de boîte de dialogue ou de message sous forme de fiche. Dans cet exemple, une boîte de dialogue demande à l'utilisateur de saisir des informations sur un contact à l'aide des widgets TextInput
et SelectionInput
:
Une fois l'opération terminée, l'application Chat reçoit les données que les utilisateurs ont saisies dans la boîte de dialogue au format JSON et un événement d'interaction dans lequel:
EventType
estCARD_CLICKED
.DialogEventType
estSUBMIT_DIALOG
(pour les boîtes de dialogue uniquement).
Pour obtenir des données sur ce que les utilisateurs ont saisi, utilisez le champ Event.common.formInputs
dans la charge utile de l'événement. Le champ formInputs
est un mappage dans lequel les clés sont des ID de chaîne attribués à chaque widget, et les valeurs représentent les entrées utilisateur pour chaque widget. Chaque objet représente différents types de données d'entrée. Par exemple, Event.common.formInputs.stringInputs
représente les entrées de chaîne.
Votre application peut accéder à la première valeur saisie par l'utilisateur dans event.common.formInputs.NAME.stringInputs.value[0]
, où NAME
est le champ name
d'un widget TextInput
.
Recevoir des données des cartes
Lorsqu'un utilisateur saisit des données dans un message de carte, votre application Chat reçoit un événement d'interaction avec l'application Chat, comme dans l'exemple suivant:
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
}
}
Recevoir des données à partir des boîtes de dialogue
Lorsqu'un utilisateur envoie des données dans une boîte de dialogue, votre application Chat reçoit un autre événement d'interaction, comme dans l'exemple suivant:
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
}
}
Répondre aux données collectées à partir d'un message associé à une fiche ou d'une boîte de dialogue
Après avoir reçu les données d'un message de carte ou d'une boîte de dialogue, l'application Chat répond soit en accusant réception de la demande, soit en renvoyant une erreur, les deux opérations se faisant en renvoyant une ActionResponse
:
- Pour accuser réception, répondez avec un paramètre
ActionResponse
contenant"actionStatus": "OK"
. - Pour renvoyer une erreur, répondez avec un paramètre
ActionResponse
contenant"actionStatus": "ERROR MESSAGE"
.
Exemple
L'exemple suivant vérifie la présence d'une valeur name
. Si ce champ n'est pas renseigné, l'application renvoie une erreur. Le cas échéant, l'application accuse réception des données du formulaire et ferme la boîte de dialogue.
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 ;
Cet exemple envoie un message de carte en renvoyant card JSON. Vous pouvez également utiliser le service de cartes 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!'
}
}
}
Résoudre les problèmes
Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche un message indiquant "Une erreur s'est produite". ou "Impossible de traiter votre demande". Parfois, l'UI Chat n'affiche aucun message d'erreur, mais l'application ou la carte Chat produit un résultat inattendu. Par exemple, il est possible qu'un message de fiche ne s'affiche pas.
Bien qu'aucun message d'erreur ne s'affiche dans l'UI Chat, des messages d'erreur descriptifs et des données de journal sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs est activée pour les applications Chat. Pour obtenir de l'aide sur l'affichage, le débogage et la correction des erreurs, consultez Résoudre les problèmes dans Google Chat.