Política SetDialogflowResponse

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Información general

La política SetDialogflowResponse facilita la integración de Dialogflow con Apigee. Para obtener más información, consulta Integrar Apigee con Contact Center AI.

La política SetDialogflowResponse procesa y da formato a los datos de respuesta de tus sistemas backend antes de enviar los datos como WebhookResponse al agente de Dialogflow. Un agente de Dialogflow requiere que WebhookResponse tenga un formato específico, y la política SetDialogflowResponse crea la respuesta con el formato necesario. La política crea un WebhookResponse con el formato necesario para un agente de Dialogflow. El objeto WebhookResponse tiene frases en lenguaje natural y otros parámetros que el agente de Dialogflow entiende.

Si eres integrador de servicios de backend, no tienes que dedicar tiempo a entender el formato de WebhookResponse de Dialogflow. La política SetDialogflowResponse predefinida gestiona el procesamiento de los datos de respuesta sin problemas.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

<SetDialogflowResponse>

Define una política SetDialogflowResponse.

En la siguiente tabla se ofrece una descripción general de todos los elementos secundarios del elemento SetDialogflowResponse:

Ejemplo

En el siguiente ejemplo se muestra una política SetDialogflowResponse de muestra y la WebhookResponse enviada al agente de 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
        }
    }
}

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Referencia de elemento secundario

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

El elemento <DisplayName> es común a todas las políticas.

El elemento <DisplayName> utiliza la siguiente sintaxis:

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

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Source>

Especifica la variable que se va a analizar. El valor de <Source> es message de forma predeterminada. El valor message depende del contexto. En un flujo de solicitudes, message se resuelve en el mensaje de solicitud. En un flujo de respuesta, message se resuelve en el mensaje de respuesta.

Aunque esta política se suele usar para extraer información de un mensaje de solicitud o respuesta, también se puede usar para extraer información de cualquier variable. Por ejemplo, puedes usarla para extraer información de una entidad creada por la política AccessEntity, de datos devueltos por la política ServiceCallout o de un objeto XML o JSON.

Si <Source> no se puede resolver o se resuelve en un tipo que no es de mensaje, la política falla y se produce un error de tiempo de ejecución.

<Source>MESSAGE_VARIABLE</Source>

<Source>myMessageVar</Source>

<DialogflowVersion>

Especifica la versión de Dialogflow. La política SetDialogflowResponse solo admite la versión CX. Si no especifica este elemento en su política, la versión será CX de forma predeterminada.

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver.

Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento. De lo contrario, asigna el valor false. El valor predeterminado es true.

Asignar el valor true a <IgnoreUnresolvedVariables> no es lo mismo que asignar el valor true a continueOnError de <SetDialogflowResponse>. Si asigna el valor true a continueOnError, Apigee ignora todos los errores, no solo los de las variables.

El elemento <IgnoreUnresolvedVariables> utiliza la siguiente sintaxis:

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

       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<MergeBehavior>

Define el comportamiento de combinación de los mensajes de respuesta. Puedes especificar cualquiera de los siguientes valores:

• APPEND: añade los mensajes a la lista de mensajes que están esperando a enviarse al usuario.
• REPLACE: sustituye los mensajes antiguos por mensajes más recientes en la lista de mensajes que están esperando a enviarse al usuario.

<MergeBehavior>BEHAVIOR</MergeBehavior>

<MergeBehavior>APPEND</MergeBehavior>

<NaturalLanguageResponse>

Encapsula toda la respuesta en lenguaje natural que quieras enviar al agente de Dialogflow.

<Parameters>

Define el conjunto de parámetros que se van a definir en la respuesta del webhook. El nombre del parámetro se indica como atributo del elemento <Parameter>.

<Parameter>

Especifica un parámetro que se va a definir en el objeto sessionInfo.parameters de la respuesta del webhook.

Puede especificar un texto estático como valor de un parámetro o extraer el valor de cualquiera de los siguientes campos de la respuesta:

• Campos de encabezado de respuesta
• Carga útil de JSON
• Variables de flujo

Debes definir un elemento <Parameter> independiente para cada valor que quieras extraer.

El elemento <Parameter> utiliza la siguiente sintaxis:

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

Elemento principal de <Phrase>. Define la lista ordenada de frases en lenguaje natural que se incluirán en la respuesta del webhook.

<Phrase>

Especifica la frase (texto) que se va a definir en el objeto fulfillmentResponse.messages de la respuesta del webhook.

Puede especificar un texto estático como valor de frase o extraer el valor de cualquiera de los siguientes campos de la respuesta:

• Campos de encabezado de respuesta
• Carga útil de JSON
• Variables de flujo

Debes definir un elemento <Phrase> independiente para cada valor que quieras extraer.

El elemento <Phrase> utiliza la siguiente sintaxis:

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

Extrae el valor del campo especificado en el encabezado de respuesta. Puede usar el valor del encabezado para definir un texto en lenguaje natural o un parámetro de respuesta.

• Para extraer el valor del encabezado como respuesta en lenguaje natural, especifica el elemento <Header> dentro del elemento <Phrase>.
• Para extraer el valor del encabezado como parámetro de respuesta, especifica el elemento <Header> dentro del elemento <Parameter>.

<Header name="HEADER_FIELD"/>

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

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

El elemento <Header> tiene los siguientes atributos:

<JSONPath>

Extrae el valor de una ruta JSON en una carga útil JSON de la llamada externa de servicio. Puede usar el valor para definir un texto en lenguaje natural o un parámetro de respuesta.

• Para extraer el valor JSON como texto en lenguaje natural, especifica el elemento <JSONPath> dentro del elemento <Phrase>.
• Para extraer el valor JSON como parámetro de respuesta, especifica el elemento <JSONPath> dentro del elemento <Parameter>.

<JSONPath>JSON_PATH</JSONPath>

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

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

<Ref>

Extrae el valor de una variable de flujo. Puede usar el valor para definir un texto en lenguaje natural o un parámetro de respuesta.

• Para extraer el valor de una variable como texto en lenguaje natural, especifique el elemento <Ref> dentro del elemento <Phrase>.
• Para extraer el valor de una variable como parámetro de respuesta, especifique el elemento <Ref> dentro del elemento <Parameter>.

<Ref>EXISTING_FLOW_VARIABLE</Ref>

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

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

<Value>

Asigna un valor literal a un texto en lenguaje natural o a un parámetro de respuesta.

• Para definir el valor literal como texto en lenguaje natural, especifica el elemento <Value> dentro del elemento <Phrase>.
• Para definir el valor literal como parámetro de respuesta, especifica el elemento <Value> dentro del elemento <Parameter>.

<Value>CUSTOM_TEXT</Value>

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

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

Códigos de error

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Variables de error

Cuando se producen errores de ejecución en una política, Apigee genera mensajes de error. Puedes ver estos mensajes de error en la respuesta de error. En muchas ocasiones, los mensajes de error generados por el sistema pueden no ser relevantes en el contexto de su producto. Puede que quieras personalizar los mensajes de error en función del tipo de error para que sean más significativos.

Para personalizar los mensajes de error, puedes usar reglas de error o la política RaiseFault. Para obtener información sobre las diferencias entre las reglas de errores y la política RaiseFault, consulta Reglas de errores frente a la política RaiseFault. Debes comprobar las condiciones mediante el elemento Condition tanto en las reglas de errores como en la política RaiseFault. Apigee proporciona variables de error únicas para cada política. Los valores de las variables de error se definen cuando una política activa errores de tiempo de ejecución. Al usar estas variables, puede comprobar si se dan condiciones de error específicas y tomar las medidas oportunas. Para obtener más información sobre cómo comprobar las condiciones de error, consulta Crear condiciones.

En la siguiente tabla se describen las variables de error específicas de esta política.

Temas relacionados

En Apigee GitHub se pueden consultar implementaciones de referencia de proxies de Apigee y flujos compartidos que muestran el uso de la política SetDialogflowResponse. Para obtener más información, consulta las implementaciones de referencia de IA conversacional.