Skip to main content

​
Installation

Get started with VK-IO by installing it in your Node.js project. VK-IO supports all modern package managers and comes with full TypeScript support out of the box.

​
Requirements

Node.js 12.20.0 or newer is requiredVK-IO requires a modern Node.js runtime with ESM support. Check your Node.js version with node --version.
Before installing VK-IO, ensure you have:
  • Node.js 12.20.0 or higher
  • A VK API token (group token or user token)
  • A package manager: npm, yarn, or pnpm

​
Installing VK-IO

Choose your preferred package manager to install VK-IO: 
npm install vk-io

​
Getting Your VK API Token

To use VK-IO, you need an API token from VK. The type of token depends on your use case:

​
Community (Group) Token

For building bots and automated community tools:
1

Create or Select a Community

Go to vk.com/groups and create a new community or select an existing one
2

Access Settings

Navigate to Manage → Settings → API usage
3

Create Access Token

Click Create token and select the required permissions:
  • For bots: messages (to send and receive messages)
  • For wall posts: wall (to create and manage wall posts)
  • For additional features: select other permissions as needed
4

Enable Messages API (for bots)

If building a bot, enable Long Poll API under Messages → Bot settings
5

Save Your Token

Copy the generated token and store it securely (never commit it to version control)

​
User Token

For applications that need user-level access:
User tokens provide access to your personal account. Use them carefully and never share them. For most bot applications, use a Community token instead.
You can obtain a user token through:
  • Implicit Flow - Using the @vk-io/authorization package
  • VK Admin Panel - Through the VK application settings
For detailed authorization flows, see the Authorization Guide.

​
Storing Your Token Securely

Never hardcode your token in your source code. Use environment variables instead:
1

Create a .env file

Create a .env file in your project root:
TOKEN=your_vk_token_here
2

Add .env to .gitignore

Ensure .env is in your .gitignore file:
.gitignore
.env
node_modules/
3

Install dotenv (optional)

If using CommonJS, install dotenv to load environment variables:
npm install dotenv
Then load it at the top of your main file:
require('dotenv').config();
For production deployments, use your hosting platform’s environment variable configuration instead of .env files.

​
Module System Support

VK-IO supports both ESM (ES Modules) and CommonJS: 
import { VK } from 'vk-io';

const vk = new VK({
  token: process.env.TOKEN
});
VK-IO is built with native ESM support. For the best experience, use ES Modules in your project by adding "type": "module" to your package.json.

​
TypeScript Support

VK-IO is written in TypeScript and includes full type definitions: 
import { VK, MessageContext } from 'vk-io';

const vk = new VK({
  token: process.env.TOKEN as string
});

vk.updates.on('message_new', async (context: MessageContext) => {
  // Full TypeScript autocomplete and type checking
  await context.send('Hello!');
});

vk.updates.start();
No additional @types packages are needed - everything is included.

​
Installing Ecosystem Packages

Enhance VK-IO with official ecosystem packages: 
# Command matching
npm install @vk-io/hear

# Session management
npm install @vk-io/session

# Conversation scenes
npm install @vk-io/scenes

# Real-time streaming
npm install @vk-io/streaming

# User authorization
npm install @vk-io/authorization
See the Ecosystem section in the documentation for detailed information about each package.

​
Verifying Your Installation

Test your installation with a simple API call: 
import { VK } from 'vk-io';

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

async function test() {
  const response = await vk.api.users.get({
    user_ids: [1]
  });
  
  console.log(response);
}

test().catch(console.error);
Run the script: 
node test.js
If you see user information in the console, you’re ready to build with VK-IO!

​
Next Steps

Quick Start

Build your first VK bot with a working example

API Documentation

Explore the complete API reference

Updates & Webhooks

Learn how to receive and handle VK events

Examples

Discover real-world implementation examples

Build docs developers (and LLMs) love

Get started for freeTalk to us