Developers » Создание скилла Маруси
Создание скилла Маруси
1. Регистрация приложения ВКонтакте
2. Схема взаимодействия со скиллом
            Тестирование скилла
      2.1 Формат POST-запроса на Webhook URL
      2.2 Формат ответа обработчика скилла Марусе
3. Модерация скилла

Для голосового помощника Маруси теперь можно создавать скиллы, которые пополнят её базу навыков. Пользователям будет удобнее общаться с Марусей, а разработчики и владельцы бизнеса смогут сделать голосовой интерфейс для своих продуктов
1. Регистрация приложения ВКонтакте
Скилл можно создать в разделе для разработчиков: https://vk.com/editapp?act=create.
В день можно создать не более 3-х скиллов, и не более 10-и за 5 дней.

Для этого:
1. Выберите «Скилл Маруси» в типах приложения;
2. Добавьте название, которое будет совпадать с командой для активации скилла;
3. Введите в поле Webhook URL адрес сервера, по которому будет размещен навык, например https://example.com/test-webhook;
4. Подтвердите действие.

Вы попадёте в интерфейс администрирования Вашего скилла.
Обратите внимание: имя является первой фразой-триггером для вызова скилла.

Фразы для вызова скилла должны быть специфичны и уникальны, чтобы мы могли использовать их для внешних скиллов. Например, фразу «Расскажи анекдот» добавить не сможем, т.к. она уже используется во внутренних скиллах Маруси. А вот фразу «Давай сделаем кодревью» — пока можно использовать для внешнего скилла.
Длина фразы активации не может превышать 64 символа.
2. Схема взаимодействия со скиллом
1. Пользователь произносит фразу для вызова скилла.
2. Получив и распознав выражение, сервер Маруси отправляет POST-запрос на Webhook URL, который вы указали в настройках.
3. Обработчик скилла должен ответить на полученный от сервера Маруси запрос. Таймаут ожидания ответа — 5 секунд, после чего сервер Маруси завершит сессию.

Фраза вызова скилла строится по следующей схеме:
Слово «Маруся» + любая из дефолтных фраз вызова скилла + фраза активации.


Дефолтные фразы вызова скилла:
  • хочу скилл/навык
  • запусти скилл/навык
  • включи скилл/навык
  • открой скилл/навык

Примеры:
«Маруся, запусти навык шутка дня», «Маруся, включи скилл шутка дня».
Тестирование скилла
При создании скилла по умолчанию доступ к нему имеют только его администраторы.
Для того, чтобы проверить скилл, авторизуйтесь в приложении Маруси для Android или iOS через VK Connect, используя номер, привязанный к учётной записи ВКонтакте.

Запустить скилл можно как голосовой командой, так и при помощи чата в приложении.
2.1 Формат POST-запроса на Webhook URL
Обратите внимание: разработчики Маруси оставляют за собой право добавлять любые новые поля в JSON, внешний скилл не должен от этого ломаться.

Запрос содержит четыре поля:
Структура запроса
meta
object
информация об устройстве, с помощью которого пользователь общается с Марусей.
request
object
данные, полученные от пользователя.
session
object
данные о сессии.
version
string
версия протокола, текущая версия — 1.0.

Структура объекта meta
locale
string
язык в POSIX-формате, максимум 64 символа.
timezone
string
название часового пояса, включая алиасы, максимум 64 символа
interfaces
array
интерфейсы, доступные на устройстве пользователя, сейчас всегда присылается screen — пользователь может видеть ответ скилла на экране и открывать ссылки в браузере.

Структура объекта session
session_id
string
уникальный идентификатор сессии, максимум 64 символа.
user_id
string
идентификатор экземпляра приложения, в котором пользователь общается с Марусей, максимум 64 символа.
skill_id
string
идентификатор вызываемого скилла, присвоенный при создании. Соответствует полю "Маруся ID" в настройках скилла.
new
bool
признак новой сессии:
  • true — пользователь начинает новый разговор с навыком,
  • false — запрос отправлен в рамках уже начатого разговора.
message_id
integer
идентификатор сообщения в рамках сессии, максимум 8 символов. Инкрементируется с каждым следующим запросом.

Структура объекта request
command
string
служебное поле: запрос пользователя, преобразованный для внутренней обработки Марусей. В ходе преобразования текст, в частности, очищается от знаков препинания, а числительные преобразуются в числа. При завершении скилла по команде "стоп", "выход" и т.д. в скилл будет передано "on_interrupt", чтобы у скилла была возможность попрощаться с пользователем.
original_utterance
string
полный текст пользовательского запроса, максимум 1024 символа.
type
string
тип ввода, обязательное свойство. Возможные значения: "SimpleUtterance" — голосовой ввод, "ButtonPressed" — нажатие кнопки.
payload
object
JSON, полученный с нажатой кнопкой от обработчика скилла (в ответе на предыдущий запрос), максимум 4096 байт.
nlu
object
объект, содержащий слова и именованные сущности, которые Маруся извлекла из запроса пользователя, в поле tokens (array)

Пример запроса

{
  "meta": {
    "client_id": "MailRu-VC/1.0",
    "locale": "ru_RU",
    "timezone": "Europe/Moscow",
    "interfaces": {
      "screen": {}
      }
   },
  "request": {
    "command": "какая очередь в столовой",
    "original_utterance": "какая очередь в столовой",
    "type": "SimpleUtterance",
    "payload": {},
    "nlu": {
      "tokens": [
        "какая",
        "очередь",
        "в",
        "столовой"
      ]
    }
  },
  "session": {
    "session_id": "574d41e0-a41e-4028-a73a-6f5b5bfed299",
    "user_id": "6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee",
    "skill_id": "6861e5a9-4e0f-4660-9331-01f720ddaf5d",
    "new": true,
    "message_id": 0
  },
  "version": "1.0"
}

2.2 Формат ответа обработчика скилла Марусе
Структура ответа
response
object, обязательное
данные для ответа пользователю.
session
object, обязательное
данные о сессии.
version
string, обязательное
версия протокола, текущая версия — 1.0.

Структура объекта response
text
string, обязательное
текст, который следует показать и сказать пользователю. Максимум 1024 символа. Не должен быть пустым. В тексте ответа можно указать переводы строк последовательностью «\n».
tts
object
ответ в формате TTS (text-to-speech), максимум 1024 символа. Поддерживается расстановка ударений с помощью '+'.
buttons
array
кнопки (suggest'ы), которые следует показать пользователю. Кнопки можно использовать как релевантные ответу ссылки или подсказки для продолжения разговора.
end_session
bool, обязательное
признак конца разговора:
  • true — сессию следует завершить,
  • false — сессию следует продолжить.
card
object
описание карточки — сообщения с поддержкой изображений.

Структура объекта buttons
title
string, обязательное
текст кнопки. Максимум 64 символа.
url
string
URL, который откроется при нажатии на кнопку, максимум 1024 байта. Если свойство url не указано, по нажатию кнопки навыку будет отправлен текст кнопки. (Пока кнопки с url поддерживаются только на Android, на iOS появятся совсем скоро)
payload
array
любой JSON, который нужно отправить скиллу, если данная кнопка будет нажата. Максимум 4096 байт.

Структура объекта card
type
string, обязательное
тип карточки:
  • BigImage — одно изображение.
  • ItemsList — набор изображений.
title
string
заголовок изображения (пока не отображается)
description
string
описание изображения (пока не отображается)
image_id
integer
ID изображения из раздела "Медиа-файлы" настроек в VKApps (игнорируется для типа ItemsList).
items
array
список изображений, каждый элемент которого является объектом с обязательным полем image_id (игнорируется для BigImage).

Структура объекта session
session_id
string, обязательное
уникальный идентификатор сессии, максимум 64 символа.
user_id
string, обязательное
идентификатор экземпляра приложения, в котором пользователь общается с Марусей, максимум 64 символа.
message_id
string, обязательное
идентификатор сообщения в рамках сессии, максимум 8 символов. Инкрементируется с каждым следующим запросом.

Пример ответа без картинок
{
  "response": {
    "text": "Сейчас очередь в столовой 5 человек.",
    "tts": "Сейчас очередь в столовой пять человек.",
    "buttons": [
      {
        "title": "Надпись на кнопке",
        "payload": {},
        "url": "https://example.com/"
      }
    ],
    "end_session": true
  },
  "session": {
    "session_id": "574d41e0-a41e-4028-a73a-6f5b5bfed299",
    "message_id": 0,
    "user_id": "6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
  },
  "version": "1.0"
}

Пример ответа с картинкой
{
       "response":{
       "text":"Сейчас очередь в столовой 5 человек.",
       "tts":"Сейчас очередь в столовой пять человек.",
       "card":{
          "type":"BigImage",
          "image_id":239017,
          "title": "Заголовок для изображения",
          "description": "Описание изображения"
       },
      "buttons":[
         {
            "title":"Надпись на кнопке",
            "payload":{

},
            "url":"https://example.com/"
         }
      ],
      "end_session":true
   },
   "session":{
      "session_id":"574d41e0-a41e-4028-a73a-6f5b5bfed299",
      "message_id":0,
      "user_id":"6953b29afe19e372ecdd34d07b3eae3c2f69b9f04e8cb15e157c4a9e056d58ee"
   },
   "version":"1.0"
}