npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

node-vk-bot-api

v3.5.0

Published

🤖 VK bot framework for Node.js, based on Bots Long Poll API and Callback API

Downloads

258

Readme

node-vk-bot-api node-vk-bot-api node-vk-bot-api

node-vk-bot-api

🤖 VK bot framework for Node.js, based on Bots Long Poll API and Callback API.

Install

$ npm i node-vk-bot-api -S

Usage

const VkBot = require('node-vk-bot-api');

const bot = new VkBot(process.env.TOKEN);

bot.command('/start', (ctx) => {
  ctx.reply('Hello!');
});

bot.startPolling();

Webhooks

const express = require('express');
const bodyParser = require('body-parser');
const VkBot = require('node-vk-bot-api');

const app = express();
const bot = new VkBot({
  token: process.env.TOKEN,
  confirmation: process.env.CONFIRMATION,
});

bot.on((ctx) => {
  ctx.reply('Hello!');
});

app.use(bodyParser.json());

app.post('/', bot.webhookCallback);

app.listen(process.env.PORT);

Examples

There's a few simple examples.

Community support

Any questions you can ask in the telegram chat. [russian/english]

Tests

$ npm test

API

const api = require('node-vk-bot-api/lib/api');

api('users.get', {
  user_ids: 1,
  access_token: process.env.TOKEN,
}); // => Promise

Error handling

// bad
bot.command('/start', (ctx) => {
  ctx.reply('Hello, world!');
});

// not bad
bot.command('/start', async (ctx) => {
  try {
    await ctx.reply('Hello, world!');
  } catch (e) {
    console.error(e);
  }
});

// good
bot.use(async (ctx, next) => {
  try {
    await next();
  } catch (e) {
    console.error(e);
  }
});

bot.command('/start', async (ctx) => {
  await ctx.reply('Hello, world!');
});
// bad
bot.startPolling();

// good
bot.startPolling((err) => {
  if (err) {
    console.error(err);
  }
});

Methods

constructor(settings)

Create bot.

// Simple usage
const bot = new VkBot(process.env.TOKEN);

// Advanced usage
const bot = new VkBot({
  token: process.env.TOKEN,
  group_id: process.env.GROUP_ID,
  execute_timeout: process.env.EXECUTE_TIMEOUT, // in ms   (50 by default)
  polling_timeout: process.env.POLLING_TIMEOUT, // in secs (25 by default)

  // webhooks options only
  secret: process.env.SECRET,                   // secret key (optional)
  confirmation: process.env.CONFIRMATION,       // confirmation string
});

.execute(method, settings)

Execute request to the VK API.

const response = await bot.execute('users.get', {
  user_ids: 1,
});

.use(middleware)

Add simple middleware.

bot.use((ctx, next) => {
  ctx.message.timestamp = new Date().getTime();

  return next();
});

.command(triggers, ...middlewares)

Add middlewares with triggers for message_new event.

bot.command('start', (ctx) => {
  ctx.reply('Hello!');
});

.event(triggers, ...middlewares)

Add middlewares with triggers for selected events.

bot.event('message_edit', (ctx) => {
  ctx.reply('Your message was editted');
});

.on(...middlewares)

Add reserved middlewares without triggers.

bot.on((ctx) => {
  ctx.reply('No commands for you.');
});

.sendMessage(userId, message, attachment, keyboard, sticker)

Send message to user.

// Simple usage
bot.sendMessage(145003487, 'Hello!', 'photo1_1');

// Multiple recipients
bot.sendMessage([145003487, 145003488], 'Hello!', 'photo1_1');

// Advanced usage
bot.sendMessage(145003487, {
  message: 'Hello!',
  lat: 59.939095,
  lng: 30.315868,
});

.startPolling([callback])

Start polling with optional callback.

bot.startPolling((err) => {
  if (err) {
    console.error(err);
  }
});

.webhookCallback(...args)

Get webhook callback.

// express
bot.webhookCallback(req, res, next);

// koa
bot.webhookCallback(ctx, next);

.stop()

Stop the bot. Disables any receiving updates from Long Poll or Callback APIs.

bot.stop();

.start()

Start the bot after it was turned off via .stop() method. When you are using Long Poll API, you need to call .startPolling([callback]) again.

bot.start();

Context Structure

  • message - received message (pure object from VK API)
    • type - received type event (e.g. message_new)
    • ... other fields from VK API
  • eventId - callback's eventId
  • groupId - callback's groupId
  • match? - regexp match of your trigger
  • clientInfo? - received client info (pure object from VK API)
  • bot - instance of bot, you can call any methods via this instance

Context Methods

.reply(message, attachment, markup, sticker)

Helper method for reply to the current user.

bot.command('start', (ctx) => {
  ctx.reply('Hello!');
});

Markup

Keyboards

  • Markup.keyboard(buttons, options): Create keyboard
  • Markup.button(label, color, payload): Create custom button
  • Markup.oneTime(): Set oneTime to keyboard

Simple usage

ctx.reply('Select your sport', null, Markup
  .keyboard([
    'Football',
    'Basketball',
  ])
  .oneTime(),
);

Advanced usage

// custom buttons
ctx.reply('Hey!', null, Markup
  .keyboard([
    Markup.button({
      action: {
        type: 'open_link',
        link: 'https://google.com',
        label: 'Open Google',
        payload: JSON.stringify({
          url: 'https://google.com',
        }),
      },
      color: 'default',
    }),
  ]),
);

// default buttons
ctx.reply('How are you doing?', null, Markup
  .keyboard([
    [
      Markup.button('Normally', 'primary'),
    ],
    [
      Markup.button('Fine', 'positive'),
      Markup.button('Bad', 'negative'),
    ],
  ]),
);

.keyboard(buttons, options)

Create keyboard with optional settings.

/*

  Each string has maximum 2 columns.

  | one   | two   |
  | three | four  |
  | five  | six   |

 */

Markup.keyboard([
  'one',
  'two',
  'three',
  'four',
  'five',
  'six',
], { columns: 2 });
/*

  By default, columns count for each string is 4.

  | one | two | three |

 */

Markup.keyboard([
  'one',
  'two',
  'three',
]);

.button(label, color, payload)

Create custom button.

Markup.button('Start', 'positive', {
  foo: 'bar',
});

.oneTime()

Helper method for create one time keyboard.

Markup
  .keyboard(['Start', 'Help'])
  .oneTime();

.inline()

Helpers method for create inline keyboard.

Markup
  .keyboard(['Start', 'Help'])
  .inline();

Sessions

Store anything for current user in local (or redis) memory.

Usage

const VkBot = require('node-vk-bot-api');
const Session = require('node-vk-bot-api/lib/session');

const bot = new VkBot(process.env.TOKEN);
const session = new Session();

bot.use(session.middleware());

bot.on((ctx) => {
  ctx.session.counter = ctx.session.counter || 0;
  ctx.session.counter++;

  ctx.reply(`You wrote ${ctx.session.counter} messages.`);
});

bot.startPolling();

API

Options

  • key: Context property name (default: session)
  • getSessionKey: Getter for session key
Default getSessionKey(ctx)
const getSessionKey = (ctx) => {
  const userId = ctx.message.from_id || ctx.message.user_id;

  return `${userId}:${userId}`;
};

Stage

Scene manager.

const VkBot = require('node-vk-bot-api');
const Scene = require('node-vk-bot-api/lib/scene');
const Session = require('node-vk-bot-api/lib/session');
const Stage = require('node-vk-bot-api/lib/stage');

const bot = new VkBot(process.env.TOKEN);
const scene = new Scene('meet',
  (ctx) => {
    ctx.scene.next();
    ctx.reply('How old are you?');
  },
  (ctx) => {
    ctx.session.age = +ctx.message.text;

    ctx.scene.next();
    ctx.reply('What is your name?');
  },
  (ctx) => {
    ctx.session.name = ctx.message.text;

    ctx.scene.leave();
    ctx.reply(`Nice to meet you, ${ctx.session.name} (${ctx.session.age} years old)`);
  },
);
const session = new Session();
const stage = new Stage(scene);

bot.use(session.middleware());
bot.use(stage.middleware());

bot.command('/meet', (ctx) => {
  ctx.scene.enter('meet');
});

bot.startPolling();

API

Stage

  • constructor(...scenes): Register scenes

Scene

  • constructor(name, ...middlewares): Create scene
  • .command(triggers, ...middlewares): Create commands for scene

Context

ctx.scene.enter(name, [step]) // Enter in scene
ctx.scene.leave()             // Leave from scene
ctx.scene.next()              // Go to the next step in scene
ctx.scene.step                // Getter for step in scene
ctx.scene.step=               // Setter for step in scene

License

MIT.