Tài liệu tham khảo về Interactive Canvas API

API Canvas tương tác là một thư viện JavaScript mà bạn dùng để giao diện với Hành động trò chuyện bằng cách sử dụng đối tượng interactiveCanvas trong ứng dụng web.

Lưu ý: Đối tượng interactiveCanvas được đính kèm vào đối tượng window. Nếu sử dụng khung giao diện người dùng để phát triển ứng dụng web, bạn phải đảm bảo có quyền truy cập vào window để thiết lập API.

Để biết thêm thông tin về Canvas tương tác, hãy xem tài liệu về Canvas tương tác.

Phương thức

Cảnh báo: Một số API Canvas tương tác hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể kiểm thử các API trong trình mô phỏng, nhưng không triển khai Hành động sử dụng các tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng các tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

sẵn sàng

ready(callbacks) returns undefined

Được ứng dụng web Canvas tương tác gọi sau khi tải để đăng ký các lệnh gọi lại.

Các tham số
callbacks	InteractiveCanvasCallbacks Một đối tượng chứa các lệnh gọi lại phương thức.

Lưu ý: Bạn phải gọi API ready trong ứng dụng web ngay khi tải trang. Nếu không, Hành động đó sẽ kết thúc.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Gửi một yêu cầu văn bản đến hành động trò chuyện.

Các tham số
textQuery	string Cụm từ tìm kiếm để gửi đến hành động trò chuyện.
state	string Một trong những giá trị sau: READY: Nền tảng có thể chấp nhận yêu cầu. BLOCKED: Có một truy vấn đang được sử dụng và truy vấn mới sẽ bị loại bỏ. UNKNOWN: Không thể xác định trạng thái truy vấn hiện tại.

Lưu ý: textQuery chỉ được có tối đa 640 ký tự.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Xác định chiều cao của tiêu đề ở đầu màn hình.

Các tham số
height	number Chiều cao tính bằng pixel.

outputTts

outputTts(text, openMic) returns undefined;

Phát văn bản SSML.

Các tham số
text	string Chuỗi được hỗ trợ SSML sẽ được phát.
openMic	boolean Liệu có bật micrô sau khi tính năng TTS phát hay không.

createIntentHandler

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

createIntentHandler(intentId, callback) returns IntentHandler

Tạo trình xử lý ý định cho một ý định tuỳ chỉnh NLU.

Các tham số
intentId	string Tên ý định như được xác định trong Trình tạo hành động.
callback	function(MatchedIntent) Hàm sẽ được thực thi khi ý định được so khớp.
IntentHandler	object Đối tượng trình xử lý ý định có thể được đăng ký bằng expect().

IntentHandler

Một đối tượng đại diện cho trình xử lý ý định. Có thể đăng ký bằng expect() hoặc prompt().

MatchedIntent

Một đối tượng chứa dữ liệu cho một ý định phù hợp.

Phương thức
getIntentArg(parameterName)	function(string) Phương thức để lấy tham số ý định của một ý định đã so khớp.

createNumberSlot

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Tạo một khe theo kiểu số.

Các tham số
callback	function(FilledSlot) Hàm sẽ được thực thi khi vị trí được lấp đầy.
hints	Hints Các từ ngắn mà người dùng có thể nói khi lấp đầy một ô trống. hints giúp hệ thống NLU quyết định vị trí cần lấp đầy.
Slot	object Đối tượng vị trí có thể được đăng ký bằng prompt().

createTextSlot

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Tạo một khe của chuỗi kiểu.

Các tham số
callback	function(FilledSlot) Hàm sẽ được thực thi khi vị trí được lấp đầy.
hints	Hints Các từ ngắn mà người dùng có thể nói khi lấp đầy một ô trống. hints giúp hệ thống NLU quyết định vị trí cần lấp đầy.
Slot	object Đối tượng vị trí có thể được đăng ký bằng prompt().

createConfirmationSlot

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Tạo một khe thuộc loại boolean.

Các tham số
callback	function(FilledSlot) Hàm sẽ được thực thi khi vị trí được lấp đầy.
hints	Hints Các từ ngắn mà người dùng có thể nói khi lấp đầy một ô trống. hints giúp hệ thống NLU quyết định vị trí cần lấp đầy.
Slot	object Đối tượng vị trí có thể được đăng ký bằng prompt().

createOptionsSlot

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Tạo một vùng từ danh sách các tuỳ chọn được xác định trước.

Các tham số
options	array<Option> Hàm sẽ được thực thi khi vị trí được lấp đầy.
callback	function(FilledSlot) Hàm sẽ được thực thi khi vị trí được lấp đầy.
hints	Hints Các từ ngắn mà người dùng có thể nói khi lấp đầy một ô trống. hints giúp hệ thống NLU quyết định vị trí cần lấp đầy.
Slot	object Đối tượng vị trí có thể được đăng ký bằng prompt().

Vùng

Một đối tượng đại diện cho một vị trí cần lấp đầy. Có thể đăng ký bằng expect() hoặc prompt().

FilledSlot<T>

Một đối tượng đại diện cho một vùng đã lấp đầy.

Thông số
T	boolean|number|string Loại vị trí.

Lựa chọn

Một đối tượng đại diện cho mục nhập loại vị trí.

Các trường
key	string Giá trị nhận dạng duy nhất cho mục loại vị trí.
synonyms	array<string> Danh sách các từ được dùng để chọn tuỳ chọn vị trí.

Gợi ý

Một đối tượng đại diện cho các gợi ý cho một vị trí.

Các trường
associatedWords	array<string> Danh sách các từ được dùng để giúp hệ thống NLU quyết định ô nào cần điền.

expect

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

expect(expectation) returns HandlerRegistration

Đăng ký kỳ vọng đối với ứng dụng. Có thể được gọi trên trình xử lý ý định và vị trí.

Các tham số
expectation	IntentHandler|Slot Trình xử lý ý định hoặc vị trí cần đăng ký.
HandlerRegistration	object Trình xử lý hoặc vị trí ý định đã đăng ký.

HandlerRegistration

Một đối tượng đại diện cho một trình xử lý ý định đã đăng ký.

Phương thức
deleteHandler()	function Huỷ đăng ký trình xử lý ý định dự kiến.

clearExpectations

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

clearExpectations() returns undefined;

Loại bỏ mọi kỳ vọng bằng cách xoá mọi vị trí và trình xử lý ý định đã đăng ký trước đó.

lời nhắc

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Nhắc người dùng bằng chuỗi TTS được cung cấp và đăng ký kỳ vọng trên ứng dụng. Có thể được gọi trên trình xử lý ý định và vị trí.

Các tham số
tts	string Chuỗi TTS dùng để nhắc người dùng về kỳ vọng được cung cấp.
expectation	IntentHandler|Slot Trình xử lý ý định hoặc vị trí cần đăng ký.
Answer<T>	object Câu trả lời do người dùng cung cấp cho lời nhắc.

Câu trả lời<T>

Một đối tượng biểu thị câu trả lời do người dùng cung cấp cho một câu lệnh.

Các trường
value	boolean|number|string Giá trị của câu trả lời do người dùng cung cấp.
status	string Trạng thái của câu trả lời. Một trong những giá trị sau: ANSWERED: Người dùng đã phản hồi lời nhắc bằng một câu trả lời. NO_MATCH: Người dùng được nhắc nhập câu trả lời nhưng phản hồi bằng một câu trả lời không khớp với câu trả lời dự kiến hoặc bất kỳ ý định dự kiến nào khác. YIELD: Người dùng trả lời lời nhắc với một ý định khác.

triggerScene

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Kích hoạt một cảnh.

Các tham số
sceneName	string Tên cảnh cần kích hoạt.
TriggerSceneStatus	string Trạng thái của lệnh gọi đến kích hoạtScene(). Một trong những giá trị sau: SUCCESS: Yêu cầu đã được máy chủ xử lý thành công. BLOCKED: Yêu cầu đã bị chặn bởi một truy vấn hiện có trong giai đoạn hiển thị. UNKNOWN: Trạng thái của yêu cầu là không xác định.

setUserParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Đặt cặp khoá-giá trị được truyền và duy trì giữa các cuộc trò chuyện.

Các tham số
key	string Khoá thông số.
value	object|array|boolean|number|string Giá trị thông số.

getUserParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Lấy giá trị tham số cho khoá đã cho (nếu khoá đó tồn tại) và trạng thái của lệnh gọi.

Các tham số
key	string Khoá thông số.

resetUserParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

resetUserParam() returns Promise<void>;

Xoá tất cả thông số người dùng.

setHomeParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Đặt cặp khoá-giá trị được truyền và duy trì giữa các cuộc trò chuyện.

Các tham số
key	string Khoá thông số.
value	object|array|boolean|number|string Giá trị thông số.

getHomeParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

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

Lấy giá trị tham số cho khoá đã cho (nếu khoá đó tồn tại) và trạng thái của lệnh gọi.

Các tham số
key	string Khoá thông số.

resetHomeParam

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

resetHomeParam() returns Promise<void>;

Xoá tất cả thông số người dùng.

setCanvasState

setCanvasState(state) returns undefined

Thông báo cho Trợ lý rằng ứng dụng web Canvas đã cập nhật trạng thái. Phương thức setCanvasState không trả về giá trị. Bạn có thể truy cập vào tải trọng trạng thái thông qua thuộc tính conv.context.canvas.state.

Chú ý: Độ dài chuỗi biểu thị của đối tượng state phải nhỏ hơn hoặc bằng 50.000 ký tự. Nếu chuỗi vượt quá 50.000 ký tự, hệ thống sẽ gửi lỗi.

Các tham số
state	Object Trạng thái cập nhật của ứng dụng Canvas dưới dạng đối tượng JSON.

InteractiveCanvasCallbacks

Các lệnh gọi lại này giúp bạn phản hồi thông tin hoặc yêu cầu từ Hành động trò chuyện, còn các phương thức là một cách để gửi thông tin hoặc yêu cầu đến Hành động trò chuyện.

onUpdate

onUpdate(data) returns Promise|undefined

Được gọi khi Hành động trò chuyện gửi phản hồi Canvas. TTS sẽ bắt đầu khi Lời hứa được trả về được giải quyết hoặc hết thời gian chờ sau 10 giây.

Các tham số
data	Object Dữ liệu cập nhật do webhook gửi.

onTtsMark

onTtsMark(markName) returns undefined

Lệnh gọi lại được gọi trong khi phát TTS.

Các dấu đặc biệt luôn được kích hoạt:

• START cho biết điểm bắt đầu của chức năng TTS.
• END cho biết kết thúc TTS.
• ERROR cho biết đã xảy ra lỗi khi phát tính năng TTS.

Bạn cũng có thể xác định nhãn tuỳ chỉnh bằng cách sử dụng SSML và thẻ <mark>, chẳng hạn như <mark name="custom"/>.

Lưu ý: Các nhãn SSML không được gọi khi những trường hợp sau đây xảy ra:

• Trước khi tính năng TTS bắt đầu, người dùng nhấn vào micrô hoặc ứng dụng Canvas tương tác sẽ gọi sendTextQuery. Chức năng TTS sẽ bị huỷ và mọi nhãn SSML trong giao diện TTS sẽ bị bỏ qua.
• Trong quá trình TTS, người dùng nhấn vào micrô hoặc ứng dụng Canvas tương tác sẽ gọi sendTextQuery. Chức năng TTS bị gián đoạn và mọi dấu SSML còn lại trong TTS sẽ bị bỏ qua.

Các tham số
markName	string Đánh dấu tên là đã gọi khi phát lại TTS.

onInputStatusChanged

Thận trọng: API này hiện đang ở Bản dùng thử cho nhà phát triển. Bạn có thể thử nghiệm API này trong trình mô phỏng, nhưng không triển khai Hành động sử dụng tính năng này cho các kênh alpha, beta hoặc sản xuất. Những hành động được triển khai bằng tính năng này sẽ không hoạt động trên thiết bị của người dùng cuối.

onInputStatusChanged(inputStatus) returns undefined

Thông báo cho ứng dụng Canvas rằng trạng thái nhập bằng Trợ lý đã thay đổi.

Các tham số
inputStatus	Enum Trạng thái của quá trình xử lý dữ liệu nhập bằng giọng nói và/hoặc văn bản trên thiết bị. Có thể là: LISTENING : Micrô đang mở. IDLE : Micrô đang đóng. PROCESSING : Trợ lý đang thực thi một truy vấn (micrô đã đóng).