Paramètres

Définir, référencer, régler et obtenir des paramètres

Il existe quatre façons générales d'utiliser les paramètres :

• Définir au moment de la conception : lors de la conception, vous utilisez la console ou l'API pour définir les paramètres. Par exemple, vous pouvez définir un paramètre d'intent et l'utiliser dans une phrase d'entraînement pour indiquer une entrée d'utilisateur final à extraire.
• Références au moment de la conception : les références de paramètres sont des variables contenant des valeurs de paramètre à extraire lors de l'exécution. Au moment de la conception, vous utilisez la console ou l'API pour référencer des paramètres dans différents types de données. Par exemple, vous pouvez référencer un paramètre de session dans une réponse de fulfillment statique pour une route.
• Définition au moment de l'exécution : au moment de l'exécution, le service d'agents conversationnels (Dialogflow CX), votre service qui appelle l'API et votre service de webhook peuvent tous définir des valeurs de paramètres. Par exemple, le service d'agents conversationnels (Dialogflow CX) définit la valeur d'un paramètre d'intent lorsqu'une entrée d'utilisateur final correspond à l'intent et que cette entrée contient des données de paramètre.
• Obtention au moment de l'exécution : au moment de l'exécution, vos références de paramètres contiennent les valeurs de paramètres qui ont été définies. Vous pouvez utiliser l'API ou un webhook pour les obtenir. Par exemple, lorsqu'un intent est mis en correspondance et que votre webhook est appelé, votre service de webhook reçoit les valeurs des paramètres de l'intent.

Nommer les paramètres

Les règles suivantes s'appliquent à l'attribution de noms aux paramètres :

• Utilisez les caractères suivants : [A-Z], [a-z], [0-9], ., -, _.
• Les noms de paramètres n'étant pas sensibles à la casse, les agents de conversation (Dialogflow CX) traitent Apple et apple comme étant le même paramètre. Le webhook et le code client de l'API doivent également traiter les noms de paramètres comme n'étant pas sensibles à la casse, car il n'y a aucune garantie quant à la casse des noms de paramètres renvoyés par les agents de conversation (Dialogflow CX).
• Lorsque vous créez des paramètres avec le même ID ou le même nom à afficher dans différents intents ou formulaires, assurez-vous que le type d'entité et les autres paramètres sont les mêmes pour toutes les définitions. Si le type d'entité ou d'autres paramètres de paramètre diffèrent, utilisez un ID ou un nom à afficher unique pour chaque définition.

Types de valeurs de paramètres

Les valeurs de paramètre acceptent plusieurs types de valeurs. La section "Sessions" ci-dessous décrit comment faire référence à chaque type de valeur de paramètre. Les types de valeurs suivants sont acceptés :

Chaîne vide et valeurs nulles du paramètre

Vous pouvez définir les valeurs de paramètre de chaîne sur "", ce qui définit le paramètre sur la chaîne vide.

Vous pouvez définir n'importe quelle valeur de paramètre sur null, ce qui indique que le paramètre n'a pas été défini.

Valeurs d'origine des paramètres

Lorsque du texte est mis en correspondance avec une entité particulière au moment de l'exécution, il est souvent résolu en une valeur plus pratique pour le traitement. Par exemple, le mot "pommes" dans les entrées saisies par l'utilisateur final peut être résolu en tant que "pomme" pour une entité fruitière.

Tous les types de valeurs pour les références de paramètres d'intent peuvent faire référence à la valeur d'origine ou à la valeur résolue.

Seuls les types de valeurs composites pour les références de paramètres de session peuvent faire référence à la valeur d'origine.

Paramètres d'intent

Les intents utilisent des paramètres pour extraire les données fournies par les utilisateurs finaux lorsque les intents sont mis en correspondance. Les données suivantes sont utilisées pour définir un paramètre d'intent :

• Nom (également appelé ID ou Nom à afficher) : nom qui identifie le paramètre.
• Type d'entité : type d'entité associé au paramètre.
• Est une liste : si le paramètre est défini sur "vrai", le paramètre est traité comme une liste de valeurs.
• Masquer dans le journal : si la valeur est définie sur "true", les données de paramètre fournies par l'utilisateur final sont masquées.

Définir des paramètres d'intent

Les paramètres d'intent sont définis au moment de la conception lors de la création des données d'intent ou lors de l'annotation de phrases d'entraînement.

Paramètres d'intent de référence

Les références des paramètres d'intent peuvent être utilisées dans les messages de réponse de fulfillment statique des routes d'intents.

Vous pouvez référencer la valeur d'origine ou la valeur résolue.

Pour référencer un paramètre pour l'intent actuellement associé, utilisez l'un des formats suivants :

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

Par exemple, si l'ID de paramètre est date, vous pouvez référencer la valeur résolue au format suivant : $intent.params.date.resolved.

Définir des paramètres d'intent

Lorsqu'une entrée d'utilisateur final correspond à un intent au moment de l'exécution, tout paramètre utilisé par une annotation pour la phrase d'entraînement associée est défini par les agents conversationnels (Dialogflow CX).

Le fulfillment d'une route d'intent peut utiliser un préréglage des paramètres de fulfillment pour définir une valeur de paramètre d'intent au moment de l'exécution.

Obtenir des paramètres d'intent

Lors du tour de conversation dans lequel un intent est mis en correspondance, votre code peut accéder aux valeurs des paramètres d'intent.

Les interactions avec l'API renverront les valeurs du paramètre d'intent. Consultez le champ de réponse queryResult.parameters de la méthode detectIntent pour le type Session. Accéder à la documentation de référence de l'API Session

Le webhook reçoit les valeurs de paramètre de l'intent. Consultez le champ intentInfo.parameters dans la requête du webhook.

Paramètres de formulaire

Pour chaque page, vous pouvez définir un formulaire, qui est une liste de paramètres devant être collectés par l'utilisateur final pour la page. L'agent interagit avec l'utilisateur final pour plusieurs tours de conversation, jusqu'à ce qu'il ait collecté tous les paramètres du formulaire requis, également appelés paramètres de page L'agent collecte ces paramètres dans l'ordre défini sur la page. Pour chaque paramètre du formulaire requis, vous fournissez également des invites que l'agent utilise pour demander ces informations à l'utilisateur final. Ce processus est appelé le remplissage du formulaire.

Par exemple, vous pouvez créer un formulaire qui recueille le nom et le numéro de téléphone de l'utilisateur final pour une page Collect Customer Info.

Les données suivantes sont utilisées pour définir un paramètre de formulaire :

Définir et gérer des paramètres de formulaire

Les paramètres du formulaire sont définis au moment de la conception lors de la création d'une page.

Pour modifier l'ordre des paramètres de formulaire à l'aide de la console, cliquez sur le titre de la section Paramètres sur la page, puis faites glisser les lignes de paramètre dans le tableau des paramètres.

Pour supprimer un paramètre de formulaire, cliquez sur le titre de la section Paramètres sur la page, pointez sur un paramètre, puis cliquez sur le bouton de suppression delete.

Paramètres du formulaire de référence

Les références des paramètres du formulaire ne sont pas utilisées directement. Vous ne pouvez vérifier l'état de remplissage que pour les paramètres de formulaire individuels ou pour l'ensemble du formulaire. Vous pouvez utiliser ces références d'état du formulaire dans une exigence de condition d'une route de condition.

Pour vérifier si le formulaire de la page actuelle est rempli, utilisez la condition suivante :

$page.params.status = "FINAL"

Pour vérifier si un paramètre de formulaire particulier a été rempli lors du dernier tour, utilisez la condition suivante :

$page.params.parameter-id.status = "UPDATED"

Définir des paramètres de formulaire

Les valeurs des paramètres de formulaire peuvent être définies de différentes manières. Les sous-sections suivantes décrivent chaque mécanisme permettant de définir les valeurs des paramètres de formulaire.

Valeurs des paramètres par défaut

Vous pouvez fournir des valeurs par défaut pour les paramètres de formulaire facultatifs. Au début du remplissage du formulaire, tous les paramètres facultatifs du formulaire non définis sont définis sur leurs valeurs par défaut. Ces valeurs peuvent être initialisées ou remplacées par certains des mécanismes ci-dessous.

Si un paramètre est obligatoire, sa valeur par défaut est ignorée.

Remplissage de formulaire

Les agents conversationnels (Dialogflow CX) définissent automatiquement les valeurs de paramètre fournies par l'utilisateur final lors du remplissage du formulaire. L'agent collecte les paramètres obligatoires dans l'ordre défini sur la page. L'agent invite l'utilisateur final à saisir les valeurs requises à l'aide du fulfillment initial des invites que vous fournissez pour chaque paramètre requis. Les paramètres facultatifs ne déclenchent pas d'invites.

Si la valeur du paramètre requis n'est pas fournie par l'utilisateur final après une invite d'agent, l'invite initiale est répétée, sauf si un comportement différent est défini dans les gestionnaires de nouvelles invites. Si plusieurs invites de texte initiales sont définies, le comportement de l'agent est identique à celui des réponses textuelles de fulfillment.

Propagation des paramètres de l'intent et de session

Lorsqu'un paramètre de n'importe quel type est défini au moment de l'exécution, il est écrit dans la session et devient un paramètre de session.

Lorsqu'une page devient initialement active, et au cours de sa période d'activité, tout paramètre de formulaire portant le même nom qu'un paramètre de session est automatiquement défini sur la valeur du paramètre de session.

Cela peut se produire avec un paramètre d'intent correspondant dans une route d'intent ou une propagation de paramètre.

La propagation des paramètres d'intent et de session est le seul moyen de définir des paramètres de formulaire facultatifs sur les valeurs saisies par l'utilisateur final. Cependant, ce mécanisme peut également définir ou remplacer les valeurs de paramètres de formulaire requises.

Préréglages des paramètres de fulfillment

Le fulfillment pour une route, un gestionnaire d'événements ou une nouvelle invite de formulaire peut utiliser un préréglage de paramètre de fulfillment pour définir une valeur de paramètre de formulaire au moment de l'exécution. Un préréglage des paramètres de fulfillment remplace une valeur de paramètre, y compris les valeurs par défaut des paramètres.

Configuration des paramètres de webhook

Votre webhook peut définir les valeurs des paramètres du formulaire au moment de l'exécution. Consultez le champ pageInfo.formInfo.parameterInfo dans la réponse Webhook.

Obtenir des paramètres de formulaire

Les interactions avec l'API renvoient les valeurs des paramètres de formulaire. Consultez le champ de réponse queryResult.parameters de la méthode detectIntent pour le type Session. Accéder à la documentation de référence de l'API Session

Le webhook reçoit les valeurs de paramètre du formulaire. Consultez le champ pageInfo.formInfo.parameterInfo dans la requête du webhook.

Gestionnaires de nouvelles invites de remplissage de formulaires

Les gestionnaires de nouvelles invites, également appelés gestionnaires d'événements au niveau des paramètres, permettent de définir le comportement complexe d'invite de paramètres pour les paramètres requis. Par exemple, les gestionnaires de nouvelles invites peuvent être utilisés pour modifier l'invite lorsque l'utilisateur final ne fournit pas de valeur après l'invite initiale et pour passer à une autre page après N tentatives infructueuses.

Si aucun gestionnaire de nouvelles invites n'est défini, l'invite initiale est à nouveau soumise à l'utilisateur final si nécessaire.

Si l'utilisateur final répond par une entrée inattendue, un événement sys.no-match-* ou sys.no-input-* est appelé, et tous les gestionnaires de nouvelles invites définis pour ces événements sont appelés.

Comme d'autres gestionnaires d'événements, un gestionnaire de nouvelles invites est un type de gestionnaire d'état pouvant être configuré avec l'un des éléments suivants, ou les deux :

• Un fulfillment pour fournir un message de nouvelle invite à l'utilisateur final et/ou un préréglage de paramètres.
• Une cible de transition permettant de modifier la page actuelle

Paramètres de session

Lorsqu'un paramètre de n'importe quel type est défini au moment de l'exécution, il est écrit dans la session et devient un paramètre de session. Ces paramètres ne sont pas explicitement définis au moment de la conception. Vous pouvez référencer ces paramètres de session à tout moment au cours d'une session.

Paramètres de session de référence

Les références de paramètres de session peuvent être utilisées dans les messages de réponse statique pour les types de fulfillment suivants :

• Fulfillment des entrées de page
• Fulfillment de la route
• Fulfillment du gestionnaire d'événements
• Fulfillment d'invite de formulaire
• Fulfillment de nouvelle invite de formulaire

Les références peuvent également être utilisées dans:

• Valeurs d'en-tête de webhook pour l'authentification.
• Requêtes de webhook flexibles, pour envoyer des valeurs de paramètre à un webhook.

Pour référencer un paramètre de session, utilisez les formats suivants :

$session.params.parameter-id

Définir des paramètres de session

Une fois le formulaire rempli, les paramètres renseignés sont écrits dans la session par les agents conversationnels (Dialogflow CX).

Le fulfillment pour une route, un gestionnaire d'événements ou une nouvelle invite de formulaire peut utiliser un préréglage de paramètre de fulfillment pour définir une valeur de paramètre de session au moment de l'exécution.

Votre webhook peut définir les valeurs des paramètres de session lors de l'exécution. Consultez le champ sessionInfo.parameters dans la réponse de webhook standard ou la réponse de webhook flexible.

Les interactions avec l'API peuvent définir des valeurs de paramètres de session. Consultez le champ de requête queryParams.parameters de la méthode detectIntent pour le type Session. Accéder à la documentation de référence de l'API Session

Obtenir des paramètres de session

Les interactions avec l'API renverront les valeurs du paramètre de la session. Consultez le champ de réponse queryResult.parameters de la méthode detectIntent pour le type Session. Accéder à la documentation de référence de l'API Session

Le webhook reçoit les valeurs de paramètre de la session. Consultez le champ sessionInfo.parameters dans la requête du webhook.

Propagation des paramètres

Lorsqu'une entrée d'utilisateur final fournit une valeur de paramètre, le paramètre peut être propagé vers d'autres niveaux :

• Lorsqu'un paramètre d'intent est défini par une correspondance d'intent, les paramètres de formulaire ayant un nom similaire de la page active sont définis sur la même valeur. Le type d'entité du paramètre est déterminé par la définition du paramètre d'intent.
• Lorsqu'un paramètre d'intent est défini par une correspondance d'intent ou qu'un paramètre de formulaire est défini lors du remplissage du formulaire, le paramètre devient un paramètre de session.

DTMF pour les intégrations de téléphonie

Vous pouvez activer et configurer DTMF (signaux à double fréquence) pour un paramètre. Une fois activé, un utilisateur final d'un agent utilisant une intégration de téléphonie peut utiliser le clavier téléphonique pour fournir les valeurs des paramètres.

Pour réduire toute ambiguïté, les entrées DTMF peuvent être interprétées sous les formes normale et spécifique à DTMF (recommandées) :

• La forme normale est simplement les valeurs du clavier telles qu'elles ont été saisies par l'utilisateur final. Par exemple, 123#.
• Le formulaire spécifique à DTMF convertit l'entrée en dtmf_digits_[digits], où [digits] correspond aux chiffres DTMF d'origine, avec * remplacé par star et # remplacé. avec pound. Par exemple, 123# est interprété comme dtmf_digits_123pound.

Lors de la mise en correspondance des types d'entités pour un paramètre, les agents de conversation (Dialogflow CX) tentent de faire correspondre les formulaires normaux et spécifiques à DTMF. Lorsqu'un type d'entité est utilisé pour une entrée DTMF, il est recommandé de définir des synonymes tels que dtmf_digits_123 pour améliorer la mise en correspondance de la NLU.

Si l'entrée DTMF ne remplit pas la condition de fin (soit elle n'a pas atteint la longueur maximale de chiffres, soit elle n'a pas été arrêtée par le chiffre de fin). L'agent Conversational Agents (Dialogflow CX) continue à attendre d'autres entrées. Au cours de cette période, si le délai avant expiration de la reconnaissance vocale est déclenché, l'agent appelle alors un événement sans entrée. Si seul un énoncé est détecté, l'agent fait la correspondance avec l'entrée vocale. Si les données vocales et les entrées DTMF sont détectées, l'entrée vocale est ignorée et seule l'entrée DTMF est prise en compte.

Pour activer et personnaliser le DTMF pour un paramètre, procédez comme suit :

Lorsque vous créez votre agent, vous pouvez tester les entrées DTMF dans le simulateur.

Point de terminaison intelligent

Si la terminaison intelligente est activée pour l'agent, vous pouvez personnaliser son comportement pour un paramètre numérique.

1. Définissez Chiffres minimaux pour indiquer au pointeur intelligent d'attendre que tous les chiffres aient été collectés.
2. Définissez Corriger les transcriptions pour améliorer la reconnaissance vocale des chiffres en corrigeant les erreurs de transcription courantes. Cette fonctionnalité n'est disponible que pour les requêtes qui spécifient un code de langue en ou en-*.
3. Définissez Waiting timeout (Délai d'attente) pour spécifier le temps supplémentaire pendant lequel les agents de conversation (Dialogflow CX) attendent que l'utilisateur fournisse d'autres entrées.

Paramètres de portée de flux

Les paramètres de portée de flux peuvent être définis en tant que préréglages de paramètre de fulfillment ou paramètres de formulaire. Ces paramètres ne peuvent être référencés que lorsque le flux dans lequel ils sont définis est actif. Ils ne sont pas conservés dans les paramètres de session.

Pour définir ou référencer un paramètre de portée flux, utilisez la syntaxe suivante:

$flow.parameter-name

Par exemple, si le nom du paramètre est date, vous pouvez le définir ou le référencer comme $flow.date.

Notez que l'utilisation d'un préfixe $ lors de la définition des paramètres est différente des autres types de paramètres qui n'utilisent pas $ pour les définitions de paramètres.

Exemple de définition de paramètre de portée flux :

Durée de vie des valeurs de paramètre de portée flux

Il est rare, mais dans certains cas avancés, vous devrez peut-être comprendre comment les valeurs de paramètres de portée de flux sont conservées (ou supprimées) lorsqu'un flux devient inactif, puis actif à nouveau.

Le fait que les valeurs de paramètres de portée de flux soient conservées lorsqu'un flux devient inactif, puis actif à nouveau, dépend de la pile de flux et des instances de flux sur la pile.

• Lorsque le flux A passe au flux B à l'aide d'une cible de transition spécifique, le flux A (flux parent) reste sur la pile, conserve ses valeurs de paramètre de portée de flux et une nouvelle instance du flux B (flux enfant) est ajoutée à la pile.
• Lorsqu'un flux enfant revient à un flux parent à l'aide d'une cible de transition symbolique (par exemple, END_FLOW), le flux enfant est supprimé de la pile, toutes les valeurs de paramètre de portée enfant sont supprimées et toutes les valeurs de paramètre de portée parent sont conservées.
• À l'aide d'une série de transitions avec des cibles de transition spécifiques, la pile de flux peut contenir plusieurs instances d'un même type de flux. Chaque instance du type de flux possède des valeurs de paramètres uniques au niveau du flux. Par exemple: A1 -> B1 -> C1 -> B2, où A, B et C sont des types de flux, et les nombres désignent des instances de ces types de flux. Dans cet exemple, B1 et B2 sont différentes instances du flux B et disposent de paramètres uniques de portée flux.

Exemples :

Paramètres de portée de requête

Les paramètres de portée de requête sont des paramètres de courte durée créés par les agents conversationnels (Dialogflow CX). Ils ne peuvent être référencés que pendant le cycle de vie de la requête en cours et ne sont pas conservés dans les paramètres de session.

Les paramètres de portée de la requête sont générés par les agents conversationnels (Dialogflow CX) pour les fonctionnalités suivantes.

Paramètres intégrés

Vous pouvez accéder aux différentes données associées à la requête à l'aide des éléments suivants:

Charge utile personnalisée

Lorsque QueryParameters.payload est défini, vous pouvez accéder au paramètre correspondant via $request.payload.param-id.

Analyse des sentiments

Les références de sentiment suivantes sont disponibles lorsque l'analyse des sentiments est activée:

Masquage du paramètre

Pour tout paramètre d'intent ou de formulaire, vous pouvez activer le masquage des paramètres afin de masquer les données de paramètre d'exécution pour l'utilisateur final dans les journaux et le stockage interne des agents conversationnels (Dialogflow CX). Les paramètres masqués sont affichés sous la forme $parameter-name_redacted dans les journaux.

Par exemple, considérons une entrée d'utilisateur final "Mon adresse est 1600 Amphitheatre Parkway" qui génère l'envoi d'un paramètre adresse à "1600 Parkway Parkway". Le texte enregistré sera "Mon adresse est $address_redacted".

Pour activer le masquage des paramètres, procédez comme suit :

Vous pouvez également masquer tous les paramètres d'un type d'entité spécifique.