This is general documentation for developers wanting to interface with Prosody’s MUC module.

Loading modules

It is recommended that MUC-focused modules are loaded directly onto the appropriate host by the user. This means they cannot go in the global modules_enabled list, because those modules get loaded for all VirtualHosts, but not Components.

The correct config would look like:

    Component "" "muc"
        modules_enabled = { "my_muc_module", "my_other_muc_module", "super_muc_module" }

Hooking/filtering messages

This is easy, as MUC messages fire the standard stanza events. As per XEP-0045 room messages are sent to the room’s bare JID, so they trigger “message/bare”. Private messages between occupants go to full JIDs, and you can get those with “message/full”. Other stanza types are allowed too.

Accessing room data

mod_muc has a function that returns room objects given a room JID, accessible this way:

local mod_muc = module:depends("muc");
local get_room_from_jid = mod_muc.get_room_from_jid;

Your module will automatically be reloaded or unloaded if mod_muc is.

The get_room_from_jid() function allows retrieving rooms by each room’s bare JID, and returns the room object.

local myroom = get_room("myroom@";

Config forms

You can add an item to the room’s configuration form by hooking the “muc-config-form” event, which receives a util.dataforms object. When (and if) the form is submitted by the user, the “muc-config-submitted” event is fired, which receives the values extracted from the submitted form.

    local st = require "util.stanza";
    function handle_form(event)
        -- Insert a new field into the form, a simple checkbox
        table.insert(event.form, {
                name = "test";
                type = "boolean";
                label = "Does it work?";
                value = true; -- Default/current value
    module:hook("muc-config-form", handle_form);
    function handle_submit(event)
        local msg = st.message({type='groupchat',})
            :tag('x', {xmlns=''}):up();
        if event.fields.test == true then
            msg:tag("body"):text("It works!"):up();
            msg:tag("body"):text("It doesn't work :("):up();
        end, false);
module:hook("muc-config-submitted", handle_submit);

If the config has changed, you must let mod_muc know, so that it can notify the user according to XEP-0045. Simply set event.changed = true for this.