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

Interactive Canvas API 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 bạn 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 rằng bạ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 Canvas tương tác .

Phương thức

Cảnh báo: Một số API Canvas tương tác hiện có trong 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 giai đoạn alpha, beta hoặc phát hành chính thức các kênh. Những thao tác được triển khai bằng các tính năng này sẽ không hoạt động đối với người dùng cuối thiết bị di động.

sẵn sàng

ready(callbacks) returns undefined

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

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 trang đã tải xong. Nếu không, Hành động sẽ đóng lại.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Gửi một truy vấn bằng văn bản đến hành động trò chuyện.

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

Thận trọng: 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.

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.

Tham số
text	string Chuỗi hỗ trợ SSML sẽ được phát.
openMic	boolean Xem có mở micrô sau khi 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 một trình xử lý ý định cho đối tượng có ý định tuỳ chỉnh NLU.

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 đượ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

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

MatchedIntent

Đối tượng chứa dữ liệu cho ý định được so khớp.

Phương thức
getIntentArg(parameterName)	function(string) Phương thức lấy tham số ý định của ý định được 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 ô thuộc loại số.

Tham số
callback	function(FilledSlot) Hàm đượ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 khung giờ. 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 ô thuộc loại chuỗi.

Tham số
callback	function(FilledSlot) Hàm đượ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 khung giờ. 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 khung giờ thuộc loại boolean.

Tham số
callback	function(FilledSlot) Hàm đượ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 khung giờ. 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 ô từ danh sách tuỳ chọn được xác định trước.

Tham số
options	array<Option> Hàm được thực thi khi vị trí được lấp đầy.
callback	function(FilledSlot) Hàm đượ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 khung giờ. 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().

Khe

Đố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>

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

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

Phương thức

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

Trường
key	string Giá trị nhận dạng duy nhất của mục nhập loại vùng.
synonyms	array<string> Danh sách các từ được dùng để chọn lựa chọn vị trí.

Gợi ý

Một đối tượng đại diện cho gợi ý cho một ô.

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

dự kiến

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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 trên ứng dụng. Có thể được gọi trên các khe và trình xử lý ý định.

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

HandlerRegistration

Đố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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 khe và trình xử lý ý định đã đăng ký trước đó.

câu lệnh

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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 khách. Có thể được gọi trên các khe và trình xử lý ý định.

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>

Đối tượng đại diện cho một câu trả lời do người dùng cung cấp cho một câu lệnh.

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 số sau: ANSWERED: Người dùng đã trả lời lời nhắc. NO_MATCH: Người dùng được nhắc trả lời bằng 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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.

Tham số
sceneName	string Tên của cảnh cần kích hoạt.
TriggerSceneStatus	string Trạng thái của lệnh gọi đến triggerScene(). Một trong số 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 chuyến bay. UNKNOWN: Yêu cầu này có trạng thái 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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ị đã truyền và duy trì giữa các cuộc trò chuyện.

Tham số
key	string Khoá tham 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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.

Tham số
key	string Khoá tham 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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ị đã truyền và duy trì giữa các cuộc trò chuyện.

Tham số
key	string Khoá tham 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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.

Tham số
key	string Khoá tham 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 Canvas trên web đã cập nhật trạng thái. Chiến lược phát hành đĩa đơn setCanvasState không trả về giá trị. Tải trọng trạng thái có thể được truy cập thông qua Thuộc tính conv.context.canvas.state.

Thận trọng: Độ dài của chuỗi biểu diễn đối tượng state phải là có độ dài tối đa là 50.000 ký tự. Nếu chuỗi vượt quá 50.000 ký tự thì sẽ có lỗi xảy ra.

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 cung cấp cho bạn cách thức phản hồi thông tin hoặc yêu cầu từ Hành động trò chuyện trong khi các phương thức cung cấp cách gửi thông tin hoặc yêu cầu nào đối với Hành động trò chuyện.

onUpdate

onUpdate(data) returns Promise|undefined

Được gọi khi phản hồi Canvas được gửi từ Hành động trò chuyện. 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.

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 phần đầu của TTS.
• END cho biết phần cuối của TTS.
• ERROR cho biết đã xảy ra lỗi khi phát 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>, 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 TTS bắt đầu, người dùng nhấn vào micrô hoặc tương tác Canvas ứng dụng khách sẽ gọi sendTextQuery. TTS bị huỷ và mọi dấu SSML trong TTS bị bỏ qua.
• Trong TTS, người dùng nhấn vào micrô hoặc ứng dụng Canvas tương tác sẽ gọi sendTextQuery. TTS bị gián đoạn và mọi SSML còn lại trong TTS bị bỏ qua.

Tham số
markName	string Tên đánh dấu được gọi trong khi phát 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 kênh alpha, beta hoặc sản xuất. Các hành động được triển khai bằng cách dù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 dữ liệu của Trợ lý đã thay đổi.

Tham số
inputStatus	Enum Trạng thái xử lý nhập liệu thoại và/hoặc văn bản trên thiết bị. Lon như sau: LISTENING : Micrô đang bật. IDLE : Micrô đã tắt. PROCESSING : Trợ lý hiện đang thực hiện một truy vấn (micrô bị đóng).