Channel history

UnrealIRCd supports channel history playback. It has several interfaces for this, the most visible being able to see history-on-join. Note that history playback requires a modern IRC client.

This article gives background information on the history feature. For actual server settings, see the set::history block.

Short guide

To enable this you have to set channel mode +H, type: MODE #channel +H 15:1440. This will make it remember the last 15 lines for the past 1440 minutes (1 day).

Now, talk in the channel a bit and leave and rejoin the channel. You should see history playback:

NOTE: Of course, you must not be the only person in the channel, otherwise when you leave the channel (or rejoin), the channel will be destroyed, including the message history. (You can counteract this by setting the channel +P)

If you don't see history playback, then check out the client support section.

Ways to retrieve history

There are 3 ways to retrieve channel history:

1. on-join: Automatic history playback whenever you JOIN a channel. The number of lines playback is limited to only the last 15 lines.
2. HISTORY command: Simple command for end-users to retrieve history. Ex: HISTORY #channel. May provide up to 100 lines.
3. CHATHISTORY (IRCv3): An IRCv3 draft extension which allows IRC clients to fetch channel history dynamically when scrolling. This is a flexible and complex command that is used by IRC clients themselves, not to be typed by end-users.

In the end, the 3rd interface will give the best results. However, it will take a while until it is out of draft and potentially years for all IRC clients to implement this. In the meantime, #1 is working already for many clients, and end-users can use #2 if their client does not support #3 yet.

Note 1: All interfaces will always obey channel mode +H. So if +H is not set then you will not be able to retrieve history. If +H is set only allowing 5 lines, then no method can get more than 5 lines. Etc..

Note 2: A common question: FAQ: History mode (+H) causes my bot to re-trigger previous commands - What do I do?.

Client support

History playback works with modern IRC clients that support the server-time capability.

Full support for fetching all history

Clients supporting CHATHISTORY can fetch all history there is, so hundreds or thousands of lines, depending on the +H setting.

The following clients implement CHATHISTORY:

• KiwiIRC
• Gamja
• Goguma
• Senpai

Partial support

The following clients support the earlier mentioned options #1 (15 lines of history on-join) and #2 (users can manually type HISTORY command to fetch more):

• AdiIRC
• Colloquy
• HexChat
• IceChat
• irssi (since 1.2.3, Oct 2021)
• Konversation
• KVIrc
• mIRC: since 7.34 (June 2014)
• Quassel
• Textual
• WeeChat (server-time is enabled by default since v3.3).
• Swirc
• Glirc
• IRCCloud
• The Lounge

If it's not working with any of these clients, make sure you are using their latest version and check the client documentation / client support resources.

No support

Notable clients which do NOT support any history option (#1/#2/#3) are:

• LimeChat
• Mibbit.

Long guide

To start recording history, set channel mode +H. The syntax is: MODE #channel +H max-lines-to-record:max-time-to-record.

For example: MODE #channel +H 50:1d means the last 50 messages will be stored and no message will be stored longer than 1 day (1440 minutes).

For max-time-to-record UnrealIRCd will automatically use the appropriate suffix for minutes (XXm), hours (XXh) or days (XXd). For anything that doesn't round perfectly off to days or hours, minutes are used.

The channel history is then played back when a user joins such a channel. However, the following restrictions apply:

1. The client must support the 'server-time' CAP ('time' message tag), otherwise history is not shown. Any modern IRC client supports this.
2. Only a maximum of 15 lines are played back on-join by default

The reason for the maximum 15 lines on-join playback is that this can be quite annoying if you rejoin repeatedly and as to not flood the users screen too much (unwanted).

UnrealIRCd supports simple history pulling (fetching) via the HISTORY #channel number-of-lines command. It allows you to retrieve up to 100 lines. In the future there will likely be other ways to fetch history as well. In all cases, the maximum number of lines and time configured in the +H channel mode applies, of course, so if your +H setting only allows 20 lines, then you will never be able to fetch more than 20 lines.

You can configure the exact number of lines that are played back and all the limits that apply to +H via set::history::channel.

For saving and retrieving history we currently have the following backend options:

• history_backend_mem: channel history is stored in memory. This is very fast but also means history is lost on restart.
• history_backend_null: don't store channel history at all. This can be useful to load on servers with no users on it, such as a hub server, where storing history is unnecessary.

For history being saved on disk, see Persistent channel history.