تنسيق الردّ التلقائي على الويب في Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

يوضّح هذا القسم تنسيق حمولة JSON عندما تستدعي "المهام مع مساعد Google" عملية التنفيذ من خلال الإصدار 2 من Dialogflow.

إذا كنت تستخدم Dialogflow لإنشاء "إجراءات"، يتم ربط عملية التنفيذ بـ Dialogflow من خلال تنسيق الرد التلقائي على الويب العادي الخاص بها بدلاً من تنسيق الرد التلقائي على الويب لمحادثة "المهام مع مساعد Google". يحتوي تنسيق الرد التلقائي على الويب في Dialogflow على جميع معلومات تنسيق الرد التلقائي على الويب للمحادثة إلى جانب البيانات الإضافية المتعلقة بـ Dialogflow، مثل معلومات السياقات والمعلمات.

للاطّلاع على المزيد من الأمثلة على رسائل JSON للردّ التلقائي على الويب في Dialogflow، يمكنك الرجوع إلى مشروع GitHub هذا.

نص الطلب

تحتوي رسالة الطلب من Dialogflow على بيانات بتنسيق الرد التلقائي على الويب في Dialogflow. يتضمن هذا الكائن معلومات "المهام مع مساعد Google"، كما هو موضح أدناه:

  • قيمة originalDetectIntentRequest.source هي "google".
  • تشير العلامة originalDetectIntentRequest.version إلى إصدار "المهام مع مساعد Google" الخاص بالطلب.
  • يحتوي originalDetectIntentRequest.payload على المعلومات الأساسية الخاصة بـ "المهام مع مساعد Google"، بما في ذلك المحادثة request JSON من "مساعد Google".
  • لا يتوفّر الحقل Conversation.conversationToken مع طلبات الردّ التلقائي على الويب في Dialogflow. بدلاً من ذلك، يمكن لعملية التنفيذ استخدام سياق 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، حيث يكون إدخال المستخدم سلسلة نصية.

{
  "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. يعرض هذا المثال ردّ المستخدم بعد أن يوضّح الردّ التلقائي على الويب لـ "مساعد Google" أنّه بحاجة إلى الحصول على تأكيد من المستخدم.

{
  "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 من نقطة نهاية التنفيذ إلى "مساعد Google" هو application/json.

يجب أن تكون رسالة الرد التي ترسلها عملية التنفيذ إلى Dialogflow بتنسيق الرد التلقائي على الويب في Dialogflow.

عند التواصل مع "مساعد Google"، يتضمّن ردّك عادةً عنصر payload يحتوي على عنصر "google". يتضمن كائن حمولة البيانات "google" معلومات خاصة بـ "المهام مع مساعد Google". ويجب أن تحتوي على الأقل على حقل expectUserResponse وحقل richResponse أو systemIntent.

يتم تلخيص الحقول الرئيسية لكائن حمولة البيانات "google" أدناه:

الحقل الوصف
expectUserResponse يشير هذا الحقل إلى ما إذا كان تنفيذ طلبك يتضمّن ردًا من المستخدم. اضبط القيمة على true وقت مواصلة المحادثة وعلى false لإنهاء المحادثة.
userStorage يخزِّن هذا الإعداد البيانات المستمرة المرتبطة بمستخدم محدَّد. يبلغ إجمالي حجم مساحة التخزين 10,000 بايت.
richResponse يحتوي هذا الحقل على محتوى صوتي أو نص أو بطاقات أو اقتراحات أو بيانات منظَّمة يمكن أن يعرضها "مساعد Google". لمزيد من المعلومات حول استخدام الردود المنسّقة في "المهام مع مساعد Google"، يمكنك مراجعة الردود المنسّقة.
systemIntent هذا الحقل له نفس بنية ExpectedInput.possibleIntents. يحتوي ردّك عادةً على systemIntent إذا كان تنفيذ طلبك يستخدم هدف مساعد. يجب ضبط الحقل possibleIntents في systemIntent على كائن ExpectedIntent، وتغيير اسم الحقل inputValueData إلى data.

ضمن الكائن ExpectedIntent، يمكنك تحديد القيم التالية:

  • النية: اسم الغرض من المساعد يحدِّد نوع المعلومات التي تريد أن يقدّمها المستخدم
  • data: وصف القيمة، وهي سلسلة تصف البيانات المطلوبة للمساعد في تنفيذ المساعد.

على سبيل المثال، إذا كنت تطلب إذن المستخدم، اضبط السمة intent على actions.intent.PERMISSSION والقيمة data على مواصفات القيمة على "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"، بالإضافة إلى الحقول الخاصة بذلك النوع.

تلخّص القائمة التالية سلاسل مواصفات القيم للمساعدين التي يمكنك ضبطها في systemIntent لردّ الرد التلقائي على الويب في Dialogflow. للحصول على قائمة كاملة بأغراض "المهام مع مساعد Google" للتحكُّم في المحادثات، يُرجى الاطّلاع على مرجع الأهداف.

اسم الغرض اسم حدث 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"
            }
          }
        ]
      }
    }
  }
}

مثال على تسهيل الاستخدام

يوضِّح المقتطف أدناه مثالاً لاستخدام هدف المساعد في تنسيق الردّ التلقائي على الويب في Dialogflow. في هذا المثال، يستخدم الرد التلقائي على الويب هدف مساعد actions.intent.OPTIONS لتوجيه "مساعد Google" للحصول على اختيار للمستخدمين من بين خيارَين.

{
  "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"
              }
            ]
          }
        }
      }
    }
  }
}

عند استلام الرسالة من المثال السابق، يتولّى "مساعد Google" المحادثة مؤقتًا ويطلب من المستخدم الاختيار بناءً على الخيارات المحدّدة. عند جمع كل البيانات المطلوبة التي يدخلها المستخدم، يرسل "مساعد Google" هذه النتيجة إلى عملية التنفيذ في طلب الرد التلقائي على الويب في 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. تشير قيمة expectUserResponse العدد false في رسالة الاستجابة إلى "مساعد Google" بأنه لا يُتوقع أن يُدخل المستخدم أي بيانات أخرى وأنّها من المفترض أن تُنهي المحادثة الحالية.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

لمعرفة كيفية إلغاء السلوك التلقائي عندما يستدعي المستخدمون عبارة عادية لإنهاء محادثة مع "مساعد Google"، اطّلِع على دليل الخروج من المحادثة.