PircBot Java IRC Bot

The most popular Java IRC API

Download PircBot 1.5.0 (about 200kb)

PircBot Java IRC API Resources

PircBot Javadoc Documentation
PircBot Tutorial Video (New)
PircBot Developers' FAQ
PircBot Change Log
PircBot Implementations
PircBot lecture slides (PowerPoint)
PircBot lecture slides (PDF 6-per-page)
PircBot Forums (external link)

Java IRC API

PircBot is a Java framework for writing IRC bots quickly and easily. Its features include an event-driven architecture to handle common IRC events, flood protection, DCC resuming support, ident support, and more. Its comprehensive logfile format is suitable for use with pisg to generate channel statistics. Full documentation is included, and this page contains a 5-minute step-by-step guide to making your first IRC bot.

PircBot allows you to perform a variety of fun tasks on IRC, but it is also used for more serious applications by the US Navy, the US Air Force, the CIA (unconfirmed), several national defence agencies, and inside the Azureus bittorrent client. But don't let that put you off - it's still easy to use!

Using the PircBot Java IRC API package

The download link at the top points at a zip file that contains the pircbot.jar archive and associated documentation. When compiling or running your own Bot that makes use of the pircbot package, you must be sure to include the pircbot.jar file in your classpath.

How to make an IRC Bot

The pircbot package contains (amongst others) an abstract class named PircBot. Because this is abstract, it means that you cannot create an instance of it, but you can extend it and inherit its functionality. Please read on if you want to go through a step by step guide to making your first IRC Bot based on PircBot.

Step by step guide to making an IRC Bot

In this example, we shall take you through how to make an IRC Bot that responds to a simple command. This should take no more than 5 minutes if you work fast. It will send a message to the channel saying what the local time is whenever someone says "time".

First, let's create a directory in which we can store the code for your IRC Bot. For this example, we shall be using c:\mybot\

Download the PircBot jar archive (see above) and save this in c:\mybot\

We now need to create our own IRC Bot by extending the functionality of PircBot. We can do this by creating MyBot.java in our directory (note that Java is case sensitive). To extend the PircBot without introducing any of our own functionality, all we need to do is put the following in the file named MyBot.java: -

MyBot.java

import org.jibble.pircbot.*;

public class MyBot extends PircBot {
    
    public MyBot() {
        this.setName("MyBot");
    }
    
}

Note that in the constructor, we are setting the name of our Bot to "MyBot". This is the name that our Bot will try to use when it joins an IRC Server.

Now, to actually run our IRC Bot, we need to have a main method. We will put this main method in a separate class in a file called MyBotMain.java. We will also use this main method to instruct our Bot to connect to a server and join a channel. For this example, we will be telling our Bot to join the IRC server irc.freenode.net and then to join the channel called #pircbot.

Please note that the IRC server used in this example tries to check the identity of the user of the PircBot process before it is allowed to connect. Be patient, as it may take a minute or two to connect to the server if it is unable to complete this check.

MyBotMain.java

import org.jibble.pircbot.*;

public class MyBotMain {
    
    public static void main(String[] args) throws Exception {
        
        // Now start our bot up.
        MyBot bot = new MyBot();
        
        // Enable debugging output.
        bot.setVerbose(true);
        
        // Connect to the IRC server.
        bot.connect("irc.freenode.net");

        // Join the #pircbot channel.
        bot.joinChannel("#pircbot");
        
    }
    
}

That's great so far. Now, if we were to try and compile and run the main method, our Bot would try and connect to the IRC server and then join the #pircbot channel. We now need to add something to the MyBot class to get it to respond to events. In this example, we were going to try and get it to send a message containing the current time to the #pircbot channel whenever somebody says "time". To respond to events, we can override methods in the PircBot abstract class. To send messages, we can use methods that are also defined in the PircBot abstract class.

You may notice that our main method is declared to throw an Exception. We have done this in our example just to keep the total amount of code small. A better way of handling exceptions (if you have time) is to explicitly catch the IOException, IrcException or NickAlreadyInUseException that may be thrown when trying to join an IRC Server.

Anyway, to complete the functionality of our IRC Bot, we simply add a new method to our MyBot class: -

MyBot.java (version 2)

import org.jibble.pircbot.*;

public class MyBot extends PircBot {
    
    public MyBot() {
        this.setName("MyBot");
    }
    
    public void onMessage(String channel, String sender,
                       String login, String hostname, String message) {
        if (message.equalsIgnoreCase("time")) {
            String time = new java.util.Date().toString();
            sendMessage(channel, sender + ": The time is now " + time);
        }
    }
}

The onMessage method that we are now using in MyBot.java overrides a method of the same signature in the PircBot abstract class. This method will be called whenever somebody sends a message to a channel. Notice that our Bot could run in multiple channels if it wanted to, as the channel name is given as a parameter in this method. Inside our onMessage method, we check to see if somebody said "time", and if they did, we reply to the same channel.

Running our IRC Bot

If you have not got a Java SDK installed already, then you will need to install this before you can run the bot. Please read this guide on How to set up Java if you need help.

To compile our example IRC Bot, you will need to open a command prompt and navigate to the directory containing the code. Assuming you have Java correctly set up, you can then compile the Bot by issuing the following command: -

javac -classpath pircbot.jar;. *.java

If all went okay, then you can run the IRC Bot by typing: -

java -classpath pircbot.jar;. MyBotMain

(Note that on UNIX/Linux, you should use ':' instead of ';') When the Bot runs, you will see it outputting information from the server. You should now be able to open your own IRC client and join the channel that the Bot is in. If you say "time" then the Bot should reply to the channel, wahey!

Adding further features

If the above example has given you some more ideas for features that you could put into your own IRC Bot, then you might like to have a read of the documentation for PircBot. This details all of the available methods and event handlers in the PircBot class.

Detailed examples for making lots of bots can be found in the O'Reilly book IRC Hacks. This is recommended reading for anyone who wants to make IRC bots!

Using PircBot

If you use PircBot, it would be nice if you could help me by doing the following:-

Please email me to let me know that you are using it. Let me know what you are using it for and where it can be seen in use - interesting submissions will then be included on the PircBot Implementations page!
If you document your IRC Bot on the web, it would be nice if you could create a hyperlink to this web page.

Some bots based on the PircBot framework

This section has grown a little too big to fit comfortably on this page. You may now find a list of some IRC Bots based on this framework on the PircBot Implementations page.

Revision history

This section is also now located on a separate page. Please visit the PircBot Change Log to see what changes have been made in the current version.

Miscellaneous jibble

PircBot has been designed so that it will work on Java Virtual Machine versions as low as 1.1, making it runnable on smaller handheld devices such as iPAQs. To demonstrate the versatility of the PircBot package, I have also written a graphical IRC client suitable for use on the iPAQ and other similar devices which have restrictive JVMs. After all, an IRC client is just an IRC bot with a bit of human interaction...

PircBot is written in pure Java, so it will run on any operating system that has a Java Virtual Machine.

If you wish to commission me to make a custom IRC bot for you, then please contact me. As the author of PircBot, I believe I can rapidly produce anything to meet your needs.

Please send all feature requests, feedback and bug reports to the email address at the bottom of this page.

Licensing

This software product is OSI Certified Open Source Software, available under the GNU General Public License (GPL). Since the GPL may be too restrictive for use in proprietary applications, a commercial license is also provided.

Purchase a commercial license for this software.

Search this site