IRC Bot Application

Last modified by Admin on 2022/02/28 00:10

status_onlineUI for the IRC Bot Application
Developed by

Vincent Massol, XWiki Development Team

Active Installs0
1 Votes
LicenseGNU Lesser General Public License 2.1

Till version 8.1, this application could be installed on XWiki 7.4.2+
Starting with version 8.2, it requires XWiki 8.2.1+

Installable with the Extension Manager


When you install this IRC Bot application it registers itself automatically in the Applications Panel:


The IRC Bot sports the following features.

Logging the IRC channel

Whenever a message is sent to the IRC Channel it's logged in a wiki page for archiving and later perusal.



Wiki Activity notification

Whenever a wiki page is modified in the wiki (or in any subwiki if it's a multiwiki setup) a notification about the modification is sent to the IRC Channel, allowing to see in real time the activity of the wiki. This is useful to keep abreast of what's happening in the wiki, help users having difficulties or simply revert spam as it happens...


The application recognizes XAR import events and when receiving one, it doesn't send subsequent IRC notifications for modified or created documents to avoid spamming the IRC channel.


List all Commands available

Type !help in the IRC channel and the Bot will list all commands available.


Note that it's possible to add new commands easily by creating a new Bot Listener in a wiki page.

Wiki News

Type !news and you'll get the last 4 pages modified in your wiki (see the configuration section below to configure which wikis are taken into account).


Wiki Search

Type !search <search token> and you'll get the top 4 pages matching the specified token.



Whenever you type some text containing a JIRA key id, the Bot will talk to the configured JIRA server to gather information about the concerned issue and will print its detail.


JIRA Search

Type !jira <search token> and you'll get the top 4 JIRA issues matching the specified token.


Broken Links Notifications

Whenever a broken link is viewed by someone in the wiki, a notification is sent to the IRC Channel. The idea is to make it clearly visible where are the broken links in the wiki and have contributors to the wiki fix them as soon as possible. It's possible to deactivate this feature (see the configuration section below).


Type !bl and you'll get the latest 4 broken links found in the wiki.



You'll need to be logged in with a user registered on the main wiki and having Admin rights on the main wiki in order to be able to start and stop the Bot. In addition, some Bot Listeners require Programming Rights to execute properly and thus when installing the IRC Bot Application it's preferable to use a user having Programming Rights.

Starting and Stopping the Bot

The Bot can be stared and stopped from the Command Center which is located at IRC.IRCBot:


A link to the Command Center is also available from the IRC Home Page:


When the Bot is started all the Bot Listeners defined in wiki pages are also started and when the Bot is stopped they are stopped. The Bot listeners defined in Java as Components are always started but can be made inactive by configuring them (see more below for configuration).

Scheduler Job

There's an optional Scheduler Job that you'll need to schedule once. When active this Job will automatically start the IRC Bot when the XWiki Server is started or more generally if the IRC Bot is found to be disconnected.


Also note that there's a special Bot Listener registered, called the Auto Reconnect Bot Listener which will automatically try to reconnect the Bot to the IRC Channel whenever it gets disconnected. It will try and retry every 30 seconds indefinitely.


All configuration is done from the IRC.IRCConfiguration page and currently modifying the configuration means editing this page with the Object Editor.

Configuration for the Bot


Configuration data available:

  • Bot Name: Name of the bot as it appears in the IRC Channel
  • Server: Name of the IRC Server to connect to
  • Channel: Name of the IRC Channel to connect to on that Server
  • Password: This is optional and when specified the password specified will be used to identify agains the IRC Server. Some IRC Networks (such as freenode) require users to register and identify with NickServ before they are able to send private messages to other users, thus reducing the amount of spam. 
  • Inactive: The Bot can be marked inactive and this is done automatically when stopping the Bot in the Command Center. Starting the Bot in the Command Center will automatically set the Bot as active again. If the Bot is marked active and it's disconnected the Scheduler will automatically restart it. In addition whenever the XWiki server is restarted the Bot will be automatically restarted too. If it's marked as inactive this won't happen.

Configuration for the Logging Bot Listener


Configuration data available:

  • Page: Name of the page in which the Logging Bot Listener will save the messages coming from the IRC Channel. By default the page name is computed based on the current date and the channel the Bot is connected to: IRC.<channel name>Archive<date>. For example: IRC.xwikiArchive20120321

Configuration for the JIRA Bot Listeners

The JIRA Id Bot Listener and the JIRA Search Bot Listeners shared the same configuration:


Configuration data available:

  • JIRA URL: The URL of the JIRA server from which to get information from
  • JIRA Pattern: The pattern (regex format) of JIRA issues that the JIRA Id Bot Listener recognize and for which is prints details about the specified issue. By default it recognizes tokens in the format: uppercase letters followed by a dash ("-") followed by number. For example: XWIKI-1000

Configuration for the Wiki News Bot Listener


Configuration data available:

  • Wikis: The comma-separated list of wikis for which news should be returned. If not specified then news for all the wikis will be returned.

Configuration for the Documents Modified Event Listener


Configuration data available:

  • Exclusion Pattern: A regex specifying which modified created or modified shouldn't generate a notification sent to the IRC Channel. By default all Archives pages created by the Logging Bot Listener won't generate notifications. Note that the regex must match the full document reference which is using the format: <wiki name>:<space name>.<page name>.

Configuration for the Broken Links Event Listener


Configuration data available:

  • Inactive: If set to true then the Broken Link Event Listener which finds broken links in the wiki will not send notifications in the IRC Channel whenever such a link is discovered.

Adding a new Bot Listener

To add a new Command do the following:

  • Create a page anywhere in your wiki and add an XObject of type IRC.IRCBotListenerClass. Fill the parameters


  • Add as many IRC.IRCBotListenerEventClass XObjects as you want. Each such XObject will allow you to react to a given Event happening in the IRC Channel. For example, onMessage will allow you to do something when a message is typed on the IRC channel.


    In the textarea for your event you can put any wiki syntax, including scripts. In these scripts you can access variables containing data for your event. The variables bound depend on the event itself. For example for the onMessage event, the following variables are bound:
    • message: The message typed on the channel
    • user: A User object representing the user who typed the message
    • bot: The Bot object which is the Bot instance itself
    • channel: The Channel object representing the channel in which the message was typed

These variables are accessible from the Bot Context in the following manner (example in Velocity): $services.ircbot.context.<variable name>. For example:


  • There's a special event called onRegistration which isn't an event coming from the IRC Channel. This event is sent by the Bot itself when it starts your Bot Listener and it allows you to perform some initialization for your Bot Listener such as gathering configuration information and making them available to the other events you wish to handle. For example:


    In this example we create 2 new variables jiraURL and jiraPattern that we add to the irclistener context. From then on they are available and can be used from your other events. For example:


Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki
  • If you wish to use the Scheduler to automatically restart the Bot when it's disconnected or when the wiki restarts, go to Scheduler.Webhome and click "Schedule" on the IRC Bot job.
  • If you wish to benefit from the Broken Links features you need to enable the LinkChecker Transformation.

If you upgrade this application make sure to exclude IRC.IRCConfiguration when importing since it contains your configuration and if you import it you'll override your data.

Release Notes





Dependencies for this extension (org.xwiki.contrib:application-ircbot-ui 8.2.2):

Get Connected