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

בקטע הזה מתואר הפורמט של המטען הייעודי (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.