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')
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')
const YANDEX_KEY = 'f2cf48cd-7f44-4e56-a8ca-60c7dc3381d9'
Group.onMessageText((message) => {
if (message.body.length > 200) {
message.addText('В сообщении должно быть не больше 200 символов').send()
} else {
message.setTyping()
VK.Utils.getBuffer('https://tts.voicetech.yandex.net/generate', {text: message.body, format: 'mp3', lang: 'ru', speaker: 'zahar', key: YANDEX_KEY}, (buffer, response) => {
if (response && response.headers['content-type'] == 'audio/mpeg') {
let file = {
buffer: buffer,
filename: 'file.mp3',
mimetype: 'audio/mpeg'
}
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) => {
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')
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) => {
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')
.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',
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',
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