تنسيق الرد التلقائي على الويب للمحادثة {:#conversation-webhook-format} (Dialogflow)

يوضّح هذا القسم تنسيق حمولة JSON عندما تستدعي "المهام مع مساعد Google" عملية التنفيذ من خلال حزمة تطوير البرامج (SDK) للإجراءات.

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

نص الطلب

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

يتم تلخيص الحقول الرئيسية لأي طلب في تنسيق الرد التلقائي على المحادثة في ما يلي:

الحقل الوصف
isInSandbox يُستخدم هذا المتغير المنطقي بشكل أساسي في ميزة المعاملات، للإشارة إلى ما إذا كان يجب الرد التلقائي على الويب بمعالجة هذا الطلب في وضع الحماية. في وضع الحماية، يجب ألا يحصّل الرد التلقائي على الويب أي طلبات شراء يجريها المستخدمون أو ينفّذها. وقد تم ضبطها تلقائيًا على "true".
surface معلومات عن مساحة عرض "مساعد Google" التي يتفاعل معها المستخدم وإمكانياتها.
Inputs معلومات عن طلب الاستدعاء. بالنسبة إلى بدء الاستدعاء، يشمل ذلك نية ترتبط بإجراء ما. بالنسبة إلى الطلبات اللاحقة في المحادثة، قد يتضمّن هذا العنصر أيضًا وسيطات متوافقة مع الإدخالات المتوقّعة التي حدّدتها عملية التنفيذ.
User معلومات عن المستخدم الذي أرسل الطلب. تتضمن هذه المعلومات الأذونات التي يمنحها المستخدم ولغته.
Conversation معلومات عن سياق المحادثة، بما في ذلك رقم تعريف المحادثة والنوع (على سبيل المثال، ما إذا كان هذا الطلب يبدأ محادثة جديدة) والرمز المميز للمحادثة لتخزين البيانات الدائمة طوال فترة المحادثة.
availableSurfaces ويتم استخدام هذه المعلومات في المحادثات على عدة منصات.

مثال بسيط على طلب استدعاء

ويعرِض المقتطف أدناه مثالاً لطلب استدعاء بتنسيق الرد التلقائي على المحادثة.

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

مثال على طلب محادثة بسيط

يوضِّح المقتطف أدناه مثالاً لطلب محادثة بتنسيق الرد التلقائي على المحادثة، حيث يكون ما أدخله المستخدم عبارة عن سلسلة نصية (مثل "رقم حظي هو 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 من نقطة نهاية التنفيذ إلى "مساعد Google" هو application/json.

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

لمزيد من المعلومات حول تنسيق واجهة المستخدم الخاصة بردودك عند عرضها في "مساعد Google"، يُرجى مراجعة مستندات الردود.

مثال على ردّ بسيط

يوضِّح المقتطف أدناه مثالاً لردّ بسيط في تنسيق الردّ التلقائي على الويب في المحادثة.

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

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

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

لمزيد من المعلومات حول استخدام أهداف المساعد، يُرجى الاطّلاع على دليل المساعدة.

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

مثال على إنهاء المحادثة

يوضِّح المقتطف أدناه مثالاً لردّ بسيط لإنهاء جلسة محادثة بتنسيق ردّ الردّ التلقائي على الويب للمحادثة.

تشير القيمة expectedUserResponse التي تبلغ قيمتها false إلى "مساعد Google" في رسالة الردّ إلى أنّه لا يُتوقع من أي مستخدم آخر إدخال أي بيانات وأنّه يجب إنهاء المحادثة الحالية. تشير القيمة finalResponse إلى ما يجب أن يعرضه "مساعد Google" أو يعرضه للمستخدم قبل انتهاء المحادثة.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

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