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

Внимание.

Время ожидания ответа от навыка — 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`	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 Директивы. Содержимое зависит от типа директивы. Возможные значения: `audio_player` — запуск аудиоплеера на умных колонках; `start_account_linking` — запуск процесса авторизации в навыке.
`show_item_meta`	object Обязательный параметр только для сценария утреннего шоу. Параметр историй утреннего шоу Алисы.


Свойство	Описание
`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 Директивы. Содержимое зависит от типа директивы. Возможные значения: `audio_player` — запуск аудиоплеера на умных колонках; `start_account_linking` — запуск процесса авторизации в навыке.
`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` — кнопку нужно скрывать после нажатия.


Свойство	Описание
`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`	object JSON-объект для многоуровневых событий. Допустимо не более пяти уровней вложенности события. Многоуровневые события передаются через пары `key:value`. Подробнее — в документации AppMetrica.


Свойство	Описание
`name`	string Название события.
`value`	object JSON-объект для многоуровневых событий. Допустимо не более пяти уровней вложенности события. Многоуровневые события передаются через пары `key:value`. Подробнее — в документации AppMetrica.