vk-bot-sdk

0.1.1 • Public • Published

vk-bot-sdk

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

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

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

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

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

  • Возможность создания сценариев вопросов и ответов

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

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

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

Установка

npm install vk-bot-sdk

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

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

const VK = require('vk-bot-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-bot-sdk.').send()
})

Результат:

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

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

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

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

const VK = require('vk-bot-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-bot-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-bot-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

Объект VK.Group

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

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

Методы:

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)

Dependents (0)

Package Sidebar

Install

npm i vk-bot-sdk

Weekly Downloads

4

Version

0.1.1

License

ISC

Unpacked Size

114 kB

Total Files

17

Last publish

Collaborators

  • fetbiko