Формат ответа

Внимание

Время ожидания ответа от навыка — 4,5 секунды. Если Диалоги не получат ответ в течение этого времени, сессия навыка завершится. Алиса сообщит пользователю, что навык не отвечает.

Время ответа — это время от начала отправки запроса в навык сервером Алисы до полного получения ответа от навыка. В 4,5 секунды входят:

  • установка сетевого соединения;
  • время доставки запроса до сервера навыка;
  • собственное время работы навыка;
  • время доставки ответа до серверов Алисы.

Обработчик навыка должен ответить на полученный от Яндекс Диалогов запрос согласно формату:

{
  "response": {
    "text": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "card": {
      "type": "...",
    },     
    "buttons": [
        {
            "title": "Надпись на кнопке",
            "payload": {},
            "url": "https://example.com/",
            "hide": true
        }
    ],
    "end_session": false,
    "directives": {}
  },
  "session_state": {
      "value": 10
  },
  "user_state_update": {
      "value": 42
  },
  "application_state": {
      "value": 37
  },
  "analytics": {
        "events": [
            {
                "name": "custom event"
            },
            {
                "name": "another custom event",
                "value": {
                    "field": "some value",
                    "second field": {
                        "third field": "custom value"
                    }
                }
            }
        ]
    },
  "version": "1.0"
}

Содержимое тела ответа

Свойство

Описание

response

object

Обязательное свойство.

Данные для ответа пользователю.

session_state

object

Объект, содержащий состояние навыка для хранения в контексте сессии.

user_state_update

object

Объект, содержащий состояние навыка для хранения в контексте авторизованного пользователя.

application_state

object

Объект, содержащий состояние навыка для хранения в контексте экземпляра приложения пользователя.

analytics

object

Объект с данными для аналитики.

Доступен навыкам с подключенным параметром Настройки AppMetrica. Подробнее см. в разделе  AppMetrica.

version

string

Обязательное свойство.

Версия протокола.

Текущая версия — 1.0.

response

Данные для ответа пользователю.

Свойство

Описание

text

string

Обязательное свойство.

Текст, который следует показать и озвучить пользователю.

Максимум 1024 символа. Может быть пустым (text: ""), если заполнено свойство tts.

Текст также используется, если у Алисы не получилось отобразить включенную в ответ карточку (свойство response.card). На устройствах, которые поддерживают только голосовое общение с навыком, это будет происходить каждый раз, когда навык присылает карточку в ответе.

В тексте ответа можно указать переводы строк последовательностью «\n», например: "Отдых напрасен. Дорога крута.\nВечер прекрасен. Стучу в ворота."

tts

string

Ответ в формате TTS (text-to-speech).

Максимум 1024 символа.

Советы по использованию этого формата приведены в разделе Настройка генерации речи.

Вы также можете проигрывать звуки из библиотеки Алисы и собственные звуки (теги <speaker>, которые используются для ссылок на звуки, не учитываются в ограничении в 1024 символа на длину значения свойства tts). Фрагменты tts, собственные и библиотечные звуки можно указывать друг за другом в произвольном порядке и более одного раза каждый.

card

object

Описание карточки — сообщения с поддержкой изображений.

Если приложению удается отобразить карточку для пользователя, свойство response.text не используется.

Содержимое зависит от типа карточки, указанного в поле card.type. Возможные значения:

  • BigImage — одно изображение.
  • ItemsList — список из нескольких изображений (от 1 до 5).
  • ImageGallery — галерея из нескольких изображений (от 1 до 7).

buttons[]

array of objects

Кнопки, которые следует показать пользователю.

Все указанные кнопки выводятся после основного ответа Алисы, описанного в свойствах response.text и response.card. Кнопки можно использовать как релевантные ответу ссылки или подсказки для продолжения разговора.

end_session

boolean

Обязательное свойство.

Признак конца разговора. Допустимые значения:

  • false — сессию следует продолжить;
  • true — сессию следует завершить.

directives

object

Директивы.

Содержимое зависит от типа директивы. Возможные значения:

show_item_meta

object

Обязательный параметр только для сценария утреннего шоу.

Параметр историй утреннего шоу Алисы.

response.buttons

Кнопки, которые следует показать пользователю. Все указанные кнопки выводятся после основного ответа Алисы, описанного в свойствах response.text и response.card. Кнопки можно использовать как релевантные ответу ссылки или подсказки для продолжения разговора.

Посмотреть в интерфейсе

Свойство

Описание

title

string

Обязательное свойство для каждой кнопки.

Текст кнопки.

Максимум 64 символа.

Если для кнопки не указано свойство url, по нажатию текст кнопки будет отправлен навыку как реплика пользователя.

url

string

URL, который должна открывать кнопка.

Максимум 1024 байта.

Если свойство url не указано, по нажатию кнопки навыку будет отправлен текст кнопки.

payload

object

Произвольный JSON-объект, который Яндекс Диалоги должны отправить обработчику, если данная кнопка будет нажата.

Максимум 4096 байт.

hide

boolean

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

  • false — кнопка должна оставаться активной (значение по умолчанию);
  • true — кнопку нужно скрывать после нажатия.

analytics

Объект с данными для аналитики. Доступен навыкам с подключенным параметром Настройки AppMetrica. Подробнее — в разделе о подключении AppMetrica.

Свойство

Описание

events[]

array of objects

Массив событий.

analytics.events

Массив событий.

Свойство

Описание

name

string

Название события.

value

objects

JSON-объект для многоуровневых событий. Допустимо не более пяти уровней вложенности события.

Многоуровневые события передаются через пары key:value.

Подробнее — в документации AppMetrica.

Предыдущая
SimpleUtterance
Следующая
BigImage