قالب مکالمه وب هوک {:#conversation-webhook-format} (Dialogflow)

این بخش، قالب بارگیری JSON را هنگامی که Actions on Google از طریق Actions SDK اجرای شما را فراخوانی می‌کند، توضیح می‌دهد.

هنگامی که مکالمه شروع می شود، توسط یک conversationId منحصر به فرد شناسایی می شود. برای هر درخواست کاربر بعدی به دستیار، انجام شما هدفی را دریافت می کند که وب هوک شما باید آن را پردازش کرده و به آن پاسخ دهد. این conversationId در هر جفت درخواست و پاسخ تا پایان مکالمه باقی می ماند.

درخواست بدن

هنگامی که کاربران یک پرس و جو اولیه انجام می دهند یا ورودی های بعدی را ارائه می دهند، دستیار درخواستی را برای انجام شما ارسال می کند. درخواست‌های وب هوک مکالمه از دستیار حاوی داده‌هایی مانند هدفی که راه‌اندازی شده، متن خام ورودی کاربر و قابلیت‌های سطحی دستگاه کاربر است.

فیلدهای کلیدی برای درخواست در قالب webhook گفتگو در زیر خلاصه شده است:

میدان توضیحات
isInSandbox این متغیر بولی عمدتاً برای ویژگی تراکنش‌ها استفاده می‌شود، تا نشان دهد آیا وب‌هوک شما باید این درخواست را در حالت جعبه ایمنی انجام دهد یا خیر. در حالت sandbox، وب هوک شما نباید هیچ گونه سفارش خریدی توسط کاربران را شارژ یا انجام دهد. به طور پیش‌فرض روی " true " تنظیم شده است.
surface اطلاعاتی درباره سطح Assistant که کاربر با آن در تعامل است و قابلیت‌های آن.
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 از نقطه پایانی شما تا دستیار باید application/json باشد.

یک پاسخ در قالب webhook مکالمه حاوی داده‌هایی مانند رابط کاربری واقعی برای نشان دادن کاربر (شامل اجزای صوتی و بصری) و هدفی است که می‌تواند در درخواست بعدی فعال شود (به نام یک هدف مورد انتظار ). هدف مورد انتظار می‌تواند هر یک از مقاصدی باشد که دستیار می‌فهمد، همانطور که در مرجع Intents API توضیح داده شده است.

برای کسب اطلاعات بیشتر در مورد قالب‌بندی رابط کاربری برای پاسخ‌های خود هنگامی که در دستیار نمایش داده می‌شوند، به مستندات پاسخ‌ها مراجعه کنید.

نمونه پاسخ ساده

قطعه زیر نمونه ای از پاسخ ساده در قالب مکالمه وب هوک را نشان می دهد. 

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

مثال کمکی

قطعه زیر نمونه ای از استفاده از یک هدف کمکی در قالب گفتگوی وب هوک را نشان می دهد. در این مثال، webhook از قصد کمکی actions.intent.OPTIONS استفاده می‌کند تا به دستیار دستور دهد تا انتخاب کاربر را از بین چندین گزینه به دست آورد.

برای کسب اطلاعات بیشتر در مورد استفاده از اهداف کمکی، به راهنمای Helpers مراجعه کنید. 

{
  "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 در پیام پاسخ به دستیار نشان می دهد که هیچ ورودی دیگری از کاربر انتظار نمی رود و باید مکالمه فعلی را پایان دهد. مقدار finalResponse نشان می‌دهد که دستیار باید قبل از پایان مکالمه چه چیزی را به کاربر نمایش یا خروجی بدهد. 

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

برای یادگیری نحوه نادیده گرفتن رفتار پیش‌فرض هنگامی که کاربران یک عبارت استاندارد را برای پایان دادن به مکالمه با دستیار فراخوانی می‌کنند، به خروجی‌های مکالمه مراجعه کنید.