درخواست می کند

درخواست‌ها مشخص می‌کنند که Action شما چگونه پاسخ‌ها را به کاربران ارائه می‌کند و چگونه Action شما از آنها می‌خواهد ادامه دهند. همانطور که Action خود را می‌سازید، می‌توانید دستورات را به فراخوان‌ها و مکان‌های مختلف در صحنه‌ها اضافه کنید. درخواست‌ها می‌توانند به سادگی پاسخ متن یا گفتار باشند، یا می‌توانند پیچیده‌تر و حاوی محتوای غنی مانند کارت‌ها، تصاویر و جداول باشند.

انواع پاسخ

برای هر درخواست، از انواع مختلفی از انواع پاسخ های جذاب برای دستیار برای ارائه به کاربران انتخاب می کنید:

• پاسخ‌های ساده : پاسخ‌های ساده از نظر بصری به شکل حباب چت هستند و از متن به گفتار (TTS) یا زبان نشانه‌گذاری سنتز گفتار (SSML) برای صدا استفاده می‌کنند. پاسخ های ساده تنها پاسخ هایی هستند که در انواع دستگاه ها پشتیبانی می شوند.
• پاسخ‌های غنی : پاسخ‌های غنی حاوی عناصر بصری یا کاربردی هستند که تعامل کاربر با اقدامات شما را افزایش می‌دهند. با پاسخ‌های غنی، می‌توانید داده‌های جدولی را نیز نمایش دهید یا محتوای صوتی طولانی‌تر را پخش کنید.
• پاسخ‌های انتخاب بصری : پاسخ‌های انتخاب بصری یک رابط بصری برای کاربران فراهم می‌کند تا از بین گزینه‌های متعددی که به راحتی بر اساس عنوان یا تصویر متمایز می‌شوند، انتخاب کنند.
• پاسخ‌های رسانه‌ای : پاسخ‌های رسانه‌ای به Actions شما اجازه می‌دهند تا محتوای صوتی طولانی‌تری نسبت به SSML پخش کنند و یک جزء بصری با کنترل‌های رسانه ارائه کنند.
• بوم تعاملی : بوم تعاملی پاسخ ها را به صورت نمایش های وب تمام صفحه نمایش می دهد و به عنوان یک برنامه وب تعاملی عمل می کند که Assistant به عنوان پاسخی برای کاربر در مکالمه ارسال می کند. Canvas از یک فرمت سریع کمی متفاوت استفاده می‌کند تا انعطاف‌پذیری بیشتری نسبت به استانداردهای وب مانند HTML، CSS و جاوا اسکریپت داشته باشد.

هر یک از این نوع پاسخ ها از همان قالب اعلان پایه استفاده می کنند و به همان ویژگی های کلی که در زیر توضیح داده شده است دسترسی دارند.

فرمت یک اعلان

در پروژه Actions خود، دستورات را در قالب YAML یا JSON تعریف می کنید. هر اعلان می تواند حاوی حداکثر دو پاسخ ساده باشد و به صورت اختیاری یک پاسخ غنی را تعریف کند. پاسخ ها به روش های زیر تعریف می شوند:

• first_simple : پاسخ متن یا گفتار اولیه (ساده) برای ارسال به کاربر.
• content : محتوای پاسخ غنی تکمیلی برای ارسال پس از پاسخ های ساده.
• last_simple پاسخ متن یا گفتار نهایی (ساده) برای ارسال به کاربر.
• canvas : به یک برنامه وب اشاره می کند که با بوم تعاملی ادغام می شود.

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

علاوه بر این، با استفاده از ویژگی‌های زیر، انعطاف‌پذیری را برای درخواست ارائه می‌دهید:

• کاندیداها : نامزدها به شما امکان می دهند پاسخ ها را بر اساس قابلیت های دستگاه کاربر تعریف کنید. به عنوان مثال، تنها زمانی می‌توانید پاسخ‌های غنی از نمایشگر Assistant داشته باشید که کاربر با Action شما در دستگاهی با قابلیت نمایش تعامل داشته باشد.
• انواع : انواع، تغییرات جایگزین یک پیام واحد هستند. به عنوان مثال، می‌توانید هر بار که کاربر اقدام شما را فراخوانی می‌کند، از دستیار بخواهید بین پنج نوع پیام خوش‌آمدگویی مختلف انتخاب کند.
• پیشنهادات : وقتی دستیار اعلان را نمایش می‌دهد، پیشنهادها تراشه‌های پیشنهادی را در دستگاه‌های دارای نمایشگر به کاربران ارائه می‌دهند.

یک اعلان پیش فرض از یک کاندید، یک نوع و یک پاسخ first_simple استفاده می کند.

توجه: به عنوان بهترین روش، از content برای پشتیبانی از پاسخ first_simple استفاده کنید. به عنوان مثال، اگر first_simple گزینه هایی برای سفارش نوشیدنی ارائه می دهد، می توانید از content برای ارائه تصاویری برای گزینه های نوشیدنی استفاده کنید. این رویکرد تضمین می کند که کاربران بدون توجه به دستگاهی که استفاده می کنند، اطلاعات مهم را دریافت می کنند. از طرف دیگر، از نامزدها برای ارائه پاسخ‌های مختلف بر اساس دستگاه استفاده کنید.

نامزدها

در یک اعلان، شی candidates به شما امکان می دهد پاسخ ها را بر اساس قابلیت های دستگاه کاربر تعریف کنید. به عنوان مثال، تنها زمانی می‌توانید پاسخ‌های غنی از نمایشگر Assistant داشته باشید که کاربر با Action شما در دستگاهی با قابلیت نمایش تعامل داشته باشد. برای تعریف انواع دستگاه‌هایی که Assistant می‌تواند یک نامزد را برگرداند، از ویژگی selector شی candidates استفاده کنید.

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

YAML

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    first_simple:
      variants:
        - speech: Here's a simple message.
    content:
      card:
        title: Image card title
        text: Some details about the image
        image:
          url: 'https://www.example.com/image/'
  - first_simple:
      variants:
        - speech: Text explains what the image might have shown in more detail.
    

JSON

{
  "candidates": [{
    "selector": {
      "surface_capabilities": {
        "capabilities": ["RICH_RESPONSE"]
      }
    },
    "first_simple": {
      "variants": [{
        "speech": "Here's a simple message."
      }]
    },
    "content": {
      "card": {
        "title": "Image card title",
        "text": "Some details about the image",
        "image": {
          "url": "https://www.example.com/image/"
        }
      }
    }
  }, {
    "first_simple": {
      "variants": [{
        "speech": "Text explains what the image might have shown in more detail."
      }]
    }
  }]
}
    

شما می توانید یک یا چند مورد نیاز توانایی را برای یک نامزد مشخص ارائه کنید. لیست زیر هر یک از الزامات قابلیت موجود را شرح می دهد:

• SPEECH : دستگاه می تواند از طریق تبدیل متن به گفتار یا SSML با کاربر صحبت کند.
• RICH_RESPONSE : دستگاه می‌تواند پاسخ‌های غنی مانند کارت‌ها، فهرست‌ها و جداول را نمایش دهد.
• LONG_FORM_AUDIO : دستگاه می‌تواند رسانه‌های صوتی طولانی مانند موسیقی و پادکست را پخش کند.
• INTERACTIVE_CANVAS : دستگاه می تواند یک پاسخ بوم تعاملی را نمایش دهد.
• WEB_LINK : دستگاه می‌تواند از پیوندهای وب در پاسخ‌های غنی برای باز کردن مرورگر وب استفاده کند.
• HOME_STORAGE : دستگاه می‌تواند داده‌ها را در فضای ذخیره‌سازی خانه ذخیره کرده و به آنها دسترسی داشته باشد.

انواع

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

برای مثال، انواع مختلف پیام خوشامدگویی را ارائه دهید تا کاربران هر بار که Action شما را فراخوانی می‌کنند، پاسخ یکسانی را نشنوند:

YAML

candidates:
  - first_simple:
      variants:
        - speech: Hello.
        - speech: Hi there.
        - speech: Welcome.
    

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Hello."
      },{
        "speech": "Hi there."
      },{
        "speech": "Welcome."
      }]
    }
  }]
}
    

پیشنهادات

وقتی «دستیار» درخواست را نمایش می‌دهد، پیشنهادها تراشه‌های پیشنهادی را در دستگاه‌های دارای نمایشگر به کاربران ارائه می‌دهند. از تراشه‌های پیشنهاد برای اشاره به پاسخ‌های کاربر برای ادامه یا تغییر مکالمه استفاده کنید. هنگامی که ضربه بزنید، یک تراشه پیشنهاد متن نمایش داده شده را کلمه به کلمه به مکالمه باز می گرداند، گویی که کاربر آن را تایپ کرده است.

شما ممکن است حداکثر 8 پیشنهاد در یک درخواست داشته باشید که هر کدام حداکثر 25 کاراکتر متن ساده دارند.

برای افزودن یک پیشنهاد، یک شیء Suggestion که هر پیشنهاد را در یک فیلد title جداگانه دارد، ارائه دهید. هر عنوان باید در میان مجموعه تراشه های پیشنهادی منحصر به فرد باشد. در Actions Builder، این شی در YAML و JSON به عنوان suggestions نمایش داده می شود.

برای مثال، می‌توانید پیشنهادات «بله» و «خیر» را در کنار یک سؤال ارائه دهید:

YAML

candidates:
  - first_simple:
      variants:
        - speech: 'Welcome, do you want to play a game?'
    suggestions:
      - title: 'Yes'
      - title: 'No'
    

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Welcome, do you want to play a game?"
      }]
    },
    "suggestions": [{
      "title": "Yes"
    }, {
      "title": "No"
    }]
  }]
}