Ouvrir des boîtes de dialogue interactives

Cette page explique comment une application Google Chat peut ouvrir des boîtes de dialogue pour afficher des interfaces utilisateur (UI) et répondre aux utilisateurs.

Dans Google Chat, les modules complémentaires apparaissent aux utilisateurs comme des applications Google Chat. Pour en savoir plus, consultez la présentation de l'extension Google Chat.

Les boîtes de dialogue sont des interfaces basées sur des cartes qui s'ouvrent à partir d'un espace ou d'un message Chat. La boîte de dialogue et son contenu ne sont visibles que par l'utilisateur qui l'a ouverte.

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

Prérequis

Ouvrir une boîte de dialogue

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. Gérez la requête en renvoyant et en ouvrant une boîte de dialogue.
3. Une fois que les utilisateurs ont envoyé des informations, traitez-les en fermant la boîte de dialogue ou en renvoyant une autre boîte de dialogue.

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 à une interaction utilisateur, telle qu'une commande à barre oblique ou un clic sur un bouton à partir d'un message dans une fiche.

Pour répondre aux utilisateurs avec une boîte de dialogue, une application Chat doit créer 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 Opens a dialog (Ouvre une boîte de dialogue) lorsque vous configurez la commande.
• Répondre à un clic sur un bouton dans un message, dans une fiche ou en bas du message. Pour déclencher la requête à partir d'un bouton dans un message, vous devez configurer l'action onClick du bouton en définissant son interaction sur OPEN_DIALOG.

Le code JSON suivant montre comment déclencher une requête de boîte de dialogue à partir d'un bouton dans un message de carte. Pour ouvrir la boîte de dialogue, définissez le champ onClick.action.interaction du bouton sur OPEN_DIALOG:

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

Où BUTTON_TEXT est le texte qui s'affiche dans le bouton et ACTION_FUNCTION est la fonction exécutée pour ouvrir la boîte de dialogue initiale.

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 objet d'événement avec une charge utile qui spécifie qu'un objet dialogEventType est REQUEST_DIALOG.

Pour ouvrir une boîte de dialogue, votre application Chat peut répondre à la requête en renvoyant un objet RenderActions avec la navigation pushCard pour afficher une fiche. La fiche doit contenir tous les éléments d'interface utilisateur (UI), y compris un 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 la section Collecter et traiter les informations des utilisateurs.

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

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

BUTTON_TEXT correspond au texte qui s'affiche dans le bouton (par exemple, Next ou Submit), WIDGETS représente un ou plusieurs widgets de saisie de formulaire, et ACTION_FUNCTION est la fonction de rappel de l'action 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 application Chat reçoit un objet d'événement avec un objet ButtonClickedPayload. Dans la charge utile, dialogEventType est défini sur SUBMIT_DIALOG.

Votre application Chat doit gérer l'objet d'événement en effectuant l'une des opérations suivantes:

• Renvoyer une autre boîte de dialogue pour renseigner une autre fiche ou un autre formulaire.
• Fermez la boîte de dialogue après avoir validé les données envoyées par l'utilisateur et, si vous le souhaitez, envoyez un message de confirmation.

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 renvoyer une ou plusieurs boîtes de dialogue supplémentaires pour les aider à examiner les informations avant de les envoyer, à remplir des formulaires en plusieurs étapes ou à renseigner le contenu des formulaires de manière dynamique.

Pour traiter les données saisies par les utilisateurs, l'application Chat gère les données dans l'objet commonEventObject.formInputs de l'événement. Pour en savoir plus sur la récupération de valeurs à partir de widgets de saisie, consultez la section Collecter et traiter les informations des utilisateurs.

Pour suivre les données que les utilisateurs saisissent à partir de la boîte de dialogue initiale, vous devez ajouter des paramètres au bouton qui ouvre la boîte de dialogue suivante. 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 initiale qui mène à une deuxième boîte de dialogue de confirmation avant l'envoi:

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

où WIDGETS représente tout autre widget de saisie de formulaire.

Fermer la boîte de dialogue

Lorsque les utilisateurs cliquent sur un bouton d'envoi dans une boîte de dialogue, votre application Chat exécute l'action associée et fournit l'objet d'événement avec buttonClickedPayload défini comme suit:

• isDialogEvent : true.
• dialogEventType : SUBMIT_DIALOG.

L'application Chat doit renvoyer un objet RenderActions avec EndNavigation défini sur CLOSE_DIALOG.

Facultatif: Afficher une notification

Lorsque vous fermez la boîte de dialogue, vous pouvez également afficher une notification textuelle.

Pour afficher une notification, renvoyez l'objet RenderActions avec le champ notification défini.

L'exemple suivant vérifie que les paramètres sont valides et ferme la boîte de dialogue avec une notification textuelle en fonction du résultat:

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Pour en savoir plus sur la transmission de paramètres entre les boîtes de dialogue, consultez la section Transférer des données vers une autre fiche.

Facultatif: Envoyer un message de confirmation

Lorsque vous fermez la boîte de dialogue, vous pouvez également envoyer un nouveau message ou modifier un message existant.

Pour envoyer un nouveau message, renvoyez un objet DataActions avec le champ CreateMessageAction défini sur le nouveau message. Par exemple, pour fermer la boîte de dialogue et envoyer un SMS, renvoyez ce qui suit:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Pour mettre à jour un message après qu'un utilisateur a envoyé une boîte de dialogue, renvoyez un objet DataActions contenant l'une des actions suivantes:

• UpdateMessageAction : met à jour un message envoyé par l'application Chat, comme le message à partir duquel l'utilisateur a demandé la boîte de dialogue.
• UpdateInlinePreviewAction : met à jour la fiche à partir d'un aperçu de lien.

Résoudre les problèmes

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Un problème s'est produit". ou "Impossible de traiter votre demande". Il arrive que l'interface utilisateur de Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat produise un résultat inattendu. Par exemple, un message de fiche peut ne pas s'afficher.

Bien qu'un message d'erreur ne s'affiche pas dans l'UI Chat, des messages d'erreur descriptifs et des données de journal sont disponibles pour vous aider à résoudre les erreurs lorsque la journalisation des erreurs pour les applications Chat est activée. Pour savoir comment afficher, déboguer et corriger les erreurs, consultez Résoudre et corriger les erreurs Google Chat.