פורמט של תגובה לפעולה מאתר אחר (webhook) בשיחה {:#conversation-webhook-format} (Dialogflow)

בקטע הזה מתואר הפורמט של המטען הייעודי (payload) של JSON כאשר Actions on Google מפעיל את של מילוי הזמנות באמצעות Actions SDK.

כששיחה מתחילה, היא מזוהה באמצעות conversationId ייחודי. עבור כל משתמש עוקב אל Assistant, מילוי הבקשה מקבל הכוונה התגובה לפעולה מאתר אחר (webhook) צריכה לעבד ולהגיב. הconversationId הזה מופיע בכל בקשה עד שהשיחה תסתיים.

גוף הבקשה

כשמשתמשים שולחים שאילתה ראשונית או מספקים מידע נוסף, Assistant שולחת בקשה ואספקה. בקשות ל-webhook של שיחה מ-Assistant שמכילות נתונים כמו הכוונה שהופעלה, הטקסט הגולמי של המשתמש קלט, ויכולות השטח של המכשיר של המשתמש.

בטבלה הבאה מוצג סיכום של שדות המפתח של בקשה בפורמט של תגובה לפעולה מאתר אחר (webhook):

שדה תיאור
isInSandbox משתנה בוליאני זה משמש בעיקר עבור הפונקציה עסקאות, כדי לציין אם התגובה לפעולה מאתר אחר (webhook) צריכה לטפל בבקשה הזו ב-Sandbox. במצב 'סינון תוכן'. במצב ארגז חול, אסור שהתגובה לפעולה מאתר אחר (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 מבינה, כפי שמתואר בהפניה Intents של ה-API.

למידע נוסף על עיצוב ממשק המשתמש עבור התשובות שלכם מופיעים ב-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?"
              }
            }
          ]
        }
      }
    }
  ]
}

דוגמה לעוזר דיגיטלי

בקטע הקוד הבא מוצגת דוגמה לשימוש בכוונת סיוע בשיחה פורמט של תגובה לפעולה מאתר אחר (webhook). בדוגמה הזאת, ה-webhook משתמש Intent של actions.intent.OPTIONS כדי להורות ל-Assistant לקבל בחירה של משתמש בין כמה אפשרויות.

מידע נוסף על השימוש בכוונות עוזרות זמין במאמר המדריך לעוזרים.

{
  "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: יציאות משיחה.