node package manager


plugAPI Build Status npm version npm downloads NPM David


A generic NodeJS API for creating bots.

Originally by Chris Vickery, now maintained by TAT and The plug³ Team.

NOTE: Currently not supporting facebook login.

How to use

Run the following:

npm install plugapi --production

You can choose to instantiate plugAPI with either Sync or Async


var PlugAPI = require('plugapi');
var bot = new PlugAPI({
    email: '',
    password: ''
bot.connect('roomslug'); // The part after 
bot.on('roomJoin', function(room) {
    console.log("Joined " + room);

Async 3.5.0 and Below:

var PlugAPI = require('plugapi');
new PlugAPI({
    email: '',
    password: ''
}, function(bot) {
    bot.connect('roomslug'); // The part after 
    bot.on('roomJoin', function(room) {
        console.log("Joined " + room);

Async 4.0.0:

var PlugAPI = require('plugapi');
new PlugAPI({
    email: '',
    password: ''
}, function(err, bot) {
    if (!err) {
        bot.connect('roomslug'); // The part after 
        bot.on('roomJoin', function(room) {
            console.log("Joined " + room);
    } else {
        console.log('Error initializing plugAPI: ' + err);


Here are some bots that are using this API.

Botname Room
AuntJackie Mix-N-Mash
BeavisBot I <3 the 80's and 90's
-DnB- Drum & Bass
FlavorBar Flavorz
FoxBot Approaching Nirvana
TFLBot The F**k Off Lounge | TFL
QBot EDM Qluster
Holly Refbots Connect The Songs (Read Info!)

Have a bot that uses the API? Let us know!


You can listen on essentially any event that plug emits.

// basic chat handler to show incoming chats formatted nicely 
bot.on('chat', function(data) {
    if (data.type == 'emote')
        console.log(data.from + data.message);
        console.log(data.from + "" + data.message);

Here's an example for automatic reconnecting on errors / close events!

var reconnect = function() { bot.connect(ROOM); };
bot.on('close', reconnect);
bot.on('error', reconnect);


Please Refer to the Wiki for both the Events and Actions.


  1. Clone repository to empty folder.
  2. Cd to the folder containing the repository.
  3. Run npm install to set up the environment.
  4. Edit your changes in the code, and make sure it follows our Style Guidelines.
  5. Run npm test to make sure all tests pass.
  6. After it's bug free, you may submit it as a Pull Request to this repo.


Multi line chat

Since cuts off chat messages at 250 characters, you can choose to have your bot split up chat messages into multiple lines:

var bot = new PlugAPI(auth);
bot.deleteAllChat = false; // Set to true to enable deletion of chat regardless of role . Default is false 
bot.multiLine = true; // Set to true to enable multi line chat. Default is false 
bot.multiLineLimit = 5; // Set to the maximum number of lines the bot should split messages up into. Any text beyond this number will just be omitted. Default is 5. 


We have a Slack channel we use to communicate. Please email if you'd like to be added