‚̧Nauseating Packaged Meat
    Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/plugapi package


    plugAPI Build Status npm version npm downloads NPM David Discord Server


    A generic NodeJS API for creating plug.dj bots.

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

    How to use

    Run the following:

    npm install plugapi

    You can choose to instantiate plugAPI with either Sync or Async:


    const PlugAPI = require('plugapi');
    const bot = new PlugAPI({
        email: '',
        password: ''
    bot.connect('roomslug'); // The part after https://plug.dj
    bot.on(PlugAPI.events.ROOM_JOIN, (room) => {
        console.log(`Joined ${room}`);


    const PlugAPI = require('plugapi');
    new PlugAPI({
        email: '',
        password: ''
    }, (err, bot) => {
        if (!err) {
            bot.connect('roomslug'); // The part after https://plug.dj
            bot.on(PlugAPI.events.ROOM_JOIN, (room) => {
                console.log(`Joined ${room}`);
        } else {
            console.log(`Error initializing plugAPI: ${err}`);

    New features in V5.0.0

    Guest login is now possible if no userdata is passed into plugAPI or guest is set to true


    const PlugAPI = require('plugapi');
    const bot = new PlugAPI();
    // OR
    const bot = new PlugAPI({
        guest: true

    Facebook login is now possible. Easiest way to obtain the Access Token and user ID is to login via fb on plug and view the request data.


    const PlugAPI = require('plugapi');
    const bot = new PlugAPI({
        facebook: {
            accessToken: 'xxxxxxxx',
            userID: 'xxxxxxxx'

    PlugAPI now uses tough-cookie to store cookies. Refer to the wiki for more information.


    Here are some bots that are using this API.

    Botname Room
    AuntJackie Mix-N-Mash
    BotX NightCore Fanclub
    BeavisBot I <3 the 80's and 90's
    brainbot 5M4R7
    Charlotte Youtunes
    -DnB- Drum & Bass
    DRPG Discord Dungeons
    Ekko EDT
    F!shtank SWaQ Hanger
    FlavorBar Flavorz
    FoxBot Approaching Nirvana
    Holly Refbots Connect The Songs (Read Info!)
    KawaiiBot AnimeMusic
    prehibicja [PL] Prohibicja.xyz ANY GENRE
    QBot EDM Qluster
    Skynet Cubed PlugCubed
    TFLBot The F**k Off Lounge | TFL
    Toaster-chan ‚ėÜ ‚ô• Nightcore-331 ‚ô• ‚ėÜ

    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(PlugAPI.events.CHAT, (data) => {
        if (data.type === 'emote') {
            console.log(data.from + data.message);
        } else {`
            console.log(`${data.from} > ${ data.message}`);

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

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

    API Documentation

    For V4 documentation, the Wiki is the best resource.

    For V5 documentation, please refer to the Docs for documentation on methods and events. The documentation is written in JSDoc in the respective files found in the lib/ folder. If there are changes to be made, edit the JSDoc and run the followng command:

    npm run docs

    Submit a pull request and wait for review


    1. Clone repository to an 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 codestyle.
    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 repository.

    Misc Options

    Multi line chat

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

    Delete Message Blocks

    With how plug currently works, deleting messages deletes the entire group of messages from the same user. Set this option to disallow that.

    Delete All Chat

    PlugAPI mimics plug's behavior in disallowing deletion of chat of users above the bot's rank. Setting this option to true will bypass that check.

    var bot = new PlugAPI(auth);
    bot.deleteMessageBlocks = false; //set to true if you want the bot to not delete grouped messages. Default is false.
    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.


    npm i plugapi

    DownloadsWeekly Downloads






    Unpacked Size

    2.03 MB

    Total Files


    Last publish


    • avatar
    • avatar
    • avatar