umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
524 lines (523 loc) • 16.9 kB
TypeScript
/**
* Интерфейсы для работы с Алисой.
* Определяют структуру данных для взаимодействия с API Алисы
*
* Основные компоненты:
* - Запросы (IAlisaWebhookRequest)
* - Ответы (IAlisaWebhookResponse)
* - Сессии (IAlisaSession)
* - Состояния (IAlisaRequestState)
* - Компоненты интерфейса (кнопки, карточки, изображения)
*/
import { INlu, IPlatformData } from '../../../../index';
/**
* Интерфейс для именованных сущностей в запросе.
* Используется для извлечения структурированных данных из текста пользователя
*/
export interface IAlisaEntities {
/**
* Позиция сущности в массиве слов
* Нумерация начинается с 0
*/
tokens?: {
/** Индекс первого слова сущности */
start: number;
/** Индекс первого слова после сущности */
end: number;
};
/**
* Тип именованной сущности
* Поддерживаемые типы:
* - YANDEX.DATETIME: дата и время
* - YANDEX.FIO: фамилия, имя, отчество
* - YANDEX.GEO: местоположение
* - YANDEX.NUMBER: число
*/
type: string;
/**
* Значение сущности
* Формат зависит от типа сущности:
* - YANDEX.DATETIME: { year: number, month: number, day: number, ... }
* - YANDEX.FIO: { first_name: string, last_name: string, ... }
* - YANDEX.GEO: { country: string, city: string, ... }
* - YANDEX.NUMBER: number
*
* @example
* ```ts
* // Для YANDEX.DATETIME
* value: { year: 2024, month: 3, day: 15 }
*
* // Для YANDEX.FIO
* value: { first_name: "Иван", last_name: "Иванов" }
*
* // Для YANDEX.GEO
* value: { country: "Россия", city: "Москва" }
*
* // Для YANDEX.NUMBER
* value: 42
* ```
*/
value: object | number;
}
/**
* Интерфейс для обработки естественного языка (NLU)
* Содержит результаты анализа текста пользователя
*/
export interface IAlisaNlu extends INlu {
/** Массив слов из фразы пользователя */
tokens?: string[];
/** Массив найденных именованных сущностей */
entities?: IAlisaEntities[];
/**
* Распознанные намерения пользователя.
* Каждый интент содержит слоты с параметрами
*
* @example
* ```ts
* intents: {
* "YANDEX.CONFIRM": {
* slots: []
* },
* "YANDEX.REJECT": {
* slots: []
* },
* "YANDEX.DATETIME": {
* slots: [{
* type: "YANDEX.DATETIME",
* value: { year: 2024 }
* }]
* }
* }
* ```
*/
intents?: INlu['intents'];
}
/**
* Интерфейс для данных сессии.
* Содержит информацию о текущем диалоге с пользователем
*/
export interface IAlisaSession {
/**
* Признак новой сессии
* true - начало нового диалога
* false - продолжение существующего диалога
*/
new: boolean;
/**
* ID сообщения в сессии
* Максимум 8 символов
* Увеличивается с каждым запросом
*/
message_id: number;
/**
* Уникальный ID сессии
* Максимум 64 символа
*/
session_id: string;
/**
* ID навыка
* Присваивается при создании навыка
*/
skill_id: string;
/**
* ID пользователя
* Максимум 64 символа
* Уникален для пары "приложение-пользователь"
*/
user_id?: string;
/**
* Данные авторизованного пользователя.
* Присутствует только если пользователь авторизован
*/
user?: {
/**
* ID пользователя Яндекса
* Уникален для пары "пользователь-навык"
*/
user_id: string;
/**
* OAuth токен для авторизации.
* Используется для связки аккаунтов
*/
access_token: string;
};
/**
* Данные о приложении
*/
application?: {
/**
* ID экземпляра приложения
* Максимум 64 символа
* Уникален для пары "приложение-навык"
*/
application_id: string;
};
}
/**
* Интерфейс для состояния приложения.
* Определяет, где хранятся данные:
* - session: данные сессии
* - user: данные пользователя
* - application: данные приложения
*/
export interface IAlisaRequestState {
/**
* Данные сессии
*/
session?: Record<string, unknown>;
/**
* Данные пользователя
*/
user?: Record<string, unknown>;
/**
* Данные приложения
*/
application?: Record<string, unknown>;
}
/**
* Интерфейс для метаданных запроса.
* Содержит информацию об устройстве и окружении
*/
export interface IAlisaRequestMeta {
/** Язык в POSIX-формате (макс. 64 символа) */
locale: string;
/** Часовой пояс (макс. 64 символа) */
timezone: string;
/** ID устройства и приложения (макс. 1024 символа) */
client_id: string;
/**
* Доступные интерфейсы устройства
*/
interfaces: {
/** Поддержка экрана и браузера */
screen?: object;
/** Поддержка платежей */
payments?: object | null;
/** Поддержка связки аккаунтов */
account_linking: object | null;
};
}
/**
* Интерфейс для данных запроса.
* Содержит информацию о сообщении пользователя
*/
export interface IAlisaRequest {
/**
* Обработанный текст запроса
* Очищен от знаков препинания
* Числа преобразованы в числовой формат
*/
command: string;
/**
* Исходный текст запроса
* Максимум 1024 символа
*/
original_utterance: string;
/**
* Тип ввода
* - SimpleUtterance: голосовой ввод
* - ButtonPressed: нажатие кнопки
*/
type: 'SimpleUtterance' | 'ButtonPressed';
/**
* Характеристики реплики
*/
markup?: {
/**
* Признак криминального подтекста
* true: содержит угрозы, самоубийство и т.д.
*/
dangerous_context?: boolean;
};
/**
* Данные с нажатой кнопки
* Максимум 4096 байт
*/
payload?: Record<string, unknown> | string;
/**
* Результаты анализа текста
* Содержит:
* - tokens: массив слов из фразы
* - entities: найденные именованные сущности
* - intents: распознанные намерения
*
* @example
* ```ts
* nlu: {
* tokens: ["завтра", "в", "15", "часов"],
* entities: [{
* type: "YANDEX.DATETIME",
* value: { day: 1, day_is_relative: true, hour: 15 }
* }],
* intents: {
* "YANDEX.CONFIRM": { slots: [] }
* }
* }
* ```
*/
nlu?: IAlisaNlu;
}
/**
* Интерфейс для webhook-запроса.
* Полный формат входящего запроса от Алисы
*/
export interface IAlisaWebhookRequest {
/** Метаданные устройства */
meta: IAlisaRequestMeta;
/** Данные запроса пользователя */
request: IAlisaRequest;
/** Данные сессии */
session: IAlisaSession;
/** Событие связки аккаунтов */
account_linking_complete_event?: boolean;
/** Состояние приложения */
state?: IAlisaRequestState;
/** Версия протокола (текущая: 1.0) */
version: string;
}
/**
* Интерфейс для кнопки.
* Определяет внешний вид и поведение кнопки
*/
export interface IAlisaButton {
/**
* Текст кнопки
* Максимум 64 символа
* Отправляется как команда при нажатии
*/
title?: string;
/**
* Данные для обработчика
* Максимум 4096 байт
*/
payload?: Record<string, unknown> | string;
/**
* URL для перехода
* Максимум 1024 байта
*/
url?: string;
/**
* Скрывать после нажатия
* @defaultValue false
*/
hide?: boolean;
}
/**
* Интерфейс для кнопки на карточке.
* Определяет поведение при нажатии на изображение
*/
export interface IAlisaButtonCard {
/**
* Команда при нажатии
* Максимум 64 символа
*/
text?: string;
/**
* Данные для обработчика
* Максимум 4096 байт
*/
payload?: Record<string, unknown> | string;
/**
* URL для перехода
* Максимум 1024 байта
*/
url?: string;
}
/**
* Базовый интерфейс для изображения.
* Определяет общие свойства для всех типов карточек
*/
export interface IAlisaImage {
/**
* Тип карточки
* - BigImage: одно изображение
* - ItemsList: список изображений (1-5)
* - ImageGallery: галерея (1-7)
*/
type?: string;
/**
* ID изображения
* Только для BigImage
*/
image_id?: string;
/**
* Заголовок
* Максимум 128 символов
* Игнорируется для ItemsList
*/
title: string;
/**
* Описание
* Максимум 256 символов
* Игнорируется для ItemsList и ImageGallery
*/
description?: string;
/**
* Свойства при нажатии.
* Игнорируется для ItemsList и ImageGallery
*/
button?: IAlisaButtonCard;
}
/**
* Интерфейс для большого изображения
* Одно изображение с заголовком и описанием
*/
export interface IAlisaBigImage extends IAlisaImage {
/** Тип карточки */
type: 'BigImage';
}
/**
* Интерфейс для списка изображений
* От 1 до 5 изображений с заголовком
*/
export interface IAlisaItemsList {
/** Тип карточки */
type: 'ItemsList';
/**
* Заголовок списка
*/
header?: {
/** Текст заголовка (макс. 64 символа) */
text: string;
};
/**
* Изображения
* От 1 до 5 элементов
*/
items?: IAlisaImage[];
/**
* Кнопка под списком
*/
footer?: {
/** Текст кнопки (макс. 64 символа) */
text: string;
/** Свойства кнопки */
button?: IAlisaButtonCard;
};
}
/**
* Интерфейс для галереи изображений
* От 1 до 7 изображений
*/
export interface IAlisaImageGallery {
/** Тип карточки */
type: 'ImageGallery';
/**
* Изображения
* От 1 до 7 элементов
*/
items?: IAlisaImage[];
}
/**
* Интерфейс для ответа навыка.
* Определяет формат ответа пользователю
*/
export interface IAlisaResponse {
/**
* Текст ответа
* Максимум 1024 символа
* Используется если карточка не отображается
*/
text: string;
/**
* Текст для озвучивания
* Максимум 1024 символа
* Поддерживает SSML и звуки:
* - <speak>: корневой тег
* - <say-as>: произношение чисел, дат и т.д.
* - <audio>: вставка звуков
* - <voice>: выбор голоса
*
* @example
* ```ts
* // Простой текст
* tts: "Привет, как дела?"
*
* // С SSML
* tts: "<speak>Привет! <say-as interpret-as=\"date\">2024-03-15</say-as></speak>"
*
* // Со звуком
* tts: "<speak>Слушайте <audio src=\"sound.mp3\">звук</audio></speak>"
*
* // С голосом
* tts: "<speak><voice name=\"alena\">Привет!</voice></speak>"
* ```
*/
tts?: string;
/**
* Карточка с изображением
* Отображается вместо текста
* Поддерживает три типа:
* - BigImage: одно изображение с заголовком и описанием
* - ItemsList: список из 1-5 изображений
* - ImageGallery: галерея из 1-7 изображений
*
* @example
* ```ts
* // Одно изображение
* card: {
* type: "BigImage",
* image_id: "123456",
* title: "Заголовок",
* description: "Описание",
* button: {
* text: "Подробнее",
* url: "http://localhost"
* }
* }
*
* // Список изображений
* card: {
* type: "ItemsList",
* header: { text: "Список" },
* items: [
* { title: "Изображение 1", image_id: "1" },
* { title: "Изображение 2", image_id: "2" }
* ],
* footer: {
* text: "Ещё",
* button: { text: "Показать" }
* }
* }
*
* // Галерея
* card: {
* type: "ImageGallery",
* items: [
* { title: "Изображение 1", image_id: "1" },
* { title: "Изображение 2", image_id: "2" }
* ]
* }
* ```
*/
card?: IAlisaBigImage | IAlisaItemsList | IAlisaImageGallery;
/**
* Кнопки
* Отображаются после ответа
*/
buttons?: IAlisaButton[] | null;
/**
* Завершить сессию
* true: завершить диалог
* false: продолжить диалог
*/
end_session: boolean;
}
/**
* Интерфейс для webhook-ответа.
* Полный формат исходящего ответа для Алисы
*/
export interface IAlisaWebhookResponse {
/** Ответ пользователю */
response?: IAlisaResponse;
/** Данные сессии */
session_state?: IPlatformData;
/** Данные приложения */
application_state?: IPlatformData;
/** Данные пользователя */
user_state_update?: IPlatformData;
/** Версия протокола (текущая: 1.0) */
version: string;
/** Начать авторизацию */
start_account_linking?: object;
}