ส่วนนี้อธิบายรูปแบบของเพย์โหลด JSON เมื่อ Actions on Google เรียกใช้ Fulfillment ของคุณผ่าน Dialogflow v2
หากคุณใช้ Dialogflow เพื่อสร้างการดำเนินการ การดำเนินการ Fulfillment จะสื่อสารกับ Dialogflow ผ่านรูปแบบเว็บฮุคมาตรฐานของตนเองแทนรูปแบบเว็บฮุคการสนทนาของ Actions on Google รูปแบบเว็บฮุคของ Dialogflow มีข้อมูลทั้งหมดของรูปแบบเว็บฮุคสำหรับการสนทนา พร้อมด้วยข้อมูลเพิ่มเติมสำหรับ Dialogflow โดยเฉพาะ เช่น ข้อมูลเกี่ยวกับบริบทและพารามิเตอร์
หากต้องการดูตัวอย่างข้อความ JSON เพิ่มเติมสำหรับเว็บฮุคของ Dialogflow โปรดดูโปรเจ็กต์ GitHub นี้
เนื้อหาของคำขอ
ข้อความคำขอจาก Dialogflow มีข้อมูลในรูปแบบเว็บฮุคของ Dialogflow ออบเจ็กต์นี้มีข้อมูลเฉพาะของ Actions on Google ตามที่สรุปไว้ด้านล่าง
- ค่า
originalDetectIntentRequest.source
คือ "google" originalDetectIntentRequest.version
จะระบุเวอร์ชัน Actions on Google สำหรับคำขอoriginalDetectIntentRequest.payload
มีข้อมูลเฉพาะของ Actions on Google ซึ่งรวมถึง JSON การสนทนาคำขอจาก Assistant- คำขอเว็บฮุคของ Dialogflow ไม่รองรับช่อง
Conversation.conversationToken
แต่ Fulfillment ของคุณสามารถใช้บริบทของ Dialogflow เพื่อคงข้อมูลไว้ตลอดอายุการสนทนา
ตัวอย่างคำขอการเรียกใช้อย่างง่าย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำขอเรียกใช้ในรูปแบบเว็บฮุคของ Dialogflow
{
"responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
"queryResult": {
"queryText": "GOOGLE_ASSISTANT_WELCOME",
"action": "input.welcome",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
"displayName": "Default Welcome Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "Talk to my test app",
"inputType": "VOICE"
}
],
"intent": "actions.intent.MAIN"
}
],
"user": {
"lastSeen": "2018-03-16T22:08:48Z",
"permissions": [
"UPDATE"
],
"locale": "en-US",
"userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
},
"conversation": {
"conversationId": "${SESSIONID}",
"type": "NEW"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
ตัวอย่างคำขอการสนทนาอย่างง่าย
ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างคำขอแบบสนทนาในรูปแบบเว็บฮุคของ Dialogflow ที่ผู้ใช้ป้อนเข้ามาเป็นสตริงข้อความ
{
"responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
"queryResult": {
"queryText": "query from the user",
"action": "action.name.of.matched.dialogflow.intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
"displayName": "Name of Dialogflow Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "query from the user",
"inputType": "KEYBOARD"
}
],
"arguments": [
{
"rawText": "query from the user",
"textValue": "query from the user",
"name": "text"
}
],
"intent": "actions.intent.TEXT"
}
],
"user": {
"lastSeen": "2017-10-06T01:06:56Z",
"locale": "en-US",
"userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
},
"conversation": {
"conversationId": "1522951193000",
"type": "ACTIVE",
"conversationToken": "[]"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
ตัวอย่างผลลัพธ์ที่เป็นตัวช่วย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างผลลัพธ์ที่เป็นตัวช่วยในรูปแบบเว็บฮุค Dialogflow ตัวอย่างนี้แสดงการตอบสนองของผู้ใช้หลังจากที่เว็บฮุคบอกกับ Assistant ว่าต้องได้รับการยืนยันจากผู้ใช้
{
"responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
"queryResult": {
"queryText": "actions_intent_CONFIRMATION",
"action": "Dialogflow action name of matched intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
"parameters": {
"CONFIRMATION": true
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow action name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {},
"inputs": [
{
"rawInputs": [
{
"query": "yes",
"inputType": "VOICE"
}
],
"arguments": [
{
"name": "CONFIRMATION",
"boolValue": true
}
],
"intent": "actions.intent.CONFIRMATION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
เนื้อหาการตอบกลับ
Content-Type
ในส่วนหัวของโพสต์ HTTP จากปลายทาง Fulfillment ไปยัง Assistant ต้องเป็น application/json
ข้อความตอบกลับที่ Fulfillment ของคุณส่งไปยัง Dialogflow ต้องอยู่ในรูปแบบเว็บฮุคของ Dialogflow
เมื่อสื่อสารกับ Assistant โดยปกติการตอบกลับของคุณจะมีออบเจ็กต์ payload
ที่รวมออบเจ็กต์ "google
" เอาไว้ ออบเจ็กต์เพย์โหลด "google
" มีข้อมูลเฉพาะของ Actions on Google อยู่ด้วย อย่างน้อยที่สุดจะต้องมีช่อง expectUserResponse
และช่อง richResponse
หรือ systemIntent
ช่องคีย์สำหรับออบเจ็กต์เพย์โหลด "google
" สรุปได้ดังนี้
ฟิลด์ | คำอธิบาย |
---|---|
expectUserResponse |
ระบุว่าการดำเนินการคาดหวังว่าจะได้รับการตอบสนองจากผู้ใช้หรือไม่ ตั้งค่าเป็น true เวลาที่ต้องการให้การสนทนาดำเนินต่อไป และ false เพื่อสิ้นสุดการสนทนา |
userStorage |
จัดเก็บข้อมูลถาวรที่เชื่อมโยงกับผู้ใช้ที่เฉพาะเจาะจง พื้นที่เก็บข้อมูลรวมทั้งหมดคือ 10,000 ไบต์ |
richResponse |
ช่องนี้มีเสียง ข้อความ การ์ด คำแนะนำ หรือข้อมูลที่มีโครงสร้างให้ Assistant แสดงผล ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้การตอบกลับริชมีเดียสำหรับ Actions on Google ได้ที่การตอบกลับแบบริชมีเดีย |
systemIntent |
ช่องนี้มีโครงสร้างเดียวกันกับ ExpectedInput.possibleIntents โดยปกติแล้ว การตอบกลับจะมี systemIntent หาก Fulfillment ของคุณใช้ความตั้งใจของผู้ช่วยเหลือ ต้องตั้งค่าช่อง possibleIntents ใน systemIntent เป็นออบเจ็กต์ ExpectedIntent พร้อมเปลี่ยนชื่อช่อง inputValueData เป็น data
|
ภายในออบเจ็กต์ ExpectedIntent
คุณระบุค่าต่อไปนี้
- intent: ชื่อ Intent สำหรับ Helper ที่ระบุประเภทข้อมูล ที่คุณต้องการให้ผู้ใช้ระบุ และ
- data: ข้อมูลจำเพาะของค่า ซึ่งเป็นสตริงที่อธิบายข้อมูลที่ Assistant ต้องใช้เพื่อนำมาใช้กับผู้ช่วย
ตัวอย่างเช่น หากคุณกำลังขอสิทธิ์ของผู้ใช้ ให้ตั้งค่า intent
เป็น actions.intent.PERMISSSION
และ data
เป็นข้อมูลจำเพาะของค่าเป็น "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
พร้อมด้วยช่องสำหรับประเภทนั้น
รายการต่อไปนี้สรุปสตริงข้อมูลจำเพาะของค่าสำหรับผู้ช่วยที่คุณกำหนดใน systemIntent
สำหรับการตอบกลับเว็บฮุคของ Dialogflow ดูรายการ Intent ของ Actions on Google ทั้งหมดสำหรับการควบคุมการสนทนาได้ที่ข้อมูลอ้างอิง Intent
ชื่อ Intent | ชื่อเหตุการณ์ Dialogflow | ข้อกำหนดของค่า | คำอธิบาย |
---|---|---|---|
actions.intent.CONFIRMATION
|
actions_intent_CONFIRMATION |
"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"
|
ได้รับการยืนยันจากผู้ใช้ (เช่น คำตอบสำหรับคำถาม "ใช่" หรือ "ไม่ใช่") |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
รับข้อมูลวันที่และเวลาจากผู้ใช้ |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
รับข้อมูลที่อยู่สำหรับจัดส่งจากผู้ใช้ |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
ขอขั้นตอน Deep Link ในแอป Android |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
รับรายการที่เลือกจากรายการหรือ UI ภาพหมุน |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
รับข้อมูลของผู้ใช้ รวมถึงชื่อเต็ม ตำแหน่งคร่าวๆ หรือตำแหน่งที่แน่นอน |
actions.intent.SIGN_IN
|
actions_intent_SIGN_IN |
"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"
|
ส่งคําขอลิงก์บัญชีเพื่อลิงก์บัญชีของผู้ใช้ |
ตัวอย่างคำตอบอย่างง่าย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำตอบง่ายๆ ในรูปแบบเว็บฮุคของ Dialogflow
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
ตัวอย่างตัวช่วย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างการใช้ Intent ของตัวช่วยในรูปแบบเว็บฮุคของ Dialogflow ในตัวอย่างนี้ เว็บฮุคของคุณใช้ Intent ของตัวช่วย actions.intent.OPTIONS
เพื่อสั่งให้ Assistant รับการเลือกผู้ใช้ระหว่าง 2 ตัวเลือก
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Choose a item"
}
}
]
},
"systemIntent": {
"intent": "actions.intent.OPTION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"listSelect": {
"title": "Hello",
"items": [
{
"optionInfo": {
"key": "first title key"
},
"description": "first description",
"image": {
"url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
"accessibilityText": "first alt"
},
"title": "first title"
},
{
"optionInfo": {
"key": "second"
},
"description": "second description",
"image": {
"url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
"accessibilityText": "second alt"
},
"title": "second title"
}
]
}
}
}
}
}
}
เมื่อได้รับข้อความจากตัวอย่างก่อนหน้านี้ Assistant จะดำเนินการสนทนาชั่วคราวและแจ้งให้ผู้ใช้เลือกตามตัวเลือกที่ระบุ เมื่อรวบรวมข้อมูลทั้งหมดที่จำเป็นสำหรับผู้ใช้ Assistant จะส่งผลลัพธ์ของผู้ช่วยนี้กลับไปยัง Fulfillment ของคุณในคำขอเว็บฮุคของ Dialogflow
ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างผลลัพธ์ตัวช่วยที่มีตัวเลือกของผู้ใช้ให้เลือก
{
"responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
"queryResult": {
"queryText": "actions_intent_OPTION",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
"parameters": {
"OPTION": "key of selected item"
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow intent name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": []
},
"inputs": [
{
"rawInputs": [
{
"query": "Title of selected item",
"inputType": "TOUCH"
}
],
"arguments": [
{
"textValue": "Key of selected item",
"name": "OPTION"
}
],
"intent": "actions.intent.OPTION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
ตัวอย่างสิ้นสุดการสนทนา
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำตอบง่ายๆ เพื่อสิ้นสุดเซสชันการสนทนาในรูปแบบเว็บฮุค Dialogflow ค่า false
expectUserResponse
ในข้อความตอบกลับจะส่งสัญญาณให้ Assistant ทราบว่าผู้ใช้ไม่ควรป้อนข้อมูลเพิ่มเติมและควรสิ้นสุดการสนทนาปัจจุบัน
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
หากต้องการดูวิธีลบล้างการทำงานเริ่มต้นเมื่อผู้ใช้เรียกใช้วลีมาตรฐานเพื่อจบการสนทนากับ Assistant ให้ดูคู่มือการออกจากการสนทนา