Class MarusiaRequest

Класс для взаимодействия с API голосового помощника Маруся Расширяет функционал VkRequest для работы со специфичными методами Маруси

See

https://dev.vk.ru/ru/marusia/api

Example

import { MarusiaRequest } from 'umbot/plugins';

// Создание экземпляра (appContext обязателен)
const marusia = new MarusiaRequest(appContext);
marusia.initToken('your-marusia-token');

// Загрузка изображения
async function uploadImage(imagePath: string) {
  // Получаем URL для загрузки
  const uploadLink = await marusia.marusiaGetPictureUploadLink();
  if (uploadLink) {
    // Загружаем изображение
    const upload = await marusia.upload(uploadLink.picture_upload_link, imagePath, 'photo');
    if (upload && upload.photo && upload.server && upload.hash) {
      // Сохраняем изображение (поля IVkUploadFile опциональны —
      // перед вызовом проверяем их наличие)
      const picture = await marusia.marusiaSavePicture(
        upload.photo,
        upload.server,
        upload.hash
      );
      return picture;
    }
  }
  return null;
}

// Загрузка аудио
async function uploadAudio(audioPath: string) {
  // Получаем URL для загрузки
  const uploadLink = await marusia.marusiaGetAudioUploadLink();
  if (uploadLink) {
    // Загружаем аудиофайл
    const upload = await marusia.upload(uploadLink.audio_upload_link, audioPath);
    if (upload) {
      // Сохраняем аудио
      const audio = await marusia.marusiaCreateAudio(upload);
      return audio;
    }
  }
  return null;
}

Hierarchy (View Summary)

VkRequest
- MarusiaRequest

Constructors

constructor

new MarusiaRequest(appContext: AppContext): MarusiaRequest
Создает экземпляр класса для работы с API Маруси
Parameters
- appContext: AppContext
  Контекст приложения (обязателен)
Returns MarusiaRequest
Overrides VkRequest.constructor
- Defined in plugins/platforms/API/MarusiaRequest.ts:70

Properties

`Protected`_appContext

_appContext: AppContext

Контекст приложения.

`Protected`_error

_error: string | object | null

Последняя ошибка (объект ответа API, Error или текст)

`Protected`_request

_request: Request

Экземпляр класса для выполнения HTTP-запросов

isAttachContent

isAttachContent: boolean

Флаг для прямой передачи содержимого файла По умолчанию: false

token

token: string | null

Токен доступа к VK API

Methods

`Protected`_log

_log(error?: string | Error): void
Пишет информацию об ошибках через AppContext.logError (структурированный логгер)
Parameters
- error: string | Error = ''
  Текст ошибки для логирования
Returns void
Overrides VkRequest._log
- Defined in plugins/platforms/API/MarusiaRequest.ts:275

call

call<T extends IVkApi<unknown>>(method: string): Promise<T | null>
Выполняет вызов метода VK API
Type Parameters
- T extends IVkApi<unknown>
Parameters
- method: string
  Название метода VK API
Returns Promise<T | null>
Результат выполнения метода или null при ошибке
Inherited from VkRequest.call
- Defined in plugins/platforms/API/VkRequest.ts:160

docsGetMessagesUploadServer

docsGetMessagesUploadServer(
peerId: TVkPeerId,
type: TVkDocType,
): Promise<IVkUploadServer | null>
Получает URL для загрузки документов в сообщения
Parameters
- peerId: TVkPeerId
  ID получателя сообщения
- type: TVkDocType
  Тип документа:
  
  'doc': обычный документ (PDF, ZIP и т.д.)
  
  'audio_message': голосовое сообщение
  
  'graffiti': граффити
Returns Promise<IVkUploadServer | null>
Данные для загрузки или null при ошибке
Example
```
// Загрузка обычного документа
const server = await vk.docsGetMessagesUploadServer(12345, 'doc');

// Загрузка голосового сообщения
const server = await vk.docsGetMessagesUploadServer(12345, 'audio_message');

// Загрузка граффити
const server = await vk.docsGetMessagesUploadServer(12345, 'graffiti');
```
Inherited from VkRequest.docsGetMessagesUploadServer
- Defined in plugins/platforms/API/VkRequest.ts:498

docsSave

docsSave(
    file: string,
    title: string,
    tags?: string | null,
): Promise<IVkDocSave | null>
Сохраняет загруженный документ
Parameters
- file: string
  Идентификатор документа
- title: string
  Название документа
- tags: string | null = null
  Теги документа
Returns Promise<IVkDocSave | null>
Информация о сохраненном документе или null при ошибке
Inherited from VkRequest.docsSave
- Defined in plugins/platforms/API/VkRequest.ts:516

initToken

initToken(token: string): void
Инициализирует токен доступа к VK API
Parameters
- token: string
  Токен доступа к VK API
Returns void
Inherited from VkRequest.initToken
- Defined in plugins/platforms/API/VkRequest.ts:151

marusiaCreateAudio

marusiaCreateAudio(audio_meta: object): Promise<IMarusiaApiCreateAudio | null>
Сохраняет загруженный аудиофайл в Марусе
Parameters
- audio_meta: object
  Метаданные аудиофайла после загрузки
Returns Promise<IMarusiaApiCreateAudio | null>
Результат сохранения или null при ошибке
Remarks
После успешного сохранения аудиофайл становится доступным в навыке и может быть использован в голосовых ответах.
Example
```
// Полный процесс загрузки и сохранения аудио
const uploadLink = await marusia.marusiaGetAudioUploadLink();
if (uploadLink) {
  const upload = await marusia.upload(uploadLink.audio_upload_link, 'audio.mp3');
  if (upload) {
    const audio = await marusia.marusiaCreateAudio(upload);
    if (audio) {
      console.log('ID аудио:', audio.id);
      console.log('URL аудио:', audio.url);
    }
  }
}
```
- Defined in plugins/platforms/API/MarusiaRequest.ts:251

marusiaDeleteAudio

marusiaDeleteAudio(id: string): Promise<IMarusiaApiRemove | null>
Удаляет загруженный аудиофайл из Маруси
Parameters
- id: string
  Идентификатор загруженного аудиофайла
Returns Promise<IMarusiaApiRemove | null>
Результат удаления или null при ошибке
- Defined in plugins/platforms/API/MarusiaRequest.ts:264

marusiaDeletePicture

marusiaDeletePicture(id: string): Promise<IMarusiaApiRemove | null>
Удаляет загруженное изображение из Маруси
Parameters
- id: string
  Идентификатор загруженного изображения
Returns Promise<IMarusiaApiRemove | null>
Результат удаления или null при ошибке
- Defined in plugins/platforms/API/MarusiaRequest.ts:158

marusiaGetAudioUploadLink

marusiaGetAudioUploadLink(): Promise<IMarusiaApiAudioUpdateLink | null>
Запрашивает URL для загрузки аудиофайла на сервера Маруси

Returns Promise<IMarusiaApiAudioUpdateLink | null>
Данные для загрузки аудио или null при ошибке
Remarks
Поддерживаемые форматы аудио:
- MP3
- Максимальный размер: 10MB
- Максимальная длительность: 5 минут
- Рекомендуемый битрейт: 128 kbps
Example
```
// Получение URL для загрузки
const uploadLink = await marusia.marusiaGetAudioUploadLink();
if (uploadLink) {
  // Загрузка аудио
  const upload = await marusia.upload(uploadLink.audio_upload_link, 'audio.mp3');
  if (upload) {
    console.log('Аудио загружено:', upload);
  }
}
```
- Defined in plugins/platforms/API/MarusiaRequest.ts:221

marusiaGetPictures

marusiaGetPictures(): Promise<unknown>
Получает список всех изображений из навыка

Returns Promise<unknown>
Ответ API Маруси (структура items аналогична Алисе) или null при ошибке
Remarks
Метод возвращает информацию о всех изображениях, загруженных в навык:
- id: уникальный идентификатор изображения
- url: URL для доступа к изображению
- preview_url: URL превью изображения
- created: дата создания (Unix timestamp)
Example
```
// Получение списка изображений. Метод возвращает Promise<unknown> —
// структура items аналогична Алисе, поэтому приводим тип явно.
const pictures = await marusia.marusiaGetPictures();
if (pictures) {
  const pics = pictures as { items: IMarusiaImage[] };
  pics.items.forEach(picture => {
    console.log('ID:', picture.id);
    console.log('URL:', picture.url);
    console.log('Превью:', picture.preview_url);
  });
}
```
- Defined in plugins/platforms/API/MarusiaRequest.ts:192

marusiaGetPictureUploadLink

marusiaGetPictureUploadLink(): Promise<IMarusiaApiPictureUpdateLink | null>
Запрашивает URL для загрузки изображения на сервера Маруси

Returns Promise<IMarusiaApiPictureUpdateLink | null>
Данные для загрузки изображения или null при ошибке
Remarks
Поддерживаемые форматы изображений:
- JPEG, JPG, PNG
- Максимальный размер: 5MB
- Рекомендуемое разрешение: 800x800 пикселей
Example
```
// Получение URL для загрузки
const uploadLink = await marusia.marusiaGetPictureUploadLink();
if (uploadLink) {
  // Загрузка изображения
  const upload = await marusia.upload(uploadLink.picture_upload_link, 'image.jpg', 'photo');
  if (upload) {
    console.log('Изображение загружено:', upload);
  }
}
```
- Defined in plugins/platforms/API/MarusiaRequest.ts:103

marusiaSavePicture

marusiaSavePicture(
    photo: string,
    server: string,
    hash: string,
): Promise<IMarusiaApiSavePicture | null>
Сохраняет загруженное изображение в Марусе
Parameters
- photo: string
  Идентификатор загруженного изображения
- server: string
  Идентификатор сервера загрузки
- hash: string
  Хэш-сумма для проверки изображения
Returns Promise<IMarusiaApiSavePicture | null>
Результат сохранения или null при ошибке
Remarks
После успешного сохранения изображение становится доступным в навыке и может быть использовано в карточках и других элементах интерфейса.
Example
```
// Полный процесс загрузки и сохранения изображения.
// Поля photo/server/hash у IVkUploadFile опциональны —
// после проверки upload сохраняем их в константы-строки
const uploadLink = await marusia.marusiaGetPictureUploadLink();
if (uploadLink) {
  const upload = await marusia.upload(uploadLink.picture_upload_link, 'image.jpg', 'photo');
  if (upload?.photo && upload?.server && upload?.hash) {
    const photo: string = upload.photo;
    const server: string = upload.server;
    const hash: string = upload.hash;
    const picture = await marusia.marusiaSavePicture(photo, server, hash);
    if (picture) {
      console.log('ID изображения:', picture.id);
    }
  }
}
```
- Defined in plugins/platforms/API/MarusiaRequest.ts:139

messagesSend

messagesSend(
    peerId: TVkPeerId,
    message: string,
    params?: IVkParams | null,
): Promise<IVKSendMessage | null>
Отправляет сообщение пользователю или в чат
Parameters
- peerId: TVkPeerId
  Идентификатор получателя:
  
  ID пользователя — передавайте числом (например, 12345)
  
  Короткое имя (screen_name) — передавайте строкой (например, 'durov'); строка уходит в параметр domain, а не peer_id
  
  ID чата: 2000000000 + chat_id — числом (например, для чата 1: 2000000001)
  
  ID сообщества: -ID сообщества — числом (например, -123456789)
- message: string
  Текст сообщения
- params: IVkParams | null = null
  Дополнительные параметры:
  
  random_id: уникальный ID для избежания повторов
  
  attachments: массив вложений "<owner_id>_<media_id>" (объединяются через запятую в параметр attachment) Примеры:
  
  Фото: "photo123456_789"
  
  Документ: "doc123456_789"
  
  Аудио: "audio123456_789"
  
  Видео: "video123456_789"
  
  keyboard: клавиатура в JSON формате или строкой
  
  template: шаблон карусели в JSON формате или строкой
Returns Promise<IVKSendMessage | null>
Информация об отправленном сообщении или null при ошибке
Example
```
// Простое сообщение
await vk.messagesSend(12345, 'Привет!');

// Сообщение с вложениями
await vk.messagesSend(12345, 'Фото:', {
  attachments: ['photo123_456', 'doc123_456']
});

// Сообщение с клавиатурой
const keyboard = {
  one_time: true,
  buttons: [[{
    action: {
      type: 'text',
      label: 'Кнопка',
      payload: '{"button": 1}'
    },
    color: 'primary'
  }]]
};
await vk.messagesSend(12345, 'Выберите:', {
  keyboard: JSON.stringify(keyboard)
});

// Сообщение с каруселью
const template = {
  type: 'carousel',
  elements: [{
    title: 'Заголовок',
    description: 'Описание',
    photo_id: '-123456_789',
    buttons: [{
      action: {
        type: 'text',
        label: 'Кнопка',
        payload: '{"button": 1}'
      }
    }]
  }]
};
await vk.messagesSend(12345, '', {
  template: JSON.stringify(template)
});
```
Inherited from VkRequest.messagesSend
- Defined in plugins/platforms/API/VkRequest.ts:348

photosGetMessagesUploadServer

photosGetMessagesUploadServer(
peerId: TVkPeerId,
): Promise<IVkUploadServer | null>
Получает URL для загрузки фотографий в сообщения
Parameters
- peerId: TVkPeerId
  ID получателя сообщения
Returns Promise<IVkUploadServer | null>
Данные для загрузки или null при ошибке
Inherited from VkRequest.photosGetMessagesUploadServer
- Defined in plugins/platforms/API/VkRequest.ts:450

photosSaveMessagesPhoto

photosSaveMessagesPhoto(
    photo: string,
    server: string,
    hash: string,
): Promise<IVkPhotosSave[] | null>
Сохраняет загруженную фотографию в сообщениях
Parameters
- photo: string
  Идентификатор фотографии
- server: string
  Идентификатор сервера
- hash: string
  Хэш-сумма фотографии
Returns Promise<IVkPhotosSave[] | null>
Информация о сохраненной фотографии или null при ошибке
Inherited from VkRequest.photosSaveMessagesPhoto
- Defined in plugins/platforms/API/VkRequest.ts:462

sendMessageEvent

sendMessageEvent(
    userId: TVkPeerId,
    eventId: string,
    eventData?: {
        Intent?: string;
        link?: string;
        text?: string;
        title?: string;
        type: "show_snackbar" | "open_link" | "open_modal";
    },
    peerId?: TVkPeerId,
): Promise<IVKSendMessage | null>
Подтверждение получения callback-события от кнопки. Обязательный метод для обработки message_event в VK Bot API. Без этого вызова VK показывает пользователю "Бот недоступен" при нажатии callback-кнопки.
Parameters
- userId: TVkPeerId
  ID пользователя
- eventId: string
  ID события из message_event
- OptionaleventData: {
      Intent?: string;
      link?: string;
      text?: string;
      title?: string;
      type: "show_snackbar" | "open_link" | "open_modal";
  }
  Данные события (опционально): show_snackbar, open_link или open_modal
- OptionalpeerId: TVkPeerId
  ID диалога из message_event. Для обратной совместимости используется userId
Returns Promise<IVKSendMessage | null>
Результат выполнения или null при ошибке
Example
```
// Простое подтверждение
await vkApi.sendMessageEvent(userId, eventId);

// С показом всплывающего уведомления
await vkApi.sendMessageEvent(userId, eventId, {
    type: 'show_snackbar',
    text: 'Действие выполнено!'
});
```
Inherited from VkRequest.sendMessageEvent
- Defined in plugins/platforms/API/VkRequest.ts:554

upload

upload(
    url: string,
    file: string,
    fieldName?: "photo" | "file",
): Promise<IVkUploadFile | null>
Загружает файл на сервера ВКонтакте
Parameters
- url: string
  URL для загрузки файла
- file: string
  Путь к файлу или его содержимое
- fieldName: "photo" | "file" = 'file'
  Имя multipart-поля с файлом. Сервер загрузки фото (photos.getMessagesUploadServer) принимает файл только в поле photo — с полем file он возвращает пустой photo: "[]", и сохранение фото падает. Документы и голосовые (docs.getMessagesUploadServer) ждут поле file (значение по умолчанию).
Returns Promise<IVkUploadFile | null>
Информация о загруженном файле или null при ошибке
Remarks
Для фотографий возвращает:
- photo: строка, содержащая информацию о фото
- server: строка, идентификатор сервера
- hash: строка, хеш загруженного файла
Для документов возвращает:
- file: строка, информация о загруженном файле
Example
```
// Загрузка фото.
// Поля photo/server/hash у IVkUploadFile опциональны —
// перед вызовом photosSaveMessagesPhoto проверяем их наличие
const server = await vk.photosGetMessagesUploadServer(12345);
if (server) {
  const upload = await vk.upload(server.upload_url, 'photo.jpg', 'photo');
  if (upload?.photo && upload?.server && upload?.hash) {
    const photo = await vk.photosSaveMessagesPhoto(
      upload.photo,
      upload.server,
      upload.hash
    ); // IVkPhotosSave[] — берём первый элемент
  }
}

// Загрузка документа
const server = await vk.docsGetMessagesUploadServer(12345, 'doc');
if (server) {
  const upload = await vk.upload(server.upload_url, 'document.pdf');
  if (upload) {
    const doc = await vk.docsSave(
      upload.file,
      'Документ',
      'тег1,тег2'
    );
  }
}
```
Inherited from VkRequest.upload
- Defined in plugins/platforms/API/VkRequest.ts:247

usersGet

usersGet(
userId: string[] | TVkPeerId,
params?: IVkParamsUsersGet | null,
): Promise<IVkUsersGet[] | null>
Получает информацию о пользователе или списке пользователей
Parameters
- userId: string[] | TVkPeerId
  ID пользователя, список ID через запятую или массив ID
- params: IVkParamsUsersGet | null = null
  Дополнительные параметры запроса
Returns Promise<IVkUsersGet[] | null>
Массив пользователей или null при ошибке
Inherited from VkRequest.usersGet
- Defined in plugins/platforms/API/VkRequest.ts:427

Class MarusiaRequest

See

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns MarusiaRequest

Properties

Protected_appContext

Protected_error

Protected_request

isAttachContent

token

Methods

Protected_log

Parameters

Returns void

call

Type Parameters

Parameters

Returns Promise<T | null>

docsGetMessagesUploadServer

Parameters

Returns Promise<IVkUploadServer | null>

Example

docsSave

Parameters

Returns Promise<IVkDocSave | null>

initToken

Parameters

Returns void

marusiaCreateAudio

Parameters

Returns Promise<IMarusiaApiCreateAudio | null>

Remarks

Example

marusiaDeleteAudio

Parameters

Returns Promise<IMarusiaApiRemove | null>

marusiaDeletePicture

Parameters

Returns Promise<IMarusiaApiRemove | null>

marusiaGetAudioUploadLink

Returns Promise<IMarusiaApiAudioUpdateLink | null>

Remarks

Example

marusiaGetPictures

Returns Promise<unknown>

Remarks

Example

marusiaGetPictureUploadLink

Returns Promise<IMarusiaApiPictureUpdateLink | null>

Remarks

Example

marusiaSavePicture

Parameters

Returns Promise<IMarusiaApiSavePicture | null>

Remarks

Example

messagesSend

Parameters

Returns Promise<IVKSendMessage | null>

Example

photosGetMessagesUploadServer

Parameters

Returns Promise<IVkUploadServer | null>

photosSaveMessagesPhoto

Parameters

Returns Promise<IVkPhotosSave[] | null>

sendMessageEvent

Parameters

Returns Promise<IVKSendMessage | null>

Example

upload

Parameters

`Protected`_appContext

`Protected`_error

`Protected`_request

`Protected`_log