Ouvrir des boîtes de dialogue interactives

Cette page explique comment votre application Chat peut ouvrir des boîtes de dialogue pour répondre aux utilisateurs.

Les boîtes de dialogue sont des interfaces fenêtrées basées sur des cartes qui s'ouvrent depuis un espace Chat ou un message. La boîte de dialogue et ses le contenu n'est visible que par l'utilisateur qui l'a ouvert.

Les applications de chat peuvent utiliser des boîtes de dialogue pour demander et collecter des informations auprès des Chat avec les utilisateurs, y compris les formulaires à plusieurs étapes Pour en savoir plus sur la création des entrées de formulaire, consultez Recueillir et traiter les informations des utilisateurs.

Prérequis

Node.js

  • Une application Google Chat avec des fonctionnalités interactives. Pour créer un une application Chat interactive utilisant un service HTTP, suivez ce guide de démarrage rapide.

Python

  • Une application Google Chat avec des fonctionnalités interactives. Pour créer un une application Chat interactive utilisant un service HTTP, suivez ce guide de démarrage rapide.

Apps Script

  • Une application Google Chat avec des fonctionnalités interactives. Pour créer un application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.

Ouvrir une boîte de dialogue

Boîte de dialogue présentant différents widgets.
Figure 1: Boîte de dialogue de collecte des coordonnées

Cette section explique comment répondre et configurer une boîte de dialogue en procédant comme suit:

  1. Déclenchez la requête de boîte de dialogue à partir d'une interaction utilisateur.
  2. Pour gérer la requête, renvoyez et ouvrez une boîte de dialogue.
  3. Une fois les informations envoyées, traitez l'envoi en fermant ou en renvoyant une autre.

Déclencher une requête de boîte de dialogue

Une application Chat ne peut ouvrir des boîtes de dialogue que pour répondre à un utilisateur interaction, comme une commande à barre oblique ou un clic sur un bouton à partir d'un message dans une fiche.

Pour répondre aux utilisateurs à l'aide d'une boîte de dialogue, une application Chat doit Créez une interaction qui déclenche la requête de boîte de dialogue, par exemple:

  • Répondez à une commande à barre oblique. Pour déclencher la requête à partir d'une commande à barre oblique, vous devez cocher la case Ouvre une boîte de dialogue lors de la configuration de la commande.
  • Répondez à un clic sur un bouton dans une message, soit dans une fiche, soit en bas du message. Pour déclencher à partir d'un bouton dans un message, vous configurez onClick du bouton en définissant interaction sur OPEN_DIALOG.
  • Répondre à un clic sur un bouton sur la page d'accueil de l'application Chat Pour en savoir plus sur l'ouverture des boîtes de dialogue à partir des pages d'accueil, consultez Créez une page d'accueil pour votre application Google Chat.
Bouton qui déclenche une boîte de dialogue
Figure 2: Une application Chat envoie un message invitant les utilisateurs à exécuter la commande à barre oblique /addContact.
Le message inclut également un bouton sur lequel l'utilisateur peut cliquer pour déclencher la commande.

Le code JSON suivant montre comment déclencher une requête de boîte de dialogue à partir d'un bouton dans une message de fiche. Pour ouvrir la boîte de dialogue, button.interaction est défini sur OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "FUNCTION_NAME",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

Où BUTTON_TEXT est le texte qui s'affiche dans le bouton. et FUNCTION_NAME est la fonction qui s'exécute pour ouvrir le fichier .

Ouvrir la boîte de dialogue initiale

Lorsqu'un utilisateur déclenche une requête de boîte de dialogue, votre application Chat reçoit un événement d'interaction, représenté sous la forme event saisissez la API Chat. Si l'interaction déclenche une demande de boîte de dialogue, l'événement Le champ dialogEventType est défini sur REQUEST_DIALOG.

Pour ouvrir une boîte de dialogue, votre application Chat peut répondre aux en renvoyant une actionResponse avec le type défini sur DIALOG et Message . Pour spécifier le contenu de la boîte de dialogue, vous incluez les éléments suivants : Objets:

  • Un actionResponse dont la valeur type est définie sur DIALOG.
  • Un objet dialogAction. Le champ body contient les éléments d'interface utilisateur à utiliser dans la fiche, y compris une ou plusieurs sections de widgets. Pour collecter des informations auprès des utilisateurs, vous pouvez spécifier des widgets de saisie de formulaire et un widget de bouton. Pour en savoir plus sur la conception des entrées de formulaire, consultez Collecter et traiter les informations des utilisateurs

Le fichier JSON suivant montre comment une application Chat renvoie une réponse qui ouvre une boîte de dialogue:

{ "actionResponse": {
  "type": "DIALOG",
  "dialogAction": { "dialog": { "body": { "sections": [{
    "widgets": [{
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "BUTTON_TEXT",
        "onClick": {
          "action": {"function": "FUNCTION_NAME"}
        }
      }]}}
    }]
  }]}}}
}}

Où BUTTON_TEXT est le texte qui s'affiche sur le bouton (par exemple, Next ou Submit), WIDGETS représente un ou plusieurs Widgets de saisie de formulaire FUNCTION_NAME est la fonction qui s'exécute lorsque les utilisateurs cliquent sur un bouton.

Gérer l'envoi de la boîte de dialogue

Lorsque les utilisateurs cliquent sur un bouton qui envoie une boîte de dialogue, votre L'application Chat reçoit une interaction CARD_CLICKED événement où dialogEventType est SUBMIT_DIALOG.

Votre application Chat doit gérer l'événement d'interaction en procédant comme suit : en effectuant l'une des opérations suivantes:

Facultatif: renvoyer une autre boîte de dialogue

Une fois que les utilisateurs ont envoyé la boîte de dialogue initiale, les applications Chat peuvent afficher une ou plusieurs boîtes de dialogue supplémentaires pour aider les utilisateurs à consulter les informations avant l'envoi de formulaires, de remplir des formulaires en plusieurs étapes ou de remplir dynamiquement le contenu des formulaires.

Pour charger les données saisies par les utilisateurs à partir de la boîte de dialogue initiale, vous devez ajouter au bouton qui ouvre la boîte de dialogue suivante, ou transmettez les paramètres d'origine Événement d'interaction CARD_CLICKED de la boîte de dialogue initiale. Pour en savoir plus, consultez Transférer des données vers une autre carte

Dans cet exemple, une application Chat ouvre une boîte de dialogue qui renvoie une deuxième boîte de dialogue avant l'envoi. Pour charger les données d'entrée, L'application Chat transmet l'événement d'interaction CARD_CLICKED en tant que paramètre de la fonction qui ouvre la boîte de dialogue suivante:

Node.js

// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {

  // Open the first dialog.
  if (event.common.invokedFunction === "openDialog") {
    openDialog(event);
  }

  // Open the second dialog.
  if (event.common.invokedFunction === "openNextDialog") {
    openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }});
};

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }});
}

Python

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat that includes the /createContact
     slash command by opening a dialog.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """

  if req.method == 'GET':
    return 'Sorry, this function must be called from a Google Chat.'

  request = req.get_json(silent=True)

  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_dialog':
        return open_dialog(request)

      elif invoked_function == 'open_next_dialog':
        return open_dialog(request)

def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a dialog in Google Chat.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "open_next_dialog"
        }}
      }]}}
    ]}]}}}
  }}

def open_next_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a second dialog that lets users add more contact details.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submit_dialog"
          }}
        }]}
      }
    ]}]}}}
  }}

Apps Script

Cet exemple envoie un message de carte en renvoyant fichier JSON de la carte. Vous pouvez également utiliser Service de fiches Apps Script. 

/**
* Responds to a CARD_CLICKED event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onCardClick(event) {

  // When a user clicks a card, the Chat app checks to see which function to run.
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  }

  if (event.common.invokedFunction === "openNextDialog") {
    return openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }};
}

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }};
}

Où WIDGETS représente un ou plusieurs widgets de saisie de formulaire.

Fermer la boîte de dialogue

Lorsque les utilisateurs cliquent sur un bouton d'une boîte de dialogue, votre L'application Chat reçoit un événement d'interaction avec les informations suivantes:

Les sections suivantes expliquent comment valider les données que les utilisateurs saisissent et fermer la boîte de dialogue.

Valider les données d'entrée utilisateur et fermer la boîte de dialogue

Pour traiter les données saisies par les utilisateurs, l'application Chat utilise le event.common.formInputs . Pour en savoir plus sur la récupération de valeurs à partir de widgets d'entrée, consultez Collecter et traiter les informations des utilisateurs

Si l'utilisateur omet un champ obligatoire ou saisit des valeurs incorrectes, le L'application Chat peut renvoyer une erreur en renvoyant une ActionResponse contenant "actionStatus": "ERROR MESSAGE".

L'exemple suivant vérifie qu'un utilisateur saisit une valeur pour un widget qui accepte les chaînes (stringInputs), comme un widget textInput. Si ce champ n'est pas renseigné, L'application Chat renvoie une erreur. Le cas échéant, l'application Chat accuse réception de la boîte de dialogue 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 submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] === "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    });

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    res.json({
      "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': 'ERROR_MESSAGE'
                }
              }
            }

Apps Script

Cet exemple envoie un message de carte en renvoyant fichier JSON de la carte. Vous pouvez également utiliser Service de fiches 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 submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] === "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    };

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Dans cet exemple, WIDGET_NAME représente le champ name du (comme contactName) et le ERROR_MESSAGE représente le contenu du message d'erreur (par exemple, Don't forget to name your contact). Pour en savoir plus sur le traitement des données d'entrée des widgets, consultez Recevez des données à partir de widgets interactifs.

Facultatif: Envoyer un message de confirmation

Lorsque vous fermez la boîte de dialogue, vous pouvez également envoyer un nouveau message, mettre à jour une une liste existante.

Pour envoyer un nouveau message, renvoyez un ActionResponse avec le type défini sur NEW_MESSAGE. Par exemple, pour fermer la boîte de dialogue, et envoyez un message, renvoyez le code suivant:

  {
    "actionResponse": {
      "type": "NEW_MESSAGE",
    },
    "text": "Your information has been submitted."
  }

Pour mettre à jour un message, renvoyez un objet actionResponse contenant le message mis à jour et définit type sur l'une des valeurs suivantes:

Résoudre les problèmes

Lorsqu'une application ou card renvoie une erreur, la L'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande." Parfois, l'interface utilisateur de Chat n'affiche aucun message d'erreur, mais que l'application ou la carte produit un résultat inattendu. Par exemple, un message de fiche peut ne pas s'affichent.

Même s'il est possible qu'aucun message d'erreur ne s'affiche dans l'interface utilisateur de Chat, Des messages d'erreur descriptifs et des données de journaux 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, le débogage et la correction des erreurs, consultez Résoudre les problèmes liés à Google Chat