Personalizzazione della finestra di dialogo con il contesto

Per personalizzare la conversazione, il tuo assistente può raccogliere informazioni dal cliente e quindi fare riferimento ad esso più avanti nella conversazione.

Conservazione delle informazioni tra turni di dialogo

Il dialogo è privo di stato, il che significa che non conserva le informazioni da un'interazione con l'utente all'altra. Quando aggiungi un dialogo a un assistente e lo distribuisci, l'assistente salva il contesto da una chiamata del messaggio e quindi lo reinoltra alla successiva richiesta durante la sessione corrente. La sessione corrente dura mentre un utente interagisce con l'assistente più il periodo di inattività della sessione designato. Il tempo massimo di inattività della sessione consentito è compreso tra 5 minuti e 7 giorni, a seconda del tipo di piano. Se non aggiungi la finestra di dialogo a un assistente, è tua responsabilità come sviluppatore dell'applicazione personalizzata mantenere tutte le informazioni continue di cui l'applicazione ha bisogno.

L'applicazione può passare le informazioni al dialogo e il dialogo può aggiornare queste informazioni e ritrasmetterle all'applicazione o a un nodo successivo. Il dialogo esegue tali operazioni utilizzando le variabili di contesto.

Variabili di contesto

Una variabile di contesto è una variabile che definisci in un nodo. Puoi specificare un valore predefinito per essa. Quindi, altri nodi, logica dell'applicazione o input utente possono impostare o modificare il valore della variabile di contesto.

Puoi condizionare i valori delle variabili di contesto facendo riferimento a una variabile di contesto da una condizione del nodo di dialogo per determinare se eseguire un nodo. Puoi anche fare riferimento a una variabile di contesto dalle condizioni di risposta del nodo di dialogo per mostrare risposte diverse a seconda di un valore fornito da un servizio esterno o dall'utente.

Scopri di più qui:

Passaggio del contesto dall'applicazione

Passa le informazioni dall'applicazione al dialogo impostando una variabile di contesto e passando tale variabile al dialogo.

Ad esempio, la tua applicazione può impostare una variabile di contesto $time_of_day e passarla alla finestra di dialogo che può utilizzare le informazioni per personalizzare il messaggio di saluto che mostra all'utente.

Mostra un nodo di benvenuto che usa le condizioni di risposta per controllare il valore della variabile di contesto $time_of_day passata al dialogo dall'applicazione.
Contesto ora del giorno

In questo esempio, il dialogo sa che l'applicazione imposta la variabile su uno di questi valori: morning, afternoon o evening. Può controllare ogni valore e, a seconda del valore che è presente, restituisce il messaggio iniziale appropriato. Se la variabile non viene passata o se ha un valore che non corrisponde a uno dei valori previsti, all'utente viene visualizzato un messaggio iniziale più generico.

Passaggio del contesto da un nodo all'altro

Il dialogo può anche aggiungere variabili di contesto per passare informazioni da un nodo all'altro o per aggiornare i valori delle variabili di contesto. Quando la finestra di dialogo richiede e riceve informazioni dall'utente, può tenere traccia delle informazioni e farvi riferimento in seguito nella conversazione.

Ad esempio, in un nodo potresti chiedere agli utenti il loro nome e in un nodo successivo rivolgerti a loro per nome.

Mostra un nodo introduzioni che richiede all'utente il nome e lo memorizza come variabile di contesto. Il nodo successivo fa riferimento all'utente per nome utilizzando la variabile di contesto $username.
Trasmetti contesto da un nodo all'altro

In questo esempio, l'entità di sistema @name viene utilizzata per estrarre il nome dell'utente dall'input, se l'utente ne fornisce uno. Nell'editor JSON, la variabile di contesto username è definita e impostata sul valore @name . In un nodo successivo, la variabile di contesto $username viene inclusa nella risposta per rivolgersi all'utente per nome.

Definizione di una variabile di contesto

Definisci una variabile di contesto aggiungendo il nome della variabile al campo Variabile e aggiungendo un valore predefinito per essa nel campo Valore nella vista di modifica del nodo.

  1. Fai clic per aprire il nodo di dialogo a cui desideri aggiungere una variabile di contesto.

  2. Vai alla sezione Assistant responds e fai clic sull'icona del menu Overflow menu icon.

  3. Fare clic su Apri editor di contesto.

  4. Aggiungi la coppia nome e valore della variabile ai campi Variabile e Valore.

    • Il name può contenere qualsiasi carattere alfabetico maiuscolo e minuscolo, caratteri numerici (0-9) e caratteri di sottolineatura.

    • Il value può essere qualsiasi tipo JSON supportato, come una variabile stringa semplice, un numero, un array JSON o un oggetto JSON.

La seguente tabella mostra alcuni esempi su come definire le coppie nome e valore per diversi tipi di valori:

Definire coppie nome e valore
Variabile Valore Tipo di valore
dessert "cake" Stringa
age 18 Numero
toppings_array ["onions","olives"] Array JSON
full_name {"first":"John","last":"Doe"} Oggetto JSON

Quindi, per fare riferimento a queste variabili di contesto, utilizzare la sintassi $name dove name è il nome della variabile di contesto definita.

Ad esempio, potresti specificare la seguente espressione come risposta di dialogo:

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

L'output risultante viene visualizzato come segue:

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

Puoi utilizzare l'editor JSON per definire anche le variabili di contesto. È possibile che tu preferisca utilizzare l'editor JSON se desideri aggiungere un'espressione complessa come valore della variabile. Per ulteriori dettagli, vedi Variabili di contesto nell'editor JSON.

Attività comuni della variabile di contesto

Per memorizzare l'intera stringa fornita dall'utente come input, utilizza input.text:

Cattura dell'input utente
Variabile Valore
repeat <?input.text?>

Ad esempio, l'input utente potrebbe essere, I want to order a device. Se la risposta del nodo è, You said: $repeat, la risposta verrà visualizzata come, You said: I want to order a device.

Per memorizzare il valore di un'entità in una variabile di contesto, utilizza questa sintassi:

Cattura di una citazione di entità
Variabile Valore
place @place

Ad esempio, l'input utente potrebbe essere I want to go to Paris. Se la tua entità @place riconosce Paris, il tuo assistente salva Paris nella variabile di contesto $place.

Per memorizzare il valore di una stringa che hai estratto dall'input dell'utente, puoi includere un'espressione SpEL che utilizza il metodo extract per applicare un'espressione regolare all'input utente. La seguente espressione estrae un numero dall'input utente e lo salva nella variabile di contesto $number.

Utilizzo di un metodo String
Variabile Valore
numero <?input.text.extract('[\d]+',0)?>

Per memorizzare il valore di un'entità modello, aggiungi .literal al nome entità. Utilizzando questa sintassi, verificare che l'estensione esatta del testo dall'input utente corrispondente al modello specificato sia memorizzata nella variabile.

Cattura di un valore di entità modello
Variabile Valore
email <? @email.literal ?>

Ad esempio, l'input utente è Contact me at joe@example.com. La tua entità denominata @email riconosce il formato email name@domain.com. Configurando la variabile di contesto per memorizzare @email.literal, indichi che desideri memorizzare la parte dell'input che corrisponde al modello. Se ometti la proprietà .literal dall'espressione del valore, viene restituito il nome del valore di entità che hai specificato per il modello invece del segmento dell'input utente che corrisponde al modello.

Eliminazione di una variabile di contesto

Per eliminare una variabile di contesto, imposta la variabile su null.

Nulling di una variabile di contesto
Variabile Valore
order_form null

Aggiornamento di un valore di variabile di contesto

Per aggiornare il valore di una variabile di contesto, definisci una variabile di contesto con lo stesso nome della variabile di contesto precedente ma, questa volta, specifica un valore diverso.

Quando più di un nodo imposta il valore della stessa variabile di contesto, il valore può cambiare nel corso di una conversazione con un utente. Il valore applicato dipende dal nodo attivato dall'utente nel corso della conversazione. Il valore specificato per la variabile di contesto nell'ultimo nodo elaborato sovrascrive i valori impostati per la variabile dai nodi che sono stati elaborati in precedenza.

Per informazioni su come aggiornare il valore di una variabile di contesto quando il valore è un tipo di dati oggetto JSON o array JSON, vedi Aggiornamento di un valore di variabile di contesto in JSON

Come vengono elaborate le variabili di contesto

È importante dove definisci la variabile di contesto. La variabile di contesto non viene creata e impostata sul valore che hai specificato per essa fino a quando il tuo assistente non elabora la parte del nodo di dialogo in cui hai definito la variabile di contesto. Nella maggior parte dei casi, definisci la variabile di contesto come parte della risposta del nodo. Quando lo fai, la variabile di contesto viene creata e le viene assegnato il valore specificato quando il tuo assistente restituisce la risposta del nodo.

Per un nodo con risposte condizionali, la variabile di contesto viene creata e impostata quando viene soddisfatta la condizione per una specifica risposta e tale risposta viene elaborata. Ad esempio, se definisci una variabile di contesto per la risposta condizionale #1 e il tuo assistente elabora la risposta #2, la variabile che hai definito per la risposta condizionale #1 non viene impostata.

Per informazioni sull'aggiunta di variabili di contesto che vuoi che il tuo assistente imposti come un utente interagisca con un nodo con slot, vedi Aggiunta di variabili di contesto a un nodo con slot.

Ordine delle operazioni

Quando definisci più variabili da elaborare insieme, l'ordine in cui le definisci non determina l'ordine in cui vengono valutate dal tuo assistente. Il tuo assistente valuta le variabili in ordine casuale. Non impostare un valore nella prima variabile di contesto e prevedi di utilizzarlo nella seconda variabile perché la prima variabile di contesto potrebbe non essere eseguita prima della seconda. Ad esempio, non utilizzare due variabili di contesto per implementare la logica che controlla che l'input utente contenga la parola Yes.

Utilizzo di due variabili di contesto per controllare un valore nell'input utente
Variabile Valore
user_input <? input.text ?>
contains_yes <? $user_input.contains('Yes') ?>

Utilizza invece un'espressione leggermente più complessa per evitare di dover fare affidamento sul valore della prima variabile nel tuo elenco (user_input) che viene valutata prima della seconda variabile (contains_yes).

Utilizzo di una singola variabile di contesto
Variabile Valore
contains_yes <? input.text.contains('Yes') ?>

Aggiunta di variabili di contesto a un nodo con slot

Per ulteriori informazioni, vedi Raccolta di informazioni con gli slot.

Per aggiungere una variabile di contesto che viene elaborata dopo che viene soddisfatta una condizione di risposta per uno slot:

  1. Apri il nodo con gli slot nella vista di modifica.
  2. Fare clic su Personalizza slot Personalizza slot.
  3. Fare clic sull'icona Opzioni Opzioni, quindi selezionare Abilita condizione.
  4. Fai clic sull'icona Personalizza gestore Modifica slot accanto alla risposta a cui vuoi associare la variabile di contesto.
  5. Fare clic sull'icona Opzioni Opzioni nella sezione delle risposte di Assistant e fare clic su Apri editor di contesto.
  6. Aggiungi la coppia nome e valore della variabile ai campi Variabile e Valore.

Per aggiungere una variabile di contesto impostata o aggiornata una volta soddisfatta una condizione slot, completa questi passi:

  1. Apri il nodo con gli slot nella vista di modifica.
  2. Fare clic su Personalizza slot Personalizza slot.
  3. Fare clic sull'icona Opzioni Opzioni, quindi selezionare Abilita condizione.
  4. Aggiungi la coppia nome e valore nel formato JSON.
{
"time_of_day": "morning"
}

Non puoi utilizzare l'editor di contesti per definire le variabili di contesto impostate durante questa fase di valutazione del nodo di dialogo. Devi utilizzare invece l'editor JSON. Per ulteriori informazioni sull'utilizzo dell'editor JSON, vedi Variabili di contesto nell'editor JSON.

Variabili di contesto nell'editor JSON

Puoi definire una variabile di contesto anche nell'editor JSON. Utilizza l'editor JSON se stai definendo una variabile di contesto complessa e vuoi essere in grado di visualizzare l'espressione SpEL completa mentre la aggiungi o la modifichi.

La coppia nome e valore deve soddisfare questi requisiti:

  • Il name può contenere qualsiasi carattere alfabetico maiuscolo e minuscolo, caratteri numerici (0-9) e caratteri di sottolineatura.

    Nel nome puoi includere altri caratteri, come punti e trattini. Tuttavia, in questo caso, è necessario specificare la sintassi abbreviata $(variable-name) ogni volta che si fa riferimento alla variabile. Per ulteriori dettagli, vedi Espressioni per l'accesso agli oggetti.

  • Il value può essere qualsiasi tipo JSON supportato, come una variabile stringa semplice, un numero, un array JSON o un oggetto JSON.

Il seguente esempio JSON definisce i valori per le variabili di contesto stringa $dessert, array $toppings_array, numero $age e oggetto $full_name:

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

Per definire una variabile di contesto in formato JSON, completa i seguenti passi:

  1. Fai clic per aprire il nodo di dialogo a cui desideri aggiungere la variabile di contesto.

    I valori della variabile di contesto esistenti definiti per questo nodo vengono visualizzati in una serie di campi Variabile e Valore corrispondenti. Se non desideri che vengano visualizzati nella vista di modifica del nodo, devi chiudere l'editor di contesto. Puoi chiudere l'editor dallo stesso menu che hai utilizzato per aprire l'editor JSON; la procedura riportata di seguito descrive come accedere al menu.

  2. Fai clic sull'icona Opzioni Opzioni per la risposta dell'assistente e fai quindi clic su Apri editor JSON.

    Se l'impostazione Più risposte condizionate è abilitata per il nodo, è necessario prima fare clic su Personalizza risposta Personalizza risposta per la risposta a cui si desidera associare la variabile di contesto.

  3. Aggiungi un blocco "context":{} se non è presente.

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

  4. Nel blocco di contesto, aggiungi una coppia "name" e "value" per ogni variabile di contesto che desideri definire.

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

    In questo esempio, una variabile denominata new_variable viene aggiunta ad un blocco di contesto che contiene già una variabile.

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

    Per fare riferimento alla variabile di contesto, utilizzare la sintassi $name dove name è il nome della variabile di contesto definita. Ad esempio, $new_variable.

Scopri di più qui:

Eliminazione di una variabile di contesto in JSON

Per eliminare una variabile di contesto, imposta la variabile su null.

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

Se desideri rimuovere tutta la traccia della variabile di contesto, puoi utilizzare il metodo JSONObject.remove(string) per eliminarla dall'oggetto di contesto. Tuttavia, devi utilizzare una variabile per eseguire la rimozione. Definire la nuova variabile nell'output del messaggio in modo che non venga salvata oltre la chiamata corrente.

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

In alternativa, puoi eliminare la variabile di contesto nella logica della tua applicazione.

Aggiornamento del valore di una variabile di contesto in JSON

In generale, se un nodo imposta il valore di una variabile di contesto già impostata, il valore precedente viene sovrascritto dal nuovo valore.

Aggiornamento di un oggetto JSON complesso

I valori precedenti vengono sovrascritti per tutti i tipi JSON tranne che per un oggetto JSON. Se la variabile di contesto è un tipo complesso come un oggetto JSON, viene utilizzata una procedura di unione JSON per aggiornare la variabile. L'operazione di unione aggiunge qualsiasi proprietà appena definita e sovrascrive tutte le proprietà esistenti dell'oggetto

In questo esempio, una variabile di contesto di nome è definita come un oggetto complesso.

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

Un nodo di dialogo aggiorna l'oggetto JSON della variabile di contesto con i seguenti valori:

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

Il risultato è il seguente contesto:

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

Aggiornamento di array

Se i tuoi dati di contesto del dialogo contengono un array di valori, puoi aggiornare l'array aggiungendo valori, rimuovendo un valore o sostituendo tutti i valori.

Per aggiornare l'array, scegli una delle seguenti azioni. In ogni caso, vediamo l'array prima dell'azione, l'azione e l'array dopo l'applicazione dell'azione.

  • Aggiungi: per aggiungere valori alla fine di un array, utilizza il metodo append.

    Per questo contesto di runtime di dialogo:

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

    Effettua questo aggiornamento:

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

    Risultato:

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

  • Rimuovi: per rimuovere un elemento, utilizza il metodo remove e specifica il suo valore o la sua posizione nell'array.

    • Rimuovi per valore: rimuove un elemento da un array in base al suo valore.

      Per questo contesto di runtime di dialogo:

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

      Effettua questo aggiornamento:

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

      Risultato:

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

    • Rimuovi per posizione: rimozione di un elemento da un array in base alla sua posizione nell'indice.

      Per questo contesto di runtime di dialogo:

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

      Effettua questo aggiornamento:

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

      Risultato:

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

  • Sovrascrivi: per sovrascrivere i valori in un array, impostare l'array sui nuovi valori:

    Per questo contesto di runtime di dialogo:

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

    Effettua questo aggiornamento:

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

    Risultato:

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

Impostazione di una variabile di contesto uguale a un'altra

Quando imposti una variabile di contesto uguale a un'altra, devi definire un puntatore dall'una all'altra. Successivamente, se il valore di una delle variabili cambia, viene modificato anche il valore dell'altra variabile.

Ad esempio, se si specifica una variabile di contesto come segue, quando il valore di $var1 o $var2 successivamente cambia, cambia anche il valore dell'altro.

Impostazione di una variabile di contesto uguale a un'altra
Variabile Valore
var2 var1

Non impostare una variabile uguale a un'altra per acquisire un punto nel valore di riferimento temporale. Con gli array, se si desidera catturare un valore di array memorizzato in una variabile di contesto e utilizzarlo successivamente, creare una nuova variabile in base al valore corrente della variabile.

Ad esempio, per creare una copia dei valori di un array a un determinato punto, aggiungere un array popolato con i valori per l'array esistente. Per eseguire tale operazione, puoi utilizzare la seguente sintassi:

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