Протокол работы навыка

Яндекс.Диалоги и сервера партнеров интегрируются по протоколу HTTPS по методу webhook. Формат взаимодействия включает в себя форматы запросов и ответов, которыми Яндекс.Диалоги обмениваются с серверами навыков.

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

Формат запроса

Получив реплику пользователя, Яндекс.Диалоги отправляют POST-запрос на Webhook URL, указанный при публикации.

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "client_id": "ru.yandex.searchplugin/5.80 (Samsung Galaxy; Android 4.4)",
    "interfaces": {
      "screen": { }
    }
  },
  "request": {
    "command": "закажи пиццу на улицу льва толстого, 16 на завтра",
    "original_utterance": "закажи пиццу на улицу льва толстого, 16 на завтра",
    "type": "SimpleUtterance",
    "markup": {
      "dangerous_context": true
    },
    "payload": {},
    "nlu": {
      "tokens": [
        "закажи",
        "пиццу",
        "на",
        "льва",
        "толстого",
        "16",
        "на",
        "завтра"
      ],
      "entities": [
        {
          "tokens": {
            "start": 2,
            "end": 6
          },
          "type": "YANDEX.GEO",
          "value": {
            "house_number": "16",
            "street": "льва толстого"
          }
        },
        {
          "tokens": {
            "start": 3,
            "end": 5
          },
          "type": "YANDEX.FIO",
          "value": {
            "first_name": "лев",
            "last_name": "толстой"
          }
        },
        {
          "tokens": {
            "start": 5,
            "end": 6
          },
          "type": "YANDEX.NUMBER",
          "value": 16
        },
        {
          "tokens": {
            "start": 6,
            "end": 8
          },
          "type": "YANDEX.DATETIME",
          "value": {
            "day": 1,
            "day_is_relative": true
          }
        }
      ]
    }
  },
  "session": {
    "new": true,
    "message_id": 4,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
  },
  "version": "1.0"
}

Свойства с метаинформацией о запросе

meta

Информация об устройстве, с помощью которого пользователь разговаривает с Алисой.

locale

Язык в POSIX-формате, максимум 64 символа.

timezone

Название часового пояса, включая алиасы, максимум 64 символа.

client_id
Примечание. Не рекомендуется к использованию. Интерфейсы, доступные на клиентском устройстве, перечислены в свойстве interfaces.
Идентификатор устройства и приложения, в котором идет разговор, максимум 1024 символа.
interfaces

Интерфейсы, доступные на устройстве пользователя.

screen

Пользователь может видеть ответ навыка на экране и открывать ссылки в браузере.

session

Данные о сессии.

new

Признак новой сессии. Возможные значения:

  • true — пользователь начинает новый разговор с навыком;
  • false — запрос отправлен в рамках уже начатого разговора.
message_id

Идентификатор сообщения в рамках сессии, максимум 8 символов.

Инкрементируется с каждым следующим запросом.

session_id

Уникальный идентификатор сессии, максимум 64 символов.

skill_id

Идентификатор вызываемого навыка, присвоенный при создании.

Чтобы узнать идентификатор своего навыка, откройте его в личном кабинете — идентификатор будет в адресе страницы, https://.../developer/skills/<идентификатор>/

user_id

Идентификатор экземпляра приложения, в котором пользователь общается с Алисой, максимум 64 символа.

Даже если пользователь авторизован с одним и тем же аккаунтом в приложении Яндекс для Android и iOS, Яндекс.Диалоги присвоят отдельный user_id каждому из этих приложений.

version

Версия протокола. Текущая версия — 1.0.

Содержимое запроса к навыку

request

Данные, полученные от пользователя.

command

Запрос, который был передан вместе с командой активации навыка.

Например, если пользователь активирует навык словами «спроси у Сбербанка где ближайшее отделение», в этом поле будет передана строка «где ближайшее отделение».

Команды активации, с которыми рекомендуется передавать такие запросы:

  • «скажи»;
  • «попроси»;
  • «узнай у»;
  • «спроси у».
original_utterance

Полный текст пользовательского запроса, максимум 1024 символа.

type

Тип ввода, обязательное свойство. Возможные значения:

  • "SimpleUtterance" — голосовой ввод;
  • "ButtonPressed" — нажатие кнопки.
markup

Формальные характеристики реплики, которые удалось выделить Яндекс.Диалогам. Отсутствует, если ни одно из вложенных свойств не применимо.

dangerous_context

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

Возможно только значение true. Если признак не применим, это свойство не включается в ответ.

payload

JSON, полученный с нажатой кнопкой от обработчика навыка (в ответе на предыдущий запрос), максимум 4096 байт.

nlu

Слова и именованные сущности, которые Диалоги извлекли из запроса пользователя.

Подробное описание поддерживаемых типов сущностей см. в разделе Именованные сущности в запросах.

tokens

Массив слов из произнесенной пользователем фразы.

entities

Массив именованных сущностей.

tokens

Обозначение начала и конца именованной сущности в массиве слов. Нумерация слов в массиве начинается с 0.

start

Первое слово именованной сущности.

end

Первое слово после именованной сущности.

type

Тип именованной сущности. Возможные значения:

  • YANDEX.DATETIME — дата и время, абсолютные или относительные.
  • YANDEX.FIO — фамилия, имя и отчество.
  • YANDEX.GEO — местоположение (адрес или аэропорт).
  • YANDEX.NUMBER — число, целое или с плавающей точкой.
value

Формальное описание именованной сущности.

Формат этого поля для всех поддерживаемых типов сущностей приведен в разделе Именованные сущности в запросах.

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

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

{
  "response": {
    "text": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "buttons": [
        {
            "title": "Надпись на кнопке",
            "payload": {},
            "url": "https://example.com/",
            "hide": true
        }
    ],
    "end_session": false
  },
  "session": {
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "message_id": 4,
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
  },
  "version": "1.0"
}

Обязательные свойства помечены знаком «*».

response *

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

text *

Текст, который следует показать и сказать пользователю. Максимум 1024 символа. Не должен быть пустым.

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

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

tts

Ответ в формате TTS (text-to-speech), максимум 1024 символа.

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

card

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

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

type *

Тип карточки. Поддерживаемые значения:

  • BigImage — одно изображение.
  • ItemsList — галерея изображений (от 1 до 5).

Требуемый формат ответа зависит от типа карточки.

image_id

Идентификатор изображения, который возвращается в ответ на запрос загрузки.

Необходимо указывать для карточки типа BigImage, для типа ItemsList игнорируется.

title

Заголовок для изображения.

Игнорируется для карточки типа ItemsList.

description

Описание изображения.

Игнорируется для карточки типа ItemsList.

button

Свойства изображения, на которое можно нажать.

Игнорируется для карточки типа ItemsList.

text

Текст, который будет отправлен навыку по нажатию на изображение в качестве команды пользователя. Максимум 64 символа.

Если свойство передано с пустым значением, свойство request.command в запросе будет отправлено пустым.

Если свойство не передано в ответе, Диалоги используют вместо него свойство response.card.title.

url

URL, который должно открывать нажатие по изображению. Максимум 1024 байта.

payload

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

header

Заголовок галереи изображений.

Игнорируется для карточки типа BigImage.

text

Текст заголовка, обязателен, если передается свойство header. Максимум 64 символа.

items

Набор изображений для галереи — не меньше 1, не больше 5.

Игнорируется для карточки типа BigImage.

image_id

Идентификатор изображения, который возвращается в ответ на запрос загрузки.

title

Заголовок для изображения.

description

Описание изображения.

button

Свойства изображения, на которое можно нажать.

text

Текст, который будет отправлен навыку по нажатию на изображение в качестве команды пользователя. Максимум 64 символа.

Если свойство передано с пустым значением, свойство request.command в запросе будет отправлено пустым.

Если свойство не передано в ответе, Диалоги используют вместо него свойство response.card.title.

url

URL, который должно открывать нажатие по изображению. Максимум 1024 байта.

payload

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

footer

Кнопки под галереей изображений.

text

Текст первой кнопки, обязательное свойство. Максимум 64 символа.

button

Дополнительная кнопка для галереи изображений.

text

Текст кнопки, обязателен для каждой кнопки. Максимум 64 символа.

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

url

URL, который должно открывать нажатие по изображению. Максимум 1024 байта.

payload

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

buttons

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

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

title

Текст кнопки, обязателен для каждой кнопки. Максимум 64 символа.

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

url

URL, который должна открывать кнопка, максимум 1024 байта.

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

payload

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

hide

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

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

Признак конца разговора.

Допустимые значения:

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

Данные о сессии.

session_id *

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

message_id *

Идентификатор сообщения в рамках сессии, полученный в запросе.

user_id *

Идентификатор пользователя, полученный в запросе.

version *

Версия протокола. Текущая версия — 1.0.

Обязательный параметр