02. Configuration

The client configuration consists of a JSON5 object that needs to be loaded before Kiwi IRC can be launched. In case the configuration file cannot be found or if there's an error during the loading process, an error message will be displayed on the page, and the client won't be able to start.

Loading
Format
- Dotted Notation
Options

Loading

The Kiwi IRC client offers multiple options for loading configuration, allowing you to choose the one that best suits your environment. Whether you are using PHP, Ruby, NodeJS, Java, or any other dynamic language for your existing website, you can seamlessly integrate the client by generating the configuration on-the-fly.

The following locations are checked in order:

Javascript Function

Firstly, the existence of a javascript function called window.kiwiConfig is checked. If this function is present, it will be invoked, and its return value should be in the same structure as the config.json.

<script>
window.kiwiConfig = () => ({
    windowTitle: 'Kiwi IRC - Test Config',
});
</script>

URL Location

You also have the option to specify the URL to your JSON config file using a meta tag named kiwiconfig in the client's HTML page (index.html).

<head>
    <meta name="kiwiconfig" content="http://example.com/path/to/config.json">
</head>

Inline JSON

You may also include the JSON directly into the client page (index.html) within a script tag named kiwiconfig. This is particularly useful if your index.html is generated server-side (e.g., with PHP).

<script name="kiwiconfig" type="application/json">
{
    "windowTitle": "Kiwi IRC - Test Config",
}
</script>

Configuration File

Finally, if none of the above options provide a configuration, Kiwi IRC will load the default configuration file from static/config.json.

Format

The configuration options are presented in the JSON5 format, which employs a plain object structure. For example: {"option1": "value", "option2": true}.

JSON5 is more forgiving than standard JSON, but it is still advisable to ensure compliance with plain JSON whenever possible. If you encounter formatting issues, it can be helpful to use an online JSON formatter to identify and address the problem.

Dotted Notation

You may either use nested JSON5 objects or simple dotted notation.

The following two configuration files are equivalent:

{
    "startupOptions": {
        "server": "irc.example.com"
    }
}

{
    "startupOptions.server": "irc.example.com"
}

Options

General

These are the top level settings of the configuration object.

E.g:

{
    ... HERE ...
}

windowTitle

The title for the Kiwi IRC app

{
    "windowTitle": "Kiwi IRC - The web IRC client",
}

useMonospace

Traditionally IRC clients use mono space fonts but more modern clients are starting to use other style fonts instead. Set this to true to enable monospace fonts if the theme supports it.

{
    "useMonospace": true,
}

theme

The name of the default theme. This theme must exist in the list of available themes.

{
    "theme": "Default",
}

themes

The list of themes that are available to the client.

{
    "themes": [
        { "name": "Default", "url": "static/themes/default" },
        { "name": "Dark", "url": "static/themes/dark" }
    ]
}

startupScreen

The name of the default startup screen. This is the first screen that the user sees on opening the client. Some are better suited for single IRC networks while others may be better suited for bouncer login interfaces.

Most startupScreen's can be customised with Startup Options.

Some plugins can also provide startupScreen's, See their documentation for details.

Popular values:
  "welcome" - For single networks, provides simple form for the users to enter nick / password / channel.
  "personal" - Best option when using it as a personal client connecting to multiple networks (this is the default in kiwiirc-desktop).
  "customServer" - For public gateways that allow users connection to any IRC network.
  "znc" - Use this if your using Kiwi IRC as a client for [znc](https://wiki.znc.in/).

{
    "startupScreen": "welcome",
}

kiwiServer

The URL to your webircgateway instance (called kiwiirc within the packages). This URL can either be relative to the client page or an absolute URL. However, if using a different host name or port than the client page then you must remember to allow the client address in the server config.

{
    "kiwiServer": "/webirc/kiwiirc/",
}

restricted

Setting this to true restricts the client to connect only to the IRC server you configure.

Effects:

The "Add Network" button is hidden.
The network's "Settings" panel is hidden.

{
    "restricted": true,
}

showRaw

If enabled, the raw traffic to and from the IRC servers will be shown in a buffer called *raw.

This can be handy for debugging, and plugin development.

{
    "showRaw": true,
}

hideSettings

If true the app settings cog button will be hidden from the user. Hiding the settings is really not recommended as it stops the user from changing common settings like language and theme.

{
    "hideSettings": false,
}

hideAdvancedSettings

Setting this to true will hide the advanced settings button from the settings screen. Only the basic settings will be available to the user.

{
    "hideAdvancedSettings": true,
}

warnOnExit

If enabled, the client will show a prompt to the user asking them to confirm closing the tab or trying to navigate away. This prevents accidental page refreshes and getting disconnected from the IRC network.

{
    "warnOnExit": true,
}

quitMessage

The reason to send in the quit message for direct connections when the page is closed.

{
    "quitMessage": "Page closed",
}

showAutoComplete

If enabled, an autocomplete box will appear on pressing tab to auto complete nicknames, commands, and channels. It will so show autocomplete when using one of the autocomplete tokens.

{
    "showAutoComplete": true,
}

autocompleteTokens

This setting controls what tokens will trigger the display of the autocomplete box.

/ - will show commands.
# - will show channels.
@ - will show nicknames.

{
    "autocompleteTokens": ["/", "#", "@"],
}

showSendButton

If enabled, the send message button will be shown allowing the user to click a button to send a message. This button is always shown automatically on touch screen devices.

{
    "showSendButton": true,
}

sidebarDefault

If set, the sidebar will be shown at start-up with the specified panel. When set to nicklist the sidebar will automatically switch to user view when sending direct messages.

Values:
  "about"
  "nicklist"
  "settings"

{
    "sidebarDefault": "nicklist",
}

showColorPicker

Show or hide the colour palette icon that allows the user to set styles / colours on outgoing messages.

{
    "showColorPicker": true,
}

showEmojiPicker

Show or hide the emoji picker button, This is ignored on touchscreen devices where the operating systems default keyboard usually contains a native emoji picker (this can be overridden using forceShowEmojiPicker).

{
    "showEmojiPicker": true,
}

forceShowEmojiPicker

Force the emoji picker button to be shown even on touchscreen devices where the operating systems default keyboard usually contains a native emoji picker. This option is mostly useful when using plugin-emojis and wanting a consistent experience with supported emojis.

{
    "forceShowEmojiPicker": true,
}

showAwayStatusIndicators

Show or hide away status indicators on user avatars, both in the nicklist and in modern style message list.

{
    "showAwayStatusIndicators": true,
}

noticeActiveBuffer

If true, forward all notices to the active buffer if one exists for the current network. Otherwise, all notices will be added to the server buffer's message list.

{
    "noticeActiveBuffer": true,
}

skipHiddenMessages

When enabled any message that are set to hidden are not added to the buffer. This option is most useful on networks with a high rate of join/part/quits that are hidden from the user as it prevents the join/part/quits from pushing visible messages over the buffer size limit.

{
    "skipHiddenMessages": false,
}

autoReconnect

When an unexpected disconnection occurs automatically reconnect to the network.

{
    "autoReconnect": false,
}

disconnectOnSaslFail

During the connection stage, if SASL fails for any reason, disconnect the client and return to the welcome screen if applicable. If this is set to false then the client will continue to connect but the user would not be authenticated.

{
    "disconnectOnSaslFail": true,
}

changeNickOnCollision

During the connection stage, if the requested nick is already in use automatically append random numbers, until an available nick is found. If this is set to false then the connection would fail and the user will be returned to the welcome screen if applicable.

{
    "changeNickOnCollision": true,
}

nicklistGroupAway

When enabled all users marked as away will be moved to the bottom of the nicklist. This option works best with IRCv3 away-notify.

{
    "nicklistGroupAway": false,
}

showChanlistModes

When enabled channel modes will be shown in square brackets [] at the start of channel topic within the channel list view.

{
    "showChanlistModes": false,
}

Buffers

The following settings must be within the buffer object of the configuration.

"buffers" : {
    ... HERE ...
}

messageLayout

The default layout for buffers. Traditional IRC clients are more compact and less visual, while a more modern client may be more spacious and easier to read to the general public.

Values:
  "compact"
  "modern"
  "inline"

"buffers" : {
    "messageLayout": "modern"
}

prompt_leave

Request confirmation when a user attempts to close a buffer.

Values:
  "all"
  "channels"
  "queries"
  "none"

"buffers" : {
    "prompt_leave": "channels"
}

auto_request_history

For servers that support IRCv3 chathistory which types of buffers should automatically request history.

Values:
  "all"
  "channels"
  "queries"
  "none"

"buffers" : {
    "auto_request_history": "channels"
}

alert_on

When the user should be alerted on receiving a message.

Values:
  "message"
  "highlight"
  "never"

"buffers" : {
    "alert_on": "highlight"
}

timestamp_format

The format of the timestamps shown next to a message. More information on these formats can be found here.

"buffers" : {
    "timestamp_format": "%H:%M:%S"
}

timestamp_full_format

Like the timestamp_format option but when a full date and time is needed. If set to false the browsers default format will be used, using the users default locale.

"buffers" : {
    "timestamp_full_format": false
}

show_timestamps

If enabled, the time when a message was received will be shown.

"buffers" : {
    "show_timestamps": true
}

scrollback_size

The number of messages to keep in the window. The higher this number, the more memory will be used in the browser. Setting this too high will cause performance issues.

"buffers" : {
    "scrollback_size": 250
}

show_hostnames

If enabled, show users hostnames when they join or leave a channel.

"buffers" : {
    "show_hostnames": false
}

show_joinparts

If enabled, show when users join or leave a channel.

"buffers" : {
    "show_joinparts": true
}

show_topics

If enabled, show the new topic as a message when a channel topic changes.

"buffers" : {
    "show_topics": true
}

show_topic_in_header

If enabled, the topic will be shown in the buffers header except on small screen devices where it will be shown as a message in the message list.

"buffers" : {
    "show_topic_in_header": false
}

show_nick_changes

If enabled, show when users change their nickname as a message.

"buffers" : {
    "show_nick_changes": true
}

show_mode_changes

If enabled, show channel mode changes as a message when they change.

"buffers" : {
    "show_mode_changes": true
}

show_presence_changes

If enabled, include a message when users set or unset their away messages.

"buffers" : {
    "show_presence_changes": false
}

traffic_as_activity

If enabled, include traffic messages (joins, parts, quits) in the unread message counters.

"buffers" : {
    "traffic_as_activity": false
}

server_as_activity

If enabled, show the unread counter for the sever buffer when new messages are added.

"buffers" : {
    "server_as_activity": true
}

coloured_nicklist

If enabled, the nicklist will show user nicknames in the colour that has been auto generated for them. Otherwise they will show under a single colour set by the theme.

"buffers" : {
    "coloured_nicklist": true
}

colour_nicknames_in_messages

If enabled, highlight nicknames found in messages with the colour they have been assigned.

"buffers" : {
    "colour_nicknames_in_messages": true
}

block_pms

If enabled, users will not receive private messages unless they have sent a private message to the sender first. Note: ircops and op’s of shared channels are exempt from this block.

"buffers" : {
    "block_pms": false
}

show_emoticons

If enabled, emojis and simple emoticon characters such as :) will be replaced with images.

"buffers" : {
    "show_emoticons": true
}

extra_formatting

If enabled, basic markdown will be supported in messages.

"buffers" : {
    "extra_formatting": true
}

mute_sound

If enabled, sounds will be muted when an alert is shown.

"buffers" : {
    "mute_sound": false
}

hide_message_counts

If enabled, unread message counters next to the channel names will be hidden.

"buffers" : {
    "hide_message_counts": false
}

show_realnames

If enabled, show the users real name field next to their nick on supported message layouts.

"buffers" : {
    "show_realnames": false
}

default_ban_mask

When no other automated way can be found to ban a user this user mask will be used.

Replacements:
  %n - nick
  %i - ident
  %h - hostname

"buffers" : {
    "default_ban_mask": "*!%i@%h"
}

default_kick_reason

The default reason given when you kick a user without specifying one.

"buffers" : {
    "default_kick_reason": "Your behaviour is not conducive to the desired environment."
}

shared_input

If enabled, each buffer will share the message input history. Otherwise, each buffer will contain its own message input history that will be remembered as the user switches between buffers.

"buffers" : {
    "shared_input": false
}

show_buffer_groups

If enabled, buffers will be grouped by collapsible headings for channels/queries.

"buffers" : {
    "show_buffer_groups": true
}

show_message_info

If enabled, on touch screen devices you can tap a message to open a menu to reply or view more information about a message.

"buffers" : {
    "show_message_info": true
}

who_loop

On older IRC networks without IRCv3 away-notify support, repeatedly poll the server for everyone's away status. Set this to false to disable this function.

"buffers" : {
    "who_loop": true
}

share_typing

If the IRC server supports IRCv3 message-tags, send and receive users typing statuses to show which users are currently typing a message.

"buffers" : {
    "share_typing": true
}

flash_title

Flash the window or browser tab title when a new message arrives while a different browser tab has focus.

Values:
  "message" - all messages.
  "highlight" - messages containing the users nick.
  "off" - disable this feature

"buffers" : {
    "flash_title": "message"
}

nicklist_avatars

If enabled, show users avatars in the nicklist.

"buffers" : {
    "nicklist_avatars": false
}

show_link_previews

URLs converted to links within messages will have a small icon next to it to preview the link within media viewer. This icon can be disabled by setting this to false.

"buffers" : {
    "show_link_previews": true
}

inline_link_auto_previews

When enabled, channels will show an embedded preview of links underneath the message.

"buffers" : {
    "inline_link_auto_previews": true
}

inline_link_auto_previews_query

When enabled, queries will show an embedded preview of links underneath the message.

"buffers" : {
    "inline_link_auto_previews_query": true
}

inline_link_auto_preview_whitelist

If links sent in a message match this regex pattern, a preview will be automatically shown after the message.

"buffers" : {
    "inline_link_auto_preview_whitelist": "youtube.com|imgur.com"
}

Startup

The startup screen manages how the client starts up. It may add default networks, offer a login form, display custom HTML content or any other things. The startup screen starts the initial IRC connection before telling the client to take over and display the main client interface.

Because the startup screen kick starts the IRC connection it must know the connection details, along with any other specific settings for the screen itself which may differ between different startup screens.

The following settings must be within the startupOptions object.

"startupOptions" : {
    ... HERE ...
}

server

The IRC server address to connect to. If using a webircgateway instance, the server may override this setting transparently.

"startupOptions" : {
    "server": "irc.example.com"
}

port

The port number to find the IRC server on. If using a webircgateway instance, the server may override this setting transparently.

"startupOptions" : {
    "port": 6667
}

tls

If enabled, the client will attempt to connect to the IRC server using SSL/TLS. If using a webircgateway instance, the server may override this setting transparently.

"startupOptions" : {
    "tls": false
}

direct

If the IRC server supports websocket connections, you may enable this option to ignore the kiwiServer setting and connect directly to the IRC server. This will connect to the websocket server set in the normal server / port / tls options.

"startupOptions" : {
    "direct": false
}

direct_path

If the direct option is enabled, the websocket connection will be made to this path.

"startupOptions" : {
    "direct_path": ""
}

channel

The channels to join once the IRC connection has successfully be made. More than one channel may be entered being separated by a comma.

"startupOptions" : {
    "channel": "#chan1,#chan2"
}

nick

The nickname to use on the IRC server. If it is already in use then a random number will be automatically appended until it connects successfully. A ? may be used to insert a random number in its place.

"startupOptions" : {
    "nick": "kiwi_?"
}

nick_format

If set, a user can only click the connect button if the nickname matches this regex pattern.

"startupOptions" : {
    "nick_format": "^[a-z_\\[\\]{}^`|][a-z0-9_\\-\\[\\]{}^`|]*$"
}

state_key

The user settings and state are saved within their browser (local storage) under a key name. This key may be changed to provide different instances of the client without impacting any existing state they may previously have. Setting to falsy will disable any storage.

"startupOptions" : {
    "state_key": "kiwi-state"
}

remember_buffers

When the user session is saved via state_key only the user settings are saved. Set this option to true to also save the users networks and channels.

"startupOptions" : {
    "remember_buffers": true
}

greetingText

The header that is shown on the startup page. HTML may also be used here.

"startupOptions" : {
    "greetingText": "Welcome to Kiwi IRC!"
}

buttonText

The text that is shown on the connect button on the startup page. HTML may also be used here.

"startupOptions" : {
    "buttonText": "Start"
}

infoContent

The text that is shown on the right side of the startup page. HTML may also be used here.

"startupOptions" : {
    "infoContent": "Welcome to my network! <br /> Please visit my <a href='/home' target='_blank'>homepage</a> for help."
}

infoBackground

The url to a background image for the right side of the startup page.

"startupOptions" : {
    "infoBackground": "/info_background.jpg"
}

Plugins

An array of plugins to load into the client. These are loaded as part of Kiwi IRC startup sequence.

For more information about plugins please see here.

"plugins": [
    { "name": "customise", "url": "static/plugins/customise.html" },
    { "name": "conference", "url": "static/plugins/plugin-conference.js" }
]

Aliases

Aliases let you rename existing IRC commands or even build entirely new ones.

They must be one per line and in the form of /name /what it should do.

{
    "aliases": "/j /join $1+\n/p /part $1+"
}

Variables

There are several variables that may be used to refer to the current environment such as the active channel or active nick.

$server - The current network name.
$channel / $destination - The current channel / buffer name.
$nick - The current nick.

You can also use variables to read input from the typed command.
$0 - The command name.
$1 - The first argument from the typed input.
$2 - The second argument from the typed input.
$1+ - From the first argument to the last argument.

Example 1: /greet /msg $1 Hello, $1!
This creates an IRC command /greet that accepts one argument. Typing "/greet username" will execute "/msg username Hello, username!".

Example 2: /ban /quote mode $channel +b $1+
This creates an IRC command /ban that does a few things. Typing /ban nick1 nick2 will execute /quote mode #activechannel +b nick1 nick2. $channel is replaced with the active channel name, $1+ is replaced with all the typed input from the first word to the end.

Helper Commands

/echo - Sends a message to the active buffer without sending it to the IRC network. E.g, /echo Something happened

/lines - Similar to Mirc script, this lets you execute multiples lines of commands separated by a pipe, |.
Example: /lines /ban nick1 | /echo Banned user would first execute the /ban command, and then the /echo command. This comes in handy with creating short aliases such as the common /cycle command that parts and re-joins the active channel: /cycle /lines /part $channel | /join $channel.

Default Aliases

# General aliases
/p /part $1+
/me /action $destination $1+
/j /join $1+
/q /query $1+
/w /whois $1+
/raw /quote $1+
/connect /server $1+
/disconnect /quit $1+
/cycle $channel? /lines /part $channel | /join $channel
/active /back $1+
/umode /mode $nick $1+

# Op related aliases
/op /quote mode $channel +o $1+
/deop /quote mode $channel -o $1+
/hop /quote mode $channel +h $1+
/dehop /quote mode $channel -h $1+
/voice /quote mode $channel +v $1+
/devoice /quote mode $channel -v $1+
/k /kick $channel $1+
/bans /mode $channel +b
/ban /quote mode $channel +b $1+
/unban /quote mode $channel -b $1+

# Misc aliases
/slap /me slaps $1 around a bit with a large trout
/tick /msg $channel ✔

Emojis

These option allows you to set what emoticons are supported.

kiwiirc.com provides the default EmojiOne (now JoyPixels) images.

The url to the emojis can be adjusted using the following configuration option:

{
    "emojiLocation": "https://kiwiirc.com/shared/emoji/"
}

The supported emoticons can be modified using an emojis object like below. Where the key is the text to match and the value is the filename of the emoticon image.

Default Emojis

{
    "emojis": {
        "-___-": "1f611.png",
        ":\"-)": "1f602.png",
        "\":-)": "1f605.png",
        "\":-D": "1f605.png",
        ">:-)": "1f606.png",
        "\":-(": "1f613.png",
        ">:-(": "1f620.png",
        ":\"-(": "1f622.png",
        "O:-)": "1f607.png",
        "0:-3": "1f607.png",
        "0:-)": "1f607.png",
        "0;^)": "1f607.png",
        "O;-)": "1f607.png",
        "0;-)": "1f607.png",
        "O:-3": "1f607.png",
        "-__-": "1f611.png",
        ":-Þ": "1f61b.png",
        "<3": "2764.png",
        "</3": "1f494.png",
        ":\")": "1f602.png",
        ":-D": "1f603.png",
        "\":)": "1f605.png",
        "\"=)": "1f605.png",
        "\":D": "1f605.png",
        "\"=D": "1f605.png",
        ">:)": "1f606.png",
        ">;)": "1f606.png",
        ">=)": "1f606.png",
        "XD": "1f606.png",
        ";-)": "1f609.png",
        "*-)": "1f609.png",
        ";-]": "1f609.png",
        ";^)": "1f609.png",
        "\":(": "1f613.png",
        "\"=(": "1f613.png",
        ":-*": "1f618.png",
        ":^*": "1f618.png",
        ">:P": "1f61c.png",
        "X-P": "1f61c.png",
        ">:[": "1f61e.png",
        ":-(": "1f61e.png",
        ":-[": "1f61e.png",
        ">:(": "1f620.png",
        ":\"(": "1f622.png",
        ";-(": "1f622.png",
        ">.<": "1f623.png",
        "#-)": "1f635.png",
        "%-)": "1f635.png",
        "X-)": "1f635.png",
        "\\0/": "1f646.png",
        "\\O/": "1f646.png",
        "0:3": "1f607.png",
        "0:)": "1f607.png",
        "O:)": "1f607.png",
        "O=)": "1f607.png",
        "O:3": "1f607.png",
        "B-)": "1f60e.png",
        "8-)": "1f60e.png",
        "B-D": "1f60e.png",
        "8-D": "1f60e.png",
        "-_-": "1f611.png",
        ">:\\": "1f615.png",
        ">:/": "1f615.png",
        ":-/": "1f615.png",
        ":-.": "1f615.png",
        ":-P": "1f61b.png",
        ":Þ": "1f61b.png",
        ":-b": "1f61b.png",
        ":-O": "1f62e.png",
        "O_O": "1f62e.png",
        ">:O": "1f62e.png",
        ":-X": "1f636.png",
        ":-#": "1f636.png",
        ":-)": "1f642.png",
        "(y)": "1f44d.png",
        ":D": "1f603.png",
        "=D": "1f603.png",
        ";)": "1f609.png",
        "*)": "1f609.png",
        ";]": "1f609.png",
        ";D": "1f609.png",
        ":*": "1f618.png",
        "=*": "1f618.png",
        ":(": "1f61e.png",
        ":[": "1f61e.png",
        "=(": "1f61e.png",
        ":@": "1f620.png",
        ";(": "1f622.png",
        "D:": "1f628.png",
        ":$": "1f633.png",
        "=$": "1f633.png",
        "#)": "1f635.png",
        "%)": "1f635.png",
        "X)": "1f635.png",
        "B)": "1f60e.png",
        "8)": "1f60e.png",
        ":/": "1f615.png",
        ":\\": "1f615.png",
        "=/": "1f615.png",
        "=\\": "1f615.png",
        ":L": "1f615.png",
        "=L": "1f615.png",
        ":P": "1f61b.png",
        ":p": "1f61b.png",
        "=P": "1f61b.png",
        ":b": "1f61b.png",
        ":O": "1f62e.png",
        ":X": "1f636.png",
        ":#": "1f636.png",
        "=X": "1f636.png",
        "=#": "1f636.png",
        ":)": "1f642.png",
        "=]": "1f642.png",
        "=)": "1f642.png",
        ":]": "1f642.png",
    }
}