Simple WebSocket EventEmitter library.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Simple WebSocket EventEmitter library.



const plugSocket = require('plug-socket')
const authToken = '(...)' // get one by GET-ing

let socket = plugSocket(authToken)
// events will be fired on "socket" for every incoming message
socket.on('chat', msg => log(`<${msg.un}>  ${msg.message}`))
socket.on('userJoin', msg => log(`  * ${msg.un} joined the room`))
socket.on('plugMaintenanceAlert', () => log('#ded soon… ×.×'))


let socket = plugSocket(?authToken)

Sets up a WebSocket connection to If the auth token is given, it also sends an "auth" message once the connection is open. Otherwise, you'll have to send that yourself.

socket is a WebSocket connection instance with a few extra methods and a bunch of extra events.


Sends an auth token. You should only call this once, and only if you did not pass one to the plugSocket() call.

You can obtain an auth token by logging in to using something like plug-login, or by manually sending a GET request to

const plugSocket = require('plug-socket')

// Using `plug-login`'s authToken option:
const plugLogin = require('plug-login')
plugLogin(myEmail, myPassword, { authToken: true }).then((result) => {
  const sock = plugSocket(result.token)

// Or manually, with a cookie stored in `mySessionCookie`:
const got = require('got')
got('', {
  json: true,
  // Make
  headers: { cookie: mySessionCookie }
}).then((response) => {
  const authToken =[0]
  const sock = plugSocket(authToken)

Sends a chat message to the current room. Make sure to join a room first by sending a POST request to'', {
  json: true,
  headers: {
    cookie: mySessionCookie,
    'content-type': 'application/json'
  body: JSON.stringify({
    slug: 'my-room-slug'
}).then((response) => { /* joined! */ })


Aside from the standard WebSocket events, plug-socket also emits different events for all message types. These are:

[ "ack", "advance", "ban", "banIP", "chat", "chatDelete", "djListCycle"
, "djListLocked", "djListUpdate", "earn", "sub", "cash", "gift", "floodChat"
, "floodAPI", "friendRequest", "friendAccept", "gifted", "grab", "killSession"
, "modBan", "modAddDJ", "modRemoveDJ", "modMoveDJ", "modMute", "modSkip"
, "modStaff", "nameChanged", "nameChangedRoom", "notify", "playlistCycle"
, "plugMaintenance", "plugMaintenanceAlert", "plugMessage", "plugUpdate"
, "rateLimit", "roomNameUpdate", "roomDescriptionUpdate", "roomWelcomeUpdate"
, "roomMinChatLevelUpdate", "skip", "userJoin", "userLeave", "userUpdate"
, "vote" ] events receive two arguments, param and slug. param is usually an object, or undefined for some events. The slug parameter contains the current room slug or "dashboard". When you switch rooms, sometimes you'll keep receiving a few events from your previous room, so the slug parameter allows you to filter those. You won't have to care for it if your app doesn't switch rooms much.

socket.on('chat', (param, slug) => {
  log(`${slug}: receiving`, param)

You can also handle every event by adding an "action" listener:

socket.on('action', (type, param, slug) => {
  // `type` is one of the events listed above.
  log(`${slug}: receiving a "${type}" event with`, param)

Most events are documented in more detail in the PlugCommunity Documentation repository.


Tests use mocha. All tests depend on being online and reachable, so you might get test failures if it's slow, or in maintenance mode, or shut down for a few months.