Traiter les informations saisies par les utilisateurs

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éroulants
  • DateTimePicker pour les entrées de date et d'heure.


Créez et prévisualisez des fiches avec Card Builder.

Ouvrez l'outil de création de cartes

La 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:

Boîte de dialogue présentant différents widgets.

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:

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 ;

/**
 * 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!'
                }
              }
            }

Dépannage

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche un message indiquant "Un problème est survenu" ou "Impossible de traiter votre demande". Il peut arriver que l'interface Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat génère 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'interface 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. Si vous avez besoin d'aide pour afficher, déboguer et corriger les erreurs, consultez Résoudre les erreurs Google Chat.