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

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

דוגמה לתוצאה של כלי עזר

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

בתוך 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.

דוגמה לתשובה פשוטה

בקטע הקוד הבא מוצגת דוגמה לתשובה פשוטה ב-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, תוכלו לראות מדריך ליציאה משיחה.