Parametri

Definire, fare riferimento, impostare e ottenere i parametri

Esistono quattro modi generali per utilizzare i parametri:

• Definizione in fase di progettazione: durante la progettazione, puoi utilizzare la console o l'API per definire i parametri. Ad esempio, puoi definire un parametro di intente e utilizzarlo in una frase di addestramento per indicare l'input utente finale da estrarre.
• Riferimento in fase di progettazione: i riferimenti ai parametri sono variabili che contengono i valori dei parametri da estrarre in fase di esecuzione. Durante la fase di progettazione, puoi utilizzare la console o l'API per fare riferimento ai parametri in vari tipi di dati. Ad esempio, puoi fare riferimento a un parametro di sessione in una risposta di adempimento statica per una route.
• Impostato in fase di esecuzione: in fase di esecuzione, il servizio Conversational Agents (Dialogflow CX), il servizio che chiama l'API e il servizio webhook possono impostare i valori parametro. Ad esempio, il servizio di agenti conversazionali (Dialogflow CX) imposta il valore di un parametro dell'intenzione quando un input utente finale corrisponde all'intenzione e l'input contiene i dati del parametro.
• Ottieni in fase di esecuzione: in fase di esecuzione, i riferimenti ai parametri contengono i valori dei parametri che sono stati impostati e puoi utilizzare l'API o un webhook per ottenere i valori dei parametri. Ad esempio, quando viene trovata una corrispondenza per un'intenzione e viene chiamato il tuo webhook, il servizio webhook riceve i valori dei parametri per l'intenzione.

Denominazione dei parametri

Alla denominazione dei parametri si applicano le seguenti regole:

• Utilizza i seguenti caratteri: [A-Z], [a-z], [0-9], ., -, _
• I nomi dei parametri non sono sensibili alle maiuscole, quindi Conversational Agents (Dialogflow CX) tratta Apple e apple come lo stesso parametro. Il codice client dell'API e del webhook deve anche trattare i nomi dei parametri come non sensibili alle maiuscole, perché non è garantita la sensibilità alle maiuscole per i nomi dei parametri restituiti dagli agenti conversazionali (Dialogflow CX).
• Quando crei parametri con lo stesso ID o nome visualizzato in intent o moduli diversi, assicurati che il tipo di entità e le altre impostazioni siano uguali per tutte le definizioni. Se il tipo di entità o altre impostazioni del parametro differiscono, utilizza un ID parametro o un nome visualizzato univoco per ogni definizione.

Tipi di valori dei parametri

I valori dei parametri supportano più tipi di valori. La sezione sessioni di seguito descrive come fare riferimento a ogni tipo di valore parametro. Sono supportati i seguenti tipi:

Parametro stringa vuota e valori null

Puoi impostare i valori dei parametri di stringa su "", che imposta il parametro sulla stringa vuota.

Puoi impostare qualsiasi valore parametro su null, che indica che il parametro non è stato impostato.

Valori originali dei parametri

Quando il testo viene associato a una determinata entità in fase di esecuzione, spesso viene risolto in un valore più pratico per l'elaborazione. Ad esempio, la parola "mele" nell'input utente finale può essere risolta come "mela" per un'entità di frutta.

Tutti i tipi di valori per i riferimenti ai parametri di intent possono fare riferimento al valore originale o risolto.

Solo i tipi di valori composti per i riferimenti ai parametri di sessione possono fare riferimento al valore originale.

Parametri di intent

Gli intent utilizzano i parametri per estrarre i dati forniti dagli utenti finali quando gli intent vengono abbinati. I seguenti dati vengono utilizzati per definire un parametro di intent:

• Nome (noto anche come ID o Nome visualizzato): un nome che identifica il parametro.
• Tipo di entità: Il tipo di entità associato al parametro.
• È elenco: se true, il parametro viene trattato come un elenco di valori.
• Oscuramento nel log: se true, i dati dei parametri forniti dall'utente finale vengono oscurati.

Definire i parametri di intent

I parametri di intent vengono definiti in fase di progettazione durante la creazione dei dati dell'intent o durante la annotazione delle frasi di addestramento.

Parametri di intenzione di riferimento

I riferimenti ai parametri di intent possono essere utilizzati nei messaggi di risposta all'esecuzione statica dei percorsi di intent.

Puoi fare riferimento al valore originale o al valore risolto.

Per fare riferimento a un parametro per l'intent attualmente associato, utilizza uno dei seguenti formati:

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

Ad esempio, se l'ID parametro è date, puoi fare riferimento al valore risolto come $intent.params.date.resolved.

Impostare i parametri di intent

Quando un input utente finale corrisponde a un'intenzione in fase di esecuzione, qualsiasi parametro utilizzato da un'annotazione per la frase di addestramento associata viene impostato da Conversational Agents (Dialogflow CX).

L'implementazione per un percorso dell'intent può utilizzare un predefinito del parametro di implementazione per impostare un valore parametro dell'intent in fase di esecuzione.

Ottenere i parametri dell'intenzione

Durante il turno di conversazione in cui viene associato un intento, il codice può accedere ai valori dei parametri dell'intento.

Le interazioni con l'API restituiranno i valori dei parametri di intent. Consulta il campo di risposta queryResult.parameters del metodo detectIntent per il tipo Session. Vai al riferimento all'API Session

I valori dei parametri dell'intent di ricezione del webhook. Consulta il campo intentInfo.parameters nella richiesta webhook.

Parametri del modulo

Per ogni pagina, puoi definire un modulo, ovvero un elenco di parametri che devono essere raccolti dall'utente finale per la pagina. L'agente interagisce con l'utente finale per più turni di conversazione, fino a quando non ha raccolto tutti i parametri del modulo richiesti, noti anche come parametri di pagina. L'agente raccoglie questi parametri nell'ordine definito nella pagina. Per ogni parametro del modulo obbligatorio, fornisci anche prompt che l'agente utilizza per richiedere queste informazioni all'utente finale. Questa procedura è chiamata compilazione dei moduli.

Ad esempio, potresti creare un modulo che raccoglie il nome e il numero di telefono dell'utente finale per una pagina Collect Customer Info.

I seguenti dati vengono utilizzati per definire un parametro del modulo:

Definire e gestire i parametri dei moduli

I parametri del modulo vengono definiti in fase di progettazione durante la creazione di una pagina.

Per modificare l'ordine dei parametri del modulo con la console, fai clic sul titolo della sezione Parametri nella pagina, quindi trascina le righe dei parametri nella tabella dei parametri.

Per eliminare un parametro del modulo, fai clic sul titolo della sezione Parametri nella pagina, passa il mouse sopra un parametro, quindi fai clic sul pulsante di eliminazione delete.

Parametri del modulo di riferimento

I riferimenti ai parametri del modulo non vengono utilizzati direttamente. Puoi controllare solo lo stato di compilazione dei singoli parametri del modulo o del modulo nel suo complesso. Puoi utilizzare questi riferimenti allo stato del modulo in un requisito di condizione di un percorso di condizione.

Per verificare se il modulo completo della pagina corrente è compilato, utilizza la seguente condizione:

$page.params.status = "FINAL"

Per verificare se un determinato parametro del modulo è stato compilato nell'ultimo passaggio, utilizza la seguente condizione:

$page.params.parameter-id.status = "UPDATED"

Imposta i parametri del modulo

I valori dei parametri del modulo possono essere impostati in vari modi. Le sottosezioni seguenti descrivono ogni meccanismo per impostare i valori dei parametri del modulo.

Valori predefiniti dei parametri

Puoi fornire valori predefiniti per i parametri facoltativi del modulo. Quando inizia il completamento del modulo, tutti i parametri facoltativi non impostati vengono impostati sui valori predefiniti. Questi valori possono essere inizializzati o sostituiti da alcuni dei meccanismi riportati di seguito.

Se un parametro è obbligatorio, il relativo valore predefinito viene ignorato.

Compilazione dei moduli

Gli agenti conversazionali (Dialogflow CX) impostano automaticamente i valori parametro forniti dall'utente finale durante la compilazione del modulo. L'agente raccoglie i parametri richiesti nell'ordine definito nella pagina. L'agente chiede all'utente finale i valori richiesti utilizzando il completamento della richiesta iniziale che fornisci per ogni parametro obbligatorio. I parametri facoltativi non attiveranno i prompt.

Se un valore parametro obbligatorio non viene fornito dall'utente finale dopo una richiesta dell'agente, la richiesta iniziale verrà ripetuta, a meno che non sia definito un comportamento diverso nei gestori di richiesta di nuovo input. Se sono definiti più prompt di testo iniziali, il comportamento dell'agente è lo stesso di qualsiasi risposta di testo per l'evasione.

Propagazione dei parametri di intent e sessione

Quando un parametro di qualsiasi tipo viene impostato in fase di esecuzione, viene scritto nella sessione e diventa un parametro di sessione.

Quando una pagina diventa inizialmente attiva e durante il relativo periodo di attività, qualsiasi parametro del modulo con lo stesso nome di un parametro di sessione viene impostato automaticamente sul valore parametro di sessione.

Questo può accadere con un parametro di intente abbinato in un percorso di intente o nella propagazione dei parametri.

La propagazione dei parametri di intent e sessione è l'unico meccanismo per impostare i parametri facoltativi dei moduli sui valori input utente finale, ma questo meccanismo può anche impostare o sostituire i valori dei parametri dei moduli obbligatori.

Preimpostazioni dei parametri di adempimento

L'elaborazione per una route, un gestore eventi o un richiamo del modulo può utilizzare un predefinito del parametro di adempimento per impostare un valore parametro del modulo in fase di esecuzione. Un valore preimpostato del parametro di adempimento sostituirà un valore parametro, inclusi i valori predefiniti dei parametri.

Impostazione del parametro webhook

L'webhook può impostare i valori dei parametri del modulo in fase di esecuzione. Consulta il campo pageInfo.formInfo.parameterInfo nella risposta webhook.

Ottenere i parametri del modulo

Le interazioni con l'API restituiranno i valori dei parametri del modulo. Consulta il campo di risposta queryResult.parameters del metodo detectIntent per il tipo Session. Vai al riferimento all'API Session

Valori dei parametri del modulo di ricezione del webhook. Consulta il campo pageInfo.formInfo.parameterInfo nella richiesta webhook.

Gestori di richieste di conferma per la compilazione dei moduli

I gestori di richieste di nuovo input, noti anche come gestori di eventi a livello di parametro, vengono utilizzati per definire il comportamento complesso della richiesta di un parametro per i parametri obbligatori. Ad esempio, gli handler di richiesta di nuovo prompt possono essere utilizzati per modificare la richiesta quando l'utente finale non fornisce un valore dopo la richiesta iniziale e per passare a un'altra pagina dopo N tentativi non riusciti.

Se non sono definiti gestori di richieste ripetute, la richiesta iniziale verrà utilizzata per richiedere nuovamente all'utente finale, se necessario.

Se l'utente finale risponde con un input imprevisto, viene invocato un evento sys.no-match-* o sys.no-input-* e vengono chiamati eventuali gestori di richieste di nuovo input definiti per questi eventi.

Come altri gestori di eventi, un gestore di richieste di conferma è un tipo di gestore dello stato che può essere configurato con uno o entrambi i seguenti elementi:

• Un'implementazione per fornire un messaggio di richiesta di conferma all'utente finale e/o un predefinito del parametro.
• Un target di transizione per cambiare la pagina corrente.

Parametri della sessione

Quando un parametro di qualsiasi tipo viene impostato in fase di esecuzione, viene scritto nella sessione e diventa un parametro di sessione. Questi parametri non sono definiti esplicitamente in fase di progettazione. Puoi fare riferimento a questi parametri di sessione in qualsiasi momento durante una sessione.

Parametri di sessione di riferimento

I riferimenti ai parametri di sessione possono essere utilizzati nei messaggi di risposta statica per i seguenti tipi di adempimento:

• Adempimento dell'inserimento di pagine
• Route fulfillment
• Adempimento del gestore di eventi
• Soddisfazione delle richieste del modulo
• Aggiornamento del modulo

I riferimenti possono essere utilizzati anche in:

• Valori dell'intestazione webhook per l'autenticazione.
• Richieste webhook flessibili per l'invio di valori dei parametri a un webhook.

Per fare riferimento a un parametro di sessione, utilizza i seguenti formati:

$session.params.parameter-id

Impostare i parametri della sessione

Al termine del completamento del modulo, i parametri compilati vengono scritti nella sessione da Conversational Agents (Dialogflow CX).

L'elaborazione per una route, un gestore eventi o un richiamo del modulo può utilizzare un predefinito del parametro di adempimento per impostare un valore parametro di sessione in fase di esecuzione.

L'webhook può impostare i valori dei parametri di sessione in fase di esecuzione. Consulta il campo sessionInfo.parameters nella risposta webhook standard o consulta la risposta webhook flessibile.

Le interazioni con l'API possono impostare i valori dei parametri di sessione. Consulta il campo della richiesta queryParams.parameters del metodo detectIntent per il tipo Session. Vai al riferimento all'API Session

Recupera i parametri della sessione

Le interazioni con l'API restituiranno i valori dei parametri della sessione. Consulta il campo di risposta queryResult.parameters del metodo detectIntent per il tipo Session. Vai al riferimento all'API Session

I valori dei parametri della sessione di ricezione dell'webhook. Consulta il campo sessionInfo.parameters nella richiesta webhook.

Propagazione dei parametri

Quando un input utente finale fornisce un valore parametro, il parametro può essere propagato ad altri livelli:

• Quando un parametro di intent viene impostato da una corrispondenza di intent, i parametri di modulo con nomi simili per la pagina attiva vengono impostati sullo stesso valore. Il tipo di entità del parametro è dettato dalla definizione del parametro di intent.
• Quando un parametro di intent viene impostato da una corrispondenza di intent o un parametro di modulo viene impostato durante la compilazione di un modulo, il parametro diventa un parametro di sessione.

DTMF per le integrazioni di telefonia

Puoi attivare e configurare il protocollo DTMF (Dual-tone multi-frequency signaling) per un parametro. Una volta attivata, un utente finale di un agente che utilizza un'integrazione di telefonia può utilizzare il tastierino del telefono per fornire i valori dei parametri.

Per ridurre l'ambiguità, l'input DTMF può essere interpretato sia in forma normale che specifica per DTMF (consigliata):

• La forma normale è semplicemente i valori del tastierino inseriti dall'utente finale. Ad esempio, 123#.
• Il formato specifico DTMF converte l'input in dtmf_digits_[digits], dove [digits] sono le cifre DTMF originali con * sostituito da star e # sostituito da pound. Ad esempio, 123# viene interpretato come dtmf_digits_123pound.

Quando abbina i tipi di entità per un parametro, Conversational Agents (Dialogflow CX) cercherà di abbinare sia le forme normali sia quelle specifiche per DTMF. Quando viene utilizzato un tipo di entità per l'input DTMF, è consigliabile definire sinonimi come dtmf_digits_123 per migliorare la corrispondenza NLU.

Se l'input DTMF non soddisfa la condizione di terminazione (non ha raggiunto la lunghezza massima delle cifre o non è stato terminato dalla cifra finale), l'agente di Dialogflow CX continuerà ad attendere ulteriori input. Durante questo periodo, se viene attivato il timeout per assenza di voce, l'agente attiverà un evento di assenza di input. Se viene rilevato solo un comando vocale, l'agente esegue la ricerca di corrispondenze con l'input vocale. Se vengono rilevati sia l'input vocale sia quello DTMF, l'input vocale viene ignorato e viene considerato solo l'input DTMF.

Per attivare e personalizzare il DTMF per un parametro:

Quando crei l'agente, puoi testare gli input DTMF nel simulatore.

Endpointing intelligente

Se l'assegnazione di endpoint intelligenti è attivata per l'agente, puoi personalizzare il comportamento di assegnazione di endpoint intelligenti per un parametro numerico.

1. Imposta Cifre minime per suggerire all'endpointer intelligente di attendere fino a quando non sono state raccolte tutte le cifre.
2. Imposta Correggi trascrizioni per migliorare il riconoscimento vocale delle cifre correggendo gli errori comuni di trascrizione delle cifre. Questa opzione è supportata solo per le richieste che specificano un codice lingua en o en-*.
3. Imposta Timeout di attesa per specificare il tempo aggiuntivo che gli agenti conversazionali (Dialogflow CX) dovranno attendere prima che l'utente fornisca ulteriori input.

Parametri basati sul flusso

I parametri basati sul flusso possono essere definiti come predefiniti dei parametri di evasione o parametri dei moduli. È possibile fare riferimento a questi parametri solo quando il flusso in cui sono definiti è attivo e non vengono mantenuti nei parametri di sessione.

Per definire o fare riferimento a un parametro basato sul flusso, utilizza la seguente sintassi:

$flow.parameter-name

Ad esempio, se il nome del parametro è date, puoi definirlo o fare riferimento al parametro come $flow.date.

Tieni presente che l'utilizzo di un prefisso $ per definire i parametri è diverso da quello di altri tipi di parametri che non utilizzano $ per le definizioni dei parametri.

Un esempio di definizione di parametro basato sul flusso:

Lifetime valore parametro basato sul flusso

Non è una situazione comune, ma in alcuni casi avanzati, potresti dover capire in che modo i valori dei parametri basati sui flussi vengono mantenuti (o eliminati) quando un flusso diventa inattivo e poi di nuovo attivo.

Il fatto che i valori dei parametri basati sui flussi vengano mantenuti quando un flusso diventa inattivo e poi di nuovo attivo dipende dall'elenco di flussi e dalle istanze di flusso nell'elenco.

• Quando il flusso A passa al flusso B utilizzando un target di transizione specifico, il flusso A (flusso principale) rimane nello stack, mantiene i valori dei parametri a livello di flusso e viene aggiunta una nuova istanza del flusso B (flusso secondario) allo stack.
• Quando un flusso secondario torna a un flusso principale utilizzando un target di transizione simbolico (ad esempio END_FLOW), il flusso secondario viene rimosso dallo stack, tutti i valori dei parametri basati sul flusso secondario vengono ignorati e tutti i valori dei parametri basati sul flusso principale vengono mantenuti.
• Utilizzando una serie di transizioni con target di transizione specifici, la serie di flussi può contenere più istanze di un tipo di flusso. Ogni istanza del tipo di flusso ha valori di parametro specifici per il flusso. Ad esempio: A1 -> B1 -> C1 -> B2, dove A, B e C sono tipi di flusso e i numeri indicano le istanze di questi tipi di flusso. In questo esempio, B1 e B2 sono istanze diverse del flusso B e hanno parametri basati sul flusso univoci.

Esempi:

Parametri basati sulla richiesta

I parametri basati sulla richiesta sono parametri di breve durata creati dagli agenti di conversazione (Dialogflow CX) a cui è possibile fare riferimento solo durante il ciclo di vita della richiesta corrente e che non vengono mantenuti nei parametri della sessione.

I parametri basati sulla richiesta vengono generati da Conversational Agents (Dialogflow CX) per le seguenti funzionalità.

Parametri integrati

Puoi accedere ai vari dati associati alla richiesta utilizzando:

Payload personalizzato

Quando è impostato QueryParameters.payload, puoi accedere al parametro corrispondente tramite $request.payload.param-id.

Analisi del sentiment

Quando l'analisi del sentiment è attiva, sono disponibili i seguenti riferimenti al sentiment:

Oscuramento dei parametri

Per qualsiasi parametro di intent o modulo, puoi attivare l'oscuramento dei parametri, che oscura i dati dei parametri di runtime dell'utente finale dai log e dallo spazio di archiviazione interno degli agenti di conversazione (Dialogflow CX). I parametri oscurati vengono visualizzati come $parameter-name_redacted nei log.

Ad esempio, immagina un input dell'utente finale "Il mio indirizzo è 1600 Amphitheatre Parkway" che genera un parametro address inviato a "1600 Amphitheatre Parkway". Il testo registrato sarà "Il mio indirizzo è $address_redacted".

Per attivare l'oscuramento dei parametri:

In alternativa, puoi oscurare tutti i parametri di un tipo di entità specifico.