coffea documentation/api

NPM version (>=0.4) Build Status Dependencies Documentation Status Code Climate

event based and extensible nodejs irc client library with multi-network support

For support, report an issue on github or join our IRC channel at #caffeinery @

If you want to support coffea, please consider donating (it helps me keeping the project active and alive!):


This is all the code needed to get you started with coffea!

 var client = require('coffea')(['', '']); // or put just one network as a string

 client.on('motd', function (event) {
     client.join(['#foo', '#bar', '#baz'],;

 client.on('message', function (event) {
     console.log('[' + + '][' + + '] ' + event.user.getNick() + ': ' + event.message);
     //[freenode][#foo] nick: message
     event.reply(event.message); // I'm a parrot

client.on('command', function (event) {
    if (event.cmd === 'ping') { // respond to `!ping SOMETHING` with `SOMETHING`, or `pong`, if SOMETHING is not specified
        event.reply(event.args.length > 0 ? event.args.join(' ') : 'pong');


For an extensive guide on getting started with coffea, make sure to read Writing an IRC Bot with JavaScript/Node.js and coffea on medium:

with ssl

If you want to enable SSL for a connection, you have to use a network config object when connecting:

var client = require('coffea')({
    host: '',
    ssl: true,
    // ssl_allow_invalid: true // uncomment this if the server has a self signed certificate, make sure to listen on('ssl-error') to catch bad certificates

full config

For multiple networks, use a JavaScript array with multiple config objects inside.

var client = require('coffea')({
    host: '',
    port: 6667, // default value: 6667
    ssl: false, // set to true if you want to use ssl
    ssl_allow_invalid: false, // set to true if the server has a custom ssl certificate
    prefix: '!', // used to parse commands and emit on('command') events, default: !
    channels: ['#foo', '#bar'], // autojoin channels, default: []
    nick: 'test', // default value: 'coffea' with random number
    username: 'test', // default value: username = nick
    realname: 'test', // default value: realname = nick
    pass: 'sup3rS3cur3P4ssw0rd', // by default no password will be sent
    nickserv: {
        username: 'test',
        password: 'l33tp455w0rD'
    throttling: 250 // default value: 250ms, 1 message every 250ms, disable by setting to false


Make sure to listen to error events to see possible errors/warnings:

client.on('error', function (err, event) {
    console.log(, err.stack);

You can also add the err parameter to any event listener (change from function (event) to function (err, event):

client.on('whois', function (err, event) {
    if (err) console.log("WHOIS ERROR:", err.stack);
    console.log("whois:", event);

configuration file

Using a configuration file for your bot is super easy with coffea! First, create config.json and paste your current configuration. (Make sure to change key: 'something' to "key": "something" as we’re dealing with JSON now, e.g. host: '' -> "host": "")

Then, simply do:

var client = require('coffea')(require('./config.json'));

config.json with full config

    "host": "",
    "port": 6667,
    "ssl": false,
    "ssl_allow_invalid": false,
    "prefix": "!",
    "channels": ["#foo", "#bar"],
    "nick": "test",
    "username": "test",
    "realname": "test",
    "pass": "sup3rS3cur3P4ssw0rd",
    "nickserv": {
        "username": "test",
        "password": "l33tp455w0rD"
    "throttling": 250


The best way to get started with coffea is playing around with it! You can use the Index to get a list of functions and events you can make use of.

coffea function: A function called with client.function() if coffea was imported to client (see Quickstart)


coffea event: You can listen to an event by defining an event listener like this (make sure to replace event with the event name):

client.on('event', function (event) {
    console.log(event); // do something with event here

Go to API reference or browse the API by…