Personnalisation du dialogue avec le contexte

Pour personnaliser la conversation, votre assistant peut collecter des informations auprès du client, puis y faire référence plus tard dans la conversation.

Conservation d'informations entre chaque échange de dialogue

Le dialogue est sans état, ce qui signifie qu'il ne conserve aucune information entre chaque interaction avec l'utilisateur. Lorsque vous ajoutez une boîte de dialogue à un assistant et que vous la déployez, l'assistant sauvegarde le contexte à partir d'un appel de message, puis le soumet à nouveau à la demande suivante tout au long de la session en cours. La session en cours dure pendant qu'un utilisateur interagit avec l'assistant plus la période d'inactivité de session désignée. La durée maximale d'inactivité de session autorisée varie de 5 minutes à 7 jours, en fonction de votre type de plan. Si vous n'ajoutez pas la boîte de dialogue à un assistant, il vous incombe, en tant que développeur d'applications personnalisées, de conserver toutes les informations dont l'application a besoin.

L'application peut transmettre des informations au dialogue, et le dialogue peut mettre à jour ces informations et les transmettre en retour à l'application ou à un noeud suivant. Pour cela, le dialogue utilise des variables contextuelles.

Variables contextuelles

Une variable contextuelle est une variable que vous définissez dans un noeud. Vous pouvez spécifier une valeur par défaut pour cette variable. Ensuite, d'autres noeuds, une logique d'application ou une entrée utilisateur peuvent définir ou modifier la valeur de la variable contextuelle.

Vous pouvez définir des conditions par rapport à des valeurs de variable contextuelle en référençant une variable contextuelle à partir d'une condition de noeud de dialogue afin de déterminer si un noeud doit être exécuté. Vous pouvez également référencer une variable contextuelle à partir de conditions de réponse de noeud de dialogue pour afficher des réponses différentes en fonction d'une valeur fournie par un service externe ou par l'utilisateur.

En savoir plus :

Transmission de contexte à partir de l'application

Transmettez des informations de l'application au dialogue en définissant une variable contextuelle et en transmettant celle-ci au dialogue.

Par exemple, votre application peut définir une variable contextuelle $time_of_day et la transmettre au dialogue qui peut utiliser les informations pour personnaliser le message d'accueil qu'elle affiche à l'utilisateur.

Affiche un noeud de bienvenue qui utilise des conditions de réponse pour vérifier la valeur de la variable contextuelle $time_of_day transmise au dialogue à partir de l'application.
Contexte de l'heure du jour

Dans cet exemple, le dialogue sait que l'application définit la variable avec l'une des valeurs suivantes : morning, afternoon ou evening. Il peut rechercher chaque valeur, et selon la valeur qui est présente, renvoyer le message d'accueil approprié. Si la variable n'est pas transmise ou comporte une valeur qui ne correspond à aucune des valeurs prévues, l'utilisateur voit s'afficher un message d'accueil plus générique.

Transmission de contexte d'un noeud à un autre

Le dialogue peut également ajouter des variables contextuelles pour transmettre des informations d'un noeud à un autre ou pour mettre à jour les valeurs de variables contextuelles. Lorsque le dialogue demande et obtient des informations de l'utilisateur, il peut suivre les informations et les référencer plus tard dans la conversation.

Par exemple, dans un noeud, vous pouvez demander leur nom à des utilisateurs, et dans un noeud ultérieur, vous pouvez vous adresser à eux directement par leur nom.

Affiche un nœud d'introduction qui demande à l'utilisateur son nom et le stocke en tant que variable de contexte. Le noeud suivant fait référence à l'utilisateur par son nom à l'aide de la variable contextuelle $username.
Transmettre le contexte d'un noeud à un autre

Dans cet exemple, l'entité système @name est utilisée pour extraire le nom de l'utilisateur de l'entrée si l'utilisateur en fournit un. Dans l'éditeur JSON, la variable de contexte de nom d'utilisateur est définie et définie sur la valeur @name. Dans un noeud suivant, la variable contextuelle $username est incluse dans la réponse pour s'adresser à l'utilisateur par son nom.

Définition d'une variable contextuelle

Définissez une variable contextuelle en ajoutant le nom de la variable à la zone Variable et en lui attribuant une valeur par défaut dans la zone Value dans la vue d'édition du noeud.

  1. Cliquez pour ouvrir le noeud de dialogue auquel vous souhaitez ajouter une variable contextuelle.

  2. Accédez à la section L'assistant répond et cliquez sur l'icône de menu icône de menu de dépassement.

  3. Cliquez sur Open context editor.

  4. Ajoutez la paire nom-valeur de la variable dans les zones Variable et Value.

    • Le name peut contenir des caractères alphabétiques en majuscules et en minuscules, des caractères numériques (0-9) et des traits de soulignement.

    • La value peut correspondre à n'importe quel type JSON pris en charge, par exemple, une variable de chaîne simple, un nombre, un tableau JSON ou un objet JSON.

Le tableau suivant montre quelques exemples sur la manière de définir des paires nom-valeur pour différents types de valeurs :

Définir des paires nom-valeur
Variable Valeur Type de valeur
dessert "gâteau" Chaîne
âge 18 Nombre
toppings_array ["onions","olives"] Tableau JSON
full_name {"first":"John","last":"Doe"} Objet JSON

Ensuite, pour faire référence à ces variables contextuelles, utilisez la syntaxe $name où name est le nom de la variable contextuelle que vous avez définie.

Par exemple, vous pouvez spécifier l'expression suivante comme réponse du dialogue :

The customer, $age-year-old <? $full_name.first ?>, wants a pizza with <? $toppings_array.join(' and ') ?>, and then $dessert.

Le résultat obtenu est affiché comme suit :

The customer, 18-year-old John, wants a pizza with onions and olives, and then cake.

Vous pouvez également utiliser l'éditeur JSON pour définir des variables contextuelles. Vous préférerez peut-être utiliser l'éditeur JSON si vous souhaitez ajouter une expression complexe en tant que valeur de variable. Pour plus d'informations, reportez-vous à la section Variables contextuelles dans l'éditeur JSON.

Tâches de variable contextuelle courantes

Pour stocker l'intégralité de la chaîne qui a été fournie en entrée par l'utilisateur, utilisez input.text :

Capture de l'entrée utilisateur
Variable Valeur
répétition <?input.text?>

Par exemple, l'entrée utilisateur peut être I want to order a device. Si la réponse du noeud est You said: $repeat, la réponse s'affiche sous la forme suivante: You said: I want to order a device.

Pour stocker la valeur d'une entité dans une variable contextuelle, utilisez la syntaxe suivante :

Capture d'une mention d'entité
Variable Valeur
espace @place

Par exemple, l'entrée utilisateur peut être I want to go to Paris. Si votre entité @place reconnaît Paris, votre assistant sauvegarde Paris dans la variable contextuelle $place.

Pour stocker la valeur d'une chaîne que vous extrayez à partir de l'entrée utilisateur, vous pouvez inclure une expression SpEL qui utilise la méthode extract afin d'appliquer une expression régulière à l'entrée utilisateur. L'expression décrite ci-après extrait un nombre de l'entrée utilisateur et le sauvegarde dans la variable contextuelle $number.

Utilisation d'une méthode String
Variable Valeur
number <?input.text.extract('[\d]+',0)?>

Pour stocker la valeur d'une entité de canevas, ajoutez .literal au nom d'entité. A l'aide de cette syntaxe, assurez-vous que l'étendue exacte du texte de l'entrée utilisateur qui correspond au modèle spécifié est stockée dans la variable.

Capture d'une valeur d'entité de canevas
Variable Valeur
adresse électronique <? @email.literal ?>

Par exemple, l'entrée utilisateur est Contact me at joe@example.com. Votre entité nommée @email reconnaît le format d'e-mail name@domain.com. En configurant la variable contextuelle pour stocker @email.literal, vous indiquez que vous souhaitez stocker la partie de l'entrée qui correspond au canevas. Si vous omettez la propriété .literal de l'expression de valeur, le nom de la valeur d'entité que vous avez spécifié pour le canevas est renvoyé au lieu du segment d'entrée utilisateur correspondant au canevas.

Suppression d'une variable contextuelle

Pour supprimer une variable contextuelle, affectez la valeur NULL à cette variable.

Annulation d'une variable contextuelle
Variable Valeur
order_form null

Mise à jour d'une valeur de variable contextuelle

Pour mettre à jour la valeur d'une variable contextuelle, définissez une variable contextuelle portant le même nom que la variable contextuelle précédente, mais cette fois, spécifiez une valeur différente pour celle-ci.

Lorsque plusieurs noeuds définissent la valeur de la même variable contextuelle, la valeur de la variable contextuelle peut changer au cours d'une conversation avec un utilisateur. La valeur qui est appliquée dépend du noeud qui est déclenché par l'utilisateur au cours de la conversation. La valeur spécifiée pour la variable contextuelle dans le dernier noeud traité remplace toutes les valeurs définies pour la variable par les noeuds traités précédemment.

Pour plus d'informations sur la mise à jour de la valeur d'une variable contextuelle lorsque celle-ci est un objet JSON ou un type de données de tableau JSON, reportez-vous à la rubrique Mise à jour d'une valeur de variable contextuelle en JSON.

Comment les variables contextuelles sont-elles traitées ?

L'emplacement où vous définissez la variable contextuelle est important. La variable contextuelle n'est pas créée et définie sur la valeur que vous spécifiez jusqu'à ce que l'assistant traite la partie du noeud de dialogue dans laquelle vous avez défini la variable contextuelle. Dans la plupart des cas, vous définissez la variable contextuelle dans le cadre de la réponse du noeud. Lorsque vous procédez ainsi, la variable contextuelle est créée et reçoit la valeur spécifiée lorsque l'assistant renvoie la réponse du noeud.

Pour un noeud avec des réponses conditionnelles, la variable contextuelle est créée et définie lorsque la condition pour une réponse spécifique est remplie et que cette réponse est traitée. Par exemple, si vous définissez une variable contextuelle pour la réponse conditionnelle #1 et que votre assistant traite la réponse #2, la variable que vous avez définie pour la réponse conditionnelle #1 n'est pas définie.

Pour plus d'informations sur l'ajout de variables contextuelles que votre assistant doit définir en tant qu'utilisateur interagit avec un noeud avec des attributs, voir Ajout de variables contextuelles à un noeud avec des attributs.

Ordre des opérations

Lorsque vous définissez plusieurs variables à traiter ensemble, l'ordre dans lequel vous les définissez ne détermine pas l'ordre dans lequel elles sont évaluées par l'assistant. L'assistant évalue les variables dans un ordre aléatoire. Ne définissez pas de valeur dans la première variable contextuelle et prévoyez de l'utiliser dans la deuxième variable car la première variable contextuelle risque de ne pas être exécutée avant la deuxième. Par exemple, n'utilisez pas deux variables contextuelles pour implémenter une logique qui vérifie si l'entrée utilisateur contient le mot Yes.

Utilisation de deux variables contextuelles pour rechercher une valeur dans une entrée utilisateur
Variable Valeur
user_input <? input.text ?>
contient_oui <? $user_input.contains('Yes') ?>

Utilisez plutôt une expression légèrement plus complexe pour éviter de devoir compter sur la valeur de la première variable de votre liste (user_input) en cours d'évaluation avant l'évaluation de la seconde variable (contains_yes).

Utilisation d'une seule variable contextuelle
Variable Valeur
contient_oui <? input.text.contains('Yes') ?>

Ajout de variables contextuelles à un noeud doté d'attributs

Pour plus d'informations sur les attributs, reportez-vous à la rubrique Collecte d'informations à l'aide d'attributs.

Pour ajouter une variable contextuelle qui est traitée une fois qu'une condition de réponse pour un attribut est remplie:

  1. Ouvrez le noeud avec attributs dans la vue d'édition.
  2. Cliquez sur l'icône Personnaliser l'emplacement Personnaliser l'emplacement.
  3. Cliquez sur l'icône Options Options, puis sélectionnez Activer la condition.
  4. Cliquez sur l'icône Personnaliser le gestionnaire Editer l'attribut en regard de la réponse à laquelle vous souhaitez associer la variable contextuelle.
  5. Cliquez sur l'icône Options Options dans la section des réponses de l'assistant, puis cliquez sur Ouvrir l'éditeur de contexte.
  6. Ajoutez la paire nom-valeur de la variable dans les zones Variable et Value.

Pour ajouter une variable contextuelle qui est définie ou mise à jour après qu'une condition d'attribut est remplie, procédez comme suit :

  1. Ouvrez le noeud avec attributs dans la vue d'édition.
  2. Cliquez sur l'icône Personnaliser l'emplacement Personnaliser l'emplacement.
  3. Cliquez sur l'icône Options Options, puis sélectionnez Activer la condition.
  4. Ajoutez la paire nom-valeur de la variable au format JSON.
{
"time_of_day": "morning"
}

Vous ne pouvez pas utiliser l'éditeur de contexte pour définir des variables contextuelles qui sont définies lors de cette phase d'évaluation de noeud de dialogue. Vous devez utiliser l'éditeur JSON à la place. Pour plus d'informations sur l'utilisation de l'éditeur JSON, reportez-vous à la rubrique Variables contextuelles dans l'éditeur JSON.

Variables contextuelles dans l'éditeur JSON

Vous pouvez également définir une variable contextuelle dans l'éditeur JSON. Utilisez l'éditeur JSON si vous définissez une variable contextuelle complexe et que vous souhaitez pouvoir voir l'expression SpEL complète lorsque vous l'ajoutez ou la modifiez.

La paire nom-valeur doit répondre aux exigences suivantes :

  • Le name peut contenir des caractères alphabétiques en majuscules et en minuscules, des caractères numériques (0-9) et des traits de soulignement.

    Vous pouvez inclure d'autres caractères, par exemple, des points et des traits d'union, dans le nom. Cependant, si vous le faites, vous devez spécifier la syntaxe abrégée $(variable-name) chaque fois que vous référencez la variable. Pour plus d'informations, reportez-vous à la rubrique Expressions permettant d'accéder à des objets.

  • La value peut correspondre à n'importe quel type JSON pris en charge, par exemple, une variable de chaîne simple, un nombre, un tableau JSON ou un objet JSON.

L'exemple JSON suivant définit des valeurs pour les variables contextuelles d'objet $dessert string, $toppings_array, $age number et $full_name :

{
  "context": {
    "dessert": "cake",
    "toppings_array": [
      "onions",
      "olives"
    ],
    "age": 18,
    "full_name": {
      "first": "Jane",
      "last": "Doe"
    }
  },
  "output":{}
}

Pour définir une variable contextuelle au format JSON, procédez comme suit :

  1. Cliquez pour ouvrir le noeud de dialogue auquel vous souhaitez ajouter la variable contextuelle.

    Toutes les valeurs de variable contextuelle existantes qui sont définies pour ce noeud sont affichées dans un ensemble de zones Variable et Valeur correspondantes. Si vous ne voulez pas qu'elles apparaissent dans la vue d'édition du noeud, vous devez fermer l'éditeur de contexte. La fermeture de l'éditeur peut se faire à partir du même menu que pour l'ouverture de l'éditeur JSON ; les étapes permettant d'accéder à ce menu sont décrites ci-après.

  2. Cliquez sur l'icône Options Options de la réponse de l'assistant, puis cliquez sur Ouvrir l'éditeur JSON.

    Si le paramètre Réponses conditionnées multiples est activé pour le noeud, vous devez d'abord cliquer sur l'icône Personnaliser la réponse Personnaliser la réponse pour la réponse à laquelle vous souhaitez associer la variable contextuelle.

  3. Ajoutez un bloc "context":{}, le cas échéant.

    {
  "context":{},
  "output":{}
}

  4. Dans le bloc context, ajoutez une paire "name" et "value" pour chaque variable contextuelle que vous souhaitez définir.

    {
  "context":{
    "name": "value"
},
  "output": {}
}

    Dans cet exemple, une variable nommée new_variable est ajoutée à un bloc de contexte qui contient déjà une variable.

    {
  "context":{
    "existing_variable": "value",
    "new_variable":"value"
  }
}

    Pour référencer la variable contextuelle, utilisez la syntaxe $name où name est le nom de la variable contextuelle que vous avez définie. Par exemple, $new_variable.

En savoir plus :

Suppression d'une variable contextuelle en JSON

Pour supprimer une variable contextuelle, affectez la valeur NULL à cette variable.

{
  "context": {
    "order_form": null
  }
}

Si vous souhaitez retirer toute trace de la variable contextuelle, vous pouvez utiliser la méthode JSONObject.remove(string) pour la supprimer de l'objet contextuel. Toutefois, vous devez utiliser une variable pour effectuer la suppression. Définissez la nouvelle variable dans la sortie du message de sorte qu'elle ne soit pas sauvegardée au-delà de l'appel en cours.

{
  "output": {
    "text" : {},
    "deleted_variable" : "<? context.remove('order_form') ?>"
  }
}

Vous pouvez également supprimer la variable contextuelle dans votre logique d'application.

Mise à jour d'une variable contextuelle en JSON

En général, si un noeud définit la valeur d'une variable contextuelle qui est déjà définie, la valeur précédente est écrasée par la nouvelle valeur.

Mise à jour d'un objet JSON complexe

Les valeurs précédentes sont écrasées pour tous les types JSON, sauf un objet JSON. Si la variable contextuelle est un type complexe, par exemple, un objet JSON, une procédure de fusion JSON est utilisée pour mettre à jour la variable. L'opération de fusion ajoute les propriétés nouvellement définies pour l'objet et écrase les propriétés existantes.

Dans l'exemple ci-dessous, une variable contextuelle de nom est définie en tant qu'objet complexe :

{
  "context": {
    "complex_object": {
      "user_firstname" : "Paul",
      "user_lastname" : "Pan",
      "has_card" : false
    }
  }
}

Un noeud de dialogue met à jour l'objet JSON de variable contextuelle avec les valeurs suivantes :

{
  "complex_object": {
    "user_firstname": "Peter",
    "has_card": true
  }
}

Le résultat obtenu est le contexte suivant :

{
  "complex_object": {
    "user_firstname": "Peter",
    "user_lastname": "Pan",
    "has_card": true
  }
}

Mise à jour de tableaux

Si les données contextuelles de votre dialogue contiennent un tableau de valeurs, vous pouvez mettre à jour ce tableau en ajoutant des valeurs, en retirant des valeurs ou en remplaçant toutes les valeurs.

Choisissez l'une des actions répertoriées ci-après pour mettre à jour le tableau. Dans chaque cas, nous voyons le tableau avant l'action, l'action et le tableau après l'application de l'action.

  • Action d'ajout : pour ajouter des valeurs à la fin d'un tableau, utilisez la méthode append.

    Pour le contexte d'exécution de dialogue suivant :

    {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

    Effectuez la mise à jour suivante :

    {
  "context": {
    "toppings_array": "<? $toppings_array.append('ketchup', 'tomatoes') ?>"
  }
}

    Résultat :

    {
  "context": {
    "toppings_array": ["onion", "olives", "ketchup", "tomatoes"]
  }
}

  • Action de retrait : pour retirer un élément, utilisez la méthode remove et spécifiez sa valeur ou sa position dans le tableau.

    • Action de retrait par valeur : permet de retirer un élément d'un tableau en utilisant sa valeur.

      Pour le contexte d'exécution de dialogue suivant :

      {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

      Effectuez la mise à jour suivante :

      {
  "context": {
    "toppings_array": "<? $toppings_array.removeValue('onion') ?>"
  }
}

      Résultat :

      {
  "context": {
    "toppings_array": ["olives"]
  }
}

    • Action de retrait par position : permet de retirer un élément d'un tableau en utilisant sa position dans l'index.

      Pour le contexte d'exécution de dialogue suivant :

      {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

      Effectuez la mise à jour suivante :

      {
  "context": {
    "toppings_array": "<? $toppings_array.remove(0) ?>"
  }
}

      Résultat :

      {
  "context": {
    "toppings_array": ["olives"]
  }
}

  • Remplacer: pour remplacer les valeurs d'un tableau, définissez le tableau sur les nouvelles valeurs:

    Pour le contexte d'exécution de dialogue suivant :

    {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

    Effectuez la mise à jour suivante :

    {
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

    Résultat :

    {
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

Définition d'une variable contextuelle égale à une autre

Lorsque vous définissez une variable contextuelle égale à une autre variable contextuelle, vous définissez un pointeur de l'une à l'autre. Par la suite, si la valeur de l'une des variables change, la valeur de l'autre variable change également.

Par exemple, si vous spécifiez une variable contextuelle comme suit, lorsque la valeur de $var1 ou de $var2 change ultérieurement, la valeur des autres variables change également.

Définition d'une variable contextuelle égale à une autre
Variable Valeur
var2 var1

Ne définissez pas une variable égale à une autre pour capturer une valeur de point dans le temps. Avec les tableaux, si vous souhaitez capturer une valeur de tableau stockée dans une variable contextuelle et l'utiliser ultérieurement, créez une nouvelle variable basée sur la valeur en cours de la variable à la place.

Par exemple, pour créer une copie des valeurs d'un tableau à un certain point, ajoutez un tableau rempli avec les valeurs du tableau existant. Pour ce faire, vous pouvez utiliser la syntaxe suivante :

{
"context": {
   "var2": "<? output.var2?:new JsonArray().append($var1) ?>"
 }
 }