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

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

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

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

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

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "client_id": "ru.yandex.searchplugin/5.80 (Samsung Galaxy; Android 4.4)"
  },
  "request": {
     "type": "SimpleUtterance",
     "markup": {
        "dangerous_context": true
     },
     "command": "архангельск",
     "original_utterance": "Алиса вызови игру в города. Архангельск.",
     "payload": {}
  },
  "session": {
    "new": true,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "message_id": 4,
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
  },
  "version": "1.0"
}
meta

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

locale

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

timezone

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

client_id

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

request

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

type

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

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

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

dangerous_context

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

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

command

Текст пользовательского запроса без активационных фраз Алисы и конкретного навыка, максимум 1024 байта. Может быть пустым.

original_utterance

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

payload

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

session

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

new

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

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

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

message_id

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

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

skill_id

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

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

user_id

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

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

version

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

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

Обработчик навыка должен ответить на полученный от Яндекс.Диалогов запрос в следующем формате:
{
  "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 символа. Обязательное свойство.

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

tts

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

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

buttons

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

title

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

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

url

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

payload

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

hide

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

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

Признак конца разговора. Обязательное свойство.

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

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

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

session_id

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

message_id

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

user_id

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

version

Версия протокола. Текущая версия — 1.0. Обязательное свойство.