Konnect Chat IRC Desktop Client | Scripting Documentation

KonnectChat Scripting API Reference Generated by AI

KonnectChat features a multi-language scripting engine designed to extend the UI, register custom slash commands, automate tasks, and hook directly into raw IRC events. Scripts are managed via the built-in Script Console and hot-reload automatically when saved.

-------------------------------------------------------------------------------

SUPPORTED LANGUAGES

-------------------------------------------------------------------------------

* JavaScript (.js) - Powered by Jint

* Lua (.lua) - Powered by NLua

* Python (.py) - Powered by IronPython

-------------------------------------------------------------------------------

THE CLIENT OBJECT

-------------------------------------------------------------------------------

Every script is injected with a global `client` object. This is your primary bridge into the native application's capabilities.

1. Sending Messages (client.send)

   * client.send.privmsg(target, message): Sends a standard chat message to a channel or user.

   * client.send.action(target, message): Sends a /me action emote.

   * client.send.raw(line): Sends any raw IRC line directly to the server, exactly as written.

     NOTE on raw(): This does not parse UI slash commands. Use this for raw IRC protocol commands (e.g., MODE #ch +b, WHO 0 o, USERHOST nick).

   Examples:

   client.send.privmsg("#general", "Hello!")

   client.send.action("#general", "waves at everyone")

   client.send.raw("MODE #general +b")

   client.send.raw("WHO 0 o")

2. Custom Commands (client.commands)

   Register custom /commands that users can type into the chat input box.

   * client.commands.register(name, callback): Registers /name. Callback receives (channel, args_list).

   * client.commands.unregister(name): Unregisters a specific command.

   * client.commands.clear(): Clears all commands registered by scripts.

   Example:

   def hello_cmd(channel, args):

       client.send.privmsg(channel, "Hello, world!")

   client.commands.register("hello", hello_cmd)

3. Logging (client.log)

   Outputs messages to the Script Console for debugging.

   * client.log.info(message): Writes an informational line.

   * client.log.warn(message): Writes a warning.

   * client.log.error(message): Writes an error (useful inside try/except blocks).

4. User List Context Menu (client.ui.userlist)

   Adds custom actions to the right-click menu of users in the channel roster.

   * client.ui.userlist.add_context_action(id, label, callback): Adds or replaces a menu item.

   * client.ui.userlist.remove_context_action(id): Removes a specific menu item.

   * client.ui.userlist.clear(): Removes all script-added items.

   Callback Context (ctx):

   * ctx.network: Server name (string)

   * ctx.channel: Current channel (string)

   * ctx.nick / ctx.selected_nick: The right-clicked user's nick (string)

   * ctx.me.nick: Your own nick (string)

5. Chat Area Context Menu (client.ui.chatbox)

   Adds custom right-click items directly to the chat message area.

   * client.ui.chatbox.add_context_action(id, label, callback): Adds or replaces a menu item.

   * client.ui.chatbox.remove_context_action(id): Removes a specific menu item.

   * client.ui.chatbox.clear(): Removes all script-added items.

   Callback Context (ctx):

   * ctx.network: Server name (string)

   * ctx.channel: Current channel (string)

   * ctx.me.nick: Your own nick (string)

-------------------------------------------------------------------------------

EVENT HOOKS

-------------------------------------------------------------------------------

Define these globally-named functions in your script, and KonnectChat will call them automatically when the corresponding event occurs.

* onPrivmsg(server, channel, sender, message):

  Fires when any PRIVMSG is received (including ACTION messages).

* onRaw(server, line):

  Aliases: onServerRaw, onIrcRaw, onLine. All four are called with the exact same arguments.

  Fires for every single raw IRC line received from the server, prior to native application parsing. Use this to intercept server replies to commands you sent via client.send.raw().

  - server: The ServerViewModel object.

  - line: The full raw string (e.g., :irc.example.com 367 you #ch *!*@* setter 1700000000).

* onNumeric(server, code, args, message):

  Fires specifically for numeric replies (e.g., 367, 352). This is often easier to use than onRaw because KonnectChat has pre-parsed the components for you.

  - code: Integer numeric code (e.g., 367).

  - args: List of parameters before the trailing text.

  - message: The trailing :text portion of the reply.

-------------------------------------------------------------------------------

WINUI POPUPS FROM PYTHON (CLR BRIDGE)

-------------------------------------------------------------------------------

IronPython scripts can access native WinUI 3 types directly via the CLR bridge. This allows you to create rich, native dialogs and interface with the application's visual tree.

CRITICAL REQUIREMENTS FOR WINUI 3:

1. Thread Safety: WinUI operations must run on the UI thread. Always wrap UI creation/updates inside a function and pass it to App.MainWindow.DispatcherQueue.TryEnqueue(fn).

2. Correct Assemblies: While the namespaces are Microsoft.UI.Xaml.*, the compiled WinUI 3 assembly is Microsoft.WinUI. You must load this specifically.

3. Use Enums, Not Integers: When setting properties like TextWrapping or Orientation, explicitly import and use the Enums rather than relying on integer casting, which can fail.

Safe Import Pattern:

Always use a try/except block to gracefully fail if the script is run in an environment without the UI bridge.

import clr

try:

    clr.AddReference("System")

    clr.AddReference("KonnectChatIRC")

    clr.AddReference("Microsoft.WinUI") # WinUI 3 Assembly

    from KonnectChatIRC import App

    from Microsoft.UI.Xaml import Thickness, TextWrapping

    from Microsoft.UI.Xaml.Controls import ContentDialog, TextBox, ScrollViewer

except Exception as ex:

    client.log.error("WinUI bridge failed: " + str(ex))

-------------------------------------------------------------------------------

ACCESSING THE APPLICATION VIEWMODEL

-------------------------------------------------------------------------------

You can access the full MVVM tree of KonnectChat to read state or trigger native application behaviors.

from KonnectChatIRC import App

main_vm   = App.MainWindow.Handle          # MainViewModel

server_vm = main_vm.SelectedServer         # ServerViewModel (current server)

channel   = server_vm.SelectedChannel      # ChannelViewModel (current channel)

client.log.info("Nick: " + server_vm.CurrentNick)

client.log.info("Channel: " + channel.Name)

# Execute a slash command exactly as if the user typed it

server_vm.ExecuteScriptCommand("/mode " + channel.Name + " b")

-------------------------------------------------------------------------------

COMPLETE EXAMPLE: NATIVE WINUI DIALOG

-------------------------------------------------------------------------------

This example demonstrates the correct way to safely load assemblies, marshal to the UI thread, and utilize native WinUI controls.

import clr

try:

    clr.AddReference("System")

    clr.AddReference("KonnectChatIRC")

    clr.AddReference("Microsoft.WinUI")

    from KonnectChatIRC import App

    from Microsoft.UI.Xaml import Thickness, TextWrapping

    from Microsoft.UI.Xaml.Controls import ContentDialog, TextBox, ScrollViewer

except Exception as ex:

    client.log.error("WinUI imports failed: " + str(ex))

def on_demo_action(ctx):

    mw = App.MainWindow

    xaml_root = mw.Content.XamlRoot

    def _build_and_show():

        try:

            dlg = ContentDialog()

            dlg.Title = "Native Script Dialog"

            tb = TextBox()

            tb.Text = "This dialog was built entirely in Python using WinUI 3 controls."

            tb.IsReadOnly = True

            tb.AcceptsReturn = True

            tb.TextWrapping = TextWrapping.Wrap # Correct Enum usage

            tb.MinWidth = 400

            tb.MinHeight = 200

            sv = ScrollViewer()

            sv.Content = tb

            dlg.Content = sv

            dlg.CloseButtonText = "Close"

            dlg.XamlRoot = xaml_root

            dlg.ShowAsync()

        except Exception as ex:

            client.log.error("Dialog generation failed: " + str(ex))

    # Marshal to UI thread

    mw.DispatcherQueue.TryEnqueue(_build_and_show)

# Hot-reload safety: Remove before adding

client.ui.chatbox.remove_context_action("demo.dialog")

client.ui.chatbox.add_context_action("demo.dialog", "Show Demo Dialog", on_demo_action)

client.log.info("Demo dialog script loaded.")

-------------------------------------------------------------------------------

AI SCRIPT ASSISTANT

-------------------------------------------------------------------------------

KonnectChat includes a built-in AI assistant to help you generate scripts.

1. Open the Script Console.

2. Select or create a new script.

3. Click the "AI Assist" (Repair icon) in the toolbar.

4. (Optional) In **AI Settings**, choose your provider (**Pollinations**, **OpenAI**, or **Gemini**) and enter your API Key/Model.

5. Describe what you want the script to do.

6. Click "Generate" to have the AI write the code for you.

The AI is aware of the KonnectChat API and your current code context. It will generate updates tailored to your selected language (JavaScript, Lua, or Python).