Functions

Plugged works with a wide variety of functions to provide you with a lot of great functionality to interface with plug.dj On this page you can find a quick summary about what each function does and how you can interface with it.

All functions have certain levels at which they can be used. Two at pre login level, quite a bit at global level and a whole lot at room level. All of them have a set background as seen above to make it easier to indicate which function can be accessed at which level.

For further information about the events and how to use them you should consider hitting up the cookbook.

Functions

clearChatCache

Clears the log.

Parameters:

undefined

Return Value:

undefined

clearChatQueue

Clears the queue.

Parameters:

undefined

Return Value:

undefined

clearUserCache

Clears the usercache.

Parameters:

undefined

Return Value:

undefined

deleteNotification

Deletes a notification received by plug.

Parameters:

id: Number notification ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

getChat

Gets chat log.

Parameters:

undefined

Return Value:

[Object] Chat time sorted array of all chat messages.

getChatByUsername

Gets all messages of a user.

Parameters:

username: String name of a user.

Return Value:

[Object] Chat list of all their messages.

getInventory

Retrieves the items you own.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

inventory: [Inventory]

Return Value:

undefined

getProducts

Retrieves all products of a type.

Parameters:

type: String type of product.

category: String category of product.

callback: function called on retrieval.

callback:

err: Object possible error returned.

products: [Product]

Return Value:

undefined

getTransactions

Retrieves all transactions made in the store.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

transactions: [Transaction]

Return Value:

undefined

cacheChat

Sets chat caching. It’s enabled by default.

Parameters:

enable: Boolean boolean value indicating state.

Return Value:

Boolean value that is now set.

isChatCached

Checks if chat is being cached.

Parameters:

undefined

Return Value:

Boolean indicating status.

setChatCacheSize

Sets the chat cache size. the default size is 256 messages.

Parameters:

size: Number size of the cache in messages

Return Value:

Number size of the cache.

getChatCacheSize

Parameters:

undefined

Return Value:

Number the chat cache size.

cacheUserOnLeave

Caches users when they leave the room.

Parameters:

enable: Boolean toggle when true caches users.

Return Value:

Boolean the current state.

isUserCachedOnLeave

Checks if users are cached when they leave the room.

Parameters:

undefined

Return Value:

Boolean the current state.

clearUserFromLists

Clears a user from the voting and grab list.

Parameters:

id: Number user’s ID.

Return Value:

Boolean true when user was found and cleared, false otherwise

setJar

Sets a cookie jar or creates a new one based on a storage object.

Parameters:

jar: Object cookie jar to use.

storage: Object (optional) can create a cookie jar.

Note

jar will be ignored when storage is set.

Return Value:

undefined

getJar

Gets the currently used jar.

Parameters:

undefined

Return Value:

Object the cookie jar.

setHeartbeatRate

Sets the time in between heartbeats in seconds

Parameters:

Number time in between heartbeats in seconds.

Return Value:

undefined

getHeartbeatRate

Gets the time in between heartbeats in seconds.

Parameters:

undefined

Return Value:

Number time in between heartbeats in seconds.

setMaxTimeout

Sets the maximum connection timeout in seconds.

Parameters:

Number time in seconds until the connection is lost.

Return Value:

undefined

getMaxTimeout

Gets the maximum connection timeout in seconds.

Parameters:

undefined

Return Value:

Number time until the connection is lost in seconds.

defaultMessageProc

The default message processor used for chat messages, this function can be overridden or exchanged, see Options.

Parameters:

message: String chat message to send.

Return Value:

[String] msgs formatted message.

setMessageProcessor

Exchanges the message processor dynamically at runtime.

Parameters:

func: function func message processor function.

Return Value:

Boolean true when function was set.

sendChat

Sends a chat message.

Parameters:

message: String message message to send.

deleteTimeout: Number delay in ms until message is deleted.

Return Value:

[String] message the formatted message.

invokeLogger

Hooks up a logging library into plug.

Parameters:

func: function logging function to register.

Return Value:

Boolean true when logger has been registered.

setVerbosity

Defines verbosity to use for logging. Lowest logging level is 0.

Parameters:

verbosity: Number sets verbosity.

Return Value:

undefined

getVerbosity

Parameters:

undefined

Return Value:

Number verbosity.

login

Log into https://www.plug.dj.

Parameters:

credentials: Object formatted loging info, see Options.

authToken: Object last session token.

callback: function called after logging in.

callback:

err: Object possible error returned.

self: [Self]

Return Value:

undefined

guest

Logs into a room as a guest.

Parameters:

slug: String room name.

callback: String called after entering the room.

callback:

err: Object possible error returned.

stats: [Room]

Return Value:

undefined

connect

Connects to a room.

Parameters:

slug: String room name.

callback: function called after entering the room.

callback:

err: Object possible error returned.

stats: [Room]

Return Value:

undefined

getUserById

Gets a user by their ID.

Parameters:

id: Number user’s ID.

cache: CACHE

Return Value:

Object User

getUserByName

Gets a user by their name.

Parameters:

username: String user’s name

cache: CACHE

Return Value:

Object User

getUserRole

Gets user by role.

Parameters:

id: Number user’s ID.

Return Value:

Number user’s role.

getUsers

Gets all users in a room.

Parameters:

undefined

Return Value:

[Object] User all users.

getSelf

Gets Self object.

Parameters:

undefined

Return Value:

Object Self Account.

setSetting

Sets a personal setting.

Parameters:

key: String key setting name.

value: * value to set.

callback: function called when data was saved.

callback:

err: Object possible error returned.

Return Value:

Boolean true when save went to server.

getSetting

Gets a personal setting.

Parameters:

key: String key setting name.

Return Value:

* value saved at key.

getSettings

Gets all personal settings.

Parameters:

undefined

Return Value:

Object Settings’ object.

isFriend

Checks if user is a friend.

Parameters:

id: Number user’s ID.

Return Value:

Boolean true when befriended.

getDJ

Gets the DJ.

Parameters:

undefined

Return Value:

Object User

getMedia

Gets the Media.

Parameters:

undefined

Return Value:

Object Media

getStartTime

Gets the Media start time.

Parameters:

undefined

Return Value:

String start time. Ex.: “2017-01-01T00:00:00.000000Z”

getBooth

Gets the Booth.

Parameters:

undefined

Return Value:

Object Booth

getRoom

Gets the Room.

Parameters:

undefined

Return Value:

Object Room

getRoomMeta

Gets the Metadata of a Room.

Parameters:

undefined

Return Value:

Object Metadata

getRoomName

Gets the name of a Room.

Parameters:

undefined

Return Value:

String Room’s name.

getFX

Gets FX data.

Parameters:

undefined

Return Value:

[String] FX settings.

checkGlobalRole

Rectifies the given role. There’s several roles but only 3 are set for the UI namely:

• NONE
• BRAND_AMBASSADOR
• ADMIN

Parameters:

role: Number global role.

Return Value:

Number rectified level.

getHostName

Gets host name.

Parameters:

undefined

Return Value:

String Host’s name.

getHostID

Gets host ID.

Parameters:

undefined

Return Value:

Number Host’s ID.

getPopulation

Gets population of a room.

Parameters:

undefined

Return Value:

Number Amount of users connected.

getGuests

Gets the number of guests.

Parameters:

undefined

Return Value:

Number Guests connected.

getMinChatLevel

Gets the minimum chat level.

Parameters:

undefined

Return Value:

Number Minimumin chat level.

isFavorite

Checks if room is favorited.

Parameters:

undefined

Return Value:

Boolean true when favorited.

getDescription

Gets the description.

Parameters:

undefined

Return Value:

String Room’s description.

getWelcomeMessage

Gets the welcome message.

Parameters:

undefined

Return Value:

String Room’s welcome message.

getSlug

Gets the slug.

Parameters:

undefined

Return Value:

String Room’s slug.

getWaitlist

Gets the waitlist.

Parameters:

undefined

Return Value:

[Number] Waitlist in ascending order.

isWaitlistLocked

Checks if the waitlist is locked.

Parameters:

undefined

Return Value:

Boolean true when waitlist is locked.

doesWaitlistCycle

Checks if the waitlist cycles.

Parameters:

undefined

Return Value:

Boolean true when waitlist cycles.

getVotes

Gets all votes.

Parameters:

withUserObject: Boolean replaces IDs with User objects.

Return Value:

[Number]|[Vote] number array when param is false, object array otherwise.

getGrabs

Gets all grabs.

Parameters:

undefined

Return Value:

[Number][Object] User number array when param is false, object array otherwise.

cacheUser

Saves a User.

Parameters:

user: Object User

Return Value:

Boolean true when saved, false when user is already cached.

removeCachedUserById

Removes a User from cache.

Parameters:

id: Number user’s ID.

Return Value:

Boolean true when the user was found and removed.

removeCachedUserByUsername

Removes a User from cache.

Parameters:

username: String

Return Value:

Boolean true when the user was found and removed.

getStaffOnline

Gets staff online.

Parameters:

undefined

Return Value:

[Object] User Staff online.

getStaffOnlineByRole

Gets staff online by role.

Parameters:

role: Number USERROLE staff by role.

Return Value:

[Object] User staff currently online with role specified.

getStaffByRole

Gets all staff by role.

Parameters:

role: Number USERROLE staff by role.

callback: function called on retrieval.

callback:

err: Object possible error returned.

staff: [User]

Return Value:

undefined

getNews

Gets news.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

news: [News]

Return Value:

undefined

getAuthToken

Gets auth token.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

token: String auth token.

Return Value:

undefined

getRoomStats

Gets room stats.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

room: Room

Return Value:

undefined

findRooms

Finds paginated results of rooms.

Parameters:

page: Number zero based index.

limit: Number amount of rooms per page.

callback: function called on retrieval.

callback:

err: Object possible error returned.

rooms: [FlatRoom]

Return Value:

undefined

getRoomList

Gets unfiltered paginated results of rooms.

Parameters:

page: Number zero based index.

limit: Number amount of rooms per page.

callback: function called on retrieval.

callback:

err: Object possible error returned.

rooms: [FlatRoom]

Return Value:

undefined

getStaff

Gets staff members.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

staff: [User]

Return Value:

undefined

getUser

Gets a user.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

user: User

Return Value:

undefined

getRoomHistory

Gets room history.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

history: [History]

Return Value:

undefined

validateRoomName

Validates a room name.

Parameters:

name: String name to be validated.

callback: function called on retrieval.

callback:

err: Object possible error returned.

slug: String url conform representation of room name.

Return Value:

undefined

validateUsername

Validates a username.

Parameters:

name: String name to be validated.

callback: function called on retrieval.

callback:

err: Object possible error returned.

slug: String url conform representation of name.

Return Value:

undefined

getMutes

Gets mutes.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

mutes: [Mute]

Return Value:

undefined

getBans

Gets bans.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

bans: [Ban]

Return Value:

undefined

saveSettings

Saves settings.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setLock

Sets up a lock.

Parameters:

lock: Boolean should waitlist be locked?

removeAllDJs: Boolean remove all users in waitlist?

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setCycle

Decides cycle mode.

Parameters:

shouldCycle: Boolean should waitlist cycle?

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

resetPassword

Sends a request to the server to reset the account’s password.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

requestUsers

Gets users in bulk.

Parameters:

ids: [Number] user IDs.

callback: function called on retrieval.

callback:

err: Object possible error returned.

users: [User]

Return Value:

undefined

joinRoom

Joins a room.

Parameters:

slug: String room name.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

joinWaitlist

Joins the waitlist.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

addToWaitlist

Adds a user to the waitlist.

This fires the WAITLIST_UPDATE event indirectly.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

addPlaylist

Creates a new playlist with media objects.

Parameters:

name: String playlist name.

media: [Object] Media media to add.

callback: function called on retrieval.

callback:

err: Object possible error returned.

playlist: Playlist

Return Value:

undefined

grab

Grabs media.

Parameters:

id: Number playlist ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

playlist: Playlist

Return Value:

undefined

skipDJ

Skips the DJ.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

moveDJ

Moves a user in the waitlist.

Parameters:

id: Number user’s ID.

position: Number zero based index with zero being the first

position.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

createRoom

Creates a new room.

Parameters:

name: String room name.

unlisted: Boolean makes room private.

callback: function called on retrieval.

callback:

err: Object possible error returned.

room: NewRoom info of new room.

Return Value:

undefined

sendSOS

Sends an SOS to the admins and global moderators of plug.dj

Note

Please keep in mind that this is a function with power and should be used only in a real emergency. Don’t just spam this function at your leisure.

Parameters:

message: String message send to moderators.

callback:

err: Object possible error returned.

Return Value:

undefined

updateRoomInfo

Updates the room info.

This fires the ROOM_DESCRIPTION_UPDATE event indirectly.

Parameters:

name: String room name.

description: String room description.

welcome: String welcome message shown on entrance.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setMinChatLevel

Sets the room’s minimum chat level.

This will raise the ROOM_MIN_CHAT_LEVEL_UPDATE event.

Parameters:

level: Number level required to chat.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

banUser

Bans a user.

This will raise the USER_LEAVE and MOD_BAN event indirectly.

Parameters:

id: Number user’s ID.

time: Enum BANDURATION duration of ban.

reason: Enum REASON reason of ban.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

banBooth

Bans a user from the booth.

This will raise the WAITLIST_UPDATE as well as the ADVANCE event indirectly.

Parameters:

id: Number user’s ID.

time: Enum BOOTHBANDURATION duration

of ban.

reason: Enum BOOTHBANREASON reason of

ban.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

deleteBanBooth

Removes a previously registered ban.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

muteUser

Mutes a user.

Parameters:

id: Number user’s ID.

time: Enum MUTEDURATION duration of mute.

reason: Enum REASON reason of mute.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

addStaff

Adds a user to staff.

This will raise the USER_UPDATE event.

Parameters:

id: Number user’s ID.

role: Enum USERROLE role to give.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

ignoreUser

Ignores a user.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

ignored: Ignore ignored user.

Return Value:

undefined

deletePlaylist

Deletes a playlist.

Parameters:

id: Number playlist to delete.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

removeIgnore

Unignores a user.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

unignored: Ignore unignored

user.

Return Value:

undefined

removeStaff

Removes a user from staff.

This will raise the USER_UPDATE event.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

removeDJ

Removes a DJ.

This will raise the WAITLIST_UPDATE and ADVANCE event indirectly.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

leaveWaitlist

Leaves the waitlist.

This will raise the WAITLIST_UPDATE event indirectly.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

unbanUser

Unbans a user.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

unmuteUser

Unmutes a user.

Parameters:

id: Number user’s ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

deleteMessage

Deletes a message.

This will raise the CHAT_DELETE event.

Parameters:

cid: Number message ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

logout

Logs the account out.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

requestSelf

Request the account info.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

self: [Self]

Return Value:

undefined

getMyHistory

Gets the account play history.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

history: [History]

Return Value:

undefined

getFriends

Gets the account’s friends.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

friends: [User]

Return Value:

undefined

getFriendRequests

Gets the account’s friend request.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

requests: [Invitation]

Return Value:

undefined

findPlaylist

Finds personal playlists.

Parameters:

query: String keywords to look for.

callback: function called on retrieval.

callback:

err: Object possible error returned.

playlist: [Playlist]

Return Value:

undefined

findMedia

Finds media in all playlists.

Parameters:

query: String keywords to look for.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media]

Return Value:

undefined

findMediaPlaylist

Finds media in a playlist.

Parameters:

id: Number playlist to use for search.

query: String keywords to look for.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media]

Return Value:

undefined

getPlaylist

Gets playlist.

Parameters:

id: Number playlist to retrieve.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media]

Return Value:

undefined

getPlaylists

Gets all playlists.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

playlists: [Playlist]

Return Value:

undefined

getIgnores

Gets ignores.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

users: [Ignore] ignored users.

Return Value:

undefined

getFavoriteRooms

Gets favorite rooms.

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

rooms: [FlatRoom] favorited rooms.

Return Value:

undefined

setProfileMessage

Sets profile message.

Parameters:

message: String profile message.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

renamePlaylist

Renames a playlist.

Parameters:

id: String playlist to rename.

name: String new name.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setAvatar

Sets avatar.

Parameters:

id: String avatar to set.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setBadge

Sets badge.

Parameters:

id: String badge to set.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

setLanguage

Sets language.

Parameters:

language: String ISO 3166-2 country code.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

rejectFriendRequest

Rejects a user’s friend request.

Parameters:

id: Number user to reject.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

activatePlaylist

Sets a playlist to play from.

Parameters:

id: Number playlist to set.

callback: function called on retrieval.

callback:

err: Object possible error returned.

activated: String ID of activated playlist.

Return Value:

undefined

moveMedia

Moves media in a playlist.

Parameters:

id: Number playlist in which the media resides.

media: [Number] media to move.

beforeID: Number where to insert the media at.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media] order after move.

Return Value:

undefined

updateMedia

Updates a media item’s info.

Parameters:

id: Number playlist in which the media resides.

mediaID: Number media to edit.

author: String media author like artist.

title: String media title like song title.

callback: function called on retrieval.

callback:

err: Object possible error returned.

update: [Update]

Return Value:

undefined

shufflePlaylist

Shuffles a media item in a playlist.

Parameters:

id: Number playlist to shuffle.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media] order after shuffle.

Return Value:

undefined

addFriend

Adds a user as a friend.

Parameters:

id: Number user to add as friend.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

deleteMedia

Deletes a media item in a playlist.

Parameters:

id: Number playlist in which the media resides.

mediaIDs: [Number] media to delete.

callback: function called on retrieval.

callback:

err: Object possible error returned.

media: [Media] in playlist after deletion.

Return Value:

undefined

addMedia

Adds media to a playlist.

Parameters:

id: Number playlist to add the media to.

media: [Object] media objects to add.

append: Boolean append media to the end.

callback: function called on retrieval.

callback:

err: Object possible error returned.

mediaAdd: MediaAdd

Return Value:

undefined

woot

Woots the media (upvote).

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

meh

Mehs the media (downvote).

Parameters:

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

favoriteRoom

Favorites the room you are currently connected to.

Parameters:

id: Number room ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

removeFriend

Removes a user as a friend.

Parameters:

id: Number user ID.

callback: function called on retrieval.

callback:

err: Object possible error returned.

Return Value:

undefined

purchaseUsername

Purchases a username from the store.

Parameters:

username: String name to purchase.

callback: function called on retrieval.

callback:

err: Object possible error returned.

item: Purchase

Return Value:

undefined

purchaseItem

Purchases an item from the store.

Parameters:

id: String item to purchase.

callback: function called on retrieval.

callback:

err: Object possible error returned.

item: Purchase

Return Value:

undefined

removeChatMessage

Removes a message.

Note

you have to enable cacheChat first! Otherwise you won’t be able to delete any messages since plugged has no record of them.

Parameters:

cid: String unique message ID.

cacheOnly: Boolean clears only the cache when true.

Return Value:

Boolean whether the message was deleted

removeChatMessagesByUser

Removes all messages of a user.

Note

you have to enable cacheChat first! Otherwise you won’t be able to delete any messages since plugged has no record of them.

Parameters:

username: String name of a user.

cacheOnly: Boolean clears only the cache when true.

Return Value:

Boolean whether the messages were deleted

watchUserCache

Enables time based cleanup of cached users.

Default time is 5 minutes.

Parameters:

enable: Boolean boolean value indicating state.

Return Value:

undefined