Riferimento API Interactive Canvas

L'API Interactive Canvas è una libreria JavaScript che puoi usare per interfacciarti con l'azione conversazionale utilizzando l'oggetto interactiveCanvas nella tua app web.

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

Per ulteriori informazioni su Interactive Canvas, consulta la documentazione di Interactive Canvas.

Metodi

Avviso: alcune API Interactive Canvas sono attualmente in Anteprima per gli sviluppatori. Puoi testare le API nel simulatore, ma non eseguire il deployment di un'Azione che utilizza queste funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando queste funzionalità non funzioneranno sui dispositivi degli utenti finali.

pronta

ready(callbacks) returns undefined

Richiamato dall'app web Interactive Canvas dopo il caricamento per registrare le richiamate.

Parametri
callbacks	InteractiveCanvasCallbacks Un oggetto che contiene i callback di metodo.

Nota: devi richiamare l'API ready nell'app web non appena la pagina viene caricata. 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: È presente una query in corso e la nuova query verrà eliminata. UNKNOWN: Impossibile determinare lo stato attuale della query.

Attenzione: 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 Consente di stabilire se attivare o meno il microfono dopo la riproduzione della sintesi vocale.

createIntentHandler

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno 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 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. Si può registrare utilizzando expect() o prompt().

MatchedIntent

Un oggetto contenente i dati per un intent corrispondente.

Metodi
getIntentArg(parameterName)	function(string) Metodo per ottenere il parametro dell'intent per un intent con corrispondenza.

createNumberSlot

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno 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 l'area annuncio viene riempita.
hints	Hints Parole brevi che l'utente potrebbe pronunciare durante l'inserimento di un'area annuncio. 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno 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 l'area annuncio viene riempita.
hints	Hints Parole brevi che l'utente potrebbe pronunciare durante l'inserimento di un'area annuncio. 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Crea un'area di tipo booleano.

Parametri
callback	function(FilledSlot) Funzione da eseguire quando l'area annuncio viene riempita.
hints	Hints Parole brevi che l'utente potrebbe pronunciare durante l'inserimento di un'area annuncio. 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Crea un'area da un elenco predefinito di opzioni.

Parametri
options	array<Option> Funzione da eseguire quando l'area annuncio viene riempita.
callback	function(FilledSlot) Funzione da eseguire quando l'area annuncio viene riempita.
hints	Hints Parole brevi che l'utente potrebbe pronunciare durante l'inserimento di un'area annuncio. hints aiutano il sistema NLU a decidere quale slot riempire.
Slot	object Oggetto slot che può essere registrato utilizzando prompt().

Area

Oggetto che rappresenta un'area da riempire. Si può registrare utilizzando expect() o prompt().

FilledSlot<T>

Oggetto che rappresenta un'area riempita.

Parametro
T	boolean|number|string Il tipo di area annuncio.

Opzione

Oggetto che rappresenta una voce di tipo slot.

Campi
key	string L'identificatore univoco della voce di tipo area.
synonyms	array<string> Un elenco di parole utilizzate per selezionare l'opzione 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.

expect

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

expect(expectation) returns HandlerRegistration

Registra l'aspettativa sul client. Può essere chiamato su gestori di intent e slot.

Parametri
expectation	IntentHandler|Slot Il gestore di intent o l'area annuncio da registrare.
HandlerRegistration	object L'area o il gestore di intent registrato.

HandlerRegistration

Un oggetto che rappresenta un gestore di intent registrato.

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

clearExpectations

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

clearExpectations() returns undefined;

Rimuove tutte le aspettative eliminando tutti i gestori di intent e le aree annuncio registrati in precedenza.

richiesta

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Invia una richiesta all'utente con la stringa TTS fornita e registra l'aspettativa sul client. Può essere chiamato su gestori di intent e slot.

Parametri
tts	string La stringa TTS utilizzata per richiedere all'utente l'aspettativa fornita.
expectation	IntentHandler|Slot Il gestore di intent o l'area annuncio 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 con una risposta che non corrispondeva alla risposta prevista o a nessun altro intento previsto. YIELD: L'utente ha risposto alla richiesta con un intento diverso.

triggerScene

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Imposta la coppia chiave-valore trasmessa 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Consente di acquisire il valore del parametro per la chiave specificata se esiste e lo stato della chiamata.

Parametri
key	string La chiave del parametro.

resetUserParam

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

resetUserParam() returns Promise<void>;

Cancella tutti i parametri utente.

setHomeParam

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Imposta la coppia chiave-valore trasmessa 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 sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

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

Consente di acquisire il valore del parametro per la chiave specificata se esiste e lo stato della chiamata.

Parametri
key	string La chiave del parametro.

resetHomeParam

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

resetHomeParam() returns Promise<void>;

Cancella tutti i parametri utente.

setCanvasState

setCanvasState(state) returns undefined

Comunica all'assistente che lo stato dell'app web Canvas è stato aggiornato. Il metodo setCanvasState non restituisce un valore. È possibile accedere al payload dello stato tramite la proprietà conv.context.canvas.state.

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

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

InteractiveCanvasCallbacks

Questi callback forniscono un modo per rispondere a informazioni o richieste dell'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 scadrà dopo 10 secondi.

Parametri
data	Object Dati aggiornati inviati dal webhook.

onTtsMark

onTtsMark(markName) returns undefined

Callback richiamato durante la riproduzione di sintesi vocale.

Segni 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 del TTS.

Puoi anche definire marchi personalizzati utilizzando SSML e il tag <mark>, come <mark name="custom"/>.

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

• Prima dell'inizio della sintesi vocale, l'utente tocca il microfono o il client Interactive Canvas richiama sendTextQuery. La sintesi vocale viene annullata e gli eventuali marchi SSML nel TTS vengono ignorati.
• Durante la sintesi vocale, l'utente tocca il microfono o il client Interactive Canvas richiama sendTextQuery. La sintesi vocale viene interrotta ed eventuali contrassegni SSML rimanenti nel TTS vengono ignorati.

Parametri
markName	string Contrassegna il nome richiamato durante la riproduzione TTS.

onInputStatusChanged

Attenzione: questa API è attualmente in anteprima per sviluppatori. Puoi testare questa API nel simulatore, ma non eseguire il deployment di un'azione che utilizzi questa funzionalità nei canali alpha, beta o di produzione. Le azioni distribuite utilizzando questa funzionalità non funzioneranno sui dispositivi degli utenti finali.

onInputStatusChanged(inputStatus) returns undefined

Comunica all'app Canvas che lo stato di inserimento dell'assistente è cambiato.

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