Riferimento API Interactive Canvas

L'API Interactive Canvas è una libreria JavaScript che puoi utilizzare per l'interfaccia con l'azione conversazionale utilizzando l'oggetto interactiveCanvas nell'app web.

Nota: l'oggetto interactiveCanvas è collegato all'oggetto window. Se utilizzare un framework front-end per sviluppare la tua applicazione web, devi assicurarti di avere accesso a window per configurare l'API.

Per ulteriori informazioni su Interactive Canvas, vedi Interactive Canvas documentazione.

Metodi

Avviso: alcuni dei Le API Interactive Canvas sono attualmente in Anteprima per gli sviluppatori. Puoi testare le API nella il simulatore, ma non implementare un'azione che utilizza queste funzionalità nei canali alpha, beta o di produzione canali. Le azioni di cui è stato eseguito il deployment utilizzando queste funzionalità non funzioneranno sull'utente finale dispositivi mobili.

pronto

ready(callbacks) returns undefined

Richiamato dall'app web Interactive Canvas al termine del caricamento per la registrazione dei callback.

Parametri
callbacks	InteractiveCanvasCallbacks Un oggetto che contiene callback di metodi.

Nota: devi richiamare l'API ready nell'app web non appena la pagina viene caricato. In caso contrario, l'azione si chiude.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Invia una query di testo all'azione conversazionale.

Parametri
textQuery	string La query da inviare all'azione conversazionale.
state	string Il valore sarà uno dei seguenti: READY: Le richieste possono essere accettate dalla piattaforma. BLOCKED: Esiste una query in fase di pubblicazione e la nuova query verrà eliminata. UNKNOWN: Impossibile determinare lo stato attuale della query.

Attenzione: il valore textQuery deve contenere al massimo 640 caratteri.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Determina l'altezza dell'intestazione nella parte superiore di una visualizzazione.

Parametri
height	number L'altezza in pixel.

outputTts

outputTts(text, openMic) returns undefined;

Riproduce il testo SSML.

Parametri
text	string La stringa supportata da SSML da riprodurre.
openMic	boolean Indica se attivare il microfono dopo la sintesi vocale.

createIntentHandler

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

createIntentHandler(intentId, callback) returns IntentHandler

Crea un gestore di intent per un intent personalizzato NLU.

Parametri
intentId	string Nome dell'intent come definito in Actions Builder.
callback	function(MatchedIntent) Funzione da eseguire in caso di corrispondenza dell'intent.
IntentHandler	object Oggetto gestore di intent che può essere registrato utilizzando expect().

IntentHandler

Un oggetto che rappresenta un gestore di intent. Può essere registrato utilizzando expect() o prompt().

MatchedIntent

Un oggetto contenente i dati per un intent corrispondente.

Metodi
getIntentArg(parameterName)	function(string) Metodo per ottenere il parametro di intent di un intent corrispondente.

createNumberSlot

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

createNumberSlot(callback, hints?) returns Slot<number>

Crea uno slot di tipo numero.

Parametri
callback	function(FilledSlot) Funzione da eseguire quando lo slot è riempito.
hints	Hints Parole brevi che l'utente potrebbe pronunciare per riempire uno spazio. hints aiutano il sistema NLU a decidere quale slot riempire.
Slot	object Oggetto slot che può essere registrato utilizzando prompt().

createTextSlot

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

createTextSlot(callback, hints?) returns Slot<string>

Crea uno slot di tipo stringa.

Parametri
callback	function(FilledSlot) Funzione da eseguire quando lo slot è riempito.
hints	Hints Parole brevi che l'utente potrebbe pronunciare per riempire uno spazio. hints aiutano il sistema NLU a decidere quale slot riempire.
Slot	object Oggetto slot che può essere registrato utilizzando prompt().

createConfirmationSlot

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

createConfirmationSlot(callback, hints?) returns Slot<boolean>

Crea uno slot di tipo booleano.

Parametri
callback	function(FilledSlot) Funzione da eseguire quando lo slot è riempito.
hints	Hints Parole brevi che l'utente potrebbe pronunciare per riempire uno spazio. hints aiutano il sistema NLU a decidere quale slot riempire.
Slot	object Oggetto slot che può essere registrato utilizzando prompt().

createOptionsSlot

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

createOptionsSlot(options, callback, hints?) returns Slot<string>

Crea uno spazio da un elenco predefinito di opzioni.

Parametri
options	array<Option> Funzione da eseguire quando lo slot è riempito.
callback	function(FilledSlot) Funzione da eseguire quando lo slot è riempito.
hints	Hints Parole brevi che l'utente potrebbe pronunciare per riempire uno spazio. hints aiutano il sistema NLU a decidere quale slot riempire.
Slot	object Oggetto slot che può essere registrato utilizzando prompt().

Slot

Un oggetto che rappresenta un'area da riempire. Può essere registrato utilizzando expect() o prompt().

FilledSlot<T>

Un oggetto che rappresenta uno spazio pieno.

Parametro
T	boolean|number|string Il tipo di slot.

Opzione

Un oggetto che rappresenta una voce di tipo slot.

Campi
key	string L'identificatore univoco della voce del tipo di slot.
synonyms	array<string> Un elenco di parole utilizzate per selezionare l'opzione di slot.

Suggerimenti

Un oggetto che rappresenta i suggerimenti per uno slot.

Campi
associatedWords	array<string> Un elenco di parole utilizzate per aiutare il sistema NLU a decidere quale slot riempire.

aspettavo

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

expect(expectation) returns HandlerRegistration

Registra l'aspettativa sul cliente. Può essere chiamato sui gestori di intent e gli slot.

Parametri
expectation	IntentHandler|Slot Il gestore di intent o lo slot da registrare.
HandlerRegistration	object Il gestore o lo slot dell'intent registrato.

HandlerRegistration

Un oggetto che rappresenta un gestore di intent registrato.

Metodi
deleteHandler()	function Annulla la registrazione del gestore di intent previsto.

clearExpectations

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

clearExpectations() returns undefined;

Rimuove tutte le aspettative eliminando tutti i gestori di intent e gli slot registrati in precedenza.

richiesta

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

prompt(tts, expectation) returns Promise<Answer<T>>

Chiedi all'utente la stringa TTS fornita e registra l'aspettativa sul client. Può essere chiamato sui gestori di intent e gli slot.

Parametri
tts	string La stringa della sintesi vocale utilizzata per chiedere all'utente l'aspettativa fornita.
expectation	IntentHandler|Slot Il gestore di intent o lo slot da registrare.
Answer<T>	object La risposta alla richiesta fornita dall'utente.

Risposta<T>

Un oggetto che rappresenta una risposta fornita dall'utente a un prompt.

Campi
value	boolean|number|string Il valore della risposta fornita dall'utente.
status	string Lo stato della risposta. Il valore sarà uno dei seguenti: ANSWERED: L'utente ha risposto alla richiesta con una risposta. NO_MATCH: All'utente è stata chiesta una risposta e ha risposto che non corrispondeva a quanto previsto o a qualsiasi altra intenzione prevista. YIELD: L'utente ha risposto alla richiesta con un intento diverso.

triggerScene

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Attiva una scena.

Parametri
sceneName	string Il nome della scena da attivare.
TriggerSceneStatus	string Lo stato della chiamata a triggerScene(). Il valore sarà uno dei seguenti: SUCCESS: La richiesta è stata elaborata correttamente dal server. BLOCKED: La richiesta è stata bloccata da una query esistente in fase di pubblicazione. UNKNOWN: Lo stato della richiesta è sconosciuto.

setUserParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

setUserParam(key, value) returns Promise<undefined>;

Imposta la coppia chiave-valore trasferita e persistente tra le conversazioni.

Parametri
key	string La chiave del parametro.
value	object|array|boolean|number|string Il valore del parametro.

getUserParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

getUserParam(key) returns Promise<object|array|boolean|number|string>;

Recupera il valore del parametro per la chiave specificata, se esistente, e lo stato della chiamata.

Parametri
key	string La chiave del parametro.

resetUserParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

resetUserParam() returns Promise<void>;

Cancella tutti i parametri utente.

setHomeParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

setHomeParam(key, value) returns Promise<undefined>;

Imposta la coppia chiave-valore trasferita e persistente tra le conversazioni.

Parametri
key	string La chiave del parametro.
value	object|array|boolean|number|string Il valore del parametro.

getHomeParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

Recupera il valore del parametro per la chiave specificata, se esistente, e lo stato della chiamata.

Parametri
key	string La chiave del parametro.

resetHomeParam

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

resetHomeParam() returns Promise<void>;

Cancella tutti i parametri utente.

setCanvasState

setCanvasState(state) returns undefined

Informa l'assistente che l'app web Canvas ha aggiornato il proprio stato. La setCanvasState non restituisce alcun valore. È possibile accedere al payload dello stato tramite Proprietà conv.context.canvas.state.

Attenzione: la lunghezza della rappresentazione in formato stringa dell'oggetto state deve essere inferiore o uguale a 50.000 caratteri. Se la stringa supera i 50.000 caratteri viene restituito un errore.

Parametri
state	Object Lo stato aggiornato dell'app Canvas come oggetto JSON.

InteractiveCanvasCallbacks

Questi callback ti permettono di rispondere a informazioni o richieste dall'azione conversazionale mentre i metodi forniscono un modo per inviare informazioni o richieste all'Azione conversazionale.

onUpdate

onUpdate(data) returns Promise|undefined

Richiamato quando viene inviata una risposta Canvas dall'azione conversazionale. La sintesi vocale inizierà quando la promessa restituita viene risolta o scade dopo 10 secondi.

Parametri
data	Object Dati aggiornati inviati dal webhook.

onTtsMark

onTtsMark(markName) returns undefined

Callback richiamato durante la riproduzione della sintesi vocale.

Segnali speciali che vengono sempre attivati:

• START indica l'inizio della sintesi vocale.
• END indica la fine della sintesi vocale.
• ERROR indica un errore durante la riproduzione della sintesi vocale.

Puoi anche definire i segni personalizzati utilizzando SSML e il tag <mark>, ad esempio <mark name="custom"/>.

Nota: i contrassegni SSML non vengono richiamati quando si verifica quanto segue:

• Prima dell'inizio della sintesi vocale, l'utente tocca il microfono o il Canvas interattivo il client richiama sendTextQuery. La sintesi vocale viene annullata e qualsiasi contrassegno SSML nella vengono ignorati.
• Durante la sintesi vocale, l'utente tocca il microfono o il client Interactive Canvas richiama sendTextQuery. La sintesi vocale viene interrotta e qualsiasi SSML rimanente nella sintesi vocale vengono ignorati.

Parametri
markName	string Contrassegna il nome richiamato durante la riproduzione della sintesi vocale.

onInputStatusChanged

Attenzione: questa API è attualmente in Anteprima per gli sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizza questa funzionalità per i canali alfa, beta o di produzione. Azioni di cui è stato eseguito il deployment utilizzando questo non funzionerà sui dispositivi degli utenti finali.

onInputStatusChanged(inputStatus) returns undefined

Informa l'app Canvas che lo stato dell'input dell'assistente è cambiato.

Parametri
inputStatus	Enum Stato dell'elaborazione dell'input vocale e/o di testo sul dispositivo. Lattina potrebbe essere il seguente: LISTENING : il microfono è aperto. IDLE : microfono chiuso. PROCESSING : l'assistente sta eseguendo una (il microfono è chiuso).