MUC

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 "rooms.example.com" "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 room object for each room to hold data and methods. You can access the room list this way:

    local rooms = module:depends("muc").rooms;

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

The rooms table has an entry for each room's bare JID, and the value is the room object.

    local myroom = rooms["myroom@"..module.host];

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
        });
    end
 
    module:hook("muc-config-form", handle_form);
 
    function handle_submit(event)
        local msg = st.message({type='groupchat', from=event.room.jid})
            :tag('x', {xmlns='http://jabber.org/protocol/muc#user'}):up();
        if event.fields.test == true then
            msg:tag("body"):text("It works!"):up();
        else
            msg:tag("body"):text("It doesn't work :("):up();
        end
        event.room:broadcast_message(msg, false);
    end
 
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.

 
doc/developers/muc.txt · Last modified: 2013/04/29 11:55 by Matthew Wild