Skip to main content
The VK class is the primary entry point for the VK-IO library. It initializes and provides access to all core services including API methods, file uploads, and update handling.

​
Constructor

Creates a new VK instance with the specified configuration. 
import { VK } from 'vk-io';

const vk = new VK({
  token: 'your_access_token',
  apiVersion: '5.199'
});

​
Parameters

​
options
Partial<VKOptions> & { token: string }
required
Configuration options for the VK instance

​
Properties

​
api
API
Instance of the API class for making VK API method calls. Provides access to all VK API methods.See API Reference for detailed documentation.
​
upload
Upload
Instance of the Upload class for uploading files to VK (photos, videos, documents, etc.).See Upload Reference for detailed documentation.
​
updates
Updates
Instance of the Updates class for receiving and handling updates from VK (messages, wall posts, etc.).See Updates Reference for detailed documentation.
​
callbackService
CallbackService
Service for handling callbacks like captcha validation. Can be shared across multiple VK instances.

​
Examples

​
Basic Initialization

import { VK } from 'vk-io';

const vk = new VK({
  token: process.env.VK_TOKEN
});

// Make API calls
const user = await vk.api.users.get({ user_ids: [1] });
console.log(user);

​
With Custom Configuration

const vk = new VK({
  token: process.env.VK_TOKEN,
  apiVersion: '5.199',
  language: 'en',
  apiLimit: 3,
  apiMode: 'sequential',
  apiRetryLimit: 5
});

​
Using Parallel Mode for Performance

const vk = new VK({
  token: process.env.VK_TOKEN,
  apiMode: 'parallel',
  apiExecuteCount: 25
});

// Multiple requests will be automatically batched
await Promise.all([
  vk.api.users.get({ user_ids: [1] }),
  vk.api.users.get({ user_ids: [2] }),
  vk.api.users.get({ user_ids: [3] })
]);

​
With Webhook Configuration

const vk = new VK({
  token: process.env.VK_TOKEN,
  webhookSecret: process.env.VK_WEBHOOK_SECRET,
  webhookConfirmation: process.env.VK_WEBHOOK_CONFIRMATION
});

// Start receiving updates via webhook
vk.updates.on('message_new', async (context) => {
  await context.send('Hello!');
});

await vk.updates.startWebhook({
  port: 8080,
  path: '/webhook'
});

​
Multi-Instance Setup

import { VK, CallbackService } from 'vk-io';

// Shared callback service for multiple instances
const callbackService = new CallbackService();

const userVk = new VK({
  token: process.env.VK_USER_TOKEN,
  callbackService
});

const groupVk = new VK({
  token: process.env.VK_GROUP_TOKEN,
  callbackService
});

// Both instances share the same captcha handler
callbackService.onCaptcha(async ({ src, send }) => {
  const key = await solveCaptcha(src);
  await send(key);
});

​
Best Practices

Token Security: Never hardcode tokens in your source code. Use environment variables or secure configuration management.
Rate Limits: Respect VK’s rate limits. User tokens typically allow 3 requests/second, while service tokens may allow more. Adjust apiLimit accordingly.
API Mode Selection:
  • Use sequential for simple bots and reliable request ordering
  • Use parallel for high-performance applications with many requests
  • Use parallel_selected to optimize specific methods while keeping others sequential

Build docs developers (and LLMs) love

Get started for freeTalk to us