Подсказки

Подсказки определяют, как ваше действие отображает ответы пользователей и как ваше действие предлагает им продолжить. Создавая свое действие, вы можете добавлять подсказки к его вызовам и в различные места внутри сцены. Подсказки могут быть простыми, например текстовый или речевой ответ, или более сложными и содержать разнообразное содержимое, такое как карточки, изображения и таблицы.

Типы ответов

Для каждого запроса вы выбираете один из множества интересных типов ответов, которые Ассистент будет показывать пользователям:

Простые ответы . Простые ответы визуально принимают форму чат-пузыря и используют преобразование текста в речь (TTS) или язык разметки синтеза речи (SSML) для звука. Простые ответы — единственные ответы, поддерживаемые на всех типах устройств.
Расширенные ответы . Расширенные ответы содержат визуальные или функциональные элементы, которые улучшают взаимодействие пользователя с вашими действиями. Благодаря расширенным ответам вы также можете отображать табличные данные или воспроизводить более длинный аудиоконтент.
Ответы на визуальный выбор . Ответы на визуальный выбор предоставляют пользователям визуальный интерфейс для выбора между несколькими вариантами, которые легче всего отличить по названию или изображению.
Ответы мультимедиа . Ответы мультимедиа позволяют вашим действиям воспроизводить аудиоконтент дольше, чем SSML , и предоставляют визуальный компонент с элементами управления мультимедиа.
Интерактивный холст : Интерактивный холст отображает ответы в виде полноэкранных веб-представлений и функционирует как интерактивное веб-приложение, которое Ассистент отправляет в качестве ответа пользователю в разговоре. Canvas использует немного другой формат приглашений, чтобы обеспечить дополнительную гибкость веб-стандартов, таких как HTML, CSS и JavaScript.

Каждый из этих типов ответов использует один и тот же базовый формат приглашения и имеет доступ к одним и тем же общим функциям, описанным ниже.

Формат приглашения

В проекте Actions вы определяете подсказки в формате YAML или JSON. Каждое приглашение может содержать до двух простых ответов и при необходимости определять расширенный ответ. Ответы определяются следующим образом:

first_simple : Начальный текстовый или речевой (простой) ответ для отправки пользователю.
content : дополнительный контент расширенного ответа для отправки после простых ответов.
last_simple Конечный текстовый или речевой (простой) ответ для отправки пользователю.
canvas : ссылается на веб-приложение, которое интегрируется с Interactive Canvas.

По умолчанию подсказки добавляются друг к другу в указанном выше порядке в очереди подсказок. Прежде чем пользователь сможет ответить, Ассистент предоставляет пользователю все запросы в очереди запросов.

Вы дополнительно обеспечиваете гибкость подсказки, используя следующие функции:

Кандидаты : Кандидаты позволяют вам определять ответы на основе возможностей устройства пользователя. Например, вы можете настроить Ассистент на отображение расширенных ответов только тогда, когда пользователь взаимодействует с вашим действием на устройстве с поддержкой дисплея.
Варианты : Варианты — это альтернативные варианты одного сообщения. Например, вы можете поручить Ассистенту выбирать между пятью различными вариантами приветственного сообщения каждый раз, когда пользователь вызывает ваше действие.
Предложения . Предложения предоставляют пользователям устройств с дисплеем подсказки, когда Ассистент отображает подсказку.

В приглашении по умолчанию используется один кандидат, один вариант и ответ first_simple .

Примечание. Рекомендуется использовать content для поддержки ответа first_simple . Например, если first_simple предоставляет варианты заказа напитка, вы можете использовать content , чтобы предоставить визуальные эффекты для вариантов напитка. Такой подход гарантирует, что пользователи получат важную информацию независимо от того, какое устройство они используют. Альтернативно, используйте кандидатов для предоставления разных ответов в зависимости от устройства.

Кандидаты

В приглашении объект candidates позволяет вам определять ответы на основе возможностей устройства пользователя. Например, вы можете настроить Ассистент на отображение расширенных ответов только тогда, когда пользователь взаимодействует с вашим действием на устройстве с поддержкой дисплея. Чтобы определить типы устройств, на которых Assistant может возвращать кандидата, используйте свойство selector объекта candidates .

В приведенном ниже примере свойство selector содержит информацию о возможностях устройства. Подсказки, заданные в первом кандидате, отправляются пользователям на устройство, которое может отображать развернутые ответы. Второй кандидат содержит подсказки для пользователей, которые могут получать только текстовые и речевые ответы.

ЯМЛ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.

{
  "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 : Устройство может хранить и получать доступ к данным из домашнего хранилища .

Варианты

Варианты позволяют определить несколько версий ответа. Когда Ассистент отправляет пользователю подсказку, один из вариантов выбирается случайным образом. Рекомендуется предоставлять пользователям альтернативные ответы, когда они взаимодействуют с вашим действием.

Например, предоставьте разные варианты приветственного сообщения, чтобы пользователи не слышали один и тот же ответ каждый раз, когда вызывают ваше действие:

ЯМЛJSON

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

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

Предложения

Предложения предоставляют пользователям устройств с дисплеем чипы предложений, когда Ассистент отображает подсказку. Используйте чипы предложений, чтобы подсказать ответы пользователей, чтобы продолжить или развернуть разговор. При нажатии чип подсказки возвращает отображаемый текст в разговор дословно, как если бы пользователь его напечатал.

В одном приглашении может быть максимум 8 предложений, максимальная длина каждого из которых составляет 25 символов открытого текста.

Чтобы добавить предложение, предоставьте объект Suggestion , который содержит каждое предложение в отдельном поле title . Каждое название должно быть уникальным среди набора фишек предложений. В Actions Builder этот объект представлен в форматах YAML и JSON в виде suggestions .

Например, вы можете предложить варианты «Да» и «Нет» рядом с вопросом:

ЯМЛJSON

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

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