SetDialogflowResponse policy

You're viewing Apigee X documentation.
View Apigee Edge documentation.

policy icon

Overview

The SetDialogflowResponse policy facilitates the integration of Dialogflow with Apigee. For more information, see Integrating Apigee with Contact Center AI.

The SetDialogflowResponse policy processes and formats the response data from your backend systems before sending the data as a WebhookResponse to the Dialogflow agent (bot). A Dialogflow agent requires the WebhookResponse in a specific format, and the SetDialogflowResponse policy builds the response in the required format. The policy constructs a WebhookResponse in the required format for a Dialogflow agent. The WebhookResponse has natural language phrases and other parameters that the Dialogflow agent understands.

If you are a backend service integrator, you need not spend time understanding the format of the Dialoglfow WebhookResponse. The out-of-the-box SetDialogflowResponse policy handles the processing of the response data seamlessly.

<SetDialogflowResponse>

Defines a <SetDialogflowResponse> policy.

Default Value N/A
Required? Required
Type Complex object
Parent Element N/A
Child Elements <DialogflowVersion>
<DisplayName>
<NaturalLanguageResponse>
<Parameters>
<IgnoreUnresolvedVariables>

The following table provides a high-level description of all the child elements (direct and indirect) of the SetDialogflowResponse element:

Child Element Required? Description
<DisplayName> Optional A custom name for the policy.
<DialogflowVersion> Optional Specifies the Dialogflow version.
<NaturalLanguageResponse> Optional Encapsulates all content required to be sent as as a WebhookResponse.FulfillmentResponse object.
<Parameters> Optional Parent element of <Paremeter>. Defines the set of parameters to be set in the Webhook's response.
<IgnoreUnresolvedVariables> Optional Specifies whether processing stops when an unresolved variable is encountered.
Other child elements
<MergeBehavior> Optional Specifies the merge behavior for the response messages.
<Header> Optional Extracts the value of the specified field in the response header.
<JSONPath> Optional Extracts the value of the specified JSON path.
<Parameter> Required Specifies a parameter to be set in the sessionInfo.parameters object of the Webhook's response.
<Phrase> Required Specifies the phrase (text) to be set in the fulfillmentResponse.messages object of the Webhook's response.
<Phrases> Optional Parent element of <Phrase>. Defines the set of natural language phrases to be set in the Webhook's response.
<Ref> Optional Extracts the value of the specified reference variable.
<Value> Optional Sets a custom text to the specified parameter.

Example

The following example shows a sample SetDialogflowResponse policy and the WebhookResponse sent to the Dialogflow agent:

Syntax

<?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 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>
      

SetDialogflowResponse policy

The following example shows the SetDialogflowResponse policy defnition:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetDialogflowResponse continueOnError="false" enabled="true"
        name="CCAIDialogflowResponse-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Response Policy</DisplayName>
    <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>

Go to the next sample to see the flow variables created by this policy.

Webhook response

The following example shows a WebhookResponse sent to the Dialogflow agent:

{
    "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
        }
    }
}

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Child element reference

This section describes the child elements of <SetDialogflowResponse>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<DialogflowVersion>

Specifies the Dialogflow version. The SetDialogflowResponse policy supports only the CX version. If you do not specify this element in your policy, the version defaults to CX.

Default Value N/A
Required? Optional
Type String
Parent Element <SetDialogflowResponse>
Child Elements None
The <DialogflowVersion> element uses the following syntax:

Syntax

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

Example

The following example sets the DialogflowVersion to CX:

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

Determines whether processing stops when an unresolved variable is encountered.

Default Value True
Required? Optional
Type Boolean
Parent Element <SetDialogflowResponse>
Child Elements None

Set to true to ignore unresolved variables and continue processing; otherwise false. The default value is true.

Setting <IgnoreUnresolvedVariables> to true is different from setting the <SetDialogflowResponse>'s continueOnError to true. If you set continueOnError to true, Apigee ignores all errors, not only errors in variables.

The <IgnoreUnresolvedVariables> element uses the following syntax:

Syntax

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

Example

The following example sets <IgnoreUnresolvedVariables> to false:

       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<MergeBehavior>

Defines the merge behavior for the response messages. You can specify any of the following values:

  • APPEND: Appends the messages to the list of messages waiting to be sent to the user.
  • REPLACE: Replaces the older messages with newer messages in the list of messages waiting to be sent to the user.
If you do not specify the element, the behavior defaults to APPEND.
Default Value N/A
Required? Optional
Type String
Parent Element <NaturalLanguageResponse>
Child Elements None
The <MergeBehavior> element uses the following syntax:

Syntax

<MergeBehavior>BEHAVIOR</MergeBehavior>

Example

The following example sets the merge behavior to APPEND:

<MergeBehavior>APPEND</MergeBehavior>

<NaturalLanguageResponse>

Encapsulates all the natural language response that you want to send to the Dialogflow agent.

Default Value N/A
Required? Optional
Type Complex Object
Parent Element <SetDialogflowResponse>
Child Elements <MergeBehavior>
<Phrases>

<Parameters>

Defines the set of parameters to be set in the Webhook's response. The name of the parameter is as an attribute of the <Parameter> element.

Default Value N/A
Required? Optional
Type Complex Object
Parent Element <SetDialogflowResponse>
Child Elements <Parameter>

<Parameter>

Specifies a parameter to be set in the sessionInfo.parameters object of the Webhook's response.

You can specify a static text as a parameter value or extract the value from any of the following fields in the response:

  • Response header fields
  • JSON payload
  • Flow variables

You must define a separate <Parameter> element for each value that you want to extract.

Default Value N/A
Required? Required
Type Complex Object
Parent Element <Parameters>
Child Elements <Header>
<JSONPath>
<Ref>
<Value>
The following table describes the attributes of <Parameter>:
Attribute Description Required? Type
name The name of the variable to create with this parameter. Yes String

The <Parameter> element uses the following syntax:

Syntax


<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>

Extract Header field value

This example sets the timeSpent parameter to the value of the X-Time-Spent header field.

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

Extract JSON path value

This example sets the claimAmount parameter to the value of the claim.amount field in the JSON payload.

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

Extract flow variable value

This example sets the myVar parameter to the value of the dialogflow.my.var flow variable.

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

Set custom text

This example sets the value of the responder parameter to SYSTEM.

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

<Phrases>

Parent element of <Phrase>. Defines the ordered list of natural language phrases to be set in the Webhook's response.

Default Value N/A
Required? Optional
Type Complex Object
Parent Element <NaturalLanguageResponse>
Child Elements <Phrase>

<Phrase>

Specifies the phrase (text) to be set in fulfillmentResponse.messages object of the Webhook's response.

You can specify a static text as a phrase value or extract the value from any of the following fields in the response:

  • Response header fields
  • JSON payload
  • Flow variables

You must define a separate <Phrase> element for each value you want to extract.

Default Value N/A
Required? Required
Type Complex Object
Parent Element <Phrases>
Child Elements <Header>
<JSONPath>
<Ref>
<Value>

The <Phrase> element uses the following syntax:

Syntax

<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>

Extract Header field value

This example sets a natural language text in the response to the value of the X-Response-Text header field.

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

Extract JSON path value

This example sets a natural language text in the response to the value of the claim.status.text field in the JSON payload.

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

Extract flow variable value

This example sets a natural language text in the response to the value of the myVar flow variable.

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

Set custom text

This example adds the text You call is important to us to the natural language text in the response.

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

Extracts the value from the specified field in the response header. You can use the header value either to set a natural language text or a response parameter.

  • To extract the header value as a natural language response, specify the <Header> element inside the <Phrase> element.
  • To extract the header value as a response parameter, specify the <Header> element inside the <Parameter> element.
Default Value N/A
Required? Optional
Type String
Parent Element <Phrase>
<Parameter>
Child Elements None
The <Header> element uses the following syntax:

Syntax

<Header name="HEADER_FIELD"/>

Example 1

The following example gets the value of the X-Response-Text header field as a natural language response:

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

Example 2

The following example gets the value of the X-Response-Text header field as a response parameter:

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

The timeSpent flow variable is set to the value of the X-Response-Text header field.

The <Header> element has the following attributes:

Attribute Description Required ? Type
name Specifies the name of the response header from which you extract the value. Required String

<JSONPath>

Extracts the value of a JSON path in a JSON payload of the service callout. You can use the value either to set a natural language text or a response parameter.

  • To extract the JSON value as a natural language text, specify the <JSONPath> element inside the <Phrase> element.
  • To extract the JSON value as a response parameter, specify the <JSONPath> element inside the <Parameter> element.
Default Value N/A
Required? Optional
Type String
Parent Element <Phrase>
<Parameter>
Child Elements None
The <JSONPath> element uses the following syntax:

Syntax

<JSONPath>JSON_PATH</JSONPath>

Example 1

The following example gets the value of the claim.status.text JSON field as a natural language response:

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

Example 2

The following example gets the value of the claim.amount JSON field as a response parameter:

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

The claimAmount flow variable is set to the value of the {claim.amount} JSON field.

<Ref>

Extracts the value of an existing flow variable. You can use the value either to set a natural language text or a response parameter.

  • To extract the value of a variable as a natural language text, specify the <Ref> element inside the <Phrase> element.
  • To extract the value of a variable as a response parameter, specify the <Ref> element inside the <Parameter> element.
Default Value N/A
Required? Optional
Type String
Parent Element <Phrase>
<Parameter>
Child Elements None
The <Ref> element uses the following syntax:

Syntax

<Ref>EXISTING_FLOW_VARIABLE</Ref>

Example 1

The following example gets the value of the myVar flow variable as a natural language response:

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

Example 2

The following example gets the value of the dialogflow.my.var flow variable as a response parameter:

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

The customVar flow variable is set to the value of the dialogflow.my.var variable.

<Value>

Sets a literal value to a natural language text or a response parameter.

  • To set the literal value as a natural language text, specify the <Value> element inside the <Phrase> element.
  • To set the literal value as a response parameter, specify the <Value> element inside the <Parameter> element.
Default Value N/A
Required? Optional
Type String
Parent Element <Phrase>
<Parameter>
Child Elements None
The <Value> element uses the following syntax:

Syntax

<Value>CUSTOM_TEXT</Value>

Example 1

The following example sets the literal text You call is important to us as a natural language response:

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

Example 2

The following example sets the literal text SYSTEM as a response parameter:

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

The responder flow variable is set to SYSTEM.

Error codes

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.setdialogflowresponse.ExecutionFailed 500 This error occurs when the execution of the policy failed because of a generic exception. The fault message has the details of the exception.
steps.setdialogflowresponse.MalformedInput 500 This error occurs when the JSON provided to this policy is invalid or malformed.
steps.setdialogflowresponse.UnresolvedHeader 500 This error occurs if the Header element has an invalid header. For example, if the Header element has the value X-Response-Text, and there is no X-Response-Text in the response header, you will get this error.
steps.setdialogflowresponse.UnresolvedJSONPath 500 This error occurs if the JSONPath element has an invalid path. For example, if the JSONPath element has the value {claim.status.value}, and there is no status object in the JSON payload, you will get this error.
steps.setdialogflowresponse.UnresolvedVariable 500

This error occurs if a variable specified in the SetDialogflowResponse policy is either:

  • Out of scope (not available in the specific flow where the policy is being executed)
  • or
  • Can't be resolved (is not defined)

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
UnsupportedOperation This error occurs if you have specified unsupported Dialogflow version in the DialogflowVersion element. The SetDialogflowResponse policy supports only the CX version.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="FAULT_NAME" FAULT_NAME is the name of the fault, as listed in the Runtime errors table. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
setdialogflowresponse.POLICY_NAME.failed POLICY_NAME is the user-specified name of the policy that threw the fault. setdialogflowresponse.My-Set-Dialogflow-Response.failed = true

Example error response

{
  "fault": {
    "faultstring": "Unable to resolve JSON path $.explanation1 in policy My-Set-Dialogflow-Response",
    "detail": {
      "errorcode": "steps.setdialogflowresponse.UnresolvedJSONPath"
    }
  }
}

You can configure Apigee to display custom error messages by adding fault rules in your proxy configuration. For more information about adding fault rules, see Handling faults.

Schemas

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Related topics

Reference implementations of Apigee proxies and shared flows that show the usage of the SetDialogflowResponse policy are available on Apigee GitHub. For more information, see Conversational AI Reference Implementations.