Helga comes with many builtin plugins, webhooks, and features.
As of version 1.7.0, helga supports IRC, XMPP, and HipChat out of the box. Note, however, that helga originally started as an IRC bot, so much of the terminology will reflect that. The current status of XMPP and HipChat support is very limited and somewhat beta. In the future, helga may have a much more robust and pluggable backend system to allow connections to any number of chat services.
The default configuration assumes that you wish to connect to an IRC server. However, if you wish to connect to an XMPP or HipChat server, see XMPP Configuration.
Helga comes with several builtin plugins. Generally speaking, it is better to have independently maintained plugins rather than modifying helga core. In fact, many of the plugins listed here may be retired as core plugins and moved to externally maintained locations. This is mainly due to the fact that some are either not useful as core plugins or would require more maintenance for helga core than should be needed.
Some builtin plugins may be deprecated and removed in a future version of helga. They will be moved and maintained elsewhere as independent plugins.
A command plugin to show help strings for any installed command plugin. Usage:
helga (help|halp) [<plugin>]
With no arguments, all command plugin help strings are returned to the requesting user in a private message.
This plugin requires database access for some features
A command plugin that acts as an IRC-based plugin manager. Usage:
helga plugins (list|(enable|disable) (<name> ...))
The ‘list’ subcommand will list out both enabled and disabled plugins for the current channel. For example:
<sduncan> !plugins list <helga> Enabled plugins: foo, bar <helga> Disabled plugins: baz
Both enable and disable will respectively move a plugin between enabled and disabled status on the current channel. If a database connection is configured, both enable and disable will record plugins as either automatically enabled for the current channel or not. For example:
<sduncan> !plugins enable baz <sduncan> !plugins list <helga> Enabled plugins: foo, bar, baz <sduncan> !plugins disable baz <helga> Enabled plugins: foo, bar <helga> Disabled plugins: baz
This plugin requires database access for some features
A command plugin that exposes some capabilities exclusively for helga operators. Operators are nicks
with elevated privileges configured via the
OPERATORS setting (see Core Settings).
helga (operator|oper|op) (reload <plugin>|(join|leave|autojoin (add|remove)) <channel>).
Each subcommand acts as follows:
- Experimental. Given a plugin name, perform a call to the python builtin
reload()of the loaded module. Useful for seeing plugin code changes without restarting the process.
- Join or leave a specified channel
autojoin (add|remove) <channel>
- Add or remove a channel from a set of autojoin channels. This features requries database access.
A simple command plugin to ping the bot, which will always respond with ‘pong’. Usage:
A special type of command plugin that enables webhook support (see Webhooks). This command is more of a high-level manager of the webhook system. Usage:
helga webhooks (start|stop|routes)
stop are privileged actions and can start and stop the HTTP listener for
webhooks respectively. To use them, a user must be configured as an operator. The
subcommand will list all of the URL routes known to the webhook listener.
Helga also includes some builtin webhooks for use out of the box.
The announcements webhook exposes a single HTTP endpoint for allowing the ability to
post a message in an IRC channel via an HTTP request. This webhook only supports
POST requests and requires HTTP basic authentication (see Authenticated Routes).
Requests must be made to a URL path
/announce/<channel> such as
and made with a POST parameter
message containing the IRC message contents. The
endpoint will respond with ‘Message Sent’ on a successful message send.
The logger webhook is a browsable web frontend for helga’s builtin channel logger (see Channel Logging). This webhook is enabled by default but requires that channel logging is enabled for it to be of any use. Logs are shown in a dated order, grouped by channel.
Without any configuration, this web frontend will allow browsing all channels in which the
bot resides or has resided. This behavior can be changed with the setting
CHANNEL_LOGGING_HIDE_CHANNELS which should be a list of channel names
that should be hidden from the browsable web UI. NOTE: they can still be accessed directly.
This webhook exposes a root
/logger URL endpoint that serves as a channel listing. The
webhook will support any url of the form
/logger/<channel>/YYYY-MM-DD such as
As of the 1.6 release, helga includes support for a simple channel logger, which may be useful for
those wanting to helga to, in addition to any installed plugins, monitor and save conversations that
occur on any channel in which the bot resides. This is a helga core feature and not managed by a plugin,
mostly to ensure that channel logging always happens with some level of confidence that no
preprocess plugins have modified the message. Channel logging feature can be either enabled or
disabled via the setting
Channel logs are kept in UTC time and stored in dated logfiles that are rotated automatically. These
log files are written to disk in a configurable location indicated by
and are organized by channel name. For example, message that occurred on Dec 31 2014 on channel #foo
would be written to a file
The channel logger also includes a web frontend for browsing any logs on disk, documented as the builtin webhook logger.
Non-public channels (i.e. those not beginning with a ‘#’) will be ignored by helga’s channel logger. No conversations via private messages will be logged.