Referenz zur Interactive Canvas API

Die Interactive Canvas API ist eine JavaScript-Bibliothek, die Sie als Schnittstelle mit der Konversationsaktion unter Verwendung des interactiveCanvas-Objekts in Ihrer Webanwendung.

Hinweis: Das interactiveCanvas-Objekt ist an das window-Objekt angehängt. Wenn Sie Frontend-Framework für die Entwicklung Ihrer Webanwendung verwenden, müssen Sie sicherstellen, Zugriff auf window, um die API einzurichten.

Weitere Informationen zum Interactive Canvas finden Sie unter Interactive Canvas. Dokumentation.

Methoden

Warnung: Einige der Interactive Canvas APIs befinden sich derzeit in der Entwicklervorschau. Sie können die APIs in der Simulator. Stellen Sie jedoch keine Aktionen bereit, die diese Funktionen für Alpha-, Beta- oder Produktionszwecke verwenden. Kanäle. Aktionen, die mit diesen Funktionen bereitgestellt werden, funktionieren für den Endnutzer nicht Geräte.

bereit

ready(callbacks) returns undefined

Wird von der Interactive Canvas-Web-App aufgerufen, nachdem sie geladen wurde, um Callbacks zu registrieren.

Parameter
callbacks	InteractiveCanvasCallbacks Ein Objekt, das Methodenrückrufe enthält.

Hinweis: Sie müssen die ready API in der Webanwendung aufrufen, sobald die Seite geladen. Andernfalls wird die Aktion geschlossen.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Sendet eine Textabfrage an die Unterhaltungsaktion.

Parameter
textQuery	string Die Abfrage, die an die Unterhaltungsaktion gesendet werden soll.
state	string Eines der folgenden Betriebssysteme: READY: Anfragen können von der Plattform akzeptiert werden. BLOCKED: Eine Abfrage ist aktiv und die neue Abfrage wird gelöscht. UNKNOWN: Der aktuelle Abfragestatus konnte nicht ermittelt werden.

Achtung :textQuery darf maximal 640 Zeichen enthalten.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Legt die Höhe der Kopfzeile oben auf einer Anzeige fest.

Parameter
height	number Die Höhe in Pixeln.

outputTts

outputTts(text, openMic) returns undefined;

Spielt SSML-Text ab.

Parameter
text	string Der von SSML unterstützte String, der abgespielt werden soll.
openMic	boolean Gibt an, ob das Mikrofon nach der Sprachausgabe aktiviert werden soll.

createIntentHandler

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

createIntentHandler(intentId, callback) returns IntentHandler

Erstellt einen Intent-Handler für einen benutzerdefinierten NLU-Intent.

Parameter
intentId	string Intent-Name gemäß Definition in Actions Builder.
callback	function(MatchedIntent) Funktion, die ausgeführt werden soll, wenn der Intent zugeordnet wird.
IntentHandler	object Intent-Handler-Objekt, das mit expect() registriert werden kann.

IntentHandler

Ein Objekt, das einen Intent-Handler darstellt. Kann mit expect() oder prompt() registriert werden.

MatchedIntent

Ein Objekt, das die Daten für einen zugeordneten Intent enthält.

Methoden
getIntentArg(parameterName)	function(string) Methode zum Abrufen des Intent-Parameters eines zugeordneten Intents.

createNumberSlot

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Erstellt einen Slot des Typs "number".

Parameter
callback	function(FilledSlot) Funktion, die ausgeführt werden soll, wenn die Anzeigenfläche gefüllt wird.
hints	Hints Kurze Wörter, die Nutzende beim Füllen einer Anzeigenfläche sagen könnten. hints das NLU-System bei der Entscheidung hilft, welche Anzeigenfläche gefüllt werden soll.
Slot	object Slot-Objekt, das mit prompt() registriert werden kann.

createTextSlot

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Erstellt einen Slot des Typs String.

Parameter
callback	function(FilledSlot) Funktion, die ausgeführt werden soll, wenn die Anzeigenfläche gefüllt wird.
hints	Hints Kurze Wörter, die Nutzende beim Füllen einer Anzeigenfläche sagen könnten. hints das NLU-System bei der Entscheidung hilft, welche Anzeigenfläche gefüllt werden soll.
Slot	object Slot-Objekt, das mit prompt() registriert werden kann.

createConfirmationSlot

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Erstellt einen Slot des Typs Boolesch.

Parameter
callback	function(FilledSlot) Funktion, die ausgeführt werden soll, wenn die Anzeigenfläche gefüllt wird.
hints	Hints Kurze Wörter, die Nutzende beim Füllen einer Anzeigenfläche sagen könnten. hints das NLU-System bei der Entscheidung hilft, welche Anzeigenfläche gefüllt werden soll.
Slot	object Slot-Objekt, das mit prompt() registriert werden kann.

createOptionsSlot

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Erstellt eine Anzeigenfläche aus einer vordefinierten Liste von Optionen.

Parameter
options	array<Option> Funktion, die ausgeführt werden soll, wenn die Anzeigenfläche gefüllt wird.
callback	function(FilledSlot) Funktion, die ausgeführt werden soll, wenn die Anzeigenfläche gefüllt wird.
hints	Hints Kurze Wörter, die Nutzende beim Füllen einer Anzeigenfläche sagen könnten. hints das NLU-System bei der Entscheidung hilft, welche Anzeigenfläche gefüllt werden soll.
Slot	object Slot-Objekt, das mit prompt() registriert werden kann.

Anzeigenfläche

Ein Objekt, das einen zu füllenden Slot darstellt. Kann mit expect() oder prompt() registriert werden.

FilledSlot<T>

Ein Objekt, das einen ausgefüllten Slot darstellt.

Parameter
T	boolean|number|string Der Slottyp.

Option

Ein Objekt, das einen Eintrag vom Typ „Slot“ darstellt.

Felder
key	string Die eindeutige Kennung für den Slottypeintrag.
synonyms	array<string> Eine Liste der Wörter, mit denen die Slot-Option ausgewählt wird.

Hinweise

Ein Objekt, das Hinweise für eine Anzeigenfläche darstellt.

Felder
associatedWords	array<string> Eine Liste von Wörtern, die dem NLU-System bei der Entscheidung helfen, welche Anzeigenfläche gefüllt werden soll.

erwarten

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

expect(expectation) returns HandlerRegistration

Registriert die Erwartung auf dem Client. Kann für Intent-Handler und -Slots aufgerufen werden.

Parameter
expectation	IntentHandler|Slot Der Intent-Handler oder Slot, der registriert werden soll.
HandlerRegistration	object Der registrierte Intent-Handler oder Slot.

HandlerRegistration

Ein Objekt, das einen registrierten Intent-Handler darstellt.

Methoden
deleteHandler()	function Hebt die Registrierung des erwarteten Intent-Handlers auf.

clearExpectations

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

clearExpectations() returns undefined;

Alle Erwartungen werden entfernt, indem alle zuvor registrierten Intent-Handler und ‐Slots gelöscht werden.

prompt

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Fordert den Nutzer mit dem angegebenen TTS-String auf und registriert die Erwartung auf dem Client. Kann für Intent-Handler und -Slots aufgerufen werden.

Parameter
tts	string Der TTS-String, mit dem der Nutzer aufgefordert wird, die angegebene Erwartung zu erfüllen.
expectation	IntentHandler|Slot Der Intent-Handler oder Slot, der registriert werden soll.
Answer<T>	object Die vom Nutzer angegebene Antwort auf die Aufforderung.

Answer<T> (Antwort<T>)

Ein Objekt, das eine vom Nutzer angegebene Antwort auf eine Aufforderung darstellt.

Felder
value	boolean|number|string Der Wert der vom Nutzer angegebenen Antwort.
status	string Der Antwortstatus. Eines der folgenden Betriebssysteme: ANSWERED: Der Nutzer hat auf die Aufforderung geantwortet. NO_MATCH: Der Nutzer wurde zu einer Antwort aufgefordert und antwortete mit einer Antwort, die nicht der erwarteten Antwort oder einer anderen erwarteten Absicht entspricht. YIELD: Der Nutzer hat mit einem anderen Intent auf die Aufforderung geantwortet.

triggerScene

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Löst eine Szene aus.

Parameter
sceneName	string Der Name der Szene, die ausgelöst werden soll.
TriggerSceneStatus	string Der Status des Aufrufs an triggerScene(). Eines der folgenden Betriebssysteme: SUCCESS: Die Anfrage wurde vom Server erfolgreich verarbeitet. BLOCKED: Die Anfrage wurde durch eine laufende Abfrage blockiert. UNKNOWN: Der Status der Anfrage ist unbekannt.

setUserParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Legt das Schlüssel/Wert-Paar fest, das zwischen Unterhaltungen übergeben und beibehalten wird.

Parameter
key	string Der Parameterschlüssel.
value	object|array|boolean|number|string Der Parameterwert.

getUserParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Ruft den Parameterwert für den angegebenen Schlüssel ab, sofern vorhanden, sowie den Status des Aufrufs.

Parameter
key	string Der Parameterschlüssel.

resetUserParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

resetUserParam() returns Promise<void>;

Löscht alle Nutzerparameter.

setHomeParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Legt das Schlüssel/Wert-Paar fest, das zwischen Unterhaltungen übergeben und beibehalten wird.

Parameter
key	string Der Parameterschlüssel.
value	object|array|boolean|number|string Der Parameterwert.

getHomeParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

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

Ruft den Parameterwert für den angegebenen Schlüssel ab, sofern vorhanden, sowie den Status des Aufrufs.

Parameter
key	string Der Parameterschlüssel.

resetHomeParam

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

resetHomeParam() returns Promise<void>;

Löscht alle Nutzerparameter.

setCanvasState

setCanvasState(state) returns undefined

Informiert Assistant darüber, dass die Canvas-Web-App ihren Status aktualisiert hat. Die setCanvasState gibt keinen Wert zurück. Auf die Statusnutzlast kann über die conv.context.canvas.state-Property.

Achtung :Die Stringdarstellung des state-Objekts muss mindestens maximal 50.000 Zeichen enthalten. Wenn der String länger als 50.000 Zeichen ist wird ein Fehler ausgegeben.

Parameter
state	Object Der aktualisierte Status der Canvas-App als JSON-Objekt.

InteractiveCanvasCallbacks

Mit diesen Callbacks kannst du auf Informationen oder Anfragen aus der Konversationsaktion generieren, während Sie mit den Methoden oder Anfragen an deine Konversationsaktion senden.

onUpdate

onUpdate(data) returns Promise|undefined

Wird aufgerufen, wenn eine Canvas-Antwort von der Konversationsaktion gesendet wird. Sprachausgabe wird gestartet, wenn Das zurückgegebene Promise wird aufgelöst oder es tritt nach 10 Sekunden eine Zeitüberschreitung auf.

Parameter
data	Object Aktualisierte Daten, die vom Webhook gesendet wurden.

onTtsMark

onTtsMark(markName) returns undefined

Callback, der während der Text-in-Sprache-Wiedergabe aufgerufen wird.

Sonderzeichen, die immer ausgelöst werden:

• START gibt den Beginn der Sprachausgabe an.
• END kennzeichnet das Ende der Sprachausgabe.
• ERROR zeigt einen Fehler bei der Sprachausgabe an.

Sie können benutzerdefinierte Marken auch mithilfe von SSML und dem <mark>-Tag definieren: <mark name="custom"/>.

Hinweis:SSML-Markierungen werden in folgenden Fällen nicht aufgerufen: <ph type="x-smartling-placeholder">

</ph>
• Vor der Sprachausgabe tippt der Nutzer auf das Mikrofon oder den interaktiven Canvas. ruft sendTextQuery auf. Die Sprachausgabe wird abgebrochen und alle SSML-Markierungen in werden die Sprachausgabe ignoriert.
• Während der Sprachausgabe tippt der Nutzer auf das Mikrofon oder ruft der Interactive Canvas Client sendTextQuery Die Text-in-Sprache-Funktion und die verbleibende SSML werden unterbrochen. werden ignoriert.

Parameter
markName	string Kennzeichnet den Namen, der während der Sprachausgabe-Wiedergabe aufgerufen wird.

onInputStatusChanged

Achtung: Diese API befindet sich derzeit in Entwicklervorschau Sie können diese API im Simulator testen, aber keine Aktion bereitstellen. die diese Funktion für Alpha-, Beta- oder Produktionskanäle nutzen. Aktionen, die mit diesem nicht auf Endnutzergeräten funktionieren.

onInputStatusChanged(inputStatus) returns undefined

Informiert die Canvas App darüber, dass sich der Assistant-Eingabestatus geändert hat.

Parameter
inputStatus	Enum Status der Verarbeitung der Sprach- und/oder Texteingabe auf dem Gerät. Kann wie folgt sein: LISTENING : Das Mikrofon ist offen. IDLE : Das Mikrofon ist geschlossen. PROCESSING : Assistant führt gerade eine (Mikrofon ist geschlossen).