PlugAPI Util Functions

PlugAPI.Utils.uppercase('HAI') // returns 100

Prefix that defines if a message is a command. Default is !

Type: String

Should the bot split messages up if the message length limit is reached?

Type: Boolean

The maximum number of messages sent after splitting the message.

Type: Number

Should the bot process commands the bot itself is sending?

Type: Boolean

Should the bot delete incoming commands?

Type: Boolean

Should the bot delete message blocks?

Type: boolean

Should the bot be able to delete all chat regardless of role? Note: This will NOT delete gRole chat.

Type: Boolean

Should muted users trigger normal events?

Type: Boolean

Pre-command Handler

// this prevents anyone without the user id of 1234567 from running a command. There are also other things a user can do such as cooldowns per command.
bot.preCommandHandler((data) => {
   if (data && data.from && !Object.is(data.from.id, 1234567)) return false;
})

Connect to a room

bot.connect('plugcubed');

Join another room

bot.changeRoom('my-other-room-is-better');

Close the connection

bot.close();

Get a history of chat messages. (Limit 512 messages)

bot.getChatHistory();

Get a history of songs played. (Limit 50 songs)

bot.getHistory();

Get information about the booth such as who's DJing, if booth is locked, cycle is enabled, DJs in waitList

bot.getBoothMeta();

Get historyID of the currently playing media. This is used for voting, grabbing, skipping, and various other purposes

bot.getHistoryID();

Get the currently playing media. Null if there isn't

bot.getMedia();

Get the room's metadata

bot.getRoomMeta();

Get the current room score fot the song playing.

bot.getRoomScore();

Adds bot to waitList.

bot.joinBooth();

Removes bot from waitList.

bot.leaveBooth();

Send a chat message

// without timeout
bot.sendChat('Hello world!');

// with timeout. Will delete after 5 seconds.
bot.sendChat('Hello world!', 5)

Get the current avatar

bot.getAvatar();

Get all available avatars

bot.getAvatars((err, data) => console.log(err, data));

Set avatar Be sure you only use avatars that are available PlugAPI#getAvatars

bot.setAvatar('classic07');

Get plug.dj admins currently in the community

bot.getAdmins();

Get all staff for the community, also offline.

bot.getAllStaff((err, data) => console.log(err, data));

Get all ambassadors in the community

bot.getAmbassadors();

Get users in the community that aren't DJing nor in the waitList

bot.getAudience();

Get the current DJ

bot.getDJ();

Get the DJ and users in the waitList

bot.getDJs();

Host if in community, otherwise null

bot.getHost();

Get the user object for yourself

bot.getSelf();

Get staff currently in the community

bot.getStaff();

Get specific user in the community

bot.getUser(123456);

Get all users in the community

bot.getUsers();

Get all DJs in waitList

bot.getWaitList();

Get a user's position in waitList

bot.getWaitListPosition(123456);

Implementation of plug.dj haveRoomPermission method

// is user bouncer or above?
bot.havePermission(123456, PlugAPI.ROOM_ROLE.BOUNCER);

// is user a BA or admin?
bot.havePermission(123456, PlugAPI.ROOM_ROLE.BOUNCER, true);

Get time elapsed of current song

bot.getTimeElapsed();

Get time remaining of current song

bot.getTimeRemaining();

Get the command prefix

bot.getCommandPrefix();

Set the command prefix

bot.setCommandPrefix('.');

Get the url that http requests are being sent to

bot.getBaseURL();

Set the url that http requests are being sent to

bot.setBaseURL('https://plug.dj');

Get the url that webSocket events are being sent to

bot.getSocketURL();

Set the url that webSocket events are being sent to

bot.setSocketURL('wss://ws-prod.plug.dj');

Woot current song

bot.woot();

Meh current song

bot.meh();

Grab current song

bot.grab();

Activate a playlist

bot.activatePlaylist(123456);

Add a song to a playlist

bot.addSongToPlaylist(123456, [{cid: '789abc', format: 1, image: 'https://i.ytimg.com/blah', duration: 300, title: 'My song', author: 'My song author'}])

Removes a media from a playlist

bot.removeSongFromPlaylist(1233456, 789abc);

Create a new playlist

bot.createPlaylist('Swag');

Delete a playlist

bot.deletePlaylist(123456);

Get active playlist

bot.getActivePlaylist();

Get playlist by ID

bot.getPlaylist(123456);

Get playlists

const playlists = bot.getPlaylists();

Get all medias in playlist

const playlistMedias = bot.getPlaylistMedias(123456);

Move a media in a playlist

Shuffle playlist

bot.shufflePlaylist(123456);

Add a DJ to Waitlist/Booth

bot.moderateAddDJ(123456);

Ban a user from the community

// Note for the reason / time you can either use bot. or PlugAPI.
bot.moderateBanUser(123456, bot.BAN_REASON.SPAMMING_TROLLING, bot.BAN.PERMA);

Delete a chat message

bot.moderateDeleteChat('123456-78910');

Skip current media

bot.moderateForceSkip();

Skip self

bot.selfSkip();

Move a DJ in the waitList

bot.moderateMoveDJ(123456, 1);

Mute user

// Note for the reason / time you can either use bot. or PlugAPI.
bot.moderateMuteUser(123456, bot.MUTE._REASON.VIOLATING_COMMUNITY_RULES, bot.MUTE.LONG);

Remove a DJ from Waitlist/Booth

bot.moderateRemoveDJ(123456);

Set the role of a user

// Note for the role you can either use bot. or PlugAPI.
bot.moderateSetRole(123456, bot.ROOM_ROLE.BOUNCER);

Ban a user from the WaitList

// Note for the reason / time you can either use bot. or PlugAPI.
bot.moderateWaitListBan(123456, bot.BAN_REASON.SPAMMING_TROLLING, bot.BAN.PERMA);

Unban a user

bot.moderateUnbanUser(123456);

Unban a user from the WaitList

bot.moderateWaitListUnban(123456);

Unmute a user

bot.moderateUnmuteUser(123456);

Change the name of the community

bot.changeRoomName('Yolo Swag');

Change the chat level of the community

bot.changeRoomChatLevel(3);

Change the description of the community

bot.changeRoomDescription('My room is better than yours. #420');

Change the welcome message of the community

// Both %u and %r are automatically replaced by plug to the welcomed user's username and the room's name.
bot.changeRoomWelcome('Welcome %u to %r');

Change the DJ cycle of the community

bot.changeDJCycle(false);

Get the current cookie jar being used for API requests

bot.getJar();

Set your badge. Be sure you only use badges that are available PlugAPI#getBadges

bot.setBadge('raveb02');

Get your current badge

bot.getBadge();

Get all available badges

bot.getBadges((err, data) => { console.log(err, data); });

Lock/Clear the waitList/booth

// PlugAPI has an alias function moderateLockWaitList. Both work the same
// To lock and not clear
bot.moderateLockBooth(true, false);

// To lock and clear
bot.moderateLockBooth(true, true);

// to unlock
bot.moderateLockBooth(false, false);

This is emitted when the bot is banned.

This is emitted when a user is muted

bot.on(PlugAPI.events.MODERATE_MUTE, (data) => {
   console.log(`${data.moderator.username} has ${!Object.is(data.duration, 'Unmuted') ? `muted ${data.user} - ${data.duration}` : `unmuted ${data.user}`}`);
});

This is emitted when the room welcome message has changed.

bot.on(PlugAPI.events.ROOM_WELCOME_UPDATE, (data) => {
   console.log(`${data.user.username} changed the room welcome message to ${data.welcome}`);
});

This is emitted when the song has changed to another one.

bot.on(PlugAPI.events.ADVANCE, (data) => {
});

This is emitted when a user votes on the song (Undecided, Meh, Woot)

bot.on(PlugAPI.events.VOTE, (data) => { *
   if (Object.is(data.vote, 1)) {
        console.log(`${data.user.username} Wooted`);
   } else if (Object.is(data.vote, -1)) {
        console.log(`${data.user.username} Mehed`);
   } else if (Object.is(data.vote, 0)) {
        console.log(`${data.user.username} hasn't voted`);
   }
})

This is emitted when the bot connects to plug more than once.

This is emitted when someone grabs a song.

bot.on(PlugAPI.events.GRAB, (data) => {*
  console.log(`${data.user.username} grabbed the currently playing song`)
});

This is emitted when someone gifts the bot Plug Points.

This is emitted when the bot earns XP or Plug Points

bot.on(PlugAPI.events.EARN, (data) => {
   console.log(`You are currently level ${data.level} with: ${data.pp} PP and ${data.xp} XP `);
});

This is emitted when the waitList has changed.

This is emitted when the dj waitList has been locked, cleared, or unlocked.

bot.on(PlugAPI.events.DJ_LIST_LOCKED, (data) => {
  console.log(`${data.user.username} ${data.locked ? 'Locked' : 'Unlocked'} the waitList and ${data.clear ? 'Did' : "didn't"} clear the waitList`);
});

This is emitted when the dj cycle is enabled or disabled

bot.on(PlugAPI.events.DJ_LIST_CYCLE, (data) => {
   console.log(`${data.user.username} ${data.cycle? 'Enabled' : 'Disabled'} the DJ Cycle `);
});

This is emitted when a user is banned from waitList.

bot.on(PlugAPI.events.MODERATE_WLBAN, (data) => {
   console.log(`${data.moderator.username} banned ${data.user} from the waitList ${data.duration}`);
});

This is emitted when a chat message starting with the PlugAPI#commandPrefix is received

bot.on('command:ping', (data) => {
   data.respond('Pong!');
});

bot.on('command:add', (data) => {
   // check for bouncer or above permissions.
   if (data.havePermission(PlugAPI.ROOM_ROLE.BOUNCER)) {
      // check if a user was mentioned and is not in waitList
      if (data.args[0] && data.args[0].id && (Object.is(bot.getWaitListPosition(data.args[0].id, -1)) || (bot.getDJ() && bot.getDJ().id && !Object.is(bot.getDJ().id, data.args[0].id)))) {
      bot.moderateAddDJ(data.args[0].id, () => {
         data.respond(`Added ${data.args[0].username} to waitList`);
      });
      }
   }
});

bot.on('command:skip', (data) => {
   if (data.havePermission(PlugAPI.ROOM_ROLE.BOUNCER)) {
      bot.moderateForceSkip(()=> {
         data.respond('Song Skipped.');
      });
   }
});

This is emitted when the chat level has been updated.

bot.on(PlugAPI.events.CHAT_LEVEL_UPDATE, (data) => {
   console.log(`${data.user.username} updated the chat level to ${data.level}`);
});

This is emitted when a chat message starting with /em or /me has been received.

This is emitted when a chat message has been deleted.

bot.on(PlugAPI.events.CHAT_DELETE, (data) => {
  const user = bot.getUser(mi);

   console.log(`${user.username} deleted message: ${data.c}`);
});

This is emitted when a chat message starting with the PlugAPI#commandPrefix is received.

This is emitted when a chat message has been received.

bot.on(PlugAPI.events.CHAT, function(data) {
  console.log(`[${data.id}] [${data.from.username}] ${data.message}`);
 });

This is emitted when a bouncer or above skips a song

bot.on(PlugAPI.events.MODERATE_SKIP, (data) => {
   console.log(`${data.user.username} Skipped the song`);
})

This is emitted when the room name has changed.

bot.on(PlugAPI.events.ROOM_NAME_UPDATE, (data) => {
   console.log(`${data.user.username} changed the room name to ${data.name}`);
});

This event is emitted when staff roles are changed.

bot.on(PlugAPI.events.MODERATE_STAFF, (data) => {
   if (data.users.length > 0) {
     console.log(`${data.moderator.username} has changed ${data.users.map((item) => {
         if (item.user != null) {
             return `${item.user.username} to ${item.role}`;
         }
     })}`);
   }
});

This is emitted when a user is banned

bot.on(PlugAPI.events.MODERATE_BAN, (data) => {
   console.log(`${data.moderator.username} banned ${data.user} ${data.duration}`);
});

Add the user to the waitlist

Remove the user from the waitlist

Move the user to a new position in the waitlist