בקטע הזה מתואר הפורמט של המטען הייעודי (payload) של JSON, כאשר שירות Actions on Google מפעיל את מילוי הבקשה דרך Dialogflow v2.
אם אתם משתמשים ב-Dialogflow כדי ליצור פעולות, מילוי הבקשה מתקשר עם Dialogflow באמצעות פורמט webhook סטנדרטי משלו במקום פורמט webhook של שיחה ב-Actions on Google. הפורמט של webhook ל-Dialogflow כולל את כל הפרטים על הפורמט של תגובה לפעולה מאתר אחר (webhook), לצד נתונים נוספים שספציפיים ל-Dialogflow, כמו מידע על הקשרים ופרמטרים.
בפרויקט ב-GitHub תוכלו לראות דוגמאות נוספות להודעות JSON בקשר ל-webhooks ב-Dialogflow.
גוף הבקשה
הודעת הבקשה מ-Dialogflow מכילה נתונים בפורמט Dialogflow webhook. האובייקט הזה כולל פעולות על פרטים ספציפיים ל-Google, כפי שמתואר בהמשך:
- הערך של
originalDetectIntentRequest.source
הוא 'google'. - השדה
originalDetectIntentRequest.version
מציין את הגרסה של Actions on Google לבקשה. originalDetectIntentRequest.payload
מכיל מידע חשוב על פעולות ספציפיות ב-Google, כולל בקשת השיחה מ-Assistant.- השדה
Conversation.conversationToken
לא נתמך בבקשות Dialogflow של webhook. במקום זאת, מילוי הבקשה יכול להשתמש בהקשר של 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 webhook, שבו קלט המשתמש הוא מחרוזת טקסט.
{
"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 webhook. בדוגמה הזו מוצגת התגובה של המשתמש לאחר שהתגובה לפעולה מאתר אחר (webhook) מציינת ל-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 מנקודת הקצה של מילוי הבקשה ל-Assistant חייב להיות application/json
.
הודעת התשובה ששולחים ל-Dialogflow צריכה להיות בפורמט Dialogflow webhook.
כשמתקשרים עם Assistant, התשובה שלך בדרך כלל מכילה אובייקט payload
שכולל אובייקט "google
". אובייקט המטען הייעודי (payload) 'google
' כולל
פעולות במידע ספציפי ל-Google. הוא צריך להכיל לפחות שדה expectUserResponse
ושדה richResponse
או systemIntent
.
סיכום השדות העיקריים של אובייקט המטען הייעודי (payload) "google
" מופיע בהמשך:
שדה | התיאור |
---|---|
expectUserResponse |
שדה זה מציין אם מילוי ההזמנה שלך מצפה לתגובת משתמש. מגדירים את הערך כ-true מתי להמשיך את השיחה ו-false כדי לסיים את השיחה. |
userStorage |
שמירת נתונים קבועים שקשורים למשתמש מסוים. נפח האחסון הכולל הוא 10,000 בייטים. |
richResponse |
השדה הזה מכיל אודיו, טקסט, כרטיסים, הצעות או נתונים מובְנים שדרושים ל-Assistant לעיבוד. מידע נוסף על השימוש בתגובות עשירות ל-Actions on Google מופיע במאמר תגובות מתקדמות |
systemIntent |
המבנה של השדה הזה זהה לזה של השדה ExpectedInput.possibleIntents . התשובה שלך כוללת בדרך כלל
systemIntent אם מילוי הבקשה שלך כולל כוונת עזרה. יש להגדיר את השדה possibleIntents ב-systemIntent כאובייקט ExpectedIntent , ולשנות את שם השדה inputValueData ל-data .
|
באובייקט ExpectedIntent
, מציינים את הערכים הבאים:
- כוונה: שם Intent שמציין את סוג המידע שאתם רוצים שהמשתמש יספק.
- data: מפרט ערכים, שהוא מחרוזת שמתארת את הנתונים שנדרשים כדי ש-Assistant תבצע את המסייע.
לדוגמה, אם מבקשים את הרשאת המשתמש, מגדירים את intent
כ-actions.intent.PERMISSSION
ואת data
כמפרט הערכים כ-"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
, יחד עם השדות של
הסוג הזה.
הרשימה הבאה מסכמת את המחרוזות של מפרט הערכים שעוזרות שאפשר להגדיר ב-systemIntent
לתגובה webhook מסוג Dialogflow. לרשימה מלאה של אובייקטים מסוג Intent ב-Actions on Google לבקרת שיחות, תוכלו לעיין בחומר העזר בנושא Intents.
שם 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"
|
בקשת העברה של קישור עומק לאפליקציה ל-Android. |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
מקבל את הפריט שנבחר מממשק משתמש של רשימה או קרוסלה. |
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"
}
}
]
}
}
}
}
דוגמה ל-Assistant
בקטע הקוד הבא מוצגת דוגמה לשימוש ב-Intent עוזר בפורמט Dialogflow. בדוגמה הזו, ב-webhook נעשה שימוש ב-Intent העזר actions.intent.OPTIONS
כדי להנחות את Assistant לבחור משתמש בין שתי אפשרויות.
{
"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 שולחת את תוצאת המסייע הזו בחזרה למילוי בקשת Dialogflow webhook.
קטע הקוד הבא מציג דוגמה לתוצאת המסייע עם בחירת המשתמש.
{
"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 webhook. הערך expectUserResponse
של false
בהודעת התגובה מסמן ל-Assistant שלא צפוי קלט נוסף של משתמשים, ושצריך לסיים את השיחה הנוכחית.
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
במדריך ליציאה משיחה מוסבר איך לשנות את התנהגות ברירת המחדל כשמשתמשים מפעילים ביטוי סטנדרטי כדי לסיים שיחה עם Assistant.