All events are represented by Event instances. Every event has the following attributes: = None

The Bot which triggered the event.

Event.event_type = None

The name of the event.

Event.datetime = None

The value of when the event was triggered.

Event instances are also dictionaries, and the keys present depend on the particular event type. The following sections describe each event, specified as event_type(keys).

Raw events

These events are very low-level and most plugins shouldn’t need them.


Client established connection.


Client lost connection.


Client sent message to the server.


Client received message from the server.

Bot events

These events represent changes in the bot’s state.


IRC connection successfully established.


Client joined channel.


Client left channel.

Message events

These events occur when messages are received by the bot.

core.message.privmsg(channel, user, message, is_private, reply_to)

Received message from user which was sent to channel. If the message was sent directly to the client, i.e. channel is the client’s nick and not a channel name, then is_private will be True and any response should be to user, not channel. reply_to is the channel/user any response should be sent to.

core.message.notice(channel, user, message, is_private, reply_to)

As core.message.privmsg, but representing a NOTICE rather than a PRIVMSG. Bear in mind that according to RFC 1459 “automatic replies must never be sent in response to a NOTICE message” - this definitely applies to bot functionality!

core.message.action(channel, user, message, is_private, reply_to)

Received a CTCP ACTION of message from user sent to channel. Other arguments are as for core.message.privmsg.

Channel events

These events occur when something about the channel changes, e.g. people joining or leaving, the topic changing, etc., user)

user joined channel., user)

user left channel., names, raw_names)

Received the list of users currently in the channel, in response to a NAMES command., author, topic)

Fired whenever the channel topic is changed, and also immediately after joining a channel. The author field will usually be the server name when joining a channel (on Freenode, at least), and the nick of the user setting the topic when the topic has been changed.

User events

These events occur when a user changes state in some way, i.e. actions that aren’t limited to a single channel.

core.user.quit(user, message)
core.user.renamed(oldnick, newnick)