Paramètres

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Les paramètres sont utilisés pour capturer et mentionner des valeurs ayant été fournies par l'utilisateur final au cours d'une session. Chaque paramètre possède un nom et un type d'entité. Contrairement aux entrées utilisateur brutes, les paramètres sont des données structurées pouvant être utilisées pour exécuter une logique ou générer des réponses.

Les paramètres CX ressemblent aux paramètres ES, mais l'utilitaire et le champ d'application ont été étendus, et la syntaxe des paramètres de référence a changé.

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 Dialogflow, votre service qui appelle l'API, et votre service de webhook peuvent tous définir des valeurs de paramètres. Par exemple, le service Dialogflow 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, Dialogflow traite 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 Dialogflow.

Types de valeurs de paramètres

Les valeurs des paramètres acceptent plusieurs types de valeurs. La section dédiée aux sessions ci-dessous explique comment référencer chaque type de valeur de paramètre. Les types de valeurs suivants sont acceptés :

Type Description
Scalaire Valeur numérique ou de chaîne unique.
Composite Objet JSON renseigné en faisant correspondre une entité composite ou en remplissant un paramètre d'intent contenant les champs original et resolved.
Liste Liste de valeurs scalaires ou composites renseignées pour un paramètre configuré en tant que liste. Consultez les options Est une liste ci-dessous.

Paramètre vide de la chaîne et valeurs nulles

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 du paramètre

Lorsque du texte est associé à 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 l'entrée utilisateur peut être résolu en tant que "pomme" pour une entité de fruits.

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 faire référence à 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 Dialogflow.

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.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3 V3beta1
REST Ressource associée à la session Ressource associée à la session
RPC Interface de session Interface de session
C++ SessionsClient Non disponible
C# SessionsClient Non disponible
Go SessionsClient Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

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.

Le remplissage de formulaire CX ressemble au remplissage de cases ES.

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

Nom de l'option de console Chaîne de champ de l'API Description
Nom à afficher Page.form.parameters[].displayName Un nom qui identifie le paramètre.
Type d'entité Page.form.parameters[].entityType Le type d'entité associé au paramètre.
Requis Page.form.parameters[].required Indique si le paramètre est requis. Les paramètres obligatoires doivent être renseignés avant la fin du remplissage du formulaire. L'agent demande alors des valeurs à l'utilisateur final. Pour en savoir plus, consultez la section Définir des paramètres de formulaire ci-dessous.
Valeur par défaut (visible uniquement lorsque la case Obligatoire est décochée) Page.form.parameters[].defaultValue Valeur par défaut d'un paramètre facultatif. Pour en savoir plus, consultez la section Définir des paramètres de formulaire ci-dessous.
Est une liste Page.form.parameters[].isList Si le paramètre est défini sur "true", le paramètre est traité comme une liste de valeurs.
Masquer dans le journal Page.form.parameters[].redact Si la valeur est définie sur "true", les données de paramètre fournies par l'utilisateur final sont masquées.
Fulfillment d'invite initial Page.form.parameters[].fillBehavior.initialPromptFulfillment Invite initiale sous la forme de fulfillment pour demander une valeur de paramètre requise à l'utilisateur final. Pour en savoir plus, consultez la section Définir des paramètres de formulaire ci-dessous.
Gestionnaires d'événements de nouvelle invite Page.form.parameters[].fillBehavior.repromptEventHandlers Ils sont utilisés lorsque l'agent doit demander à nouveau à l'utilisateur final de remplir le paramètre en cas d'échec d'une tentative. Consultez la section Gestionnaires de nouvelles invites de remplissage de formulaires. Si aucun gestionnaire d'événements de nouvelle invite n'est défini, l'agent envoie une nouvelle invite avec les invites initiales après une tentative infructueuse.
DTMF Non disponible Consultez la section DTMF ci-dessous.

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 du formulaire avec la console, cliquez sur le titre de la section Paramètres sur la page, puis faites glisser les lignes des paramètres 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, passez la souris sur un paramètre, puis cliquez sur le bouton de suppression .

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

Dialogflow définit 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.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3 V3beta1
REST Ressource associée à la session Ressource associée à la session
RPC Interface de session Interface de session
C++ SessionsClient Non disponible
C# SessionsClient Non disponible
Go SessionsClient Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

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 les valeurs d'en-tête webhook pour l'authentification.

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

Scalaire

Pour accéder à un paramètre avec un type d'entité scalaire, procédez comme suit :

$session.params.parameter-id

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

Composite

  • Pour accéder à un membre d'un paramètre avec un type d'entité composite, procédez comme suit :

    $session.params.parameter-id.member-name

    Par exemple, si l'ID de paramètre est location, vous pouvez référencer la valeur de membre zip-code au format suivant : $session.params.location.zip-code.

  • Pour accéder à la valeur d'origine d'un paramètre avec un type d'entité composite:

    $session.params.parameter-id.original
  • Pour accéder à l'objet complet d'un paramètre avec un type d'entité composite, utilisez la fonction système IDENTITY.

Liste

  • Pour accéder à la liste complète des éléments, procédez comme suit :

    $session.params.parameter-id

    Par exemple, si l'ID du paramètre de liste est colors et que les valeurs extraites d'une requête utilisateur sont ["red", "blue", "yellow"], vous pouvez référencer toutes les valeurs au format suivant : $session.params.colors.

  • Pour accéder à l'énième élément d'un paramètre de liste :

    $session.params.parameter-id[i]

    Par exemple, si l'ID du paramètre de liste est colors, vous pouvez référencer la première valeur au format suivant : $session.params.colors[0].

Définir des paramètres de session

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

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 du webhook.

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.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3 V3beta1
REST Ressource associée à la session Ressource associée à la session
RPC Interface de session Interface de session
C++ SessionsClient Non disponible
C# SessionsClient Non disponible
Go SessionsClient Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

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.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3 V3beta1
REST Ressource associée à la session Ressource associée à la session
RPC Interface de session Interface de session
C++ SessionsClient Non disponible
C# SessionsClient Non disponible
Go SessionsClient Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

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 l'option activée, un utilisateur final d'un agent utilisant une intégration téléphonique peut utiliser le clavier téléphonique pour fournir des valeurs de 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, Dialogflow essaie 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 Dialogflow 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 :

Console

  1. Activez les Paramètres avancés dans les paramètres de synthèse vocale et de réponse vocale interactive si ce n'est pas déjà fait.
  2. Créez un paramètre de page.
  3. Dans le volet des paramètres, activez l'option Activer DTMF.
  4. Définissez Chiffres max sur le nombre maximal de chiffres que l'utilisateur final peut fournir pour ce paramètre.
  5. Définissez Finish digit (chiffre de fin) sur la valeur du clavier qui mettra fin à l'entrée DTMF pour le paramètre. Il est courant d'utiliser # pour ce paramètre. Le chiffre de fin n'est pas ajouté à la requête Dialogflow sur l'agent. Par conséquent, si le chiffre de fin est # et que l'entrée est 123#, l'entrée de requête réelle est "123".

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

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 Dialogflow. 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 :

Console

Cochez la case Masquer dans le journal lors de la création ou de la mise à jour d'un paramètre.

API

Définissez le champ parameters[].redact sur "true" pour le type Intent.

Sélectionnez un protocole et une version pour la référence de l'intent :

Protocole V3 V3beta1
REST Ressource d'intent Ressource d'intent
RPC Interface de l'intent Interface de l'intent
C++ IntentsClient Non disponible
C# IntentsClient Non disponible
Go IntentsClient Non disponible
Java IntentsClient IntentsClient
Node.js IntentsClient IntentsClient
PHP Non disponible Non disponible
Python IntentsClient IntentsClient
Ruby Non disponible Non disponible

Définissez le champ form.parameters[].redact sur "true" pour le type Page.

Sélectionnez un protocole et une version pour la référence de la page :

Protocole V3 V3beta1
REST Ressource de la page Ressource de la page
RPC Interface de la page Interface de la page
C++ PageClient Non disponible
C# PageClient Non disponible
Go PageClient Non disponible
Java PageClient PageClient
Node.js PageClient PageClient
PHP Non disponible Non disponible
Python PageClient PageClient
Ruby Non disponible Non disponible

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