تنسيق الرد التلقائي على الويب للمحادثة {:#conversation-webhook-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"
        }
      ]
    }
  ]
}

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

يعرض المقتطف أدناه مثالاً لطلب محادثة في تنسيق الرد التلقائي على الويب للمحادثة، حيث يكون البيانات التي أدخلها المستخدم عبارة عن سلسلة نصية (على سبيل المثال، "رقم حظي هو 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"
          }
        }
      ]
    }
  }
}

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