سيتم إيقاف "إجراءات المحادثات" اعتبارًا من 13 حزيران (يونيو) 2023. لمزيد من المعلومات، يُرجى الاطّلاع على إنهاء إجراءات المحادثة.

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

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

بمجرد بدء محادثة، يتم تحديدها بواسطة conversationId فريد. بالنسبة إلى كل طلب بحث لاحق يجريها المستخدم على "مساعد 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"
        }
      ]
    }
  ]
}

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

يُظهر المقتطف أدناه مثالاً لطلب محادثة بتنسيق الرد التلقائي على الويب للمحادثة، حيث يكون إدخال المستخدم سلسلة نصية (على سبيل المثال، "My الحظ number is 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"، كما هو موضّح في مرجع واجهة برمجة التطبيقات Intents.

لمعرفة المزيد حول تنسيق واجهة المستخدم لردودك، عند عرضها في "مساعد 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?"
              }
            }
          ]
        }
      }
    }
  ]
}

مثال مساعِد

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