Classic Multi-User chat, as described in XEP-0045, adds an IRC-like functionality to XMPP.
It distinguishes between the affiliation list and the occupant list, where the latter is based on presences routed to the room from the client resource.
While perfectly sufficient for desktop applications and relatively stable network connection, it does not exactly meet the challenges the mobile world it is facing.
Modern mobile applications do not rely on presence information, as it can frequently change. The expected user experience not only differs from the IRC model, but also uses only a small subset of XEP-0045 features.
The service described in this specification attempts to provide a complete solution for all common use cases of mobile groupchats.
Here are some high-level features required from a new variant of MUC
The service allows any user to create a room for group communication.
Users cannot join rooms on their own. They have to be added by the room owner or (if configured by service administrator) any other occupant.
Only the owner can remove other occupants from the room.
Every occupant can leave the room.
A user may block the attempts of being added to the specific room or by specific user.
The message sent in the room is always broadcasted to every occupant.
The full occupant list is always available to all occupants.
The occupant is always visible on the list, even if they do not have any resources online.
Occupants can only have two affiliations: owner and member.
There MUST be at most one owner in the room (the service can choose to treat all users equally).
If the room becomes empty, it is destroyed.
Occupants cannot hide behind nicks. Their real bare JID is always visible to everyone
No exchange of any <presence/> stanza inside the room.
The user MUST be able to retrieve the list of rooms they occupy.
The owner can modify the room configuration at any time; members may also be allowed to set configuration.
All occupants can get the full room configuration at any time.
Room history is available only in Message Archive Management.
3. Entity Use Cases
3.1. Discovering a MUC Light Service
An entity often discovers a MUC service by sending a Service Discovery items ("disco#items") request to its own server.
The service discovery items ("disco#items") protocol enables an entity to query a service for a list of associated items, which in the case of a chat service would consist of the specific chat rooms the entity occupies.
The service MUST return a full list of the rooms the entity occupies. The server SHOULD include room name and version in each item.
Service Returns a Disco Items Result
1 2 3 4 5 6 7 8 910111213
<firstname.lastname@example.org/pda'type='result'><queryxmlns='http://jabber.org/protocol/disco#items'><email@example.com'name='A Lonely Heath'version='1'/><firstname.lastname@example.org'name='A Dark Cave'version='2'/><email@example.com'name='The Palace'version='3'/><firstname.lastname@example.org'name='Macbeth's Castle'version='4'/></query></iq>
If the full list of rooms is large (see XEP-0030 for details), the service MAY return only a partial list of rooms. If it does, it MUST include a <set/> element qualified by the 'http://jabber.org/protocol/rsm' namespace (as defined in Result Set Management (XEP-0059) ) to indicate that the list is not the full result set.
Service Returns a Limited List of Disco Items Result
<email@example.com/pda'type='result'><queryxmlns='http://jabber.org/protocol/disco#items'><firstname.lastname@example.org'name='Everybody dies'version='1'/><email@example.com'name='As you like it'version='2'/><firstname.lastname@example.org'name='Cleo fans'version='3'/><email@example.com'name='404 Comedy not found'version='4'/><firstname.lastname@example.org'name='What is Coriolanus?'version='5'/><email@example.com'name='Music room'version='6'/><firstname.lastname@example.org'name='To chat or not to chat?'version='7'/><email@example.com'name='Royal Room 1'version='8'/><firstname.lastname@example.org'name='Royal Room 2'version='9'/><email@example.com'name='Royal Room Prime'version='10'/><setxmlns='http://jabber.org/protocol/rsm'><firstindex='0'>firstname.lastname@example.org</first><last>email@example.com</last><count>37</count></set></query></iq>
4. Occupant Use Cases
4.1. Sending a message to a room
Every occupant in the room MAY broadcast messages to other occupants. In order to do so, the client MUST send a groupchat message to the room bare JID.
The room automatically assumes that occupants' nicks are equal to their bare JIDs. MUC light is designed for applications where it is not important to hide behind nicknames. On the contrary - it is up to the client to replace pure JIDs with user-friendly names like phone numbers or full names if necessary.
The room MUST route all messages of the 'groupchat' type.
Client sends a message to the room
<firstname.lastname@example.orgemail@example.com'type='groupchat'><body>Harpier cries: 'tis time, 'tis time.</body></message>
Server broadcasts a groupchat message
<firstname.lastname@example.orgemail@example.comfirstname.lastname@example.org'><body>Harpier cries: 'tis time, 'tis time.</body></message>
<email@example.comfirstname.lastname@example.orgemail@example.com'><body>Harpier cries: 'tis time, 'tis time.</body></message>
Note the message is sent to all the room occupants including the original sender.
<firstname.lastname@example.orgemail@example.comfirstname.lastname@example.org'><body>Harpier cries: 'tis time, 'tis time.</body></message>
4.2. Changing a room subject
The service MAY allow room occupants to set the room subject by changing the "subject" configuration field. A standard configuration stanza is used in this case. Subject change is announced like an ordinary configuration change.
Client sends a message to the room
<email@example.comfirstname.lastname@example.org'type='set'><queryxmlns='urn:xmpp:muclight:0#configuration'><subject>To be or not to be?</subject></query></iq>
1 2 3 4 5 6 7 8 91011
<email@example.comfirstname.lastname@example.org'type='groupchat'id='newsubject'><xxmlns='urn:xmpp:muclight:0#configuration'><prev-version>asdfghj000</prev-version><version>asdfghj</version><subject>To be or not to be?</subject></x><body/></message>
1 2 3 4 5 6 7 8 91011
<email@example.comfirstname.lastname@example.org'type='groupchat'id='newsubject'><xxmlns='urn:xmpp:muclight:0#configuration'><prev-version>asdfghj000</prev-version><version>asdfghj</version><subject>To be or not to be?</subject></x><body/></message>
Room occupants may request room information (configuration and/or occupants list) by an information version. It is up to the service to define the version string, the only requirement for it, is to be unique per room. Please note there are no separate versions for configuration and occupant list alone.
If the server side version does not match the one provided by the client (or if the client does not provide one, i.e. the 'version' element is empty), the service MUST respond with a current version string and full configuration and/or occupant list.
If the version strings match, server MUST reply with an empty result.
<email@example.comfirstname.lastname@example.org/desktop'type='result'><queryxmlns='urn:xmpp:muclight:0#configuration'><version>123456</version><roomname>A Dark Cave</roomname></query></iq>
<email@example.comfirstname.lastname@example.org/desktop'type='result'><queryxmlns='urn:xmpp:muclight:0#info'><version>123456</version><configuration><roomname>A Dark Cave</roomname></configuration><occupants><useraffiliation='owner'>email@example.com</user><useraffiliation='member'>firstname.lastname@example.org</user><useraffiliation='member'>email@example.com</user></occupants></query></iq>
4.4. Leaving the room
Every occupant is allowed to leave the room at any time. It is done by modifying their own affiliation.
A user MAY choose to automatically deny being added to the room. All stanzas must be directed to MUC Light service. User MAY send more than one item in a single request and mix both 'user' and 'room' elements.
If the occupant tries to add another user to the room, and this user has set a blocking policy, the server MUST ignore the attempt. No error is returned, this user is simply skipped when processing affiliation change query.
A room is created by submitting a dedicated stanza. The client application should pick a random room node name, since a human-readable room name is in configuration.
For rules that apply to the configuration options, please see "Setting room configuration" chapter.
The client MAY include initial configuration and occupant list (the list MUST NOT include the creator). The server MAY allow sending an incomplete configuration form. In such case the server MUST use the default values for missing fields. The server MAY enforce a minimal occupant list length.
The service MAY either give the creator the 'owner' or 'member' status. In the latter case all users are equal.
Upon room creation success, the service MUST reply with an empty IQ result.
The following rules (similar to the ones relevant to the affiliation change request) apply to the occupant list:
'none' affiliation cannot be used.
All user bare JIDs must be unique
At most one owner can be chosen. If none is chosen, the room creator will become "just" a 'member'.
After the room is created (but before receiving IQ result), new occupants (including the creator) receive <message/> from the room with their affiliations (the stanza MUST include only recipient's affiliation) and the initial room version. <prev-version/> element MUST NOT be included.
Client requests room creation
1 2 3 4 5 6 7 8 91011121314
<firstname.lastname@example.orgemail@example.com'type='set'><queryxmlns='urn:xmpp:muclight:0#create'><configuration><roomname>A Dark Cave</roomname></configuration><occupants><useraffiliation='member'>firstname.lastname@example.org</user><useraffiliation='member'>email@example.com</user></occupants></query></iq>
If a client would like to avoid a room JID conflict, it MAY request creating a new room with a server-side generated name, that is verfied to be unique. In order to do so, the client MUST send a creation request to service JID, not room bare JID. The IQ result will originate from the new room bare JID
The messages with affiliation change notifications MUST have the same ID as IQ set and result.
If the chosen room name already exists, the service MUST return a 'conflict' error.
Client requests room creation with existing name
1 2 3 4 5 6 7 8 910
<firstname.lastname@example.orgemail@example.com'type='set'><queryxmlns='urn:xmpp:muclight:0#create'><configuration><roomname>A Dark Cave</roomname></configuration></query></iq>
A room is automatically destroyed when its occupant list becomes empty or the room owner explicitly sends an IQ with a room destroy request.
Before sending an IQ result, every occupant is notified that its affiliation has changed to 'none'. These notifications include an <x/> element qualified with a "urn:xmpp:muclight:0#destroy" namespace.
Only the room owner is allowed to destroy it.
Room destruction notification SHOULD NOT contain version (or "prev-version" information).
The server SHOULD accept incomplete (i.e. delta) configuration forms. In such case, values of the missing fields SHOULD be preserved.
5.4. Changing the occupant list
The occupant list is modified by a direct affiliation change. Following rules apply:
There are only 3 affiliations.
owner - can do everything in the room
member - can send messages to the room and if the service allows it, can also change configuration or change others' affiliations
none - not in the room; it's a keyword for marking a user for removal from a room
Every occupant can change its own affiliation to none in order to leave the room.
The only way to join the room is being added by other occupant.
The owner can change affiliations at will.
If the owner leaves, the server MAY use any strategy to choose a new one.
The room can have at most one owner. Giving someone else the 'owner' status effectively causes the current one to lose it.
The owner can choose a new owner when leaving by including both 'none' and 'owner' items in affiliation change request.
Every user JID can be used in the request at most once.
A single request MAY change multiple affiliations.
All changes must be meaningful, e.g. setting member's affiliation to 'member' is considered a bad request.
Server MAY allow members to add new members but they still cannot make anyone an 'owner' or remove other users from the room.
On success the server will reply with a result IQ with all the changed items. BEFORE returning the IQ result, the service MUST route a message with the affiliation change to all relevant users.
Newcomers, i.e. users that were not occupants before the change, SHOULD receive only their own affiliation and SHOULD NOT receive a <prev-version /> element.
The notifications must include both the new and old room version (<version /> and <prev-version /> respectively) string (except for the ones directed to users that have been removed from the room).
The notifications contain a list of items. The item list may be different from the list in the IQ set, because some of the changes may require additional operations, e.g. choosing new owner when the old one leaves. Users, that are still in the room after the change, will receive the full change list. Users, that have been removed from the room with the request, will get only one item: themselves with affiliation 'none'.
Affiliations change request
Let's consider a room coven with following members:
crone1 - owner
hag77 - member
hag88 - member
hag66 is not in the room yet.
User crone1 wants to add hag66 to the room, kick hag88 out and make hag77 the room owner.
Now each user will receive an update.
As you can see, affiliations have changed accordingly to crone1 request.
However, this request implies one more update.
Since hag77 has been promoted to a new owner, crone1 is automatically degraded to member.
The service MAY add user's rooms to its roster. It allows the client to skip the separate Disco request to the service.
Roster items with rooms MUST belong to the group "urn:xmpp:muclight:0" (MUC Light namespace) and include the <version/> element.
Their subscription type MUST be 'to'.
Entity requests the roster and receives a reply that includes a room item
This section defines the rules for archiving MUC Light events and messages.
Stanzas described in the subsections below MUST be archived by the server.
The stanzas not included here MUST NOT be archived.
The <message/> element inside <forwarded/> MUST include a "from" attribute and MUST NOT include a "to" attribute.
"id" SHOULD be archived as well.
In case of regular groupchat messages,
the "from" attribute MUST consist of a room full JID with a sender bare JID in the resource part.
As for room notification, e.g. create event, "from" MUST be equal to room bare JID.
Examples below use MAM v0.4 protocol.
The archive can be fetched only from a specific room, the client MUST NOT query MUC Light service directly.
6.2.1. Groupchat message from occupant
Message from a user MUST be archived with all child elements.
Occupant queries MAM and receives regular groupchat message
If the request sender does not have sufficient privileges (but is a room occupant),
the service MUST reply with a 'not-allowed' error.
It occurs in the following cases:
A member tries to change the configuration but the service is not configured to allow it.
It does not apply to the subject change,
although it has to be performed by sending <message/> with <subject/>,
not configuration <iq/>.
A member tries to change anyone's affiliation to 'none' or 'owner'.
A member tries to change someone's affiliation to 'member' but the service is not configured to allow it.
Some client-side developers might choose to use existing XEP-0045 Multi-User Chat implementations
to interface with the new MUC Light.
There may be various reasons to do so: using a familiar protocol,
avoiding additional implementation, quick prototyping etc.
This section provides suggestions of mappings between XEP-0045 stanzas and the new ones described in this document.
Operations not described here SHOULD remain unmodified.
8.1.1. Discovering the Features Supported by a MUC Service
A Disco result MAY either include a new <feature/> element with an "http://jabber.org/protocol/muc" namespace
next to MUC Light one, or completely replace it, which is the RECOMMENDED behaviour.
<firstname.lastname@example.org/pda'type='result'><queryxmlns='http://jabber.org/protocol/disco#items'><email@example.com'name='A Lonely Heath'/><firstname.lastname@example.org'name='A Dark Cave'/><email@example.com'name='The Palace'/><firstname.lastname@example.org'name='Macbeth's Castle'/></query></iq>
8.1.3. Changing a room subject
Instead of distributing the configuration change notifications,
the room MUST route <message/> with a <subject/> like a classic MUC would.
The client MUST send a classic message <subject/> as well.
The room SHOULD save a new subject in the room configuration.
New subject is routed as an ordinary message
<email@example.comfirstname.lastname@example.org'type='groupchat'><subject>To be or not to be?</subject></message>
<email@example.comfirstname.lastname@example.org'type='groupchat'id='compsubject'><subject>To be or not to be?</subject></message>
<email@example.comfirstname.lastname@example.org'type='groupchat'id='compsubject'><subject>To be or not to be?</subject></message>
8.1.4. Getting a room configuration
Room configuration is encoded in a Data Form, that simulates the XEP-0045 config form.
Getting the room configuration does not benefit from room versioning.
<email@example.comfirstname.lastname@example.org/desktop'type='result'><queryxmlns='http://jabber.org/protocol/muc#owner'><xxmlns='jabber:x:data'type='form'><title>Configuration for "coven" Room</title><fieldtype='hidden'var='FORM_TYPE'><value>http://jabber.org/protocol/muc#roomconfig</value></field><fieldlabel='Natural-Language Room Name'type='text-single'var='muc#roomconfig_roomname'><value>A Dark Cave</value></field><fieldlabel='Room subject'type='text-single'var='muc#roomconfig_subject'><value>To be or not to be?</value></field></x></query></iq>
8.1.5. Requesting a user list
A user list is retrieved with an affiliation IQ get.
There is no XEP-0045 equivalent for getting full room information.
8.1.7. Leaving the room
Leaving the room is performed by setting the own affiliation to 'none'.
The service uses <presence/> to notify all occupants (and former occupant) about the change.
<presence/> to the leaving occupant MUST be of the type "unavailable"
and MUST include a status code 321 (i.e. user leaving due to affiliation change).
The blocking functionality uses a small subset of the Privacy Lists protocol.
Stanzas MUST be addressed to the sender's bare JID (the to attribute may be skipped).
The privacy list name MUST be equal to "urn:xmpp:muclight:0".
Obviously, this method won't work properly in XMPP Server Federation, because privacy stanzas are handled by sender's server and the MUC Light Blocking functionality is handled by a MUC Light service server.
As opposed to XEP-0016, it is allowed to send "delta" privacy lists.
Room occupants can use a standard XEP-0045 configuration modification method. The service MUST broadcast only the notification about the configuration change with a status code 104, so every occupant can retrieve the new room configuration in a separate request. The client is allowed to send a config delta in a form.
The service MUST send an affiliation change notification to all participants.
Leaving users MUST NOT receive any information except for their own "none" affiliation.
New users MUST receive an invitation message.
The MUC Light service may be abused by a malicious users,
e.g. due to replicating a single message for every room occupant.
The list below contains suggested configurable limits that SHOULD be implemented.
The service features that might vary depending on a specific application are included as well.
Maximum number of rooms the user occupies.
Blocking feature enabled/disabled.
XEP-0045 compatibility mode enabled/disabled.
Room creator's initial affiliation: owner/member.
Room configuration may be changed by owner/occupants.