vk-bot-sdk

v0.1.1

Published

2 years ago

NodeJS Lib for VK API

Downloads

0High
0Medium
0Low

fetbiko

vk bot api vkontakte vk-api vk-bot bot-vk callback-api vk-group vk-sdk вк

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)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vk-bot-sdk

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

Установка

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

Результат:

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

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

Объект VK.Group

Методы:

Group.onMessage(callback)

Пример:

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

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

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

Group.onCommand(command, callback)

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

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

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)

Пример:

Объект VK.App

VK.App.Streaming()

Пример: