vk-node-sdk

vk-node-sdk

Библиотека для работы с VK API для сообществ, пользователей и приложений. Прежде чем начать использование библиотеки, получите access_token для пользователя,сообщества или приложения как описано тут. Создайте сообщество на этой странице если оно ещё не создано или приложение тут

Главные преимущества этой библиотеки

• Библиотека позволяет выполнять запросы от имени группы, так и от имени пользователя, что позволяет выполнять методы, недоступные для вызова от имени группы, например: wall.deleteComment

• Все вызванные методы помещаются в очередь и последовательно выполняются через метод execute (который за один запрос может обработать до 25 методов). Это позволяет оптимизировать количество запросов к серверам VK и не превышать лимиты на количество запросов в секунду.

• Возможность отправки медиа-вложения из URL.

• Разделение сообщении по типу (только с текстом/с фото/с документом).

• Получение и обработка событий из Callback API + автоматическая настройка сервера Callback API.

• Удобная работа с Streaming API

Установка

npm install vk-node-sdk

Простые примеры

Тут мы получаем новые сообщения присланные в сообщество и отвечаем на некоторые из них:

const VK = require('vk-node-sdk')
const Group = new VK.Group('GROUP_TOKEN') // Подробнее: https://vk.com/dev/access_token

Group.onMessage((message) => {
  console.log('new message', message.toJSON())
  message.setTyping() // Отправляем статус "печатает"
  switch(message.body) {
    case 'пинг':
      message.addText('понг').send()
      break
    case 'фото':
      message.addPhoto('https://vk.com/images/gift/875/256_1.jpg').send()
      break
    case 'документ':
      message.addPhoto('http://vk.com/images/gift/875/256.mp4').send()
      break
    case 'ответ':
      message.addText('сообщение').addForward(message.id).send()
      break
  }
})

Group.onCommand('/help', (message) => { // Пример использование комманды
  message.addText('Это тестовый бот для проверки библиотеки vk-node-sdk.').send()
})

Результат:

Пример голосового бота:

В этом примере используется синтезатор речи от Yandex. Для этого нужо получить бесплатный ключ для использования Yandex SpeechKit Cloud Подробнее тут: https://tech.yandex.ru/speechkit/cloud/

В примере показано как загружать файлы на ВК с внешних ресурсов не сохраняя их у себя на сервере.

Так же показано как загружать mp3 или wav файл как аудио сообщение на ВКонтакте.

const VK = require('vk-node-sdk')
const Group = new VK.Group('GROUP_TOKEN')

/**
 * Бесплатный ключ Yandex SpeechKit Cloud
 * Получить тут: developer.tech.yandex.ru/keys/ и вставить в эту переменную
 */
const YANDEX_KEY = 'f2cf48cd-7f44-4e56-a8ca-60c7dc3381d9'


/**
 * Получаем все сообщения которые содержат текст
 */
Group.onMessageText((message) => {
  if (message.body.length > 200) {
    message.addText('В сообщении должно быть не больше 200 символов').send()
  } else {
    message.setTyping()
    /**
     * Выполняем запрос к Yandex API
     */
    VK.Utils.getBuffer('https://tts.voicetech.yandex.net/generate', {text: message.body, format: 'mp3', lang: 'ru', speaker: 'zahar', key: YANDEX_KEY}, (buffer, response) => {
        /**
         * Получем данные и проверяем заголовки
         * content-type: audio/mpeg - значить что Yandex API вернул аудиофайл в ответ
         * Создаем объект файла и загружаем голосовое сообщение на ВК
         */
        if (response && response.headers['content-type'] == 'audio/mpeg') {
          let file = { // Создаем объект файла
              buffer: buffer, // buffer - полученное аудио c Yandex API
              filename: 'file.mp3', // имя файла, например: file.wav
              mimetype: 'audio/mpeg' // mimetype файла, для аудио - audio/mpeg. Список: vk.cc/70vqHm
            }
            /**
             * Первый аргумент (file) наш объект файла
             * Второй аргумент ('file_name') название файла на ВК
             */
          message.addVoice(file, 'file_name.mp3').send()
        } else {
          message.addText('Упс, не удалось озвучить текст').send()
        }
      })
  }
})


/**
 * Все остальные сообщения которые мы не обрабатываем
 * Например сообщения с фото
 */
Group.onMessage((message) => {
  message.addText('Пришли мне текстовое сообщение').send()
})

Или пример с получением новых комментариев и автоматическое удаление комментариев от сообществ:

const VK = require('vk-node-sdk')

const User = new VK.User('USER_TOKEN')
const Group = new VK.Group('GROUP_TOKEN', {
  webhook: {
    url: 'http://SERVER_IP/callback',
    port: 80
  }
})

Bot.onCallBackEvent('wall_reply_new', (comment) => {
  // У сообществ id всегда меньше 0.
  // Второе условие нужно, чтобы не удалять комментарии от своей группы.
  if (comment.from_id < 0 && comment.from_id != Group.Id) {
    User.api('wall.deleteComment', {
      owner_id: comment.post_owner_id,
      comment_id: comment.id
    })
  }
})

В итоге все комментарии от сообществ будут автоматически удаляться.

Инициализация

const VK = require('vk-node-sdk')

// Для сообщества с указанием Callback сервера
const Group = new VK.Group('GROUP_TOKEN', {
  webhook: {
    url: 'http://SERVER_IP/callback',
    port: 80
  }
})

// Для пользователя
const User = new VK.User('USER_TOKEN')

// Для приложения
const App = new VK.App('APP_TOKEN')

Если вы используете другой порт для Callback сервера, настройте его проксирование через ваш веб-сервер. Документация для Nginx и Apache

Подробнее о настройке callback сервера с помощью nginx на ubuntu

Объект VK.Group

Этот объект предназначен для работы с VK API от имени сообщества. Позволяет получать новые сообщения и новые события в сообществе через Callback API

Параметр	Тип	Обязательный	Описание
access_token	string или array	Да	Ключ доступа к сообществу или список ключей.
options	object	Нет	Параметры. Например параметр webhook указывает данные для Callback API

Методы:

• Group.onMessage(callback)
• Group.onCommand(command, callback)
• Group.onTypingStatusChange(callback)
• Group.onCallBackEvent(event, callback)
• Group.api(method, params, callback)
• Group.isMember(user_id, callback)
• Group.sendMessage(params, callback)
• Group.photoUpload(peer_id, file, callback)
• Group.docUpload(peer_id, file, callback, type)
• Group.coverUpload(file, callback, params)
• Group.messageGet(message_id, callback)
• Group.userGet(user_id, callback)
• Group.message(user_id)
• Group.setTyping(peer_id)
• Group.sendToIds(peer_ids, text, attachment)

Group.onMessage(callback)

Позволяет получать все новые входящие сообщения в сообщество.

Параметр	Тип	Обязательный	Описание
callback	function	Да	callback функция. Возвращает объект Message

Пример:

Group.onMessage((message) => {
  // message.toJSON() = Объект сообщения https://vk.com/dev/objects/message
  console.log(message.toJSON())
})

Так же есть методы для получения сообщений определенных типов:

*Методы *

• Group.onMessagePhoto(callback) Только сообщения с фото
• Group.onMessageText(callback) Только сообщения с текстом
• Group.onMessageSticker(callback) Только сообщение со стикером
• Group.onMessageMusic(callback) Только сообщение с музыкой
• Group.onMessageDoc(callback) Только сообщение с документом
• Group.onMessageGif(callback) Только сообщение с анимацией
• Group.onMessageVoice(callback) Только голосовые сообщения
• Group.onMessageMap(callback) Только сообщения с картой/локацией
• Group.onMessageVideo(callback) Только сообщения с видео
• Group.onMessageLink(callback) Только сообщения c объектом ссылки
• Group.onMessageMarket(callback) Только сообщение с товаром
• Group.onMessageMarketAlbum(callback) Только сообщение c альбом товаров
• Group.onMessageWall(callback) Только сообщение с объектом записи на стене
• Group.onMessageWallReply(callback) Только сообщение с комментарием
• Group.onMessageGift(callback) Только сообщение с подарком
• Group.onMessageForward(callback) Только пересланные сообщения
• Group.onChatTitleChange(callback) Событие об изменении названия беседы

Например получать сообщения только c фото:

Group.onMessagePhoto((message) => {
  console.log(message.getPhotos())
})

В каждом callback возвращаеться объект сообщения - Message.

С помощью этого объекта можно:

• Отправить ответное сообщение
• Проверить тип сообщения
• Получить все объекты фото из сообщения

Простой пример:

Group.onMessage((message) => {
  message
    .addPhoto('https://vk.com/images/gift/474/256.jpg') // Добавляем фото из URL
    .addPhoto('photo-1_456239099') // Добавление уже загруженного фото
    .addPhoto('./photos/photo.jpg') // Добавляем фото из сервера
    .addText('Test send photos') // Добавляем текст к сообщению
    .send() // Вызываем этот метод чтобы отправить сообщение
})

Более подробную документацию по объекту Message вы можете прочитать тут

Group.onCommand(command, callback)

Подписывает на события сообщении с заданной командой.

Параметр	Тип	Обязательный	Описание
command	string или array	Да	Маска или массив масок для сообщений
callback	function	Да	callback функция. Возвращает объект Message

Пример получения сообщений с текстом /start:

Group.onCommand('/start', (message) => {
  console.log(message.toJSON())
})

или массив комманд:

Group.onCommand(['/start', '!start'], (message) => {
  console.log(message.toJSON())
})

Group.onTypingStatusChange(callback)

Подписывает на события Печатает

Параметр	Тип	Обязательный	Описание
callback	function	Да	callback функция. Возвращает user_id - id пользователя и is_typing - true = человек начал печатать и false если юзера закончил печатать

Пример:

Group.onTypingStatusChange((user_id, is_typing) => {
  console.log(user_id + ' - ' + (is_typing ? 'начал' : 'закончил') + ' печатать')
})

Group.onCallBackEvent(event, callback)

Позволяет получать события Callback API

Параметр	Тип	Обязательный	Описание
event	string или array	Да	Название или массив названий Callback API событий
callback	function	Да	callback функция. Возвращает объект из события

Пример получение новых комментариев:

Group.onCallBackEvent('wall_reply_new', (comment) => {
  console.log(comment)
})

ВАЖНО! Включите отправку нужных вам событий в настройках Callback API вашего сообщества

Group.api(method, params, callback)

Выполняет произвольный метод к VK API от имени сообщества.

Параметр	Тип	Обязательный	Описание
method	string	Да	Название метода
params	object	Да	Параметры метода
callback	function	Нет	callback функция. Первый аргумент возвращает результат выполнения метода или false если метод выполнить не удалось. Второй аргумент возвращает объект ошибки (https://vk.com/dev/errors) если метод выполнить не удалось.

Пример:

Group.api('groups.getById', {fields: 'members_count'}, (data, error) => {
  if (error) {
     console.log('Ошибка выполнения метода', error)
  } else {
     console.log(data)
     console.log('Участников в сообществе:', data[0].members_count)
  }
})

Group.isMember(user_id, callback)

Проверяет подписку пользователя на текущее сообщество.

Параметр	Тип	Обязательный	Описание
user_id	integer	Да	id пользователя
callback	function	Да	callback функция. Возвращает true в случаи если пользователь подписан или false если нет

Пример:

Group.isMember(225818028, (isSubscriber) => {
  if (isSubscriber) {
     console.log('Подписан')
  } else {
     console.log('Не подписан')
  }
})

Group.sendMessage(params, callback)

Отправляет сообщение от имени сообщества.

Параметр	Тип	Обязательный	Описание
params	object	Да	Параметры для отправки сообщения
callback	function	Да	callback функция. Возвращает id отправленного сообщения или false если сообщение отправить не удалось

Пример:

Group.sendMessage({user_id: 225818028, message: 'Привет!'}, (messageId, error) => {
  if (messageId) {
     console.log('Сообщение отправлено!\n message_id: ', messageId)
  } else {
     console.log('Не удалось отправить сообщение', error)
  }
})

Group.photoUpload(peer_id, file, callback)

Загружает фотографию в диалог указанного пользователя. После загрузки фото его можно отправить пользователю.

Параметр	Тип	Обязательный	Описание
peer_id	integer	Да	id диалога в который нужно загрузить фотографию
file	object	Да	Объект с данными для загрузки файла (путь к файлу, имя файла, mime тип)
callback	function	Да	callback функция. Возвращает объект загруженного фото или false если фото загрузить не удалось

Пример:

const file = {
  filename: 'photo.jpg', // Имя файла
  mimetype: 'image/jpeg', // mime тип файла
  file: './photos/photo.jpg' // Путь к файлу
}
Group.photoUpload(225818028, file, (photo) => {
  console.log(photo)
})

Group.docUpload(peer_id, file, callback, type)

Загружает документ в диалог указанного пользователя. После загрузки документа его можно отправить пользователю.

Параметр	Тип	Обязательный	Описание
peer_id	integer	Да	id диалога в который нужно загрузить фотографию
file	object	Да	Объект с данными для загрузки файла (путь к файлу, имя файла, mime тип)
callback	function	Да	callback функция. Возвращает объект загруженного документа или false если документ загрузить не удалось
type	string	Нет	Тип документа. Например: audio_message - для голосовых сообщений и graffiti - для загрузки граффити

Пример:

const file = {
  filename: 'test.gif', // Имя файла
  mimetype: 'image/gif', // mime тип файла
  file: './animations/test.gif' // Путь к файлу
}
Group.docUpload(225818028, file, (doc) => {
  console.log(doc)
})

Group.coverUpload(file, callback, params)

Загружает обложку в текущее сообщество.

Параметр	Тип	Обязательный	Описание
file	string или object	Да	Путь или внешняя ссылка к изображению. Так же принимает объект с данными для загрузки файла (путь к файлу, имя файла, mime тип)
callback	function	Нет	callback функция. Возвращает объект загруженной обложки или false если обложку загрузить не удалось
params	object	Нет	Параметры загрузки обложки. Подробнее: https://vk.com/dev/photos.getOwnerCoverPhotoUploadServer

Пример:

Group.coverUpload('./images/cover.png')

Group.messageGet(message_id, callback)

Позволяет получить сообщения по его идентификатору.

Параметр	Тип	Обязательный	Описание
message_id	integer	Да	Идентификатор сообщения
callback	function	Да	callback функция. Возвращает объект сообщения (https://vk.com/dev/objects/message) или false если сообщение получить не удалось

Пример:

Group.messageGet(1, (message_object) => {
  console.log(message_object)
})

Group.userGet(user_id, callback)

Получает информацию о пользователе по его идентификатору.

Параметр	Тип	Обязательный	Описание
user_id	integer	Да	Идентификатор пользователя
callback	function	Да	callback функция. Возвращает объект пользователя (https://vk.com/dev/objects/user) или false если метод выполнить не удалось

Пример:

Group.userGet(225818028, (user) => {
  console.log('Пользователь - ', user.first_name)
})

Group.message(user_id)

Создает объект сообщения.

Параметр	Тип	Обязательный	Описание
user_id	integer	Да	Идентификатор получателя

Пример:

Group.message(225818028).addText('Привет!').send()

Group.setTyping(peer_id)

Отправляет статус "печатает".

Параметр	Тип	Обязательный	Описание
peer_id	integer	Да	Идентификатор получателя

Пример:

Group.setTyping(225818028)

Group.sendToIds(peer_ids, text, attachment)

Позволяет делает рассылку сообщений пользователям.

Параметр	Тип	Обязательный	Описание
peer_ids	array	Да	Список идентификаторов пользователей которым нужно отправить сообщение
text	string	Да	Текст сообщения
attachment	string	Нет	Прикрепление к сообщению. Например фото, видео или аудио

Пример:

Group.sendToIds([225818028, 1, 2], 'Привет!')

Объект VK.App

Этот объект предназначен для работы с API для приложений.

Параметр	Тип	Обязательный	Описание
access_token	string или array	Да	Ключ доступа к приложению или список ключей.

VK.App.Streaming()

Создает объект для работы с Streaming API

Пример:

const VK = require('vk-node-sdk')
const App = new VK.App('APP_TOKEN')
const Streaming = App.Streaming()

// Получение новых событий
Streaming.onListener((event) => {
  console.log('new event', event)
})

// Добавление правил
Streaming.addRule('vk', 2).addRule('bot', 'bot_tag')

// Получение текущих правил
Streaming.getRules((rules) => {
  console.log(rules)
})

// Удалить все правила
Streaming.clearRules()

// Удалить одно правило
Streaming.deleteRule(2)

Контакты

Сообщество ВКонтакте: vk.com/nodesdk