Personalizando o diálogo com o contexto

Para personalizar a conversa, seu assistente pode coletar informações do cliente e, em seguida, referenciá-las posteriormente na conversa.

Retendo informações em rodadas de diálogo

O diálogo é stateless, significando que ele não retém informações de uma interação com o usuário para a próxima. Ao incluir um diálogo em um assistente e implementá-lo, o assistente salva o contexto de uma chamada de mensagem e, em seguida, reenvia-o na próxima solicitação durante toda a sessão atual. A sessão atual dura enquanto um usuário interage com o assistente mais o prazo de inatividade da sessão designado. O tempo máximo de inatividade da sessão permitido varia de cinco minutos a sete dias, dependendo do seu tipo de plano. Se você não incluir o diálogo em um assistente, será sua responsabilidade como desenvolvedor de aplicativos customizados manter quaisquer informações contínuas que o aplicativo precisa.

O aplicativo pode passar informações para o diálogo e o diálogo pode atualizar essas informações e passá-las de volta para o aplicativo ou para um nó subsequente. O diálogo faz isso usando variáveis de contexto.

Variáveis de contexto

Uma variável de contexto é aquela que você define em um nó. É possível especificar um valor padrão para ela. Em seguida, outros nós, lógica de aplicativo ou entrada do usuário podem configurar ou alterar o valor da variável de contexto..

É possível condicionar com relação aos valores das variáveis de contexto referenciando uma variável de contexto de uma condição de nó de diálogo para determinar se deve executar um nó. Também é possível referenciar uma variável de contexto a partir das condições de resposta do nó de diálogo para mostrar respostas diferentes, dependendo de um valor fornecido por um serviço externo ou pelo usuário.

Saiba mais:

Transmitindo o contexto do aplicativo

Transmita informações do aplicativo para o diálogo configurando uma variável de contexto e transmitindo a variável de contexto para o diálogo.

Por exemplo, seu aplicativo pode configurar uma variável de contexto $time_of_day e transmiti-la ao diálogo que pode usar as informações para customizar a saudação que ele mostra para o usuário.

Mostra um nó de boas-vindas que usa condições de resposta para verificar o valor da variável de contexto $time_of_day que é transmitida para o diálogo a partir do aplicativo.
Contexto de horário do dia

Neste exemplo, o diálogo sabe que o aplicativo configura a variável com um destes valores: manhã, tarde ou noite. Ele pode verificar cada valor e, dependendo de qual valor estiver presente, retornar a saudação apropriada. Se a variável não for transmitida ou possuir um valor que não corresponde a um dos valores esperados, uma saudação mais genérica será exibida para o usuário.

Transmitindo o contexto de nó para nó

O diálogo também pode incluir variáveis de contexto para transmitir informações de um nó para outro ou para atualizar os valores de variáveis de contexto. Conforme o diálogo solicita e obtém informações do usuário, ele pode rastrear as informações e referenciá-las posteriormente na conversa.

Por exemplo, em um nó você pode perguntar o nome dos usuários e, em um nó posterior, tratá-los pelo nome.

Mostra um nó introduções que solicita ao usuário o seu nome e o armazena como uma variável de contexto. O próximo nó refere-se ao usuário por nome usando a variável de contexto $username.
Transmitir contexto de um nó para outro

Neste exemplo, a entidade do sistema @name será usada para extrair o nome do usuário da entrada se o usuário fornecer um. No editor JSON, a variável de contexto username é definida e configurada para o valor @name. Em um nó subsequente, a variável de contexto $username é incluída na resposta para tratar o usuário pelo nome.

Definindo uma variável de contexto

Defina uma variável de contexto incluindo o nome da variável no campo Variável e incluindo um valor padrão para ela no campo Valor na visualização de edição do nó.

  1. Clique para abrir o nó de diálogo no qual você deseja incluir uma variável de contexto.

  2. Vá para a seção Assistente responde e clique no ícone do menu ícone do menu overflow.

  3. Clique em Abrir o editor de contexto.

  4. Inclua o nome da variável e o par de valores nos campos Variável e Valor.

    • O name pode conter caracteres alfabéticos maiúsculos e minúsculos, caracteres numéricos (0-9) e sublinhados.

    • O value pode ser qualquer tipo JSON suportado, tal como uma variável de sequência simples, um número, uma matriz JSON ou um objeto JSON.

A tabela a seguir mostra alguns exemplos de como definir pares de nome e valor para diferentes tipos de valores:

Definir pares de nome e valor
Variável Valor Tipo de valor
dessert "Bolo" Sequência
age 18 Número
toppings_array ["onions","olives"] Matriz JSON
full_name {"first":"John","last":"Doe"} Objeto JSON

Em seguida, para fazer referência a essas variáveis de contexto, use a sintaxe $name em que name é o nome da variável de contexto definida.

Por exemplo, você pode especificar a expressão a seguir como a resposta de diálogo:

The customer, $age-year-old <? $full_name.first ?>, wants a pizza with <? $toppings_array.join(' and ') ?>, and then $dessert.

A saída resultante é exibida conforme a seguir:

The customer, 18-year-old John, wants a pizza with onions and olives, and then cake.

É possível usar o editor JSON para definir variáveis de contexto também. Você poderá preferir usar o editor JSON se desejar incluir uma expressão complexa como o valor da variável. Consulte Variáveis de contexto no editor JSON para obter mais detalhes.

Tarefas comuns de variável de contexto

Para armazenar a sequência inteira que foi fornecida pelo usuário como entrada, use input.text:

Capturando a entrada do usuário
Variável Valor
repeat <?input.text?>

Por exemplo, a entrada do usuário pode ser I want to order a device. Se a resposta do nó for You said: $repeat, a resposta será exibida como You said: I want to order a device.

Para armazenar o valor de uma entidade em uma variável de contexto, use esta sintaxe:

Capturando uma menção de entidade
Variável Valor
place @place

Por exemplo, a entrada do usuário pode ser I want to go to Paris. Se sua entidade @place reconhecer Paris, seu assistente salvará Paris na variável de contexto $place.

Para armazenar o valor de uma sequência que você extrai da entrada do usuário, é possível incluir uma expressão SpEL que usa o método extract para aplicar uma expressão regular à entrada do usuário. A expressão a seguir extrai um número da entrada do usuário e o salva na variável de contexto $number.

Usando um método String
Variável Valor
número <?input.text.extract('[\d]+',0)?>

Para armazenar o valor de uma entidade padrão, anexe .literal ao nome da entidade. Usando essa sintaxe, certifique-se de que o período exato de texto da entrada do usuário correspondente ao padrão especificado esteja armazenado na variável.

Capturando um valor de entidade padrão
Variável Valor
e-mail <? @email.literal ?>

Por exemplo, a entrada do usuário é Contact me at joe@example.com. Sua entidade denominada @email reconhece o formato de e-mail name@domain.com. Configurando a variável de contexto para armazenar @email.literal, você indica que deseja armazenar a parte da entrada que correspondeu ao padrão. Se você omitir a propriedade .literal da expressão de valor, o nome do valor da entidade especificado para o padrão será retornado no lugar do segmento de entrada do usuário que correspondeu ao padrão.

Excluindo uma variável de contexto

Para excluir uma variável de contexto, configure a variável para nulo.

Anulando uma variável de contexto
Variável Valor
order_form null

Atualizando um valor da variável de contexto

Para atualizar o valor de uma variável de contexto, defina uma variável de contexto com o mesmo nome que a variável de contexto anterior, mas, desta vez, especifique um valor diferente para ela.

Quando mais de um nó configura o valor da mesma variável de contexto, o valor para a variável de contexto pode mudar durante o curso de uma conversa com um usuário. O valor aplicado depende de qual nó está sendo acionado pelo usuário no curso da conversa. O valor especificado para a variável de contexto no último nó que é processado sobrescreve quaisquer valores que foram configurados para a variável por nós que foram processados anteriormente.

Para obter informações sobre como atualizar o valor de uma variável de contexto quando o valor for um objeto JSON ou um tipo de dados da matriz JSON, consulte Atualizando um valor da variável de contexto em JSON

Como as variáveis de contexto são processadas

Onde você define a variável de contexto importa. A variável de contexto não é criada e configurada para o valor especificado para ela até que seu assistente processe a parte do nó de diálogo na qual você definiu a variável de contexto. Na maioria dos casos, você define a variável de contexto como parte da resposta do nó. Ao fazer isso, a variável de contexto é criada e recebe o valor especificado quando seu assistente retorna a resposta do nó.

Para um nó com respostas condicionais, a variável de contexto é criada e configurada quando a condição para uma resposta específica é atendida e essa resposta é processada. Por exemplo, se você definir uma variável de contexto para a resposta condicional #1 e seu assistente processar a resposta #2, a variável definida para a resposta condicional #1 não será configurada.

Para obter informações sobre a inclusão de variáveis de contexto que você deseja que seu assistente configure como um usuário interaja com um nó com intervalos, consulte Incluindo variáveis de contexto em um nó com intervalos

Ordem de operação

Ao definir que diversas variáveis sejam processadas juntas, a ordem da definição não determina a ordem de avaliação dessas variáveis pelo seu assistente. Seu assistente avalia as variáveis em ordem aleatória. Não configure um valor na primeira variável de contexto e espere usá-lo na segunda variável porque a primeira variável de contexto pode não ser executada antes da segunda. Por exemplo, não use duas variáveis de contexto para implementar a lógica que verifica se a entrada do usuário contém a palavra Yes nela.

Usando duas variáveis de contexto para verificar um valor na entrada do usuário
Variável Valor
user_input <? input.text ?>
contains_yes <? $user_input.contains('Yes') ?>

Em vez disso, use uma expressão um pouco mais complexa para evitar precisar depender do valor da primeira variável em sua lista (user_input) que está sendo avaliada antes que a segunda variável (contains_yes) seja avaliada.

Usando uma única variável de contexto
Variável Valor
contains_yes <? input.text.contains('Yes') ?>

Incluindo variáveis de contexto em um nó com intervalos

Para obter mais informações sobre intervalos, consulte Reunindo informações com intervalos.

Para incluir uma variável de contexto que é processada após uma condição de resposta para um intervalo ser atendida:

  1. Abra o nó com intervalos na visualização de edição.
  2. Clique no ícone Customizar slot Customizar slot.
  3. Clique no ícone Opções Opções e, em seguida, selecione Ativar condição.
  4. Clique no ícone Customizar manipulador Editar slot ao lado da resposta com a qual você deseja associar a variável de contexto.
  5. Clique no ícone Opções Opções na seção de respostas do Assistente e, em seguida, clique em Abrir editor de contexto.
  6. Inclua o nome da variável e o par de valores nos campos Variável e Valor.

Para incluir uma variável de contexto que é configurada ou atualizada depois que uma condição de intervalo é atendida, conclua as etapas a seguir:

  1. Abra o nó com intervalos na visualização de edição.
  2. Clique no ícone Customizar slot Customizar slot.
  3. Clique no ícone Opções Opções e, em seguida, selecione Ativar condição.
  4. Inclua o nome da variável e o par de valores no formato JSON.
{
"time_of_day": "morning"
}

Não é possível usar o editor de contexto para definir as variáveis de contexto que são configuradas durante essa fase de avaliação do nó de diálogo Deve-se usar o editor JSON no lugar. Para obter mais informações sobre como usar o editor JSON, consulte Variáveis de contexto no editor JSON.

Variáveis de contexto no editor JSON

Também é possível definir uma variável de contexto no editor JSON. Use o editor JSON se você estiver definindo uma variável de contexto complexa e desejar ser capaz de ver a expressão SpEL completa conforme você a inclui ou muda.

O par de nome e valor deve atender a estes requisitos:

  • O name pode conter caracteres alfabéticos maiúsculos e minúsculos, caracteres numéricos (0-9) e sublinhados.

    É possível incluir outros caracteres, como pontos e hifens, no nome. No entanto, se você fizer isso, deverá especificar a sintaxe de abreviação $(variable-name) toda vez que fizer referência à variável. Consulte Expressões para acessar objetos para obter mais detalhes.

  • O value pode ser qualquer tipo JSON suportado, tal como uma variável de sequência simples, um número, uma matriz JSON ou um objeto JSON.

A amostra JSON a seguir define valores para as variáveis de contexto de sequência $dessert, matriz $toppings_array, número $age e objeto $full_name:

{
  "context": {
    "dessert": "cake",
    "toppings_array": [
      "onions",
      "olives"
    ],
    "age": 18,
    "full_name": {
      "first": "Jane",
      "last": "Doe"
    }
  },
  "output":{}
}

Para definir uma variável de contexto no formato JSON, conclua as etapas a seguir:

  1. Clique para abrir o nó de diálogo no qual você deseja incluir a variável de contexto.

    Quaisquer valores de variáveis de contexto existentes que estão definidos para esse nó são exibidos em um conjunto de campos Variável e Valor correspondentes. Se você não deseja que eles sejam exibidos na visualização de edição do nó, deve-se fechar o editor de contexto. É possível fechar o editor por meio do mesmo menu que é usado para abrir o editor JSON; as etapas a seguir descrevem como acessar o menu.

  2. Clique no ícone Opções Opções para a resposta do assistente e, em seguida, clique em Abrir editor JSON.

    Se a configuração Diversas respostas condicionadas for ativada para o nó, você deverá primeiro clicar no ícone Customizar resposta Customizar resposta para a resposta à qual deseja associar a variável de contexto.

  3. Inclua um bloco "context":{} se um não estiver presente.

    {
  "context":{},
  "output":{}
}

  4. No bloco de contexto, inclua um par "name" e "value" para cada variável de contexto que você deseja definir.

    {
  "context":{
    "name": "value"
},
  "output": {}
}

    Neste exemplo, uma variável denominada new_variable é incluída em um bloco de contexto que já contém uma variável.

    {
  "context":{
    "existing_variable": "value",
    "new_variable":"value"
  }
}

    Para referenciar a variável de contexto, use a sintaxe $name em que name é o nome da variável de contexto definida. Por exemplo, $new_variable.

Saiba mais:

Excluindo uma variável de contexto no JSON

Para excluir uma variável de contexto, configure a variável para nulo.

{
  "context": {
    "order_form": null
  }
}

Se você deseja remover todo rastreio da variável de contexto, é possível usar o método JSONObject.remove(string) para excluí-lo do objeto de contexto. No entanto, deve-se usar uma variável para executar a remoção. Defina a nova variável na saída de mensagem para que ela não seja salva além da chamada atual.

{
  "output": {
    "text" : {},
    "deleted_variable" : "<? context.remove('order_form') ?>"
  }
}

Como alternativa, é possível excluir a variável de contexto na sua lógica de aplicativo.

Atualizando um valor da variável de contexto em JSON

Em geral, se um nó configura o valor de uma variável de contexto que já está configurado, o valor anterior é sobrescrito pelo novo valor.

Atualizando um objeto JSON complexo

Os valores anteriores são sobrescritos para todos os tipos de JSON, exceto um objeto JSON. Se a variável de contexto é um tipo complexo tal como o objeto JSON, um procedimento de mesclagem JSON é usado para atualizar a variável. A operação de mesclagem inclui quaisquer propriedades recém-definidas e sobrescreve quaisquer propriedades existentes do objeto.

Neste exemplo, uma variável de contexto name é definida como um objeto complexo.

{
  "context": {
    "complex_object": {
      "user_firstname" : "Paul",
      "user_lastname" : "Pan",
      "has_card" : false
    }
  }
}

Um nó de diálogo atualiza o objeto JSON da variável de contexto com os valores a seguir:

{
  "complex_object": {
    "user_firstname": "Peter",
    "has_card": true
  }
}

O resultado é este contexto:

{
  "complex_object": {
    "user_firstname": "Peter",
    "user_lastname": "Pan",
    "has_card": true
  }
}

Atualizando matrizes

Se seus dados de contexto de diálogo contiverem uma matriz de valores, você poderá atualizar a matriz anexando valores, removendo um valor ou substituindo todos os valores.

Escolha uma dessas ações para atualizar a matriz. Em cada caso, vemos a matriz antes da ação, a ação e a matriz após a ação ser aplicada.

  • Anexar: para incluir valores no final de uma matriz, use o método append.

    Para esse contexto de tempo de execução de diálogo:

    {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

    Faça essa atualização:

    {
  "context": {
    "toppings_array": "<? $toppings_array.append('ketchup', 'tomatoes') ?>"
  }
}

    Resultado:

    {
  "context": {
    "toppings_array": ["onion", "olives", "ketchup", "tomatoes"]
  }
}

  • Remover: Para remover um elemento, use o método remove e especifique seu valor ou posição na matriz.

    • Remover por valor remove um elemento de uma matriz por seu valor.

      Para esse contexto de tempo de execução de diálogo:

      {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

      Faça essa atualização:

      {
  "context": {
    "toppings_array": "<? $toppings_array.removeValue('onion') ?>"
  }
}

      Resultado:

      {
  "context": {
    "toppings_array": ["olives"]
  }
}

    • Remover por posição: removendo um elemento de uma matriz por sua posição de índice:

      Para esse contexto de tempo de execução de diálogo:

      {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

      Faça essa atualização:

      {
  "context": {
    "toppings_array": "<? $toppings_array.remove(0) ?>"
  }
}

      Resultado:

      {
  "context": {
    "toppings_array": ["olives"]
  }
}

  • Sobrescrever: para sobrescrever os valores em uma matriz, configure a matriz para os novos valores:

    Para esse contexto de tempo de execução de diálogo:

    {
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

    Faça essa atualização:

    {
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

    Resultado:

    {
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

Configurando uma variável de contexto igual à outra

Ao configurar uma variável de contexto igual à outra variável de contexto, você define um ponteiro de uma para a outra. Posteriormente, se o valor de uma das variáveis for alterado, o valor da outra variável também será alterado.

Por exemplo, se você especificar uma variável de contexto como a seguir, quando o valor de $var1 ou $var2 posteriormente for alterado, o valor do outro também será alterado...

Configurando uma variável de contexto igual à outra
Variável Valor
var2 var1

Não configure uma variável igual à outra para capturar um valor de momento. Com matrizes, se você desejar capturar um valor de matriz que é armazenado em uma variável de contexto e usá-lo posteriormente, crie uma nova variável com base no valor atual da variável.

Por exemplo, para criar uma cópia dos valores de uma matriz em um determinado ponto, inclua uma matriz preenchida com os valores para a matriz existente. Para fazer isso, é possível usar a sintaxe a seguir:

{
"context": {
   "var2": "<? output.var2?:new JsonArray().append($var1) ?>"
 }
 }