Dokumentacja interfejsu Interactive Canvas API

Interfejs Interactive Canvas API to biblioteka JavaScript, której możesz używać do za pomocą akcji związanej z rozmową, używając obiektu interactiveCanvas w aplikacji internetowej.

Uwaga: obiekt interactiveCanvas jest dołączony do obiektu window. Jeśli korzysta z platformy frontendowej do tworzenia aplikacji internetowej, musisz upewnić się, że masz dostęp do usługi window w celu skonfigurowania interfejsu API.

Więcej informacji o interaktywnym obszarze roboczym znajdziesz w artykule Interaktywny obszar roboczy dokumentacji.

Metody

Ostrzeżenie: niektóre Interfejsy API Interactive Canvas są obecnie dostępne w wersji przedpremierowej dla programistów. Interfejsy API możesz przetestować w symulatora, ale nie wdrażaj Akcji, które korzystają z tych funkcji w wersji alfa, beta lub produkcyjnej kanałów. Działania wdrożone za pomocą tych funkcji nie będą działać u użytkowników urządzenia.

gotowe

ready(callbacks) returns undefined

Wywoływana przez aplikację internetową Interactive Canvas po załadowaniu w celu zarejestrowania wywołań zwrotnych.

Parametry
callbacks	InteractiveCanvasCallbacks Obiekt zawierający wywołania zwrotne metody.

Uwaga: musisz wywołać interfejs API ready w aplikacji internetowej, gdy tylko strona zostanie wczytano. W przeciwnym razie akcja zostanie zamknięta.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Wysyła zapytanie tekstowe do działania konwersacyjnego.

Parametry
textQuery	string Zapytanie, które ma zostać wysłane do działania konwersacyjnego.
state	string Jedna z tych wartości: READY: Prośby mogą być akceptowane przez platformę. BLOCKED: jest w trakcie wyświetlania zapytanie, w związku z czym nowe zostanie usunięte. UNKNOWN: Nie udało się określić bieżącego stanu zapytania.

Uwaga: pole textQuery może zawierać maksymalnie 640 znaków.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Określa wysokość nagłówka na górze wyświetlacza.

Parametry
height	number Wysokość w pikselach.

outputTts

outputTts(text, openMic) returns undefined;

Odtwarza tekst SSML.

Parametry
text	string Ciąg tekstowy obsługiwany przez SSML, który ma zostać odtworzony.
openMic	boolean Określa, czy włączyć mikrofon po zakończeniu odtwarzania tekstu.

createIntentHandler

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

createIntentHandler(intentId, callback) returns IntentHandler

Tworzy moduł obsługi intencji dla intencji niestandardowej NLU.

Parametry
intentId	string Nazwa intencji zdefiniowana w Actions Builder.
callback	function(MatchedIntent) Funkcja, która ma zostać wykonana po spełnieniu intencji.
IntentHandler	object Obiekt modułu obsługi intencji, który można zarejestrować za pomocą expect().

IntentHandler

Obiekt reprezentujący moduł obsługi intencji. Można zarejestrować się za pomocą expect() lub prompt().

MatchedIntent

Obiekt zawierający dane dopasowanej intencji.

Metody
getIntentArg(parameterName)	function(string) Metoda pobierania parametru intencji dopasowanej intencji.

createNumberSlot

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Tworzy przedział typu liczbowego.

Parametry
callback	function(FilledSlot) Funkcja, która ma zostać wykonana po wypełnieniu boksu.
hints	Hints Krótkie słowa, które użytkownik może wypowiedzieć podczas wypełniania boksu. hints pomaga systemowi NLU zdecydować, który boks wypełnić.
Slot	object Obiekt boksu, który można zarejestrować za pomocą prompt().

createTextSlot

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Tworzy boks reklamowy typu ciąg znaków.

Parametry
callback	function(FilledSlot) Funkcja, która ma zostać wykonana po wypełnieniu boksu.
hints	Hints Krótkie słowa, które użytkownik może wypowiedzieć podczas wypełniania boksu. hints pomaga systemowi NLU zdecydować, który boks wypełnić.
Slot	object Obiekt boksu, który można zarejestrować za pomocą prompt().

createConfirmationSlot

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Tworzy przedział typu wartość logiczna.

Parametry
callback	function(FilledSlot) Funkcja, która ma zostać wykonana po wypełnieniu boksu.
hints	Hints Krótkie słowa, które użytkownik może wypowiedzieć podczas wypełniania boksu. hints pomaga systemowi NLU zdecydować, który boks wypełnić.
Slot	object Obiekt boksu, który można zarejestrować za pomocą prompt().

createOptionsSlot

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Tworzy boks ze wstępnie zdefiniowanej listy opcji.

Parametry
options	array<Option> Funkcja, która ma zostać wykonana po wypełnieniu boksu.
callback	function(FilledSlot) Funkcja, która ma zostać wykonana po wypełnieniu boksu.
hints	Hints Krótkie słowa, które użytkownik może wypowiedzieć podczas wypełniania boksu. hints pomaga systemowi NLU zdecydować, który boks wypełnić.
Slot	object Obiekt boksu, który można zarejestrować za pomocą prompt().

Boks

Obiekt reprezentujący boks do wypełnienia. Można zarejestrować się za pomocą expect() lub prompt().

FilledSlot<T>

Obiekt reprezentujący wypełniony boks.

Parametr
T	boolean|number|string Typ przedziału.

Opcja

Obiekt reprezentujący wpis typu przedziału.

Pola
key	string Unikalny identyfikator wpisu typu przedziału.
synonyms	array<string> Lista słów używanych do wyboru opcji boksu.

Wskazówki

Obiekt reprezentujący wskazówki dotyczące boksu.

Pola
associatedWords	array<string> Lista słów pomaganych systemowi NLU w podjęciu decyzji, które boksy wypełnić.

Nie tego się spodziewałem

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

expect(expectation) returns HandlerRegistration

Rejestruje oczekiwanie na kliencie. Może być wywoływana w przypadku modułów obsługi intencji i przedziałów.

Parametry
expectation	IntentHandler|Slot Moduł obsługi intencji lub przedział do zarejestrowania.
HandlerRegistration	object Zarejestrowany moduł obsługi intencji lub przedział.

HandlerRegistration

Obiekt reprezentujący zarejestrowany moduł obsługi intencji.

Metody
deleteHandler()	function Wyrejestrowuje oczekiwany moduł obsługi intencji.

clearExpectations

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

clearExpectations() returns undefined;

Eliminuje wszystkie oczekiwania przez usunięcie wszystkich zarejestrowanych wcześniej modułów obsługi intencji i przedziałów.

prompt

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Wyświetla użytkownikowi prośbę o podany ciąg tekstowy zamiany tekstu na mowę i rejestruje oczekiwanie u klienta. Może być wywoływana w przypadku modułów obsługi intencji i przedziałów.

Parametry
tts	string Ciąg tekstowy zamiany tekstu na tekst używany, aby zapytać użytkownika o podaną odpowiedź.
expectation	IntentHandler|Slot Moduł obsługi intencji lub przedział do zarejestrowania.
Answer<T>	object Odpowiedź użytkownika na prompt.

Odpowiedz<T>

Obiekt reprezentujący odpowiedź użytkownika na prompt.

Pola
value	boolean|number|string Wartość odpowiedzi podanej przez użytkownika.
status	string Stan odpowiedzi. Jedna z tych wartości: ANSWERED: Użytkownik odpowiedział na prompt NO_MATCH: Użytkownik został poproszony o podanie odpowiedzi, która nie pasuje do oczekiwanej lub niezwiązanej z innym zamiarem użytkownika. YIELD: Użytkownik odpowiedział na prompt w innym zamiarze.

triggerScene

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Wyzwala scenę.

Parametry
sceneName	string Nazwa sceny, która ma zostać wyzwolona.
TriggerSceneStatus	string Stan wywołania aktywatora Scene(). Jedna z tych wartości: SUCCESS: Serwer pomyślnie przetworzył żądanie. BLOCKED: Żądanie zostało zablokowane przez istniejące zapytanie w trakcie wyświetlania. UNKNOWN: Stan prośby jest nieznany.

setUserParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Ustawia parę klucz-wartość, która jest przekazywana i zachowywana między wątkami.

Parametry
key	string Klucz parametru.
value	object|array|boolean|number|string Wartość parametru.

getUserParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Pobiera wartość parametru dla danego klucza (jeśli istnieje) oraz stan wywołania.

Parametry
key	string Klucz parametru.

resetUserParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

resetUserParam() returns Promise<void>;

Usuwa wszystkie parametry użytkownika.

setHomeParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Ustawia parę klucz-wartość, która jest przekazywana i zachowywana między wątkami.

Parametry
key	string Klucz parametru.
value	object|array|boolean|number|string Wartość parametru.

getHomeParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

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

Pobiera wartość parametru dla danego klucza (jeśli istnieje) oraz stan wywołania.

Parametry
key	string Klucz parametru.

resetHomeParam

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

resetHomeParam() returns Promise<void>;

Usuwa wszystkie parametry użytkownika.

setCanvasState

setCanvasState(state) returns undefined

Powiadamia Asystenta, że aplikacja internetowa Canvas zaktualizowała swój stan. setCanvasState nie zwraca wartości. Dostęp do ładunku stanowego można uzyskać za pomocą conv.context.canvas.state.

Uwaga: obiekt state może mieć długość reprezentacji ciągu znaków nie może być dłuższy niż 50 000 znaków. Jeśli ciąg zawiera więcej niż 50 000 znaków wyświetli się błąd.

Parametry
state	Object Zaktualizowany stan aplikacji Canvas jako obiekt JSON.

InteractiveCanvasCallbacks

Dzięki tym wywołaniem możesz odpowiadać na informacje lub prośby z akcji konwersacyjnych, a metody umożliwiają wysyłanie informacje lub żądania do akcji dotyczącej konwersacji.

onUpdate

onUpdate(data) returns Promise|undefined

Wywoływana, gdy z poziomu akcji dotyczącej rozmów zostanie wysłana odpowiedź Canvas. Funkcja TTS rozpocznie się, zwrócona obietnica jest zrealizowana lub upłynął limit czasu po 10 sekundach.

Parametry
data	Object Zaktualizowane dane wysłane przez webhooka.

onTtsMark

onTtsMark(markName) returns undefined

Wywołanie zwrotne wywoływane podczas odtwarzania zamiany tekstu na mowę.

Znaki specjalne, które są zawsze aktywowane:

• START wskazuje początek TTS.
• END oznacza koniec TTS.
• ERROR oznacza błąd zamiany tekstu na mowę.

Znaczniki niestandardowe możesz też zdefiniować, używając SSML i tagu <mark>, np. <mark name="custom"/>

Uwaga: znaczniki SSML nie są wywoływane w tych przypadkach:

.
• Przed rozpoczęciem zamiany tekstu na mowę użytkownik klika mikrofon lub obszar interaktywnego obszaru roboczego. klient wywołuje metodę sendTextQuery. Transmitowanie na żywo zostanie anulowane, a wszystkie znaki SSML funkcja zamiany tekstu na mowę będzie ignorowana.
• Podczas zamiany tekstu na mowę użytkownik klika mikrofon lub klient Interactive Canvas wywołuje sendTextQuery Przetwarzanie tekstu na mowę zostanie przerwane i wszystkie pozostałe fragmenty SSML są ignorowane.

Parametry
markName	string Oznacz nazwę wywoływaną podczas odtwarzania TTS.

onInputStatusChanged

Uwaga: ten interfejs API jest obecnie w wersji przedpremierowa wersja dla programistów. Możesz przetestować ten interfejs API w symulatorze, ale nie wdrażaj działania który korzysta z tej funkcji w kanale alfa, beta lub produkcyjnym. Działania wdrożone za pomocą tego nie działa na urządzeniach użytkowników.

onInputStatusChanged(inputStatus) returns undefined

Powiadamia aplikację Canvas o zmianie stanu wprowadzania danych przez Asystenta.

Parametry
inputStatus	Enum Stan przetwarzania głosu lub tekstu na urządzeniu. Puszka w następujący sposób: LISTENING : mikrofon jest otwarty. IDLE : mikrofon jest zamknięty. PROCESSING : Asystent właśnie wykonuje (mikrofon jest zamknięty).