تنسيق الردّ التلقائي على الويب في 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 المعلومات، بما في ذلك المحادثة طلب ملف 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 يخزن البيانات الدائمة المرتبطة بمستخدم محدد. إجمالي مساحة التخزين يبلغ 10000 بايت.
richResponse يتضمّن هذا الحقل صوتًا أو نصًا أو بطاقات أو اقتراحات أو بيانات منظَّمة. حتى يعرضها "مساعد Google" لمزيد من المعلومات حول استخدام الردود المنسّقة المهام مع مساعد Google، راجع الردود المنسّقة
systemIntent هذا الحقل له نفس هيكل ExpectedInput.possibleIntents يحتوي ردك عادةً على systemIntent إذا كانت طريقة توصيل الطلب تستخدم هدف مساعد. تشير رسالة الأشكال البيانية possibleIntents في الحقل systemIntent يجب ضبطه على ExpectedIntent مع تغيير اسم الحقل inputValueData إلى data.

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

  • intent: اسم intent للمساعد يشير إلى نوع والمعلومات التي تريد أن يقدمها المستخدم،
  • data: مواصفات القيمة، وهي سلسلة تصف البيانات المطلوبة حتى يقوم "مساعد Google" بتنفيذ المساعد.

على سبيل المثال، إذا كنت تطلب إذن المستخدم، اضبط السمة 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!"
            }
          }
        ]
      }
    }
  }
}

لمعرفة كيفية إلغاء السلوك التلقائي عندما يستدعي المستخدمون معيارًا عبارة لإنهاء محادثة مع المساعد، راجع دليل الخروج من المحادثات.