node-vk-bot

README на русском

VK BOTS

• Create and control VK bots easily.
• Uses LongPoll or Callback API to get new messages

npm install --save node-vk-bot

If you are cloning this repository, remember to run npm install to install dependencies.

Example

const { Bot, Keyboard } = require('node-vk-bot')

const bot = new Bot({
  token: 'YOUR TOKEN',
  group_id: 123456
}).start()

bot.get(/Hi|Hello|Hey/i, (message, exec, reply) => {
  const keyboard = new Keyboard().addButton('Hi!')
  const options =  { forward_messages: message.id, keyboard }

  reply('Hello!', options)
})

More examples (how to use webhooks, upload pictures, ...)

Bots created with this library

if you want your bot to be in this list, just make a pull request

• GitHub Events - Notifies you about new issues, commits, etc. in private messages by @vitalyavolyn

Table of contents

• Getting Started
• Bot
  • Methods
    • start
    • get
    • getPayload
    • send
    • uploadPhoto
    • api
    • processUpdate
    • stop
  • Events
    • update
    • voice
    • sticker
    • payload
    • poll-error
    • command-notfound
• Keyboard
  • addButton
  • addRow
  • toString
  • KeyboardColor
• The Message Object

Getting Started

In the example above you can see a super simple VK Bot. This bot will answer our greetings, that's all.

Let's explain the code, it's pretty simple.

1. Then I create a bot instance with my group's token.
2. By calling bot.start() the bot starts polling updates from the server.
3. Then I simply listen on messages which pass the RegExp test, when I get such message, Then I send a new message with text 'Hello' to that chat with a forwarded message.

---

Bot

The class used to create new bots, it takes a single argument, an options object.

new Bot({
  token: 'TOKEN',
  group_id: 123456
  api: {
    v: 5.80, // >= 5.80
    lang: 'ru'
  }
})

Parameter	Type	Required
token	String	Yes
group_id	Number	Yes
api	Object	No
controllers	String[]	No

api is object with API settings: version and language. (both strings) (Read more)

---

Methods

start

Starts polling updates from API. Emits an update event after getting updates with the response from server. Update examples.

---

get

Listens on specific message matching the RegExp pattern.

bot.get(/Hello/i, (msg, exec, reply) => {
  console.log(msg)
  reply('Hi!')
})

The argument passed to callback is a Message object, result of pattern.exec(text) and a reply function.

reply takes text as first argument and optional message.send parameters as second.

---

getPayload

Listens for specific payload (used for keyboards) This is a syntactic sugar for the payload event

bot.getPayload('{"command": "start"}', (msg, reply) => console.log(msg))

Arguments: json string and listener

---

send

Sends message.

bot.send('text', peer_id, params)

---

uploadPhoto

Upload a photo.

The only parameter is an absolute path to picture or a stream object. Returns a Promise that resolves with a photo object

bot.uploadPhoto('~/kittens.png').then(photo => {
  console.log(photo)
})

let stream = fs.createReadStream('./kittens.png')
bot.uploadPhoto(stream).then(photo => {
  console.log(photo)
})

---

api

Access VK API.

bot.api('users.get', { user_ids: 1 })
  .then(res => console.log(res[0].first_name)) // Pavel

When using execute method, this function returns full response object. (Because there may be errors and responses in same object).

---

processUpdate

Process an update from Callback API. Example of usage may be found in examples folder

---

stop

Stops the bot from listening on updates.

bot.stop()

---

Events

update

The update event is emitted whenever there is a response from LongPoll.

bot.on('update', update => {
  if (update.from_id === 1) {
    console.log('Got a message from Pavel Durov!');
  }
})

---

voice

The voice event is emitted whenever there is a new voice message. (emits Message object)

---

sticker

The sticker event is emitted whenever there is a new incoming sticker. (emits Message object)

---

payload

Emitted when bot recieves a message with json payload (used in keyboards) Emits Message object and reply function

---

poll-error

The poll-error event is emitted whenever there is an error occurred in LongPoll.

bot.on('poll-error', error => {
  console.error('error occurred on a working with the Long Poll server ' +
    `(${util.inspect(error)})`)
})

---

command-notfound

This event is emitted whenever there's no .get() listeners matching

bot.on('command-notfound', msg => {
  bot.send('What?', msg.peer_id)
})

---

Keyboard

The class used to create keyboards in messages

bot.get(/Hi|Hello|Hey/i, message => {
  const keyboard = new Keyboard(true)
    .addButton('Red', KeyboardColor.NEGATIVE)
    .addButton('Green', KeyboardColor.POSITIVE)
    .addRow()
    .addButton('Blue', KeyboardColor.PRIMARY)
    .addButton('White')

  bot.send('Hello!', message.peer_id, keyboard)
});

Full example

The only argument - one_time If true, the keyboard hides after user replies

new Keyboard(true)

---

addButton

Add a button to the last row.

Parameters:

• label (string) - Text on button (required)
• color (string or KeyboardColor)
• payload (any) - A parameter for Callback API

Maximum amount of buttons in one row is 4

---

addRow

Add a new row to the keyboard.

Maximum amount of rows is 10

---

toString

Get the keyboard as a JSON string

---

KeyboardColor

addButton('label', KeyboardColor.NEGATIVE)

Available colors:

• PRIMARY - blue
• DEFAULT - white
• NEGATIVE - red
• POSITIVE - green

---

The Message Object

interface Message {
  id: number,
  peer_id: number,
  date: number,
  text: string,
  from_id: number,
  attachments: any,
  important: boolean,
  conversation_message_id: number,
  fwd_messages: any
}

// Reference: https://vk.com/dev/objects/message