Phần này mô tả định dạng của tải trọng JSON khi Actions on Google gọi phương thức thực hiện thông qua Action SDK.
Sau khi một cuộc trò chuyện bắt đầu, cuộc trò chuyện đó được xác định bằng một conversationId duy nhất. Đối với mỗi người dùng tiếp theo
truy vấn đến Trợ lý, phương thức thực hiện sẽ nhận được một ý định
webhook của bạn phải xử lý và phản hồi. conversationId này vẫn tồn tại trong mọi yêu cầu và
cho đến khi cuộc trò chuyện kết thúc.
Nội dung yêu cầu
Khi người dùng đưa ra một truy vấn ban đầu hoặc đưa ra thông tin đầu vào tiếp theo, Trợ lý sẽ gửi một yêu cầu cho đơn hàng của bạn. Yêu cầu webhook cuộc trò chuyện từ Trợ lý chứa dữ liệu như ý định đã được kích hoạt, văn bản thô của người dùng đầu vào và khả năng trên nền tảng mà thiết bị của người dùng sử dụng.
Dưới đây là các trường chính cho một yêu cầu theo định dạng webhook cuộc trò chuyện:
| Trường | Mô tả |
|---|---|
isInSandbox |
Biến boolean này chủ yếu được dùng cho
giao dịch, để cho biết liệu webhook của bạn có xử lý yêu cầu này trong hộp cát hay không
. Ở chế độ hộp cát, webhook của bạn không được tính phí hoặc thực hiện bất kỳ đơn đặt hàng nào của người dùng.
Theo mặc định, mục này được đặt thành "true". |
surface |
Thông tin về Trợ lý hiển thị mà người dùng đang tương tác và các khả năng của Trợ lý. |
Inputs |
Thông tin về yêu cầu gọi. Đối với lệnh gọi kích hoạt, tham số này bao gồm ý định liên kết với một hành động. Để trong một cuộc trò chuyện, đối tượng này cũng có thể bao gồm các đối số tương ứng với giá trị đầu vào dự kiến do phương thức thực hiện của bạn chỉ định. |
User |
Thông tin về người dùng đã đưa ra yêu cầu. Thông tin này bao gồm cả các quyền được cấp bởi người dùng và ngôn ngữ của người dùng. |
Conversation |
Thông tin về ngữ cảnh trò chuyện, bao gồm cả mã cuộc trò chuyện, loại (ví dụ: liệu yêu cầu này có đang bắt đầu một cuộc trò chuyện mới hay không) và mã thông báo cuộc trò chuyện để lưu trữ dữ liệu liên tục trong suốt thời gian trò chuyện. |
availableSurfaces |
Thông tin này dùng cho cuộc trò chuyện trên nhiều nền tảng. |
Ví dụ về yêu cầu gọi đơn giản
Đoạn mã dưới đây cho thấy ví dụ về một yêu cầu gọi trong định dạng webhook cuộc trò chuyện.
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.MAIN",
"rawInputs": [
{
"inputType": "VOICE",
"query": "Talk to my test app"
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
Ví dụ về yêu cầu trò chuyện đơn giản
Đoạn mã dưới đây cho thấy ví dụ về một yêu cầu trò chuyện trong định dạng webhook cuộc trò chuyện: trong đó hoạt động đầu vào của người dùng là một chuỗi văn bản (ví dụ: "Số may mắn của tôi là 88"):
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.TEXT",
"rawInputs": [
{
"inputType": "VOICE",
"query": "My lucky number is 88."
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
Nội dung phản hồi
Content-Type trong tiêu đề của các bài đăng HTTP từ điểm cuối thực hiện của bạn
cho Trợ lý phải là application/json.
Phản hồi trong định dạng webhook của cuộc trò chuyện chứa dữ liệu, chẳng hạn như giao diện người dùng thực tế để hiển thị người dùng (bao gồm các thành phần âm thanh và hình ảnh) cũng như ý định có thể được kích hoạt trong yêu cầu tiếp theo (gọi là ý định dự kiến). Dự kiến ý định có thể là bất kỳ ý định nào mà Trợ lý hiểu được, như mô tả trong tài liệu tham khảo API Ý định.
Để tìm hiểu thêm về cách định dạng giao diện người dùng cho câu trả lời của bạn khi chúng hiển thị trong Trợ lý, hãy xem Tài liệu về Phản hồi.
Ví dụ về phản hồi đơn giản
Đoạn mã dưới đây cho thấy ví dụ về một câu trả lời đơn giản trong cuộc trò chuyện webhook.
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TEXT"
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
}
}
]
}
}
}
]
}
Ví dụ về trình trợ giúp
Đoạn mã dưới đây cho thấy ví dụ về cách sử dụng ý định của người trợ giúp trong cuộc trò chuyện
webhook. Trong ví dụ này, webhook sử dụng
actions.intent.OPTIONS ý định của trình trợ giúp để hướng dẫn Trợ lý có được
lựa chọn của người dùng trong số nhiều tuỳ chọn.
Để tìm hiểu thêm về cách sử dụng ý định của trình trợ giúp, hãy xem Hướng dẫn dành cho Trợ giúp.
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.OPTION",
"inputValueData": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"carouselSelect": {
"items": [
{
"optionInfo": {
"key": "one",
"synonyms": [
"synonym of KEY_ONE 1",
"synonym of KEY_ONE 2"
]
},
"description": "Description of number one",
"title": "Number one"
},
{
"optionInfo": {
"key": "two",
"synonyms": [
"synonym of KEY_TWO 1",
"synonym of KEY_TWO 2"
]
},
"description": "Description of number two",
"title": "Number two"
}
]
}
}
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this shows an example of a carousel"
}
}
],
"suggestions": [
{
"title": "1"
},
{
"title": "2"
}
]
}
}
}
]
}
Ví dụ về kết thúc cuộc trò chuyện
Đoạn mã dưới đây cho thấy ví dụ về một câu trả lời đơn giản để kết thúc cuộc trò chuyện theo định dạng phản hồi webhook của cuộc trò chuyện.
expectedUserResponse
giá trị false trong tin nhắn phản hồi báo hiệu cho Trợ lý rằng không có người dùng nào khác
dữ liệu đầu vào dự kiến và sẽ kết thúc cuộc trò chuyện hiện tại. Chiến lược phát hành đĩa đơn
finalResponse
cho biết nội dung mà Trợ lý sẽ hiển thị hoặc đưa ra cho người dùng
cuộc trò chuyện kết thúc.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Để tìm hiểu cách ghi đè hành vi mặc định khi người dùng gọi một để kết thúc cuộc trò chuyện với Trợ lý, hãy xem Thoát khỏi cuộc trò chuyện.