Créer 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.

Les boîtes de dialogue sont des interfaces basées sur des fiches 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 de 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 champs de formulaire, consultez Collecter et traiter les informations des utilisateurs.

Prérequis

Ouvrir une boîte de dialogue

Cette section explique comment répondre et configurer un dialogue en procédant comme suit :

1. Déclenchez la demande 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 l'envoi 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, comme une commande 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 demande de boîte de dialogue, par exemple :

• Répondre à une commande Pour déclencher la requête à partir d'une commande, vous devez cocher la case Ouvre une boîte de dialogue lorsque vous configurez la commande.
• Répondez à un clic sur un bouton dans un message, soit dans une fiche, soit en bas du message. Pour déclencher la requête à partir d'un bouton dans un message, configurez 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 correspond au texte affiché dans le bouton et ACTION_FUNCTION à 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 de chat reçoit un objet d'événement avec une charge utile qui spécifie un objet dialogEventType en tant que 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 des éléments d'interface utilisateur (UI), y compris un ou plusieurs widgets sections[]. Pour collecter des informations auprès des utilisateurs, vous pouvez spécifier des widgets d'entrée 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 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" }
      }
    }]}}
  }]}]}}]}
}

Où BUTTON_TEXT correspond au texte affiché dans le bouton (par exemple, Next ou Submit), WIDGETS représente un ou plusieurs widgets d'entrée de formulaire et ACTION_FUNCTION correspond à 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 événement avec un objet ButtonClickedPayload. Dans la charge utile, dialogEventType est défini sur SUBMIT_DIALOG. Pour savoir comment collecter et traiter les informations du dialogue, consultez Collecter et traiter les informations des utilisateurs Google Chat.

Votre application Chat doit répondre à l'objet événement en effectuant l'une des actions suivantes :

• Renvoie une autre boîte de dialogue pour remplir 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 à remplir 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 savoir comment récupérer des valeurs à partir de widgets d'entrée, consultez Collecter et traiter les informations des utilisateurs.

Pour suivre les données saisies par les utilisateurs dans 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 sur les valeurs suivantes :

• isDialogEvent correspond à true.
• dialogEventType correspond à SUBMIT_DIALOG.

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

Facultatif : Afficher une notification temporaire

Lorsque vous fermez la boîte de dialogue, vous pouvez également afficher une notification textuelle temporaire à l'utilisateur qui interagit avec l'application.

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 savoir comment transmettre des paramètres entre les boîtes de dialogue, consultez Transférer des données vers une autre fiche.

Facultatif : Envoyez un message de confirmation dans le chat.

Lorsque vous fermez la boîte de dialogue, vous pouvez également envoyer un nouveau message Chat 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 message texte, renvoyez ce qui suit :

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

Pour mettre à jour un message après que l'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, tel que le message à partir duquel l'utilisateur a demandé la boîte de dialogue.
• UpdateInlinePreviewAction : met à jour la fiche à partir d'un aperçu du lien.

Résoudre les problèmes

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande". Il arrive que l'UI 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'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 pour les applications Chat est activée. Pour obtenir de l'aide concernant l'affichage, le débogage et la résolution des erreurs, consultez Résoudre les problèmes et corriger les erreurs Google Chat.