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

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

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

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

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

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "interfaces": {
      screen: {},
      browser: {}
    }
}
  },
  "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 символа.

interfaces

Перечисление интерфейсов 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 Слова и именованные сущности, которые Диалоги извлекли из запроса пользователя.

Подробное описание поддерживаемых типов сущностей см. в разделе Обработка естественного языка (NLP). tokens Массив слов из произнесенной пользователем фразы. entities Массив именованных сущностей. tokens Обозначение начала и конца именованной сущности в массиве слов. Нумерация слов в массиве начинается с 0. start Первое слово именованной сущности. end Первое слово после именованной сущности. type Тип именованной сущности. Возможные значения:

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

Формат этого поля для всех поддерживаемых типов сущностей приведен в разделе Обработка естественного языка (NLP).

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

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

Без изображений

{
  "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": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "card": {
      "type": "BigImage",
      "image_id": "1027858/46r960da47f60207e924",
      "title": "Заголовок для изображения",
      "description": "Описание изображения.",
      "button": {
        "text": "Надпись на кнопке",
        "url": "http://example.com/",
        "payload": {}
      }
    },
    "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": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "card": {
      "type": "ItemsList",
      "header": {
        "text": "Заголовок галереи изображений",
      },
      "items": [
        {
          "image_id": "<image_id>",
          "title": "Заголовок для изображения.",
          "description": "Описание изображения.",
          "button": {
            "text": "Надпись на кнопке",
            "url": "http://example.com/",
            "payload": {}
          }
        }
      ],
      "footer": {
        "text": "Текст блока под изображением.",
        "button": {
          "text": "Надпись на кнопке",
          "url": "https://example.com/",
          "payload": {}
        }
      }
    },
    "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Вечер прекрасен. Стучу в ворота." 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.