Política SetDialogflowResponse

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visão geral

A política SetDialogflowResponse facilita a integração do Dialogflow com a Apigee. Para mais informações, consulte Como integrar a Apigee ao Contact Center AI.

A política SetDialogflowResponse processa e formata os dados de resposta dos sistemas de back-end antes de enviar os dados como uma WebhookResponse ao agente Dialogflow (bot). Um agente do Dialogflow exige a WebhookResponse em um formato específico, e a política SetDialogflowResponse cria a resposta no formato exigido. A política cria uma WebhookResponse no formato necessário para um agente do Dialogflow. O WebhookResponse tem frases de linguagem natural e outros parâmetros que o agente do Dialogflow entende.

Se você é um integrador de serviços de back-end, não precisa gastar tempo para entender o formato da WebhookResponse do Dialogfow. A política SetDialogflowResponse pronta para uso lida com o processamento dos dados de resposta de forma integrada.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

<SetDialogflowResponse>

Define uma política SetDialogflowResponse.

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos do elemento SetDialogflowResponse:

Exemplo

No exemplo a seguir, mostramos uma política SetDialogflowResponse de amostra e a WebhookResponse enviada para o agente do 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 tem os seguintes atributos comuns a todas as políticas:

Referência a elementos filhos

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

O elemento <DisplayName> usa a seguinte sintaxe:

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

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<Source>

Especifica a variável a ser analisada. O valor de <Source> é definido por padrão como message. O valor message diferencia o contexto. Em um fluxo de solicitação, message resolve a mensagem de solicitação. Em um fluxo de resposta, message é resolvido para a mensagem de resposta.

Muitas vezes, quando você usa essa política para extrair informações de uma mensagem de resposta ou solicitação, é possível usá-la para extrair informações de qualquer variável. Por exemplo, é possível usá-la para extrair informações de uma entidade criada pela política AccessEntity, de dados retornados pela política ServiceCallout ou de um objeto JSON ou XML.

Se <Source> não puder ser resolvido ou for resolvido para um tipo que não é de mensagem, a política falhará e você receberá um erro no ambiente de execução.

<Source>MESSAGE_VARIABLE</Source>

<Source>myMessageVar</Source>

<DialogflowVersion>

Especifica a versão do Dialogflow. A política SetDialogflowResponse é compatível apenas com a versão CX. Se você não especificar esse elemento na sua política, a versão padrão será CX.

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false. O valor padrão é true.

Definir <IgnoreUnresolvedVariables> como true é diferente de definir o continueOnError do <SetDialogflowResponse> como true. Se você definir continueOnError como true, a Apigee vai ignorar todos os erros, e não apenas os erros nas variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

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

       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<MergeBehavior>

Define o comportamento de mesclagem para as mensagens de resposta. É possível especificar qualquer um dos seguintes valores:

• APPEND: anexa as mensagens à lista de mensagens que aguardam o envio para o usuário.
• REPLACE: substitui as mensagens mais antigas por mensagens mais recentes na lista de mensagens que aguardam o envio para o usuário.

<MergeBehavior>BEHAVIOR</MergeBehavior>

<MergeBehavior>APPEND</MergeBehavior>

<NaturalLanguageResponse>

Encapsula toda a resposta de linguagem natural que você quer enviar para o agente do Dialogflow.

<Parameters>

Define o conjunto de parâmetros a serem definidos na resposta do webhook. O nome do parâmetro é um atributo do elemento <Parameter>.

<Parameter>

Especifica um parâmetro a ser definido no objeto sessionInfo.parameters da resposta do webhook.

É possível especificar um texto estático como um valor de parâmetro ou extrair o valor de qualquer um dos seguintes campos na resposta:

• Campos de cabeçalho de resposta
• Payload do JSON
• Variáveis de fluxo

É necessário definir um elemento <Parameter> separado para cada valor que você quiser extrair.

O elemento <Parameter> usa a seguinte sintaxe:

<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-pai de <Phrase>. Define a lista ordenada de frases de linguagem natural a serem definidas na resposta do webhook.

<Phrase>

Especifica a frase (texto) a ser definida no objeto fulfillmentResponse.messages da resposta do webhook.

É possível especificar um texto estático como um valor de frase ou extrair o valor de qualquer um dos seguintes campos na resposta:

• Campos de cabeçalho de resposta
• Payload do JSON
• Variáveis de fluxo

Defina um elemento <Phrase> separado para cada valor que você quiser extrair.

O elemento <Phrase> usa a seguinte sintaxe:

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

Extrai o valor do campo especificado no cabeçalho da resposta. É possível usar o valor do cabeçalho para definir um texto de linguagem natural ou um parâmetro de resposta.

• Para extrair o valor do cabeçalho como uma resposta de linguagem natural, especifique o elemento <Header> dentro do elemento <Phrase>.
• Para extrair o valor do cabeçalho como um parâmetro de resposta, especifique o elemento <Header> dentro do elemento <Parameter>.

<Header name="HEADER_FIELD"/>

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

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

O elemento <Header> tem os seguintes atributos:

<JSONPath>

Extrai o valor de um caminho JSON em um payload JSON da chamada de serviço. É possível usar o valor para definir um texto de linguagem natural ou um parâmetro de resposta.

• Para extrair o valor JSON como um texto de linguagem natural, especifique o elemento <JSONPath> dentro do elemento <Phrase>.
• Para extrair o valor JSON como um parâmetro de resposta, especifique o elemento <JSONPath> dentro do elemento <Parameter>.

<JSONPath>JSON_PATH</JSONPath>

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

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

<Ref>

Extrai o valor de uma variável de fluxo existente. É possível usar o valor para definir um texto de linguagem natural ou um parâmetro de resposta.

• Para extrair o valor de uma variável como um texto de linguagem natural, especifique o elemento <Ref> dentro do elemento <Phrase>.
• Para extrair o valor de uma variável como um parâmetro de resposta, especifique o elemento <Ref> dentro do elemento <Parameter>.

<Ref>EXISTING_FLOW_VARIABLE</Ref>

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

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

<Value>

Define um valor literal para um texto de linguagem natural ou um parâmetro de resposta.

• Para definir o valor literal como um texto de linguagem natural, especifique o elemento <Value> dentro do elemento <Phrase>.
• Para definir o valor literal como um parâmetro de resposta, especifique o elemento <Value> dentro do 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 erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Variáveis de falha

Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.

Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte FaultRules vs. a política RaiseFault. Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault. A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução. Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de erro, consulte Como criar condições.

A tabela a seguir descreve as variáveis de falha específicas da política.

Temas relacionados

As implementações de referência de proxies e fluxos compartilhados da Apigee que mostram o uso da política SetDialogflowResponse estão disponíveis no GitHub da Apigee. Para mais informações, consulte Implementações de referências do Conversation AI.