Referensi Canvas API interaktif

Interactive Canvas API adalah library JavaScript yang Anda gunakan untuk berinteraksi dengan Action Percakapan menggunakan objek interactiveCanvas di aplikasi web.

Catatan: Objek interactiveCanvas dilampirkan ke objek window. Jika menggunakan framework front-end untuk mengembangkan aplikasi web, Anda harus memastikan bahwa Anda memiliki akses ke window untuk menyiapkan API.

Untuk informasi selengkapnya tentang Interactive Canvas, lihat dokumentasi Kanvas Interaktif.

Metode

Peringatan: Beberapa API Interactive API saat ini berada dalam Pratinjau Developer. Anda dapat menguji API dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

siap

ready(callbacks) returns undefined

Dipanggil oleh aplikasi web Canvas Interaktif setelah dimuat untuk mendaftarkan callback.

Parameter
callbacks	InteractiveCanvasCallbacks Objek yang berisi callback metode.

Catatan: Anda harus memanggil ready API di aplikasi web segera setelah halaman dimuat. Jika tidak, Action akan ditutup.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Mengirim kueri teks ke tindakan percakapan.

Parameter
textQuery	string Kueri yang akan dikirim ke tindakan percakapan.
state	string Salah satu dari berikut ini: READY: Permintaan dapat diterima oleh platform. BLOCKED: Ada kueri yang sedang berlangsung dan kueri baru akan dihapus. UNKNOWN: Status kueri saat ini tidak dapat ditentukan.

Perhatian: textQuery harus terdiri dari 640 karakter atau kurang.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Menentukan tinggi header di bagian atas layar.

Parameter
height	number Tinggi dalam piksel.

outputTT

outputTts(text, openMic) returns undefined;

Memutar teks SSML.

Parameter
text	string String yang didukung SSML akan dimainkan.
openMic	boolean Apakah mikrofon akan dibuka setelah TTS diputar.

createIntentHandler

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

createIntentHandler(intentId, callback) returns IntentHandler

Membuat pengendali intent untuk intent kustom NLU.

Parameter
intentId	string Nama intent seperti yang ditetapkan dalam Actions Builder.
callback	function(MatchedIntent) Fungsi yang akan dieksekusi saat intent dicocokkan.
IntentHandler	object Objek pengendali intent yang dapat didaftarkan menggunakan expect().

Pengendali Intent

Objek yang mewakili pengendali intent. Dapat terdaftar menggunakan expect() atau prompt().

Intent yang Cocok

Objek yang berisi data untuk intent yang cocok.

Metode
getIntentArg(parameterName)	function(string) Metode untuk mendapatkan parameter intent dari intent yang cocok.

createNumberSlot

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Membuat slot nomor jenis.

Parameter
callback	function(FilledSlot) Fungsi yang akan dieksekusi saat slot diisi.
hints	Hints Kata pendek yang mungkin diucapkan pengguna saat mengisi slot. hints membantu sistem NLU menentukan slot mana yang harus diisi.
Slot	object Objek slot yang dapat didaftarkan menggunakan prompt().

createTextSlot

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Membuat slot string jenis.

Parameter
callback	function(FilledSlot) Fungsi yang akan dieksekusi saat slot diisi.
hints	Hints Kata pendek yang mungkin diucapkan pengguna saat mengisi slot. hints membantu sistem NLU menentukan slot mana yang harus diisi.
Slot	object Objek slot yang dapat didaftarkan menggunakan prompt().

createConfirmationSlot

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Membuat slot boolean jenis.

Parameter
callback	function(FilledSlot) Fungsi yang akan dieksekusi saat slot diisi.
hints	Hints Kata pendek yang mungkin diucapkan pengguna saat mengisi slot. hints membantu sistem NLU menentukan slot mana yang harus diisi.
Slot	object Objek slot yang dapat didaftarkan menggunakan prompt().

createOptionsSlot

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Membuat slot dari daftar opsi yang telah ditetapkan.

Parameter
options	array<Option> Fungsi yang akan dieksekusi saat slot diisi.
callback	function(FilledSlot) Fungsi yang akan dieksekusi saat slot diisi.
hints	Hints Kata pendek yang mungkin diucapkan pengguna saat mengisi slot. hints membantu sistem NLU menentukan slot mana yang harus diisi.
Slot	object Objek slot yang dapat didaftarkan menggunakan prompt().

Slot

Objek yang mewakili slot yang akan diisi. Dapat terdaftar menggunakan expect() atau prompt().

Slot yang Diisi<T>

Objek yang mewakili slot yang terisi.

Parameter
T	boolean|number|string Jenis slot.

Opsi

Objek yang merepresentasikan entri jenis slot.

Kolom
key	string ID unik untuk entri jenis slot.
synonyms	array<string> Daftar kata yang digunakan untuk memilih opsi slot.

Petunjuk

Objek yang merepresentasikan petunjuk untuk slot.

Kolom
associatedWords	array<string> Daftar kata yang digunakan untuk membantu sistem NLU menentukan slot mana yang harus diisi.

harapkan

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

expect(expectation) returns HandlerRegistration

Mendaftarkan ekspektasi pada klien. Dapat dipanggil pada pengendali dan slot intent.

Parameter
expectation	IntentHandler|Slot Pengendali atau slot intent yang akan didaftarkan.
HandlerRegistration	object Pengendali atau slot intent yang terdaftar.

HandlerPendaftaran

Objek yang mewakili pengendali intent terdaftar.

Metode
deleteHandler()	function Membatalkan pendaftaran pengendali intent yang diharapkan.

hapusEkspektasi

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

clearExpectations() returns undefined;

Menghapus semua ekspektasi dengan menghapus semua pengendali dan slot intent yang sebelumnya terdaftar.

perintah

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Meminta pengguna dengan string TTS yang disediakan, dan mendaftarkan ekspektasi pada klien. Dapat dipanggil pada pengendali dan slot intent.

Parameter
tts	string String TTS yang digunakan untuk meminta ekspektasi yang diberikan pengguna.
expectation	IntentHandler|Slot Pengendali atau slot intent yang akan didaftarkan.
Answer<T>	object Jawaban yang diberikan pengguna untuk perintah.

Jawaban<T>

Objek yang mewakili jawaban yang diberikan pengguna untuk perintah.

Kolom
value	boolean|number|string Nilai jawaban yang disediakan pengguna.
status	string Status jawaban. Salah satu dari berikut ini: ANSWERED: Pengguna merespons perintah dengan jawaban. NO_MATCH: Pengguna dimintai jawaban dan merespons dengan jawaban yang tidak cocok dengan jawaban yang diharapkan atau niat lain yang diharapkan. YIELD: Pengguna merespons perintah dengan intent yang berbeda.

memicu

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Memicu scene.

Parameter
sceneName	string Nama scene yang akan dipicu.
TriggerSceneStatus	string Status panggilan ke pemicuScene(). Salah satu dari berikut ini: SUCCESS: Permintaan berhasil diproses oleh server. BLOCKED: Permintaan diblokir oleh kueri yang sudah ada dan sedang diproses. UNKNOWN: Status permintaan tidak diketahui.

setUserParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Menetapkan key-value pair yang diteruskan dan dipertahankan di antara percakapan.

Parameter
key	string Kunci parameter.
value	object|array|boolean|number|string Nilai parameter.

getUserParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Mendapatkan nilai parameter untuk kunci yang diberikan jika ada dan status pemanggilan.

Parameter
key	string Kunci parameter.

resetUserParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

resetUserParam() returns Promise<void>;

Menghapus semua parameter pengguna.

setHomeParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Menetapkan key-value pair yang diteruskan dan dipertahankan di antara percakapan.

Parameter
key	string Kunci parameter.
value	object|array|boolean|number|string Nilai parameter.

getHomeParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

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

Mendapatkan nilai parameter untuk kunci yang diberikan jika ada dan status pemanggilan.

Parameter
key	string Kunci parameter.

resetHomeParam

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

resetHomeParam() returns Promise<void>;

Menghapus semua parameter pengguna.

setCanvasState

setCanvasState(state) returns undefined

Memberitahukan Asisten bahwa aplikasi web Canvas telah memperbarui statusnya. Metode setCanvasState tidak menampilkan nilai. Payload status dapat diakses melalui properti conv.context.canvas.state.

Perhatian: Panjang representasi string objek state harus kurang dari atau sama dengan 50.000 karakter. Jika panjang string melebihi 50.000 karakter, error akan ditampilkan.

Parameter
state	Object Status terbaru aplikasi Canvas sebagai objek JSON.

InteractiveCanvasCallbacks

Callback ini memberikan cara bagi Anda untuk merespons informasi atau permintaan dari Action Percakapan, sedangkan metode ini menyediakan cara untuk mengirim informasi atau permintaan ke Action Percakapan Anda.

onUpdate

onUpdate(data) returns Promise|undefined

Dipanggil saat respons Canvas dikirim dari Action Percakapan. TTS akan dimulai saat Promise yang ditampilkan diselesaikan, atau waktu tunggu habis setelah 10 detik.

Parameter
data	Object Data yang diperbarui yang dikirim oleh webhook.

onTtsMark

onTtsMark(markName) returns undefined

Callback yang dipanggil selama pemutaran TTS.

Tanda khusus yang selalu dipicu:

• START menunjukkan bagian awal TTS.
• END menunjukkan akhir TTS.
• ERROR menunjukkan error saat memutar TTS.

Anda juga dapat menentukan tanda kustom menggunakan SSML dan tag <mark>, seperti <mark name="custom"/>.

Catatan: Tanda SSML tidak dipanggil jika hal berikut terjadi:

• Sebelum TTS dimulai, pengguna mengetuk mikrofon, atau klien Interactive Canvas akan memanggil sendTextQuery. TTS dibatalkan dan tanda SSML apa pun di TTS diabaikan.
• Selama TTS, pengguna mengetuk mikrofon, atau klien Interactive Canvas memanggil sendTextQuery. TTS terganggu dan sisa tanda SSML di TTS diabaikan.

Parameter
markName	string Menandai nama yang dipanggil selama pemutaran TTS.

onInputStatusChanged

Perhatian: API ini sedang dalam Pratinjau Developer. Anda dapat menguji API ini dalam simulator, tetapi jangan men-deploy Action yang menggunakan fitur ini ke saluran alfa, beta, atau produksi. Tindakan yang di-deploy menggunakan fitur ini tidak akan berfungsi pada perangkat pengguna akhir.

onInputStatusChanged(inputStatus) returns undefined

Memberitahukan aplikasi Canvas bahwa status input Asisten telah berubah.

Parameter
inputStatus	Enum Status pemrosesan input suara dan/atau teks di perangkat. Dapat berupa hal berikut: LISTENING : Mikrofon terbuka. IDLE : Mikrofon ditutup. PROCESSING : Asisten saat ini mengeksekusi kueri (mikrofon ditutup).