Règle SetDialogflowResponse

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Présentation

La règle "SetDialogflowResponse" facilite l'intégration de Dialogflow à Apigee. Pour en savoir plus, consultez la page Intégrer Apigee à Contact Center AI.

La règle "SetDialogflowResponse" traite et met en forme les données de réponse de vos systèmes backend avant de les envoyer en tant que WebhookResponse à l'agent Dialogflow. Un agent Dialogflow nécessite la réponse "WebhookResponse" dans un format spécifique, et la règle "SetDialogflowResponse" crée la réponse au format requis. La règle crée une réponse "WebhookResponse" au format requis pour un agent Dialogflow. "WebhookResponse" comporte des expressions en langage naturel et d'autres paramètres que l'agent Dialogflow comprend.

Si vous êtes un intégrateur de services de backend, vous n'avez pas besoin de comprendre le format de la réponse Webhook Dialogflow. La règle "SetDialogflowResponse" prête à l'emploi gère le traitement des données de réponse de manière transparente.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

<SetDialogflowResponse>

Définit une règle SetDialogflowResponse.

Le tableau suivant fournit une description détaillée de tous les éléments enfants de l'élément SetDialogflowResponse :

Exemple

L'exemple suivant montre un exemple de règle "SetDialogflowResponse" et la réponse "WebhookResponse" envoyée à l'agent Dialogflow :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetDialogflowResponse continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The message variable from which the policy extracts the required information -->
    <Source>MESSAGE_VARIABLE</Source>
    <!-- The version of Dialogflow for which this response policy is written up.
         This policy supports only the CX version. This element is optional and
         defaults to CX if unspecified -->
    <DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>
    <!-- A container object to encapsulate all content needed for a natural
         language response to be returned to Dialogflow from the Southbound API -->
    <NaturalLanguageResponse>
        <!-- Defines the merge behavior for existing responses and new responses.
             Refer here for more details -->
        <MergeBehavior>MERGE_BEHAVIOR</MergeBehavior>
        <!-- An ordered list of natural language phrases to be returned to
             Dialogflow from the Southbound API -->
        <Phrases>
            <!-- A phrase is a natural language phrase that Dialogflow agents
                 can send back to their caller/chatting customer -->
            <Phrase>
                <!-- A phrase can be extracted from the response JSON payload of a
                     service callout -->
                <JSONPath>JSON_PATH</JSONPath>
            </Phrase>
            <Phrase>
                <!-- A phrase can be extracted from the response headers of a
                     service callout -->
                <Header name="HEADER_NAME"/>
            </Phrase>
            <Phrase>
                <!-- A phrase refer to the value of an existing flow variable -->
                <Ref>EXISTING_FLOW_VARIABLE</Ref>
            </Phrase>
            <Phrase>
                <!-- A phrase can be static text -->
                <Value>CUSTOM_TEXT</Value>
            </Phrase>
        </Phrases>
    </NaturalLanguageResponse>
    <!-- A container object defining the parameters to be set as session parameters
         in the Webhook response sent to Dialogflow -->
    <Parameters>
        <!-- Defines a single parameter to be set in sessionInfo.parameters object
             of the WebhookResponse object. The name of the parameter is defined
             as an attribute -->
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be extracted from the response JSON
                 payload of a service callout -->
            <JSONPath>JSON_PATH</JSONPath>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be extracted from the response headers
                 of a service callout -->
            <Header name="HEADER_NAME"/>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be refer to the value of an existing flow
                 variable -->
            <Ref>EXISTING_FLOW_VARIABLE</Ref>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be static text -->
            <Value>CUSTOM_TEXT</Value>
        </Parameter>
    </Parameters>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
</SetDialogflowResponse>
      

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetDialogflowResponse continueOnError="false" enabled="true"
        name="CCAIDialogflowResponse-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Response Policy</DisplayName>
    <Source>myMessageVar</Source>
    <DialogflowVersion>CX</DialogflowVersion>
    <NaturalLanguageResponse>
        <MergeBehavior>APPEND</MergeBehavior>
        <Phrases>
            <Phrase>
                <JSONPath>$.claim.status.text</JSONPath>
            </Phrase>
            <Phrase>
                <Header name="X-Response-Text"/>
            </Phrase>
            <Phrase>
                <Ref>myVar</Ref>
            </Phrase>
            <Phrase>
                <Value>You call is important to us</Value>
            </Phrase>
        </Phrases>
    </NaturalLanguageResponse>
    <Parameters>
        <Parameter name="claimStatus">
            <JSONPath>$.claim.status.value</JSONPath>
        </Parameter>
        <Parameter name="claimAmount">
            <JSONPath>$.claim.amount</JSONPath>
        </Parameter>
        <Parameter name="timeSpent">
            <Header name="X-Time-Spent"/>
        </Parameter>
        <Parameter name="myVar">
            <Ref>dialogflow.my.var</Ref>
        </Parameter>
        <Parameter name="responder">
            <Value>SYSTEM</Value>
        </Parameter>
    </Parameters>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</SetDialogflowResponse>

{
    "fulfillmentResponse": {
        "mergeBehavior": "APPEND",
        "messages": [{
            "text": {
                "text": ["Your claim is currently being processed",
                          "Please call back in a couple of days"]
            }
        }]
    },
    "sessionInfo": {
        "parameters": {
            "claimStatus": "PROCESSING",
            "claimAmount": 1000
        }
    }
}

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Référence d'élément enfant

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

L'élément <DisplayName> utilise la syntaxe suivante :

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<Source>

Spécifie la variable à analyser. La valeur <Source> est définie sur message par défaut. La valeur message est sensible au contexte. Dans un flux de requête, message renvoie le message de requête. Dans un flux de réponse, message renvoie le message de réponse.

Cette règle sert souvent à extraire des informations d'un message de requête ou de réponse, mais vous pouvez l'utiliser pour extraire des informations de n'importe quelle variable. Par exemple, vous pouvez l'utiliser pour extraire des informations d'une entité créée par la règle AccessEntity, des données renvoyées par la règle ServiceCallout, ou extraire des informations d'un objet XML ou JSON.

Si <Source> ne peut être résolu ou est associé à un type qui n'est pas un message, la règle échoue et une erreur d'exécution est générée.

<Source>MESSAGE_VARIABLE</Source>

<Source>myMessageVar</Source>

<DialogflowVersion>

Spécifie la version de Dialogflow. La règle "SetDialogflowResponse" n'est compatible qu'avec la version CX. Si vous ne spécifiez pas cet élément dans votre règle, la version par défaut est CX.

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false. La valeur par défaut est true.

Définir <IgnoreUnresolvedVariables> sur true n'est pas la même chose que définir la valeur continueOnError de <SetDialogflowResponse> sur true. Si vous définissez continueOnError sur true, Apigee ignore toutes les erreurs, et pas seulement les erreurs dans les variables.

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

 <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<MergeBehavior>

Définit le comportement de fusion des messages de réponse. Vous pouvez spécifier l'une des valeurs suivantes :

• APPEND : ajoute les messages à la liste des messages en attente d'envoi à l'utilisateur.
• REPLACE : remplace les anciens messages par des messages plus récents dans la liste des messages en attente d'envoi à l'utilisateur.

<MergeBehavior>BEHAVIOR</MergeBehavior>

<MergeBehavior>APPEND</MergeBehavior>

<NaturalLanguageResponse>

Encapsule toutes les réponses en langage naturel que vous souhaitez envoyer à l'agent Dialogflow.

<Parameters>

Définit l'ensemble de paramètres à définir dans la réponse du webhook. Le nom du paramètre est un attribut de l'élément <Parameter>.

<Parameter>

Spécifie un paramètre à définir dans l'objet sessionInfo.parameters de la réponse du webhook.

Vous pouvez spécifier un texte statique en tant que valeur de paramètre ou extraire la valeur de l'un des champs suivants de la réponse :

• Champs d'en-tête de réponse
• Données utiles JSON
• Variables de flux

Vous devez définir un élément <Parameter> distinct pour chaque valeur que vous souhaitez extraire.

L'élément <Parameter> utilise la syntaxe suivante :

<Parameters>
  <Parameter name="PARAMETER_NAME">
  <Header name="HEADER_NAME"/>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <JSONPath>JSON_PATH</JSONPath>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <Ref>EXISTING_FLOW_VARIABLE</Ref>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <Value>CUSTOM_TEXT</Value>
</Parameter>
</Parameters>

<Parameter name="timeSpent">
     <Header name="X-Time-Spent"/>
</Parameter>

<Parameter name="claimAmount">
   <JSONPath>$.claim.amount</JSONPath>
</Parameter>

<Parameter name="myVar">
   <Ref>dialogflow.my.var</Ref>
</Parameter>
       

<Parameter name="responder">
   <Value>SYSTEM</Value>
</Parameter>

<Phrases>

Élément parent de <Phrase>. Définit la liste numérotée des expressions en langage naturel à définir dans la réponse du Webhook.

<Phrase>

Spécifie la phrase (texte) à définir dans l'objet fulfillmentResponse.messages de la réponse du Webhook.

Vous pouvez spécifier un texte statique en tant que valeur de d'expression ou extraire la valeur de l'un des champs suivants de la réponse :

• Champs d'en-tête de réponse
• Données utiles JSON
• Variables de flux

Vous devez définir un élément <Phrase> distinct pour chaque valeur que vous souhaitez extraire.

L'élément <Phrase> utilise la syntaxe suivante :

<Phrases>
  <Phrase>
    <Header name="HEADER_NAME"/>
  </Phrase>
  <Phrase>
    <JSONPath>JSON_PATH</JSONPath>
  </Phrase>
  <Phrase>
    <Ref>EXISTING_FLOW_VARIABLE</Ref>
  </Phrase>
  <Phrase>
    <Value>CUSTOM_TEXT</Value>
  </Phrase>
</Phrases>

<Phrase>
     <Header name="X-Response-Text"/>
</Phrase>

<Phrase>
   <JSONPath>$.claim.status.text</JSONPath>
</Phrase>

<Phrase>
   <Ref>myVar</Ref>
</Phrase>
       

<Phrase>
   <Value>You call is important to us</Value>
</Phrase>

<Header>

Extrait la valeur du champ spécifié dans l'en-tête de réponse. Vous pouvez utiliser la valeur d'en-tête pour définir soit un texte en langage naturel, soit un paramètre de réponse.

• Pour extraire la valeur d'en-tête en tant que réponse en langage naturel, spécifiez l'élément <Header> dans l'élément <Phrase>.
• Pour extraire la valeur de l'en-tête en tant que paramètre de réponse, spécifiez l'élément <Header> dans l'élément <Parameter>.

<Header name="HEADER_FIELD"/>

<Phrase>
  <Header name="X-Response-Text"/>
<Phrase/>

<Parameter name="timeSpent">
  <Header name="X-Response-Text"/>
<Parameter/>

L'élément <Header> possède les attributs suivants :

<JSONPath>

Extrait la valeur d'un chemin JSON dans une charge utile JSON de l'appel de service. Vous pouvez utiliser la valeur pour définir soit un texte en langage naturel, soit un paramètre de réponse.

• Pour extraire la valeur JSON en tant que texte en langage naturel, spécifiez l'élément <JSONPath> dans l'élément <Phrase>.
• Pour extraire la valeur JSON en tant que paramètre de réponse, spécifiez l'élément <JSONPath> dans l'élément <Parameter>.

<JSONPath>JSON_PATH</JSONPath>

<Phrase>
  <JSONPath>$.claim.status.text</JSONPath>
<Phrase/>

<Parameter name="claimAmount">
  <JSONPath>$.claim.amount.</JSONPath>
<Parameter/>

<Ref>

Extrait la valeur d'une variable de flux existante. Vous pouvez utiliser la valeur pour définir soit un texte en langage naturel, soit un paramètre de réponse.

• Pour extraire la valeur d'une variable en tant que texte en langage naturel, spécifiez l'élément <Ref> dans l'élément <Phrase>.
• Pour extraire la valeur d'une variable en tant que paramètre de réponse, spécifiez l'élément <Ref> dans l'élément <Parameter>.

<Ref>EXISTING_FLOW_VARIABLE</Ref>

<Phrase>
  <Ref>myVar</Ref>
<Phrase/>

<Parameter name="customVar">
  <Ref>dialogflow.my.var</Ref>
<Parameter/>

<Value>

Définit une valeur littérale sur un texte en langage naturel ou un paramètre de réponse.

• Pour définir la valeur littérale sous forme de texte en langage naturel, spécifiez l'élément <Value> dans l'élément <Phrase>.
• Pour définir la valeur littérale en tant que paramètre de réponse, spécifiez l'élément <Value> dans l'élément <Parameter>.

<Value>CUSTOM_TEXT</Value>

<Phrase>
  <Value>You call is important to us</Value>
<Phrase/>

<Parameter name="responder">
  <Value>SYSTEM</Value>
<Parameter/>

Codes d'erreur

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Chaque fois qu'une règle comporte des erreurs d'exécution, Apigee génère des messages d'erreur. Vous pouvez afficher ces messages d'erreur dans la réponse d'erreur. Souvent, les messages d'erreur générés par le système peuvent ne pas être pertinents dans le contexte de votre produit. Vous pouvez personnaliser les messages d'erreur en fonction du type d'erreur pour rendre les messages plus significatifs.

Pour personnaliser les messages d'erreur, vous pouvez utiliser des règles d'erreur ou la règle RaiseFault. Pour en savoir plus sur les différences entre les règles d'erreur et la règle RaiseFault, consultez la section Règles d'erreur et règle RaiseFault. Vous devez vérifier les conditions à l'aide de l'élément Condition dans les règles d'erreur et dans la règle RaiseFault. Apigee fournit des variables d'erreur propres à chaque règle et les valeurs des variables d'erreur sont définies lorsqu'une règle déclenche des erreurs d'exécution. En utilisant ces variables, vous pouvez vérifier des conditions d'erreur spécifiques et prendre les mesures appropriées. Pour en savoir plus sur la vérification des conditions d'erreur, consultez la page Conditions de création.

Le tableau suivant décrit les variables d'erreur spécifiques à cette règle.

Articles associés

Les implémentations de référence des proxys Apigee et des flux partagés qui montrent l'utilisation de la règle "SetDialogflowResponse" sont disponibles sur Apigee GitHub. Pour en savoir plus, consultez la page Implémentations de référence pour l'IA conversationnelle.