mqp-api
v0.7.1
Published
API for creating musiqpad bots
Downloads
17
Readme
MQP-API
API for creating musiqpad bots
Install
NodeJS
npm install mqp-api -S
Browser
<script src="https://cdn.musiqpad.com/js/mqp-api.min.js"></script>
Setting up your own bot
Version 0.3.x changes how you connect to a pad, the old way still works for compatibility though!
Version 0.7.x changed bans to restrictions, check the docs below!
Tip: Change your bot permissions in serverconfig.js to have the same as a co-owner if you want to avoid permissions errors. If you don't know the () =>
syntax, google arrow functions!
The first thing you'll need to do is to create a new Bot. You can get these values by typing config
into the DevTools console on your Pad (if the serverhost is empty, use your domain).
const mqpAPI = require('mqp-api'); // Ignore this line if you are using the browser version
var bot = new mqpAPI({
autoreconnect: true, // Enabled by default, for other options check the wiki
logging: {
logLevel: 'info', // Default is info, others are:
// silent, error, warn, info, verbose, debug, silly
logFile: './logs.json' // Optional
}
});
Now we connect to the Websockets Server and login
bot.connect({
room: 'tastycat',
// If you don't have a room slug, you can also connect via port + domain:
// useSSL: true,
// socketDomain: 'example.com',
// socketPort: 8082,
}).then(() => {
return bot.login({
email: '[email protected]',
password: 'MyPassword',
// You can also use a token to login:
// token: '4f5a2e48-04c5-46e6-bd61-faeeeca69d6d',
});
}).then(() => {
console.log('Logged in!');
// Do what ever you want to happen after you successfully logged in for the first time
// ...
})
bot.on('reconnected', () => {
// Do what ever you want to happen after you successfully reconnected
});
Now we create an Event-listener for chat messages. To see what every event does, check the wiki. Instead of .on
, you can also use .once
if you want the function to be only called once.
bot.on('chat', function(data) {
// We pass in a function as callback which accepts one argument, data.
// Everytime a chat message is received, this function will be called
// and useful information will be passed in via this first argument.
// Check if data.msg contains '@bot'
if (data.msg.indexOf('@bot') != -1)
bot.sendMessage('Hey, ' + data.user.un + '!');
// Check if msg contains !kill
if (data.msg.indexOf('!kill ') != -1) {
// Remove !kill from the recieved message and save the
// remaining string as user
var user = data.msg.replace('!kill ', '');
bot.sendMessage(user + ' got killed by '+ data.user.un + "! Oh no!");
}
});
Some other examples:
// Add an event Listener for Chatevents
bot.on('chat', (data) => {
if (data.msg.indexOf('@YourBot') != -1) //If the message contains @YourBot
//Send a private message: bot.sendPrivateMessage(uid, message)
bot.sendPrivateMessage(data.user.uid, 'Hey, ' + data.user.un + '! \
To check all of my commands, type "!help".');
// If the message (data.msg) includes !help
if (data.msg.indexOf('!help') != -1) {
// Get the room infos
bot.getRoomInfo().then(function (roomInfos) {
//And .then() use those to send a Message
bot.sendMessage("I can't help you. But I can give you \
some Infos about the room: There are currently " +
(Object.keys(bot.users).length + 1) + ' Users connected and ' + roomInfos.queue + ' users in the Queue');
// (Object.keys(bot.users).length + 1) gets the number of online users
});
}
});
bot.on('userJoined', function (data) {
if (data.user)
setTimeout(function () {
bot.sendMessage('Welcome to Pad_Name, @' + data.user.un + ' !');
}, 5000);
});
bot.on('privateMessage', function (data) {
if (data.message.indexOf('help') != -1)
bot.sendPrivateMessage(data.uid, 'Hey, ' + bot.users[data.uid].un + '! To check all of my commands, type "!help".');
});
Available functions:
getUsers():
Example:
bot.getUsers().then(function(data) {
// ...
});
Returned Object:
{
uid: {
badge: {},
banned: true,
role: 'owner',
un: 'Username',
uid: 'uid'
}
}
getUser: (Also for getting playlists)
Example:
var user = bot.getUser(uid);
var currentUser = bot.getUser();
Returned Object:
{
badge: {},
banned: true,
role: 'owner',
un: 'Username',
uid: 'uid'
// If you get the current User, you also get
activepl: 10,
created: 1462378487408,
playlists: {
3: {
id: 3,
name: "playlist1",
content: {
[
0: {
SongObject
},
]
}
}
}
}
sendJSON:
Example:
bot.sendJSON({type: 'getUsers'});
events.once('getUsersReceived', (data) => { // You can add 'Received' to every event to get the Server Response
if (data.error)
reject(data.error);
resolve();
});
getRoomInfo:
Example:
bot.getRoomInfo().then(function(data) {
// ...
});
Returned Object:
{
name: name,
slug: slug,
greet: greet,
queue: queueLength,
media: currentsong,
staffroles: staffroles
}
sendPrivateMessage:
Example:
bot.sendPrivateMessage(uid, msg)
bot.sendPrivateMessage(7, "Hey, what's up?")
.then(function (data) {
console.log('Private Message send!');
})
joinQueue, leaveQueue, lockQueue, unlockQueue, toggleLockQueue, cycle, skip:
bot.joinQueue()
bot.joinQueue()
.then(function (data) {
console.log('Joined the DJ Queue!');
})
deleteChat():
Example:
bot.deleteChat(cid, uid)
.then(function (data) {
console.log('Deleted Chat Message!');
})
whois():
Usage:
bot.whois(uid, un)
restrictUser(), getUserRestrictions()
Usage:
restrictUser(uid, duration, reason, type);
getUserRestrictions(uid).then((data) => console.log(data));
unrestrictUser(uid, type);
.logger
Usage:
bot.logger.log(logLevel, "Text");
bot.logger.log("silly", "LOL: " + JSON.stringify({
error: {
foo: "bar",
}
}));
getConversations()
Usage:
bot.getConversations().then((data) => {
/* Data:
conversations: {
1: {
messages: {
0: {
from: 1,
message: 'Hi',
time: "2016-05-15T20:48:35.081Z",
unread: false,
}
}
}
}
*/
})
getHistory()
Usage:
bot.history().then((data) => {
/* Data:
[
{
//Song Object
}
]
*/
})
setLimit()
Usage:
bot.setLimit(limit).then(() => {
})
There are also:
broadcast()
Usage:
bot.broadcast(msg).then(() => {
})
removeDj()
Usage:
bot.removeDj(uid).then(() => {
})
swap()
Usage:
bot.swap(uid1, uid2).then(() => {
})
swap()
Usage:
bot.move(uid, position).then(() => {
})
vote()
Usage:
bot.vote(type).then(() => {
//Types: like, dislike, grab
})
getPadBySlug()
Usage:
bot.getPadBySlug(slug).then(() => {
// You get socketPort
// socketDomain
// useSSL
})
getDJ()
Usage:
dj = bot.getDJ();
getMedia()
Usage:
media = bot.getMedia();
getRoles()
Usage:
roles = bot.getRoles();
getRoleOrder()
Usage:
roleorder = bot.getRoleOrder();
getHistoryLimit()
Usage:
historylimit = bot.getHistoryLimit();
getPadDescription()
Usage:
description = bot.getPadDescription();
Available Events:
- rawSocket
- reconnected
- error // Gets passed the error object
- closed
- chat ```
{
time: 'a timestamp',
msg: "HEEY",
uid: 12,
cid: 420,
user: { Same as getUser() },
}
All of these events get passed the same like the client api:
- advance
- broadcastMessage
- chatCommand
- deleteChat
- djQueueModAdd
- djQueueCycle
- djQueueLimit
- djQueueLock
- djQueueModMove
- djQueueModSkip
- djQueueModSwap
- djQueueModRemove
- djQueueSkip
- privateMessage
- response
- systemMessage
- userBanned
- userJoined
- userJoinedQueue
- userLeft
- userLeftQueue
- moderateSetRole
- userUnbanned
- userUpdate
- voteUpdate