Skip to main content
VK-IO v4 is the next major update with significant improvements to type safety, immutability, and API design. This guide will help you migrate from v3 to v4.

​
Overview

Type System

Major improvements to TypeScript typings throughout the library

Immutability

Library now follows immutable principles for better predictability

Independence

Components no longer depend on the main VK instance

Simplification

Removed redundant components in favor of simple functions
VK-IO v4 requires Node.js 12.20.0 or higher. Older versions are no longer supported.

​
Breaking Changes

​
Import Changes

1

Update default import

The default export has been removed. Use named imports instead:
- import VK from 'vk-io';
+ import { VK } from 'vk-io';

​
VK Class Changes

The following getters and setters have been removed:
  • vk.token (getter/setter) - removed
  • vk.captchaHandler (setter) - use vk.callbackService.onCaptcha() method instead
  • vk.twoFactorHandler (setter) - use vk.callbackService.onTwoFactor() method instead
- vk.captchaHandler = (payload, retry) => { ... };
+ vk.callbackService.onCaptcha((payload, retry) => { ... });
  • vk.setOptions() - removed
  • Configuration must be set during instantiation
Several built-in modules have been extracted into separate packages:
OldNew Package
vk.auth@vk-io/authorization
vk.streaming@vk-io/streaming
- vk.auth.implicitFlow();
+ import { ImplicitFlow } from '@vk-io/authorization';
+ const auth = new ImplicitFlow({ ... });

​
API Changes

const vk = new VK({
    token: 'YOUR_TOKEN',
-   apiAttempts: 3,
+   apiRetryLimit: 3,
});
  • Automatic account verification removed - use @vk-io/authorization package with AccountVerification class
  • Automatic random_id in messages.send() removed - use getRandomId() function:
import { getRandomId } from 'vk-io';

await api.messages.send({
    peer_id: 1234,
    random_id: getRandomId(),
    text: 'Hello!'
});
  • vk.api.API_VERSION getter removed
  • APIErrorCode enum now auto-generated from VK API schema
  • Schema objects now exported in their own namespaces: Params, Objects, and Responses

​
Snippets & Utilities

vk.snippets.resolveResource() has been removed. Use the standalone resolveResource() function:
- const result = await vk.snippets.resolveResource('https://vk.com/durov');
+ import { resolveResource } from 'vk-io';
+ const result = await resolveResource({
+     api,
+     resource: 'https://vk.com/durov'
+ });
The vk.collect module has been split into smaller classes and functions:Chain - Use the Chain class:
import { Chain } from 'vk-io';

const chain = new Chain({ api });
Executes - Use the executes() function:
import { executes } from 'vk-io';

const result = await executes({
    api,
    method: 'users.get',
    queue: [
        { user_id: 1 },
        { user_id: 2 },
        { user_id: 3 }
    ]
});
Collect Iterator - Use createCollectIterator() function:
import { createCollectIterator } from 'vk-io';

const iterator = createCollectIterator({
    api,
    method: 'messages.getConversations',
    params: {
        extended: 1
    },
    countPerRequest: 200
});

for await (const chunk of iterator) {
    console.log(chunk.items);
    console.log(chunk.profiles);
    console.log(chunk.groups);
}

​
Context Changes

Return values:
  • context.send() now returns a MessageContext instance
  • context.replyMessage now returns MessageContext instead of MessageReply
  • context.forwards now returns an array of MessageContext instead of MessageForward
Method parameters changed: Methods like sendPhotos(), sendDocuments(), sendAudioMessage() now accept objects:
- context.sendPhotos('./cat.png');
+ context.sendPhotos({
+     value: './cat.png'
+ });
Removed methods:
  • context.getInviteLink()
  • context.markAsImportant()
  • context.renameChat()
  • context.newChatPhoto()
  • context.deleteChatPhoto()
  • context.inviteUser()
  • context.kickUser()
  • context.pinMessage()
  • context.unpinMessage()
  • context.editMessageText()
  • context.sendSticker() - use context.send({ sticker_id: 123 }) instead
Several context classes and properties have been renamed for consistency:
Old NameNew Name
CommentActionContextCommentContext
UserOnlineContextFriendActivityContext
ReadMessagesContextMessagesReadContext
MessageAllowContextMessageSubscriptionContext
RemovedMessagesContextDialogMessagesContext
All contexts now use undefined instead of null for better destructuring support:
updates.on('message_new', async (context) => {
    const { text = 'default text' } = context;

    if (text === 'default text') {
        return context.send('You wrote nothing');
    }

    await context.send('Hello!');
});

​
Updates Changes

The updates.hear() method and updates.setHearFallbackHandler() have been removed.Use the @vk-io/hear package instead:
import { HearManager } from '@vk-io/hear';

const hearManager = new HearManager();

updates.on('message', hearManager.middleware);

hearManager.hear('/start', async (context) => {
    await context.send('Welcome!');
});
Now using official VK event names:
- updates.on('message', ...);
+ updates.on('message_new', ...);
The second argument for updates.startWebhook() has been removed. Use the next property instead:
- updates.startWebhook({ port: 8080 }, (req, res) => { ... });
+ updates.startWebhook({
+     port: 8080,
+     next: (req, res) => { ... }
+ });
  • Polling version updated to 10
  • Option renamed: pollingAttempts → pollingRetryLimit
const { updates } = vk;
updates.start({
-   pollingAttempts: 3
+   pollingRetryLimit: 3
});

​
Upload Changes

The source parameter format has changed. It now accepts two interfaces:Single file:
upload.messagePhoto({
    source: {
        value: 'https://picsum.photos/200/300/?image=1',
        filename: 'image.jpeg',
        contentType: 'image/jpeg',
        contentLength: 12345 // Optional but recommended for streams
    }
});
Multiple files:
upload.messagePhoto({
    source: {
        uploadUrl: '...', // Optional
        timeout: 30000,   // Optional
        values: [{
            value: './photo1.jpg'
        }, {
            value: './photo2.jpg'
        }]
    }
});
When using streams without size information, you must specify contentLength, especially for upload.video().
  • upload.storiesPhoto() and upload.storiesVideo() now return StoryAttachment
  • upload.graffiti() removed - use upload.documentGraffiti() or upload.messageGraffiti() instead

​
Keyboard Changes

- Keyboard.DEFAULT_COLOR
+ Keyboard.SECONDARY_COLOR

​
Attachment Changes

Attachment constructors now require options objects:
interface IAttachmentOptions<P, Type extends string = string> {
    api: API;
    type: Type;
    payload: Partial<ISharedAttachmentPayload> & P;
}
  • document.typeName getter removed

​
Export Changes

Many lowercase exports have been replaced with PascalCase enums: 
- import { attachmentTypes } from 'vk-io';
+ import { AttachmentType } from 'vk-io';

- import { apiErrors } from 'vk-io';
+ import { APIErrorCode } from 'vk-io';

- import { captchaTypes } from 'vk-io';
+ import { CaptchaType } from 'vk-io';

- import { messageSources } from 'vk-io';
+ import { MessageSource } from 'vk-io';

- import { resourceTypes } from 'vk-io';
+ import { ResourceType } from 'vk-io';

- import { updatesSources } from 'vk-io';
+ import { UpdateSource } from 'vk-io';
Full list of renamed exports:
  • attachmentTypes → AttachmentType
  • defaultExtensions → DefaultExtension
  • defaultContentTypes → DefaultContentType
  • captchaTypes → CaptchaType
  • messageSources → MessageSource
  • resourceTypes → ResourceType
  • updatesSources → UpdateSource
  • apiErrors → APIErrorCode
  • uploadErrors → UploadErrorCode
  • updatesErrors → UpdatesErrorCode
  • snippetsErrors → ResourceErrorCode
  • sharedErrors → SharedErrorCode

​
Migration Checklist

1

Update Node.js version

Ensure you’re running Node.js 12.20.0 or higher
2

Update imports

Change default imports to named imports and update enum imports
3

Update configuration

Rename apiAttempts to apiRetryLimit and pollingAttempts to pollingRetryLimit
4

Migrate modules

Install separate packages for auth and streaming if needed
5

Update utility calls

Replace vk.snippets.* and vk.collect.* with standalone functions
6

Update message sending

Add random_id manually using getRandomId() for messages.send()
7

Update context handlers

Check for renamed context classes and removed methods
8

Migrate hear handlers

Install and use @vk-io/hear package if using hear patterns
9

Update upload calls

Adjust source parameter format for upload methods
10

Test thoroughly

Run your application and fix any TypeScript errors

​
Need Help?

If you encounter issues during migration:

GitHub Issues

Report bugs or ask questions

Community Modules

Explore ecosystem packages

Build docs developers (and LLMs) love

Get started for freeTalk to us