marusia

Documentation

Overview

Package marusia для создания скилла Маруси.

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

Документация: https://vk.com/dev/marusia_skill_docs

Регистрация приложения ВКонтакте

Скилл можно создать в разделе для разработчиков: https://vk.com/editapp?act=create. В день можно создать не более 3-х скиллов, и не более 10-и за 5 дней.

Для этого:

1. Выберите «Скилл Маруси» в типах приложения;

2. Добавьте название, которое будет совпадать с командой для активации скилла;

3. Введите в поле Webhook URL адрес сервера, по которому будет размещен навык, например https://example.com/test-webhook;

4. Подтвердите действие.

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

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

Фразы

Фразы для вызова скилла должны быть специфичны и уникальны, чтобы мы могли использовать их для внешних скиллов. Например, фразу «Расскажи анекдот» добавить не сможем, т.к. она уже используется во внутренних скиллах Маруси. А вот фразу «Давай сделаем кодревью» — пока можно использовать для внешнего скилла.

Длина фразы активации не может превышать 64 символа.

Фраза вызова скилла строится по следующей схеме:

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

Дефолтные фразы вызова скилла:

хочу скилл/навык

запусти скилл/навык

включи скилл/навык

открой скилл/навык

Примеры: «Маруся, запусти навык шутка дня», «Маруся, включи скилл шутка дня».

Схема взаимодействия со скиллом

1. Пользователь произносит фразу для вызова скилла.

2. Получив и распознав выражение, сервер Маруси отправляет POST-запрос на Webhook URL, который вы указали в настройках.

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

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

Запустить скилл можно как голосовой командой, так и при помощи чата в приложении.

Также протестировать и отладить скилл можно в отладчике скиллов https://skill-tester.marusia.mail.ru/

Пример

Пример скилла.

type myPayload struct {
	Text string
	marusia.DefaultPayload
}

wh := marusia.NewWebhook()

wh.OnEvent(func(r marusia.Request) (resp marusia.Response) {
	switch r.Request.Type {
	case marusia.SimpleUtterance:
		switch r.Request.Command {
		case marusia.OnStart:
			resp.Text = "Скилл запущен"
			resp.TTS = "Скилл запущен, жду команд"
		case "картинка":
			resp.Card = marusia.NewBigImage(
				"Заголовок",
				"Описание",
				457239017,
			)
		case "картинки":
			resp.Card = marusia.NewImageList(
				457239017,
				457239018,
			)
		case "кнопки":
			resp.Text = "Держи кнопки"
			resp.TTS = "Жми на кнопки"
			resp.AddURL("ссылка", "https://vk.com")
			resp.AddButton("подсказка без нагрузки", nil)
			resp.AddButton("подсказка с нагрузкой", myPayload{
				Text: "test",
			})
		case marusia.OnInterrupt:
			resp.Text = "Скилл закрыт"
			resp.TTS = "Пока"
			resp.EndSession = true
		default:
			resp.Text = "Неизвестная команда"
			resp.TTS = "Я вас не поняла"
		}
	case marusia.ButtonPressed:
		var p myPayload

		err := json.Unmarshal(r.Request.Payload, &p)
		if err != nil {
			resp.Text = "Что-то пошло не так"
			return
		}

		resp.Text = "Кнопка нажата. Полезная нагрузка: " + p.Text
		resp.TTS = "Вы нажали на кнопку"
	}

	return
})

http.HandleFunc("/", wh.HandleFunc)

http.ListenAndServe(":8080", nil)

Index

• Constants
• type BindingType
• type Button
• type Card
  • func NewBigImage(title, description string, imageID int) *Card
  • func NewImageList(imageIDs ...int) *Card
  • func NewItemsList(items ...CardItem) *Card
• type CardItem
• type CardType
• type DefaultPayload
• type Interfaces
  • func (i *Interfaces) IsScreen() bool
• type Meta
• type NLU
• type Request
• type RequestIn
• type RequestType
• type Response
  • func (r *Response) AddButton(title string, payload interface{})
  • func (r *Response) AddURL(title string, url string)
• type Screen
• type Session
• type Webhook
  • func NewWebhook() *Webhook
  • func (wh *Webhook) HandleFunc(w http.ResponseWriter, r *http.Request)
  • func (wh *Webhook) OnEvent(f func(r Request) Response)

Constants

const (
	// OnStart команда запуска скилла. В скилл будет передана пустая строка
	// Command = "".
	OnStart = ""

	// OnInterrupt команда завершении скилла по команде "стоп", "выход" и т.д. в
	// скилл будет передано Command = "on_interrupt", чтобы у скилла была
	// возможность попрощаться с пользователем.
	OnInterrupt = "on_interrupt"
)

Типичные команды голосового ввода.

const Version = "1.0"

Version версия протокола.

Types

type BindingType

type BindingType string

BindingType тип для DefaultPayload.

const (
	BindingTypeSuggest BindingType = "suggest"
)

Возможные значения.

type Button

type Button struct {
	Title   string      `json:"title"`
	Payload interface{} `json:"payload,omitempty"`
	URL     string      `json:"url,omitempty"`
}

Button кнопка.

type Card

type Card struct {
	// Тип карточки.
	Type CardType `json:"type"`

	// Заголовок изображения.
	Title string `json:"title,omitempty"`

	// Описание изображения.
	Description string `json:"description,omitempty"`

	// ID изображения из раздела "Медиа-файлы" в настройках скилла
	// (игнорируется для типа ItemsList).
	ImageID int `json:"image_id,omitempty"`

	// Список изображений, каждый элемент является объектом формата BigImage.
	Items []CardItem `json:"items,omitempty"`
}

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

func NewBigImage

func NewBigImage(title, description string, imageID int) *Card

NewBigImage возвращает карточку с картинкой.

func NewImageList

func NewImageList(imageIDs ...int) *Card

NewImageList возвращает карточку с набором картинок.

func NewItemsList

func NewItemsList(items ...CardItem) *Card

NewItemsList возвращает карточку с набором картинок.

type CardItem

type CardItem struct {

	// ID изображения из раздела "Медиа-файлы" в настройках скилла.
	ImageID int `json:"image_id"`
}

CardItem элемент карточки.

type CardType

type CardType string

CardType тип карточки.

const (
	// Одно изображение.
	BigImage CardType = "BigImage"

	// Набор изображений.
	ItemsList CardType = "ItemsList"
)

Возможные значения.

type DefaultPayload

type DefaultPayload struct {
	BindingType    BindingType `json:"binding_type"`
	Index          int         `json:"index"`
	TargetPhraseID string      `json:"target_phrase_id"`
}

DefaultPayload дефолтная нагрузка.

type Interfaces

type Interfaces struct {
	// Пользователь может видеть ответ скилла на экране и открывать ссылки
	// в браузере.
	Screen *Screen `json:"screen,omitempty"`
}

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

func (*Interfaces) IsScreen

func (i *Interfaces) IsScreen() bool

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

type Meta

type Meta struct {
	// Идентификатор клиентского приложения
	ClientID string `json:"client_id"`

	// Язык в POSIX-формате, максимум 64 символа.
	Locale string `json:"locale"`

	// Название часового пояса, включая алиасы, максимум 64 символа
	Timezone string `json:"timezone"`

	// Интерфейсы, доступные на устройстве пользователя.
	Interfaces Interfaces `json:"interfaces"`

	// Город пользователя на русском языке.
	CityRu string `json:"_city_ru,omitempty"`
}

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

type NLU

type NLU struct {
	Tokens   []string `json:"tokens"`
	Entities []string `json:"entities"`
}

NLU - Natural Language Understanding.

type Request

type Request struct {
	// Информация об устройстве, с помощью которого пользователь общается с Марусей.
	Meta Meta `json:"meta"`

	// Данные, полученные от пользователя.
	Request RequestIn `json:"request"`

	// Данные о сессии.
	Session Session `json:"session"`

	// Версия протокола.
	Version string `json:"version"`
}

Request структура запроса.

type RequestIn

type RequestIn struct {
	// Служебное поле: запрос пользователя, преобразованный для внутренней
	// обработки Марусей. В ходе преобразования текст, в частности, очищается
	// от знаков препинания, а числительные преобразуются в числа. При
	// завершении скилла по команде "стоп", "выход" и т.д. в скилл будет
	// передано "on_interrupt", чтобы у скилла была возможность попрощаться с
	// пользователем.
	Command string `json:"command"`

	// Полный текст пользовательского запроса, максимум 1024 символа.
	OriginalUtterance string `json:"original_utterance"`

	// Тип ввода.
	Type RequestType `json:"type"`

	// JSON, полученный с нажатой кнопкой от обработчика скилла (в ответе на
	// предыдущий запрос), максимум 4096 байт.
	Payload json.RawMessage `json:"payload,omitempty"`

	// Объект, содержащий слова и именованные сущности, которые Маруся
	// извлекла из запроса пользователя.
	NLU NLU `json:"nlu"`
}

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

type RequestType

type RequestType string

RequestType тип ввода.

const (
	SimpleUtterance RequestType = "SimpleUtterance" // голосовой ввод
	ButtonPressed   RequestType = "ButtonPressed"   //  нажатие кнопки
)

Возможные значения.

type Response

type Response struct {
	// Текст, который следует показать и сказать пользователю. Максимум 1024
	// символа. Не должен быть пустым. В тексте ответа можно указать переводы
	// строк последовательностью «\n».
	Text string `json:"text"`

	// Ответ в формате TTS (text-to-speech), максимум 1024 символа.
	// Поддерживается расстановка ударений с помощью '+'.
	TTS string `json:"tts,omitempty"`

	// Кнопки (suggest'ы), которые следует показать пользователю. Кнопки можно
	// использовать как релевантные ответу ссылки или подсказки для
	// продолжения разговора.
	Buttons []Button `json:"buttons,omitempty"`

	// Признак конца разговора:
	//
	// true — сессию следует завершить,
	//
	// false — сессию следует продолжить.
	EndSession bool `json:"end_session"`

	// Описание карточки — сообщения с поддержкой изображений.
	// Важно! Если указано данное поле, то поле text игнорируется.
	Card *Card `json:"card,omitempty"`
}

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

func (*Response) AddButton

func (r *Response) AddButton(title string, payload interface{})

AddButton добавляет к ответу кнопку с полезной нагрузкой.

Если полезная нагрузка не нужна, можно передать nil.

func (*Response) AddURL

func (r *Response) AddURL(title string, url string)

AddURL добавляет к ответу кнопку с ссылкой.

type Screen

type Screen struct{}

Screen структура для Interfaces.

type Session

type Session struct {
	// Уникальный идентификатор сессии, максимум 64 символа.
	SessionID string `json:"session_id"`

	// Идентификатор экземпляра приложения, в котором пользователь общается с
	// Марусей, максимум 64 символа.
	UserID string `json:"user_id"`

	// Идентификатор вызываемого скилла, присвоенный при создании.
	// Соответствует полю "Маруся ID" в настройках скилла.
	SkillID string `json:"skill_id"`

	// Признак новой сессии:
	//
	// true — пользователь начинает новый разговор с навыком,
	//
	// false — запрос отправлен в рамках уже начатого разговора.
	New bool `json:"new"`

	// Идентификатор сообщения в рамках сессии, максимум 8 символов.
	// Инкрементируется с каждым следующим запросом.
	MessageID int `json:"message_id"`
}

Session данные о сессии.

type Webhook

type Webhook struct {
	// contains filtered or unexported fields
}

Webhook структура.

func NewWebhook

func NewWebhook() *Webhook

NewWebhook возвращает новый Webhook.

func (*Webhook) HandleFunc

func (wh *Webhook) HandleFunc(w http.ResponseWriter, r *http.Request)

HandleFunc обработчик http запросов.

func (*Webhook) OnEvent

func (wh *Webhook) OnEvent(f func(r Request) Response)

OnEvent обработчик скилла.

Таймаут ожидания ответа — 5 секунд, после чего сервер Маруси завершит сессию.