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