בקטע הזה מתואר הפורמט של המטען הייעודי (payload) של JSON כאשר Actions on Google מפעיל את מילוי ההזמנה דרך Actions SDK.
כששיחה מתחילה, היא מזוהה באמצעות conversationId ייחודי. בכל שאילתת משתמש נוספת שתישלח ל-Assistant, מילוי הבקשה שלכם מקבל כוונה שה-webhook שלכם צריך לעבד ולהגיב עליה. הconversationId נשמרת בכל צמד של בקשה ותגובה עד שהשיחה מסתיימת.
גוף הבקשה
כשמשתמשים שולחים שאילתה ראשונית או מספקים משוב נוסף, Assistant שולחת בקשה למילוי הבקשה. בקשות של תגובה לפעולה מאתר אחר (webhook) מה-Assistant כוללות נתונים כמו הכוונה שהופעלה, הטקסט הגולמי של קלט המשתמש והיכולות של המכשיר של המשתמש.
בהמשך מופיע סיכום של השדות העיקריים של בקשה בפורמט של תגובה לפעולה מאתר אחר (webhook):
| שדה | התיאור |
|---|---|
isInSandbox |
המשתנה הבוליאני הזה משמש בעיקר עבור התכונה
Transactions כדי לציין אם ה-webhook צריך לטפל בבקשה הזו במצב ארגז חול. במצב ארגז חול, אסור שתגובה לפעולה מאתר אחר (webhook) תחייב את המשתמשים או תמלא הזמנות רכש.
ערך ברירת המחדל הוא 'true'. |
surface |
מידע על הפלטפורמה של Assistant שאיתה המשתמש מקיים אינטראקציה ועל היכולות שלה. |
Inputs |
מידע על בקשת ההפעלה. בהפעלה של הטריגר, המידע הזה כולל כוונה שממופה לפעולה. בבקשות הבאות בשיחה, יכול להיות שהאובייקט הזה יכלול גם ארגומנטים שמתאימים לקלט הצפוי, כפי שצויין במילוי הבקשה. |
User |
מידע על המשתמש שיזם את הבקשה. המידע הזה כולל את ההרשאות שהוענקו על ידי המשתמש, ואת הלוקאל של המשתמש. |
Conversation |
מידע על ההקשר של השיחה, כולל מזהה השיחה, הסוג שלו (למשל אם הבקשה מובילה שיחה חדשה) ואסימון שיחה לשמירת נתונים קבועים על פני כל משך החיים של השיחה. |
availableSurfaces |
המידע הזה משמש ל שיחות במספר פלטפורמות. |
דוגמה לבקשת הפעלה פשוטה
בקטע הקוד הבא מוצגת דוגמה לבקשת הפעלה בפורמט ה-webhook של השיחה.
{
"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"
}
]
}
]
}
דוגמה לבקשה פשוטה לשיחה
בקטע הקוד הבא מוצגת דוגמה לבקשה לשיחה בפורמט ה-webhook של השיחה, שבה קלט המשתמש הוא מחרוזת טקסט (לדוגמה, "מספר המזל שלי הוא 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"
}
]
}
]
}
גוף התגובה
הערך Content-Type בכותרת של פוסטים ב-HTTP מנקודת הקצה של מילוי הבקשה ל-Assistant חייב להיות application/json.
תגובה בפורמט של תגובה לפעולה מאתר אחר (webhook) של שיחה כוללת נתונים כמו ממשק המשתמש בפועל שמציג למשתמש (כולל רכיבים חזותיים ורכיבים אודיויים), והכוונה שאפשר להפעיל בבקשה הבאה (שנקראת כוונת רכישה צפויה). הכוונה הצפויה יכולה להיות כל אחת מהכוונות שה-Assistant מבין, כפי שמתואר בהפניה ל-API של Intents.
במסמכי התיעוד בנושא תשובות מוסבר איך לעצב את ממשק המשתמש בהתאם לתשובות שלכם כשהן מוצגות ב-Assistant.
דוגמה לתשובה פשוטה
בקטע הקוד הבא מוצגת דוגמה לתשובה פשוטה בפורמט תגובה לפעולה מאתר אחר (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?"
}
}
]
}
}
}
]
}
דוגמה ל-Assistant
בקטע הקוד הבא מוצגת דוגמה לשימוש ב-Intent עוזר בפורמט של תגובה לפעולה מאתר אחר (webhook). בדוגמה הזו, ב-webhook נעשה שימוש ב-Intent העזר actions.intent.OPTIONS כדי להנחות את Assistant לבחור משתמש בין כמה אפשרויות.
למידע נוסף על השימוש בכוונות משתמשים, ראו Helpers.
{
"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"
}
]
}
}
}
]
}
דוגמה לסיום שיחה
בקטע הקוד הבא מוצגת דוגמה לתגובה פשוטה לסיום סשן שיחה בפורמט התגובה לפעולה מאתר אחר (webhook).
הערך expectedUserResponse של false בהודעת התשובה מאותת ל-Assistant שלא צפוי קלט נוסף של משתמש ושצריך לסיים את השיחה הנוכחית. הערך finalResponse מציין מה Assistant צריכה להציג או פלט למשתמש לפני שהשיחה מסתיימת.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
במאמר יציאות משיחה מוסבר איך לשנות את התנהגות ברירת המחדל כשמשתמשים מפעילים ביטוי סטנדרטי כדי לסיים שיחה עם Assistant.