XEP-0045: Multi-User Chat

Abstract:This specification defines an XMPP protocol extension for multi-user text chat, whereby multiple XMPP users can exchange messages in the context of a room or channel, similar to Internet Relay Chat (IRC). In addition to standard chatroom features such as room topics and invitations, the protocol defines a strong room control model, including the ability to kick and ban users, to name room moderators and administrators, to require membership or passwords in order to join the room, etc.
Author:Peter Saint-Andre
Copyright:© 1999 - 2011 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Draft
Type:Standards Track
Version:1.24
Last Updated:2008-07-16

NOTICE: The protocol defined herein is a Draft Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.


Table of Contents


1. Introduction
2. Scope
3. Requirements
4. Terminology
    4.1. General Terms
    4.2. Room Types
    4.3. Dramatis Personae
5. Roles and Affiliations
    5.1. Roles
       5.1.1. Privileges
       5.1.2. Changing Roles
    5.2. Affiliations
       5.2.1. Privileges
       5.2.2. Changing Affiliations
6. Entity Use Cases
    6.1. Discovering Component Support for MUC
    6.2. Discovering Rooms
    6.3. Querying for Room Information
    6.4. Querying for Room Items
    6.5. Querying a Room Occupant
    6.6. Discovering Client Support for MUC
7. Occupant Use Cases
    7.1. Entering a Room
       7.1.1. Groupchat 1.0 Protocol
       7.1.2. Basic MUC Protocol
       7.1.3. Presence Broadcast
       7.1.4. Default Roles
       7.1.5. Non-Anonymous Rooms
       7.1.6. Semi-Anonymous Rooms
       7.1.7. Password-Protected Rooms
       7.1.8. Members-Only Rooms
       7.1.9. Banned Users
       7.1.10. Nickname Conflict
       7.1.11. Max Users
       7.1.12. Locked Room
       7.1.13. Nonexistent Room
       7.1.14. Room Logging
       7.1.15. Discussion History
       7.1.16. Managing Discussion History
    7.2. Exiting a Room
    7.3. Changing Nickname
    7.4. Changing Availability Status
    7.5. Inviting Another User to a Room
       7.5.1. Direct Invitation
       7.5.2. Mediated Invitation
    7.6. Converting a One-to-One Chat Into a Multi-User Conference
    7.7. Occupant Modification of the Room Subject
    7.8. Sending a Private Message
    7.9. Sending a Message to All Occupants
    7.10. Registering with a Room
    7.11. Getting Member List
    7.12. Discovering Reserved Room Nickname
    7.13. Requesting Voice
8. Moderator Use Cases
    8.1. Modifying the Room Subject
    8.2. Kicking an Occupant
    8.3. Granting Voice to a Visitor
    8.4. Revoking Voice from a Participant
    8.5. Modifying the Voice List
    8.6. Approving Voice Requests
9. Admin Use Cases
    9.1. Banning a User
    9.2. Modifying the Ban List
    9.3. Granting Membership
    9.4. Revoking Membership
    9.5. Modifying the Member List
    9.6. Granting Moderator Privileges
    9.7. Revoking Moderator Privileges
    9.8. Modifying the Moderator List
    9.9. Approving Registration Requests
10. Owner Use Cases
    10.1. Creating a Room
       10.1.1. General Considerations
       10.1.2. Creating an Instant Room
       10.1.3. Creating a Reserved Room
       10.1.4. Requesting a Unique Room Name
    10.2. Subsequent Room Configuration
       10.2.1. Notification of Configuration Changes
    10.3. Granting Ownership Privileges
    10.4. Revoking Ownership Privileges
    10.5. Modifying the Owner List
    10.6. Granting Administrative Privileges
    10.7. Revoking Administrative Privileges
    10.8. Modifying the Admin List
    10.9. Destroying a Room
11. Error and Status Codes
    11.1. Error Codes
    11.2. Status Codes
12. Internationalization Considerations
13. Security Considerations
    13.1. User Authentication and Authorization
    13.2. End-to-End Encryption
    13.3. Privacy
    13.4. Anonymity
    13.5. Denial of Service
    13.6. Other Considerations
14. IANA Considerations
15. XMPP Registrar Considerations
    15.1. Protocol Namespaces
    15.2. Service Discovery Category/Type
    15.3. Service Discovery Features
    15.4. Well-Known Service Discovery Nodes
    15.5. Field Standardization
       15.5.1. muc#register FORM_TYPE
       15.5.2. muc#request FORM_TYPE
       15.5.3. muc#roomconfig FORM_TYPE
       15.5.4. muc#roominfo FORM_TYPE
    15.6. Status Codes Registry
       15.6.1. Process
       15.6.2. Initial Submission
    15.7. URI Query Types
       15.7.1. join
       15.7.2. invite
16. Business Rules
    16.1. Addresses
    16.2. Message
    16.3. Presence
    16.4. IQ
17. Implementation Notes
    17.1. Services
       17.1.1. Allowable Traffic
    17.2. Clients
       17.2.1. IRC Command Mapping
18. XML Schemas
    18.1. http://jabber.org/protocol/muc
    18.2. http://jabber.org/protocol/muc#user
    18.3. http://jabber.org/protocol/muc#admin
    18.4. http://jabber.org/protocol/muc#owner
    18.5. http://jabber.org/protocol/muc#unique
19. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

Traditionally, instant messaging is thought to consist of one-to-one chat rather than many-to-many chat, which is called variously "groupchat" or "text conferencing". Groupchat functionality is familiar from systems such as Internet Relay Chat (IRC) and the chatroom functionality offered by popular consumer IM services. The Jabber community developed and implemented a basic groupchat protocol as long ago as 1999. This "groupchat 1.0" protocol provided a minimal feature set for chat rooms but was rather limited in scope. This specification (Multi-User Chat or MUC) builds on the older "groupchat 1.0" protocol in a backwards-compatible manner but provides advanced features such as invitations, room moderation and administration, and specialized room types.

2. Scope

This document addresses common requirements related to configuration of, participation in, and administration of individual text-based conference rooms. All of the requirements addressed herein apply at the level of the individual room and are "common" in the sense that they have been widely discussed within the Jabber community or are familiar from existing text-based conference environments outside of Jabber (e.g., Internet Relay Chat as defined in RFC 1459 [1] and its successors: RFC 2810 [2], RFC 2811 [3], RFC 2812 [4], RFC 2813 [5]).

This document explicitly does not address the following:

This limited scope is not meant to disparage such topics, which are of inherent interest; however, it is meant to focus the discussion in this document and to present a comprehensible protocol that can be implemented by Jabber client and component developers alike. Future specifications may of course address the topics mentioned above.

3. Requirements

This document addresses the minimal functionality provided by existing multi-user chat services in Jabber. For the sake of backwards-compatibility, this document uses the original "groupchat 1.0" protocol for this baseline functionality, with the result that:

The additional features and functionality addressed in this document include the following:

  1. native conversation logging (no in-room bot required)
  2. enabling users to request membership in a room
  3. enabling occupants to view an occupant's full JID in a non-anonymous room
  4. enabling moderators to view an occupant's full JID in a semi-anonymous room
  5. allowing only moderators to change the room subject
  6. enabling moderators to kick participants and visitors from the room
  7. enabling moderators to grant and revoke voice (i.e., the privilege to speak) in a moderated room, and to manage the voice list
  8. enabling admins to grant and revoke moderator privileges, and to manage the moderator list
  9. enabling admins to ban users from the room, and to manage the ban list
  10. enabling admins to grant and revoke membership privileges, and to manage the member list for a members-only room
  11. enabling owners to limit the number of occupants
  12. enabling owners to specify other owners
  13. enabling owners to grant and revoke administrative privileges, and to manage the admin list
  14. enabling owners to destroy the room

In addition, this document provides protocol elements for supporting the following room types:

  1. public or hidden
  2. persistent or temporary
  3. password-protected or unsecured
  4. members-only or open
  5. moderated or unmoderated
  6. non-anonymous or semi-anonymous

The extensions needed to implement these requirements are qualified by the 'http://jabber.org/protocol/muc' namespace (and the #owner, #admin, and #user fragments on the main namespace URI).

4. Terminology

4.1 General Terms

Affiliation
A long-lived association or connection with a room; the possible affiliations are "owner", "admin", "member", and "outcast" (naturally it is also possible to have no affiliation); affiliation is distinct from role. An affiliation lasts across a user's visits to a room.
Ban
To remove a user from a room such that the user is not allowed to re-enter the room (until and unless the ban has been removed). A banned user has an affiliation of "outcast".
Bare JID
The <user@host> by which a user is identified outside the context of any existing session or resource; contrast with Full JID and Room JID.
Full JID
The <user@host/resource> by which an online user is identified outside the context of a room; contrast with Bare JID and Room JID.
GC
The minimal "groupchat 1.0" protocol [7] developed within the Jabber community in 1999; MUC is backwards-compatible with GC.
History
A limited number of message stanzas sent to a new occupant to provide the context of current discussion.
Invitation
A special message sent from one user to another asking the recipient to join a room.
IRC
Internet Relay Chat.
Kick
To temporarily remove a participant or visitor from a room; the user is allowed to re-enter the room at any time. A kicked user has a role of "none".
Logging
Storage of discussions that occur within a room for public retrieval outside the context of the room.
Member
A user who is on the "whitelist" for a members-only room or who is registered with an open room. A member has an affiliation of "member".
Moderator
A room role that is usually associated with room admins but that may be granted to non-admins; is allowed to kick users, grant and revoke voice, etc. A moderator has a role of "moderator".
MUC
The multi-user chat protocol for text-based conferencing specified in this document.
Occupant
Any Jabber user who is in a room (this is an "abstract class" and does not correspond to any specific role).
Outcast
A user who has been banned from a room. An outcast has an affiliation of "outcast".
Participant
An occupant who does not have administrative privileges; in a moderated room, a participant is further defined as having voice (in contrast to a visitor). A participant has a role of "participant".
Private Message
A message sent from one occupant directly to another's room JID (not to the room itself for broadcasting to all occupants).
Role
A temporary position or privilege level within a room, distinct from a user's long-lived affiliation with the room; the possible roles are "moderator", "participant", and "visitor" (it is also possible to have no defined role). A role lasts only for the duration of an occupant's visit to a room.
Room
A virtual space that Jabber users figuratively enter in order to participate in real-time, text-based conferencing with other users.
Room Administrator
A user empowered by the room owner to perform administrative functions such as banning users; however, is not allowed to change defining room features. An admin has an affiliation of "admin".
Room ID
The node identifier portion of a Room JID, which may be opaque and thus lack meaning for human users (see Business Rules for syntax); contrast with Room Name.
Room JID
The <room@service/nick> by which an occupant is identified within the context of a room; contrast with Bare JID and Full JID.
Room Name
A user-friendly, natural-language name for a room, configured by the room owner and presented in Service Discovery queries; contrast with Room ID.
Room Nickname
The resource identifier portion of a Room JID (see Business Rules for syntax); this is the "friendly name" by which an occupant is known in the room.
Room Owner
The Jabber user who created the room or a Jabber user who has been designated by the room creator or owner as someone with owner privileges (if allowed); is allowed to change defining room features as well as perform all administrative functions. An owner has an affiliation of "owner".
Room Roster
A Jabber client's representation of the occupants in a room.
Server
A Jabber server that may or may not have associated with it a text-based conferencing service.
Service
A host that offers text-based conferencing capabilities; often but not necessarily a sub-domain of a Jabber server (e.g., conference.jabber.org).
Subject
A temporary discussion topic within a room.
Visit
A user's "session" in a room, beginning when the user enters the room (i.e., becomes an occupant) and ending when the user exits the room.
Visitor
In a moderated room, an occupant who does not have voice (in contrast to a participant). A visitor has a role of "visitor".
Voice
In a moderated room, the privilege to send messages to all occupants.

4.2 Room Types

Fully-Anonymous Room
A room in which the full JIDs or bare JIDs of occupants cannot be discovered by anyone, including room admins and room owners; such rooms are NOT RECOMMENDED or explicitly supported by MUC, but are possible using this protocol if a service implementation offers the appropriate configuration options; contrast with Non-Anonymous Room and Semi-Anonymous Room.
Hidden Room
A room that cannot be found by any user through normal means such as searching and service discovery; antonym: Public Room.
Members-Only Room
A room that a user cannot enter without being on the member list; antonym: Open Room.
Moderated Room
A room in which only those with "voice" may send messages to all occupants; antonym: Unmoderated Room.
Non-Anonymous Room
A room in which an occupant's full JID is exposed to all other occupants, although the occupant may choose any desired room nickname; contrast with Semi-Anonymous Room and Fully-Anonymous Room.
Open Room
A room that anyone may enter without being on the member list; antonym: Members-Only Room.
Password-Protected Room
A room that a user cannot enter without first providing the correct password; antonym: Unsecured Room.
Persistent Room
A room that is not destroyed if the last occupant exits; antonym: Temporary Room.
Public Room
A room that can be found by any user through normal means such as searching and service discovery; antonym: Hidden Room.
Semi-Anonymous Room
A room in which an occupant's full JID can be discovered by room admins only; contrast with Fully-Anonymous Room and Non-Anonymous Room.
Temporary Room
A room that is destroyed if the last occupant exits; antonym: Persistent Room.
Unmoderated Room
A room in which any occupant is allowed to send messages to all occupants; antonym: Moderated Room.
Unsecured Room
A room that anyone is allowed to enter without first providing the correct password; antonym: Password-Protected Room.

4.3 Dramatis Personae

Most of the examples in this document use the scenario of the witches' meeting held in a dark cave at the beginning of Act IV, Scene I of Shakespeare's Macbeth, represented here as the "darkcave@chat.shakespeare.lit" chatroom. The characters are as follows:

Table 1: Dramatis Personae

Room Nickname Full JID Affiliation
firstwitch crone1@shakespeare.lit/desktop Owner
secondwitch wiccarocks@shakespeare.lit/laptop Admin
thirdwitch hag66@shakespeare.lit/pda None

5. Roles and Affiliations

There are two dimensions along which we can measure a user's connection with or position in a room. One is the user's long-lived affiliation with a room -- e.g., a user's status as an owner or an outcast. The other is a user's role while an occupant of a room -- e.g., an occupant's position as a moderator with the ability to kick visitors and participants. These two dimensions are distinct from each other, since an affiliation lasts across visits, while a role lasts only for the duration of a visit. In addition, there is no one-to-one correspondence between roles and affiliations; for example, someone who is not affiliated with a room may be a (temporary) moderator, and a member may be a participant or a visitor in a moderated room. These concepts are explained more fully below.

5.1 Roles

The following roles are defined:

Table 2: Roles

Name Support
Moderator REQUIRED
None N/A (the absence of a role)
Participant REQUIRED
Visitor RECOMMENDED

Roles are temporary in that they do not necessarily persist across a user's visits to the room and MAY change during the course of an occupant's visit to the room. An implementation MAY persist roles across visits and SHOULD do so for moderated rooms (since the distinction between visitor and participant is critical to the functioning of a moderated room).

There is no one-to-one mapping between roles and affiliations (e.g., a member could be a participant or a visitor).

A moderator is the most powerful occupant within the context of the room, and can to some extent manage other occupants' roles in the room. A participant has fewer privileges than a moderator, although he or she always has the right to speak. A visitor is a more restricted role within the context of a moderated room, since visitors are not allowed to send messages to all occupants.

Roles are granted, revoked, and maintained based on the occupant's room nickname or full JID rather than bare JID. The privileges associated with these roles, as well as the actions that trigger changes in roles, are defined below.

Information about roles MUST be sent in all presence stanzas generated or reflected by the room and thus sent to occupants.

5.1.1 Privileges

For the most part, roles exist in a hierarchy. For instance, a participant can do anything a visitor can do, and a moderator can do anything a participant can do. Each role has privileges not possessed by the next-lowest role; these privileges are specified in the following table as defaults (an implementation MAY provide configuration options that override these defaults).

Table 3: Privileges Associated With Roles

Privilege None Visitor Participant Moderator
Present in Room No Yes Yes Yes
Receive Messages No Yes Yes Yes
Receive Occupant Presence No Yes Yes Yes
Presence Broadcasted to Room No Yes* Yes Yes
Change Availability Status No Yes Yes Yes
Change Room Nickname No Yes* Yes Yes
Send Private Messages No Yes* Yes Yes
Invite Other Users No Yes* Yes* Yes
Send Messages to All No No** Yes Yes
Modify Subject No No* Yes* Yes
Kick Participants and Visitors No No No Yes
Grant Voice No No No Yes
Revoke Voice No No No Yes***

* Default; configuration settings MAY modify this privilege.

** An implementation MAY grant voice by default to visitors in unmoderated rooms.

*** A moderator MUST NOT be able to revoke voice privileges from an admin or owner.

5.1.2 Changing Roles

The ways in which an occupant's role changes are well-defined. Sometimes the change results from the occupant's own action (e.g., entering or exiting the room), whereas sometimes the change results from an action taken by a moderator, admin, or owner. If an occupant's role changes, a MUC service implementation MUST change the occupant's role to reflect the change and communicate the change to all occupants. Role changes and their triggering actions are specified in the following table.

Table 4: Role State Chart

> None Visitor Participant Moderator
None -- Enter moderated room Enter unmoderated room Admin or owner enters room
Visitor Exit room or be kicked by a moderator -- Moderator grants voice Admin or owner grants moderator privileges
Participant Exit room or be kicked by a moderator Moderator revokes voice -- Admin or owner grants moderator privileges
Moderator Exit room Admin or owner changes role to visitor * Admin or owner changes role to participant or revokes moderator privileges * --

* A moderator MUST NOT be able to revoke moderator privileges from an occupant who is equal to or above the moderator in the hierarchy of affiliations.

Note: Certain roles are typically implicit in certain privileges. For example, an admin or owner is automatically a moderator, so if an occupant is granted admin status then the occupant will by that fact be granted moderator privileges; similarly, when an occupant is made a member in a moderated room, the occupant automatically has a role of participant. However, the loss of admin status does not necessarily mean that the occupant is no longer a moderator (since a "mere" participant can be a moderator). Therefore, the roles that are gained when an occupant is granted a certain affiliation are stable, whereas the roles that are lost when an occupant loses a certain affilitation are no hardcoded and are left up to the implementation. Since a client cannot predict what the role will be after revoking a certain affiliation, if it wants to remove both admin/owner privileges and the moderator role at the same time then it must specifically request the role change in addition to the affiliation change.

5.2 Affiliations

The following affiliations are defined:

  1. Owner
  2. Admin
  3. Member
  4. Outcast
  5. None (the absence of an affiliation)

Support for the Owner affiliation is REQUIRED. Support for the Admin, Member, and Outcast affiliations is RECOMMENDED. (The "None" affiliation is the absence of an affiliation.)

These affiliations are long-lived in that they persist across a user's visits to the room and are not affected by happenings in the room. In addition, there is no one-to-one mapping between these affiliations and an occupant's role within the room. Affiliations are granted, revoked, and maintained based on the user's bare JID.

If a user without a defined affiliation enters a room, the user's affiliation is defined as "none"; however, this affiliation does not persist across visits (i.e., a service does not maintain a "none list" across visits).

The member affiliation provides a way for a room owner or admin to specify a "whitelist" of users who are allowed to enter a members-only room. When a member enters a members-only room, his or her affiliation does not change, no matter what his or her role is. The member affiliation also provides a way for users to effectively register with an open room and thus be lastingly associated with that room in some way (one result may be that the user's nickname is reserved in the room).

An outcast is a user who has been banned from a room and who is not allowed to enter the room.

Information about affiliations MUST be sent in all presence stanzas generated or reflected by the room and sent to occupants.

5.2.1 Privileges

For the most part, affiliations exist in a hierarchy. For instance, an owner can do anything an admin can do, and an admin can do anything a member can do. Each affiliation has privileges not possessed by the next-lowest affiliation; these privileges are specified in the following table.

Table 5: Privileges Associated With Affiliations

Privilege Outcast None Member Admin Owner
Enter Open Room No Yes* Yes Yes Yes
Register with Open Room No Yes N/A N/A N/A
Retrieve Member List No No** Yes Yes Yes
Enter Members-Only Room No No Yes* Yes Yes
Ban Members and Unaffiliated Users No No No Yes Yes
Edit Member List No No No Yes Yes
Edit Moderator List No No No Yes** Yes**
Edit Admin List No No No No Yes
Edit Owner List No No No No Yes
Change Room Definition No No No No Yes
Destroy Room No No No No Yes

* As a default, an unaffiliated user enters a moderated room as a visitor, and enters an open room as a participant. A member enters a room as a participant. An admin or owner enters a room as a moderator.

** An admin or owner MUST NOT be able to revoke moderation privileges from another admin or owner.

5.2.2 Changing Affiliations

The ways in which a user's affiliation changes are well-defined. Sometimes the change results from the user's own action (e.g., registering as a member of the room), whereas sometimes the change results from an action taken by an admin or owner. If a user's affiliation changes, a MUC service implementation MUST change the user's affiliation to reflect the change and communicate that to all occupants. Affiliation changes and their triggering actions are specified in the following table.

Table 6: Affiliation State Chart

> Outcast None Member Admin Owner
Outcast -- Admin or owner removes ban Admin or owner adds user to member list Owner adds user to admin list Owner adds user to owner list
None Admin or owner applies ban -- Admin or owner adds user to member list, or user registers as member (if allowed) Owner adds user to admin list Owner adds user to owner list
Member Admin or owner applies ban Admin or owner changes affiliation to "none" -- Owner adds user to admin list Owner adds user to owner list
Admin Owner applies ban Owner changes affiliation to "none" Owner changes affiliation to "member" -- Owner adds user to owner list
Owner Owner applies ban Owner changes affiliation to "none" Owner changes affiliation to "member" Owner changes affiliation to "admin" --

6. Entity Use Cases

A MUC implementation MUST support Service Discovery [7].

6.1 Discovering Component Support for MUC

A Jabber entity may wish to discover if a service implements the Multi-User Chat protocol; in order to do so, it sends a service discovery information ("disco#info") query to the component's JID:

Example 1. User Queries Chat Service for MUC Support via Disco

<iq from='hag66@shakespeare.lit/pda'
    id='disco1'
    to='chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
    

The service MUST return its identity and the features it supports:

Example 2. Service Returns Disco Info Results

<iq from='chat.shakespeare.lit'
    id='disco1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='Macbeth Chat Service'
        type='text'/>
    <feature var='http://jabber.org/protocol/muc'/>
  </query>
</iq>
    

Note: Because MUC is a superset of the old "groupchat 1.0" protocol, a MUC service SHOULD NOT return a <feature var='gc-1.0'/> entry in a disco#info result.

6.2 Discovering Rooms

The service discovery items ("disco#items") protocol enables a user 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 hosted by the service.

Example 3. User Queries Chat Service for Rooms

<iq from='hag66@shakespeare.lit/pda'
    id='disco2'
    to='chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
    

The service SHOULD return a full list of the rooms it hosts.

Example 4. Service Returns Disco Item Results

<iq from='chat.shakespeare.lit'
    id='disco2'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='heath@chat.shakespeare.lit'
          name='A Lonely Heath'/>
    <item jid='darkcave@chat.shakespeare.lit'
          name='A Dark Cave'/>
    <item jid='forres@chat.shakespeare.lit'
          name='The Palace'/>
    <item jid='inverness@chat.shakespeare.lit'
          name='Macbeth&apos;s Castle'/>
  </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 so, it SHOULD include a <set/> element (as defined in Result Set Management [8]) to indicate that the list not the full result set.

Example 5. Service Returns Limited List of Disco Item Results

<iq from='rooms.shakespeare.lit'
    id='disco-rsm-1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='alls-well-that-ends-well@rooms.shakespeare.lit'/>
    <item jid='as-you-like-it@rooms.shakespeare.lit'/>
    <item jid='cleopatra@rooms.shakespeare.lit'/>
    <item jid='comedy-of-errors@rooms.shakespeare.lit'/>
    <item jid='coriolanus@rooms.shakespeare.lit'/>
    <item jid='cymbeline@rooms.shakespeare.lit'/>
    <item jid='hamlet@rooms.shakespeare.lit'/>
    <item jid='henry-the-fourth-one@rooms.shakespeare.lit'/>
    <item jid='henry-the-fourth-two@rooms.shakespeare.lit'/>
    <item jid='henry-the-fifth@rooms.shakespeare.lit'/>
    <set xmlns='http://jabber.org/protocol/rsm'>
      <first index='0'>alls-well-that-ends-well@rooms.shakespeare.lit</first>
      <last>henry-the-fifth@rooms.shakespeare.lit</last>
      <count>37</count>
    </set>
  </query>
</iq>
    

6.3 Querying for Room Information

Using the disco#info protocol, a user may also query a specific chat room for more detailed information about the room. A user SHOULD do so before entering a room in order to determine the privacy and security profile of the room configuration (see the Security Considerations for details).

Example 6. User Queries for Information about a Specific Chat Room

<iq from='hag66@shakespeare.lit/pda'
    id='disco3'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
    

The room MUST return its identity and SHOULD return the features it supports:

Example 7. Room Returns Disco Info Results

<iq from='darkcave@chat.shakespeare.lit'
    id='disco3'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='text'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='muc_passwordprotected'/>
    <feature var='muc_hidden'/>
    <feature var='muc_temporary'/>
    <feature var='muc_open'/>
    <feature var='muc_unmoderated'/>
    <feature var='muc_nonanonymous'/>
  </query>
</iq>
    

Note: Because MUC is a superset of the old "groupchat 1.0" protocol, a MUC room SHOULD NOT return a <feature var='gc-1.0'/> entry in a disco#info result. The room SHOULD return the materially-relevant features it supports, such as password protection and room moderation (these are listed fully in the feature registry maintained by the XMPP Registrar; see also the XMPP Registrar section of this document).

A chatroom MAY return more detailed information in its disco#info response using Service Discovery Extensions [9], identified by inclusion of a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/muc#roominfo". Such information might include a more verbose description of the room, the current room subject, and the current number of occupants in the room:

Example 8. Room Returns Extended Disco Info Results

<iq from='darkcave@chat.shakespeare.lit'
    id='disco3a'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='text'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='muc_passwordprotected'/>
    <feature var='muc_hidden'/>
    <feature var='muc_temporary'/>
    <feature var='muc_open'/>
    <feature var='muc_unmoderated'/>
    <feature var='muc_nonanonymous'/>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#roominfo</value>
      </field>
      <field var='muc#roominfo_description' label='Description'>
        <value>The place for all good witches!</value>
      </field>
      <field var='muc#roominfo_changesubject' label='Whether Occupants May Change the Subject'>
        <value>true</value>
      </field>
      <field var='muc#roominfo_contactjid' label='Contact Addresses'>
        <value>crone1@shakespeare.lit</value>
      </field>
      <field var='muc#roominfo_subject' label='Subject'>
        <value>Spells</value>
      </field>
      <field var='muc#roomconfig_changesubject' label='Subject can be modified'>
        <value>true</value>
      </field>
      <field var='muc#roominfo_occupants' label='Number of occupants'>
        <value>3</value>
      </field>
      <field var='muc#roominfo_ldapgroup' label='Associated LDAP Group'>
        <value>dc=lit,dc=shakespeare,cn=witches</value>
      </field>
      <field var='muc#roominfo_lang' label='Language of discussion'>
        <value>en</value>
      </field>
      <field var='muc#roominfo_logs' label='URL for discussion logs'>
        <value>http://www.shakespeare.lit/chatlogs/darkcave/</value>
      </field>
      <field var='muc#roominfo_pubsub' label='Associated pubsub node'>
        <value>xmpp:pubsub.shakespeare.lit?;node=the-darkcave-node</value>
      </field>
    </x>
  </query>
</iq>
    

Some extended room information may be dynamically generated (e.g., the URL for discussion logs, which may be based on service-wide configuration). Other information may be based on the room configuration, which is why any field defined for the muc#roomconfig FORM_TYPE can be included in the extended service discovery fields (as shown above for the muc#roomconfig_changesubject field).

Note: The foregoing extended service discovery fields for the 'http://jabber.org/protocol/muc#roominfo' FORM_TYPE may be supplemented in the future via the mechanisms described in the Field Standardization section of this document.

6.4 Querying for Room Items

A user MAY also query a specific chat room for its associated items:

Example 9. User Queries for Items Associated with a Specific Chat Room

<iq from='hag66@shakespeare.lit/pda'
    id='disco4'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
    

An implementation MAY return a list of existing occupants if that information is publicly available, or return no list at all if this information is kept private.

Example 10. Room Returns Disco Item Results (Items are Public)

<iq from='darkcave@chat.shakespeare.lit'
    id='disco4'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='darkcave@chat.shakespeare.lit/firstwitch'/>
    <item jid='darkcave@chat.shakespeare.lit/secondwitch'/>
  </query>
</iq>
    

Note: These <item/> elements are qualified by the disco#items namespace, not the muc namespace; this means that they cannot possess 'affiliation' or 'role' attributes, for example.

Example 11. Room Returns Empty Disco Item Results (Items are Private)

<iq from='darkcave@chat.shakespeare.lit'
    id='disco4'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
    

6.5 Querying a Room Occupant

If a non-occupant attempts to send a disco request to an address of the form <room@service/nick>, a MUC service SHOULD return the request to the entity and specify a <bad-request/> error condition. If an occupant sends such a request, the service MAY pass it through the intended recipient; see the Implementation Guidelines section of this document for details.

6.6 Discovering Client Support for MUC

A Jabber user may want to discover if one of the user's contacts supports the Multi-User Chat protocol. This is done using Service Discovery.

Example 12. User Queries Contact Regarding MUC Support

<iq from='hag66@shakespeare.lit/pda'
    id='disco5'
    to='wiccarocks@shakespeare.lit/laptop'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
    

The client SHOULD return its identity and the features it supports:

Example 13. Contact Returns Disco Info Results

<iq from='wiccarocks@shakespeare.lit/laptop'
    id='disco5'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='client'
        type='pc'/>
    ...
    <feature var='http://jabber.org/protocol/muc'/>
    ...
  </query>
</iq>
    

A user may also query a contact regarding which rooms the contact is in. This is done by querying the contact's full JID (<user@host/resource>) while specifying the well-known Service Discovery node 'http://jabber.org/protocol/muc#rooms':

Example 14. User Queries Contact for Current Rooms

<iq from='hag66@shakespeare.lit/pda'
    id='rooms1'
    to='wiccarocks@shakespeare.lit/laptop'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='http://jabber.org/protocol/muc#rooms'/>
</iq>
    

Example 15. Contact Returns Room Query Results

<iq from='wiccarocks@shakespeare.lit/laptop'
    id='rooms1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='http://jabber.org/protocol/muc#rooms'>
    <item jid='darkcave@chat.shakespeare.lit'/>
    <item jid='characters@conference.shakespeare.lit'/>
  </query>
</iq>
    

Optionally, the contact MAY include its roomnick as the value of the 'name' attribute:

    ...
    <item jid='darkcave@chat.shakespeare.lit'
          name='secondwitch'/>
    ...
    

7. Occupant Use Cases

The main actor in a multi-user chat environment is the occupant, who can be said to be located "in" a multi-user chat room and to participate in the discussions held in that room (for the purposes of this specification, participants and visitors are considered to be "mere" occupants, since they possess no administrative privileges). As will become clear, the protocol elements proposed in this document to fulfill the occupant use cases fall into three categories:

  1. existing "groupchat 1.0" protocol for minimal functionality

  2. straightforward applications of the "groupchat 1.0" protocol, for example to handle some of the errors related to new room types

  3. additional protocol elements to handle functionality not covered by "groupchat 1.0" (room invites, room passwords, extended presence related to room roles and affiliations); these are qualified by the 'http://jabber.org/protocol/muc#user' namespace

Note: All client-generated examples herein are presented from the perspective of the service, with the result that all stanzas received by a service contain a 'from' attribute corresponding to the sender's full JID as added by a normal Jabber router or session manager. In addition, normal IQ result stanzas sent upon successful completion of a request (as required by RFC 3920 [10]) are not shown.

7.1 Entering a Room

7.1.1 Groupchat 1.0 Protocol

In order to participate in the discussions held in a multi-user chat room, a Jabber user MUST first become an occupant by entering the room. In the old "groupchat 1.0" protocol, this was done by sending presence to <room@service/nick>, where "room" is the room ID, "service" is the hostname of the chat service, and "nick" is the user's desired nickname within the room:

Example 16. Jabber User Seeks to Enter a Room (Groupchat 1.0)

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'/>
      

In this example, a user with a full JID of "hag66@shakespeare.lit/pda" has requested to enter the room "darkcave" on the "chat.shakespeare.lit" chat service with a room nickname of "thirdwitch".

If the user does not specify a room nickname, the service MUST return a <jid-malformed/> error:

Example 17. No Nickname Specified

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <error type='modify'>
    <jid-malformed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

7.1.2 Basic MUC Protocol

Compliant multi-user chat services MUST accept the foregoing as a request to enter a room from any Jabber client that knows either the "groupchat 1.0" (GC) protocol or the multi-user chat (MUC) protocol; however, MUC clients SHOULD signal their ability to speak the MUC protocol by including in the initial presence stanza an empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace (note the absence of the '#user' fragment):

Example 18. Jabber User Seeks to Enter a Room (Multi-User Chat)

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>
      

Note: If an error occurs in relation to joining a room, the service SHOULD include the MUC child element (i.e., <x xmlns='http://jabber.org/protocol/muc'/>) in the <presence/> stanza of type "error".

Before attempting to enter the room, a MUC-compliant client SHOULD first discover its reserved room nickname (if any) by following the protocol defined in the Discovering Reserved Room Nickname section of this document.

7.1.3 Presence Broadcast

If the service is able to add the user to the room, it MUST send presence from all the existing occupants' room JIDs to the new occupant's full JID, including extended presence information about roles in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "moderator", "participant", or "visitor", and with the 'affiliation' attribute set to a value of "owner", "admin", "member", or "none" as appropriate:

Example 19. Service Sends Presence from Existing Occupants to New Occupant

<presence
    from='darkcave@chat.shakespeare.lit/firstwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin' role='moderator'/>
  </x>
</presence>
      

In this example, the user from the previous example has entered the room, by which time two other people had already entered the room: a user with a room nickname of "firstwitch" (who is a room owner) and a user with a room nickname of "secondwitch" (who is a room admin).

The service MUST also send presence from the new occupant's room JID to the full JIDs of all the occupants (including the new occupant):

Example 20. Service Sends New Occupant's Presence to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
    <status code='110'/>
  </x>
</presence>
      

In this example, initial room presence is being sent from the new occupant (thirdwitch) to all occupants, including the new occupant. As shown in the last stanza, the presence sent by the room to a user from itself as an occupant SHOULD include a status code of 110 so that the user knows this presence refers to itself as an occupant.

The service MAY rewrite the new occupant's roomnick (e.g., if roomnicks are locked down). If the service does not accept the new occupant's requested roomnick but instead assigns a new roomnick, it MUST include a status code of "210" in the presence broadcast that it sends to the new occupant.

Example 21. Service Sends New Occupant's Presence to New Occupant

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
    <status code='110'/>
    <status code='210'/>
  </x>
</presence>
      

Note: The order of the presence stanzas sent to the new occupant is important. The service MUST first send the complete list of the existing occupants to the new occupant and only then send the new occupant's own presence to the new occupant. This helps the client know when it has received the complete "room roster".

After sending the presence broadcast (and only after doing so), the service may then send discussion history, live messages, presence updates, and other in-room traffic.

7.1.4 Default Roles

The following table summarizes the initial default roles that a service should set based on the user's affiliation (there is no role associated with the "outcast" affiliation, since such users are not allowed to enter the room).

Table 7: Initial Role Based on Affiliation

Room Type None Member Admin Owner
Moderated Visitor Participant Moderator Moderator
Unmoderated Participant Participant Moderator Moderator
Members-Only N/A * Participant Moderator Moderator
Open Participant Participant Moderator Moderator

* Entry is not permitted.

7.1.5 Non-Anonymous Rooms

If the room is non-anonymous, the service MUST send the new occupant's full JID to all occupants using extended presence information in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with a 'jid' attribute specifying the occupant's full JID:

Example 22. Service Sends Full JID to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
      

If the user is entering a room that is non-anonymous (i.e., which informs all occupants of each occupant's full JID as shown above), the service SHOULD allow the user to enter the room but MUST also warn the user that the room is not anonymous. This SHOULD be done by including a status code of "100" in the initial presence that the room sends to the new occupant:

Example 23. Service Sends New Occupant's Presence to New Occupant

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
    <status code='100'/>
    <status code='110'/>
    <status code='210'/>
  </x>
</presence>
      

However, it MAY be done by sending a message of type "groupchat" to the new occupant containing an <x/> child with a <status/> element that has the 'code' attribute set to a value of "100":

Example 24. Service Warns New Occupant About Lack of Anonymity

<message
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='groupchat'>
  <body>This room is not anonymous.</body>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <status code='100'/>
  </x>
</message>
      

The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality).

7.1.6 Semi-Anonymous Rooms

If the room is semi-anonymous, the service MUST send presence from the new occupant to all occupants as specified above, but MUST include the new occupant's full JID only in the presence notifications it sends to occupants with a role of "moderator" and not to non-moderator occupants.

(Note: All subsequent examples include the 'jid' attribute for each <item/> element, even though this information is not sent to non-moderators in semi-anonymous rooms.)

7.1.7 Password-Protected Rooms

If the room requires a password and the user did not supply one (or the password provided is incorrect), the service MUST deny access to the room and inform the user that they are unauthorized; this is done by returning a presence stanza of type "error" specifying a <not-authorized/> error:

Example 25. Service Denies Access Because No Password Provided

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='auth'>
    <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

Passwords SHOULD be supplied with the presence stanza sent when entering the room, contained within an <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace and containing a <password/> child. Passwords are to be sent as cleartext; no other authentication methods are supported at this time, and any such authentication or authorization methods shall be defined in a separate specification (see the Security Considerations section of this document).

Example 26. User Provides Password On Entering a Room

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <password>cauldronburn</password>
  </x>
</presence>
      

7.1.8 Members-Only Rooms

If the room is members-only but the user is not on the member list, the service MUST deny access to the room and inform the user that they are not allowed to enter the room; this is done by returning a presence stanza of type "error" specifying a <registration-required/> error condition:

Example 27. Service Denies Access Because User Is Not on Member List

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='auth'>
    <registration-required xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

7.1.9 Banned Users

If the user has been banned from the room (i.e., has an affiliation of "outcast"), the service MUST deny access to the room and inform the user of the fact that he or she is banned; this is done by returning a presence stanza of type "error" specifying a <forbidden/> error condition:

Example 28. Service Denies Access Because User is Banned

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

7.1.10 Nickname Conflict

If the room already contains another user with the nickname desired by the user seeking to enter the room (or if the nickname is reserved by another user on the member list), the service MUST deny access to the room and inform the user of the conflict; this is done by returning a presence stanza of type "error" specifying a <conflict/> error condition:

Example 29. Service Denies Access Because of Nick Conflict

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

However, if the bare JID <localpart@domain.tld> of the present occupant matches the bare JID of the user seeking to enter the room, then the service SHOULD allow entry to the user, so that the user has two (or more) in-room "sessions" with the same roomnick, one for each resource. If a service allows more than one occupant with the same bare JID and the same room nickname, it SHOULD route in-room messages to all of the user's resources and allow all of the user's resources to send messages to the room; it is up to the implementation to determine how to appropriately handle presence from the user's resources and how to route private messages to all or only one resource (based on presence priority or some other algorithm).

How nickname conflicts are determined is up to the implementation (e.g., whether the service applies a case folding routine, a stringprep profile such as Resourceprep or Nodeprep, etc.).

7.1.11 Max Users

If the room has reached its maximum number of occupants, the service SHOULD deny access to the room and inform the user of the restriction; this is done by returning a presence stanza of type "error" specifying a <service-unavailable/> error condition:

Example 30. Service Informs User that Room Occupant Limit Has Been Reached

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='wait'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

Alternatively, the room could kick an "idle user" in order to free up space.

If the room has reached its maximum number of occupants and a room admin or owner attempts to join, the room SHOULD allow the admin or owner to join, up to some reasonable number of additional occupants, which number MAY be configurable.

7.1.12 Locked Room

If a user attempts to enter a room while it is "locked" (i.e., before the room creator provides an initial configuration and therefore before the room officially exists), the service MUST refuse entry and return an <item-not-found/> error to the user:

Example 31. Service Denies Access Because Room Does Not Exist

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

7.1.13 Nonexistent Room

If the room does not already exist when the user seeks to enter it, the service SHOULD create it; however, this is not required, since an implementation or deployment MAY choose to restrict the privilege of creating rooms. For details, see the Creating a Room section of this document.

7.1.14 Room Logging

If the user is entering a room in which the discussions are logged to a public archive (often accessible via HTTP), the service SHOULD allow the user to enter the room but MUST also warn the user that the discussions are logged. This SHOULD be done by including a status code of "170" in the initial presence that the room sends to the new occupant:

Example 32. Service Sends New Occupant's Presence to New Occupant

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
    <status code='100'/>
    <status code='110'/>
    <status code='170'/>
    <status code='210'/>
  </x>
</presence>
      

7.1.15 Discussion History

After sending initial presence as shown above, a room MAY send discussion history to the new occupant. (The room MUST NOT send any discussion history before it finishes sending room presence as specified in the Presence Broadcast section of this document.) Whether such history is sent, and how many messages comprise the history, shall be determined by the chat service implementation or specific deployment.

Example 33. Delivery of Discussion History

<message
    from='darkcave@chat.shakespeare.lit/firstwitch'
    to='hecate@shakespeare.lit/broom'
    type='groupchat'>
  <body>Thrice the brinded cat hath mew'd.</body>
  <delay xmlns='urn:xmpp:delay'
     from='crone1@shakespeare.lit/desktop'
     stamp='2002-10-13T23:58:37Z'/>
</message>

<message
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='hecate@shakespeare.lit/broom'
    type='groupchat'>
  <body>Thrice and once the hedge-pig whined.</body>
  <delay xmlns='urn:xmpp:delay'
     from='wiccarocks@shakespeare.lit/laptop'
     stamp='2002-10-13T23:58:43Z'/>
</message>

<message
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hecate@shakespeare.lit/broom'
    type='groupchat'>
  <body>Harpier cries 'Tis time, 'tis time.</body>
  <delay xmlns='urn:xmpp:delay'
     from='hag66@shakespeare.lit/pda'
     stamp='2002-10-13T23:58:49Z'/>
</message>
      

Discussion history messages MUST be stamped with Delayed Delivery [11] information qualified by the 'urn:xmpp:delay' namespace to indicate that they are sent with delayed delivery and to specify the times at which they were originally sent. (Note: The 'urn:xmpp:delay' namespace defined in XEP-0203 supersedes the older 'jabber:x:delay' namespace defined in Legacy Delayed Delivery [12]; until the status of XEP-0091 is changed to Obsolete, implementations SHOULD include both datetime formats.) The 'from' attribute SHOULD be the full JID of the original sender in non-anonymous rooms, but MUST NOT be in semi-anonymous rooms (where the 'from' attribute SHOULD be set to the JID of the room itself). The service SHOULD send all discussion history messages before delivering any "live" messages sent after the user enters the room.

7.1.16 Managing Discussion History

A user MAY want to manage the amount of discussion history provided on entering a room (perhaps because the user is on a low-bandwidth connection or is using a small-footprint client). This MUST be accomplished by including a <history/> child in the initial presence stanza sent when joining the room. There are four allowable attributes for this element:

Table 8: History Management Attributes

Attribute Datatype Meaning
maxchars int Limit the total number of characters in the history to "X" (where the character count is the characters of the complete XML stanzas, not only their XML character data).
maxstanzas int Limit the total number of messages in the history to "X".
seconds int Send only the messages received in the last "X" seconds.
since dateTime Send only the messages received since the datetime specified (which MUST conform to the DateTime profile specified in XMPP Date and Time Profiles [13]).

The service MUST send the smallest amount of traffic that meets any combination of the above criteria, taking into account service-level and room-level defaults. The service MUST send complete message stanzas only (i.e., it MUST not literally truncate the history at a certain number of characters, but MUST send the largest number of complete stanzas that results in a number of characters less than or equal to the 'maxchars' value specified). If the client wishes to receive no history, it MUST set the 'maxchars' attribute to a value of "0" (zero).

The following examples illustrate the use of this protocol.

Example 34. User Requests Limit on Number of Messages in History

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <history maxstanzas='20'/>
  </x>
</presence>
      

Example 35. User Requests History in Last 3 Minutes

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <history seconds='180'/>
  </x>
</presence>
      

Example 36. User Requests All History Since the Beginning of the Unix Era

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <history since='1970-01-01T00:00:00Z'/>
  </x>
</presence>
      

Obviously the service SHOULD NOT return all messages sent in the room since the beginning of the Unix era, and SHOULD appropriately limit the amount of history sent to the user based on service or room defaults.

Example 37. User Requests No History

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <history maxchars='0'/>
  </x>
</presence>
      

7.2 Exiting a Room

In order to exit a multi-user chat room, an occupant sends a presence stanza of type "unavailable" to the <room@service/nick> it is currently using in the room.

Example 38. Occupant Exits a Room

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/thirdwitch'
    type='unavailable'/>
    

The service MUST then send presence stanzas of type "unavailable" from the departing occupant's room JID to the full JIDs of the departing occupant and of the remaining occupants:

Example 39. Service Sends Presence Related to Departure of Occupant

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='none'/>
    <status code='110'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='none'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='none'/>
  </x>
</presence>
    

Presence stanzas of type "unavailable" reflected by the room MUST contain extended presence information about roles and affiliations; the 'role' attribute SHOULD be set to a value of "none" to denote that the individual is no longer an occupant.

The occupant MAY include normal <status/> information in the unavailable presence stanzas; this enables the occupant to provide a custom exit message if desired:

Example 40. Custom Exit Message

<presence
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit/oldhag'
    type='unavailable'>
  <status>gone where the goblins go</status>
</presence>
    

Normal presence stanza generation rules apply as defined in XMPP IM [14], so that if the user sends a general unavailable presence stanza, the user's server will broadcast that stanza to the <room@service/nick> to which the user's client has sent directed presence.

It is possible that a user may not be able to gracefully exit the room by sending unavailable presence directly to the room. If the user goes offline without sending unavailable presence, the user's server is responsible for sending unavailable presence on behalf of the user (in accordance with RFC 3921). If the user's server goes offline or connectivity is lost between the user's server and the MUC service to which the user is connected (e.g., in federated communications), the MUC service is responsible for monitoring error stanzas it receives in order to determine if the user has gone offline. If the MUC service determines that the user has gone offline, it must treat the user as if the user had itself sent unavailable presence.

Note: If the room is not persistent and this occupant is the last to exit, the service is responsible for destroying the room.

7.3 Changing Nickname

A common feature of multi-user chat rooms is the ability for an occupant to change his or her nickname within the room. In MUC this is done by sending updated presence information to the room, specifically by sending presence to a new room JID in the same room (changing only the resource identifier in the room JID).

Example 41. Occupant Changes Nickname

<presence
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit/oldhag'/>
    

The service then sends two presence stanzas to the full JID of each occupant (including the occupant who is changing his or her room nickname), one of type "unavailable" for the old nickname and one indicating availability for the new nickname.

The unavailable presence MUST contain the following as extended presence information in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace:

This enables the recipients to correlate the old roomnick with the new roomnick.

Example 42. Service Updates Nick

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          nick='oldhag'
          role='participant'/>
    <status code='303'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          nick='oldhag'
          role='participant'/>
    <status code='303'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          nick='oldhag'
          role='participant'/>
    <status code='303'/>
    <status code='110'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/oldhag'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/oldhag'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>
<presence
    from='darkcave@chat.shakespeare.lit/oldhag'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
    <status code='110'/>
  </x>
</presence>
    

If the user attempts to change his or her room nickname to a room nickname that is already in use by another user (or that is reserved by another user affiliated with the room, e.g., a member or owner), the service MUST deny the nickname change request and inform the user of the conflict; this is done by returning a presence stanza of type "error" specifying a <conflict/> error condition:

Example 43. Service Denies Nickname Change Because of Nick Conflict

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
    

However, if the bare JID <localpart@domain.tld> of the present occupant matches the bare JID of the user seeking to change his or her nickname, then the service MAY allow the nickname change. See the Nickname Conflict section of this document for details.

If the user attempts to change his or her room nickname but room nicknames are "locked down", the service MUST deny the nickname change request and return a presence stanza of type "error" specifying a <not-acceptable/> error condition:

Example 44. Service Denies Nickname Change Because Roomnicks Are Locked Down

<presence
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='cancel'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
    

The user SHOULD then discover its reserved nickname as specified in the Discovering Reserved Room Nickname section of this document.

7.4 Changing Availability Status

In multi-user chat systems such as IRC, one common use for changing one's room nickname is to indicate a change in one's availability (e.g., changing one's room nickname to "thirdwitch|away"). In Jabber, availability is of course noted by a change in presence (specifically the <show/> and <status/> elements), which can provide important context within a chatroom. An occupant changes availability status within the room by sending the updated presence to its <room@service/nick>.

Example 45. Occupant Changes Availability Status

<presence
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit/oldhag'>
  <show>xa</show>
  <status>gone where the goblins go</status>
</presence>
    

The service then sends a presence stanza from the occupant changing his or her presence to the full JID of each occupant, including extended presence information about the occupant's role and full JID to those with privileges to view such information:

Example 46. Service Passes Along Changed Presence to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <show>xa</show>
  <status>gone where the goblins go</status>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit/laptop'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

7.5 Inviting Another User to a Room

7.5.1 Direct Invitation

A method for sending a direct invitation (not mediated by the room itself) is defined in Direct MUC Invitations [15]. Sending the invitation directly can help to work around communications blocking on the part of the invitee (which might refuse communication with entities not in its roster).

7.5.2 Mediated Invitation

It can be useful to invite another user to a room in which one is an occupant. To do this, a MUC client MUST send XML of the following form to the <room@service> itself (the reason is OPTIONAL and the message MUST be explicitly or implicitly of type "normal"):

Example 47. Occupant Sends an Invitation by Way of Room

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'>
      <reason>
        Hey Hecate, this is the place for all good witches!
      </reason>
    </invite>
  </x>
</message>
      

The <room@service> itself MUST then add a 'from' address to the <invite/> element whose value is the bare JID, full JID, or room JID of the invitor and send the invitation to the invitee specified in the 'to' address (the service MAY include a message body explaining the invitation or containing the reason, for the sake of older clients; in addition, the room SHOULD add the password if the room is password-protected):

Example 48. Room Sends Invitation to Invitee on Behalf of Invitor

<message
    from='darkcave@chat.shakespeare.lit'
    to='hecate@shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit/desktop'>
      <reason>
        Hey Hecate, this is the place for all good witches!
      </reason>
    </invite>
    <password>cauldronburn</password>
  </x>
</message>
      

If the room is members-only, the service MAY also add the invitee to the member list. (Note: Invitation privileges in members-only rooms SHOULD be restricted to room admins; if a member without privileges to edit the member list attempts to invite another user, the service SHOULD return a <forbidden/> error to the occupant; for details, see the Modifying the Member List section of this document.)

If the invitor supplies a non-existent JID, the room SHOULD return an <item-not-found/> error to the invitor.

The invitee MAY choose to formally decline (as opposed to ignore) the invitation; and this is something that the sender may want to be informed about. In order to decline the invitation, the invitee MUST send a message of the following form to the <room@service> itself:

Example 49. Invitee Declines Invitation

<message
    from='hecate@shakespeare.lit/broom'
    to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <decline to='crone1@shakespeare.lit'>
      <reason>
        Sorry, I'm too busy right now.
      </reason>
    </decline>
  </x>
</message>
      

Example 50. Room Informs Invitor that Invitation Was Declined

<message
    from='darkcave@chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <decline from='hecate@shakespeare.lit'>
      <reason>
        Sorry, I'm too busy right now.
      </reason>
    </decline>
  </x>
</message>
      

It may be wondered why the invitee does not send the decline message directly to the invitor. The main reason is that certain implementations MAY choose to base invitations on room JIDs rather than bare JIDs (so that, for example, an occupant could invite someone from one room to another without knowing that person's bare JID). Thus the service MUST handle both the invites and declines.

7.6 Converting a One-to-One Chat Into a Multi-User Conference

Sometimes it is desirable to convert a one-to-one chat into a multi-user conference. The process flow is shown in the following examples.

First, two users begin a one-to-one chat.

Example 51. A One-to-One Chat

<message
    from='crone1@shakespeare.lit/desktop'
    to='wiccarocks@shakespeare.lit/laptop'
    type='chat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice the brinded cat hath mew'd.</body>
</message>

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='crone1@shakespeare.lit/desktop'
    type='chat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice and once the hedge-pig whined.</body>
</message>
    

Now the first person decides to include a third person in the discussion, so she (or, more precisely, her client) does the following:

  1. Creates a new multi-user chatroom
  2. Optionally sends history of the one-to-one chat to the room
  3. Sends an invitation to the second person and the third person, including a <continue/> element (optionally including a 'thread' attribute).

Note: The new room SHOULD be non-anonymous, MAY be an instant room as specified in the Creating an Instant Room section of this document, and MAY have a unique room name received from the service as specified in the Requesting a Unique Room Name section of this document.

Note: If the one-to-one chat messages included a <thread/> element, the person who creates the room SHOULD include the ThreadID with the history messages, specify the ThreadID in the invitations as the value of the <continue/> element's 'thread' attribute, and include the ThreadID in any new messages sent to the room. Use of ThreadIDs is RECOMMENDED because it helps to provide continuity between the one-to-one chat and the multi-user chat.

Example 52. Continuing the Discussion I: User Creates Room

<presence
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit/firstwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/firstwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
    <status code='110'/>
  </x>
</presence>
    

Example 53. Continuing the Discussion II: Owner Sends History to Room

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit'
    type='groupchat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice the brinded cat hath mew'd.</body>
  <delay xmlns='urn:xmpp:delay'
     from='crone1@shakespeare.lit/desktop'
     stamp='2004-09-29T01:54:37Z'/>
</message>

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit'
    type='groupchat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice and once the hedge-pig whined.</body>
  <delay xmlns='urn:xmpp:delay'
     from='wiccarocks@shakespeare.lit/laptop'
     stamp='2004-09-29T01:55:21Z'/>
</message>
    

Note: Use of the Delayed Delivery protocol enables the room creator to specify the datetime of each message from the one-to-one chat history (via the 'stamp' attribute), as well as the JID of the original sender of each message (via the 'from' attribute). The room creator SHOULD send the complete one-to-one chat history before inviting additional users to the room, and SHOULD also send as history any messages appearing in the one-to-one chat interface after joining the room and before the second person joins the room; if the one-to-one history is especially large, the sending client may want to send the history over a few seconds rather than all at once (to avoid triggering rate limits). The service SHOULD NOT add its own delay elements (as described in the Discussion History section of this document) to prior chat history messages received from the room owner.

Example 54. Continuing the Discussion III: Owner Sends Invitations, Including Continue Flag

<message
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='wiccarocks@shakespeare.lit/laptop'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue thread='e0ffe42b28561960c6b12b944a092794b9683a38'/>
    </invite>
    <invite to='hag66@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue thread='e0ffe42b28561960c6b12b944a092794b9683a38'/>
    </invite>
  </x>
</message>
    

Note: Since the invitor's client knows the full JID of the person with whom the invitor was having a one-to-one chat, it SHOULD include the full JID (rather than the bare JID) in the invitation.

The invitations are delivered to the invitees:

Example 55. Invitations Delivered

<message
    from='darkcave@chat.shakespeare.lit'>
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue thread='e0ffe42b28561960c6b12b944a092794b9683a38'/>
    </invite>
  </x>
</message>

<message
    from='darkcave@chat.shakespeare.lit'>
    to='hag66@shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='crone1@shakespeare.lit'>
      <reason>This coven needs both wiccarocks and hag66.</reason>
      <continue thread='e0ffe42b28561960c6b12b944a092794b9683a38'/>
    </invite>
  </x>
</message>
    

When the client being used by <wiccarocks@shakespeare.lit/laptop> receives the invitation, it SHOULD auto-join the room or prompt the user whether to join (subject to user preferences) and then seamlessly convert the existing one-to-one chat window into a multi-user conferencing window:

Example 56. Invitee Accepts Invitation, Joins Room, and Receives Presence and History

<presence
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit/secondwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/firstwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='wiccarocks@shakespeare.lit/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
  </x>
</presence>

<message
    from='darkcave@chat.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    type='groupchat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice the brinded cat hath mew'd.</body>
  <delay xmlns='urn:xmpp:delay'
     from='crone1@shakespeare.lit/desktop'
     stamp='2004-09-29T01:54:37Z'/>
</message>

<message
    from='darkcave@chat.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    type='groupchat'>
  <thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
  <body>Thrice and once the hedge-pig whined.</body>
  <delay xmlns='urn:xmpp:delay'
     from='wiccarocks@shakespeare.lit/laptop'
     stamp='2004-09-29T01:55:21Z'/>
</message>
    

Note: The fact that the messages come from the <room@service> itself rather than <room@service/nick> is a clue to the receiving client that these messages are prior chat history, since any message from a room occupant will have a 'from' address equal to the sender's room JID.

7.7 Occupant Modification of the Room Subject

If allowed in accordance with room configuration, a mere occupant MAY be allowed to change the subject in a room. For details, see the Modifying the Room Subject section of this document.

7.8 Sending a Private Message

Since each occupant has a unique room JID, an occupant MAY send a "private message" to a selected occupant via the service by sending a message to the occupant's room JID. The message type SHOULD be "chat" and MUST NOT be "groupchat", but MAY be left unspecified (i.e., a normal message). This privilege SHOULD be allowed to any occupant (even a visitor in a moderated room).

Example 57. Occupant Sends Private Message

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit/firstwitch'
    type='chat'>
  <body>I'll give thee a wind.</body>
</message>
    

The service is responsible for changing the 'from' address to the sender's room JID and delivering the message to the intended recipient's full JID.

Example 58. Recipient Receives the Private Message

<message
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'
    type='chat'>
  <body>I'll give thee a wind.</body>
</message>
    

If the sender attempts to send a private message of type "groupchat" to a particular occupant, the service MUST refuse to deliver the message (since the recipient's client would expect in-room messages to be of type "groupchat") and return a <bad-request/> error to the sender:

Example 59. Occupant Attempts to Send a Message of Type "Groupchat" to a Particular Occupant

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit/firstwitch'
    type='groupchat'>
  <body>I'll give thee a wind.</body>
</message>

<message
    from='darkcave@chat.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    type='error'>
  <body>I'll give thee a wind.</body>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>
    

If the sender attempts to send a private message to a room JID that does not exist, the service MUST return an <item-not-found/> error to the sender.

If the sender is not an occupant of the room in which the intended recipient is visiting, the service MUST return a <not-acceptable/> error to the sender.

7.9 Sending a Message to All Occupants

An occupant sends a message to all other occupants in the room by sending a message of type "groupchat" to the <room@service> itself (a service MAY ignore or reject messages that do not have a type of "groupchat"). In a moderated room, this privilege is restricted to occupants with a role of participant or higher.

Example 60. Occupant Sends a Message to All Occupants

<message
    from='hag66@shakespeare.lit/pda'
    to='darkcave@chat.shakespeare.lit'
    type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
</message>
    

If the sender has voice in the room (this is the default except in moderated rooms), the service MUST change the 'from' attribute to the sender's room JID and reflect the message out to the full JID of each occupant.

Example 61. Service Reflects Message to All Occupants

<message
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'
    type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
</message>
<message
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'
    type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
</message>
<message
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'
    type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
</message>
    

If the sender is a visitor (i.e., does not have voice in a moderated room), the service MAY return a <forbidden/> error to the sender and MUST NOT reflect the message to all occupants. If the sender is not an occupant of the room, the service SHOULD return a <not-acceptable/> error to the sender and SHOULD NOT reflect the message to all occupants; the only exception to this rule is that an implementation MAY allow users with certain privileges (e.g., a room owner, room admin, or service-level admin) to send messages to the room even if those users are not occupants.

7.10 Registering with a Room

An implementation MAY allow an unaffiliated user (in a moderated room, normally a participant) to register with a room and thus become a member of the room (conversely, an implementation MAY restrict this privilege and allow only room admins to add new members). In particular, it is not possible to join a members-only room without being on the member list, so an entity may need to request membership in order to join such a room.

If allowed, this functionality SHOULD be implemented by enabling a user to send a request for registration requirements to the room qualified by the 'jabber:iq:register' namespace as described in In-Band Registration [16]:

Example 62. User Requests Registration Requirements

<iq from='hag66@shakespeare.lit/pda'
    id='reg1'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='jabber:iq:register'/>
</iq>
    

If the user requesting registration requirements is not allowed to register with the room (e.g., because that privilege has been restricted), the room MUST return a <not-allowed/> error to the user. If the user is already registered, the room MUST reply with an IQ stanza of type "result" that contains an empty <register/> element as described in XEP-0077. If the room does not exist, the service MUST return an <item-not-found/> error.

Otherwise, the room MUST then return a Data Form to the user (as described in Data Forms [17]). The information required to register MAY vary by implementation or deployment and is not fully specified in this document (e.g., the fields registered by this document for the 'http://jabber.org/protocol/muc#register' FORM_TYPE may be supplemented in the future via the mechanisms described in the Field Standardization section of this document). The following can be taken as a fairly typical example:

Example 63. Service Returns Registration Form

<iq from='darkcave@chat.shakespeare.lit'
    id='reg1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      To register on the web, visit http://shakespeare.lit/
    </instructions>
    <x xmlns='jabber:x:data' type='form'>
      <title>Dark Cave Registration</title>
      <instructions>
        Please provide the following information
        to register with this room.
      </instructions>
      <field
          type='hidden'
          var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#register</value>
      </field>
      <field
          label='Given Name'
          type='text-single'
          var='muc#register_first'>
        <required/>
      </field>
      <field
          label='Family Name'
          type='text-single'
          var='muc#register_last'>
        <required/>
      </field>
      <field
          label='Desired Nickname'
          type='text-single'
          var='muc#register_roomnick'>
        <required/>
      </field>
      <field
          label='Your URL'
          type='text-single'
          var='muc#register_url'/>
      <field
          label='Email Address'
          type='text-single'
          var='muc#register_email'/>
      <field
          label='FAQ Entry'
          type='text-multi'
          var='muc#register_faqentry'/>
    </x>
  </query>
</iq>
    

The user SHOULD then submit the form:

Example 64. User Submits Registration Form

<iq from='hag66@shakespeare.lit/pda'
    id='reg2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#register</value>
      </field>
      <field var='muc#register_first'>
        <value>Brunhilde</value>
      </field>
      <field var='muc#register_last'>
        <value>Entwhistle-Throckmorton</value>
      </field>
      <field var='muc#register_roomnick'>
        <value>thirdwitch</value>
      </field>
      <field var='muc#register_url'>
        <value>http://witchesonline/~hag66/</value>
      </field>
      <field var='muc#register_email'>
        <value>hag66@witchesonline</value>
      </field>
      <field var='muc#register_faqentry'>
        <value>Just another witch.</value>
      </field>
    </x>
  </query>
</iq>
    

If the desired room nickname is already reserved for that room, the room MUST return a <conflict/> error to the user:

Example 65. Room Returns Conflict Error to User

<iq from='darkcave@chat.shakespeare.lit'
    id='reg2'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the room or service does not support registration, it MUST return a <service-unavailable/> error to the user:

Example 66. Room Returns Service Unavailable Error to User

<iq from='darkcave@chat.shakespeare.lit'
    id='reg2'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the user did not include a valid data form, the room MUST return a <bad-request/> error to the user:

Example 67. Room Returns Service Bad Request Error to User

<iq from='darkcave@chat.shakespeare.lit'
    id='reg2'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

Otherwise, the room MUST inform the user that the registration request was successfully received:

Example 68. Room Informs User that Registration Request Has Been Processed

<iq from='darkcave@chat.shakespeare.lit'
    id='reg2'
    to='hag66@shakespeare.lit/pda'
    type='result'/>
    

After the user submits the form, the service MAY request that the submission be approved by a room admin/owner (see the Approving Registration Requests section of this document) or MAY immediately add the user to the member list by changing the user's affiliation from "none" to "member". If the service changes the user's affiliation and the user is in the room, it MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".

Example 69. Service Sends Notice of Membership to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

If a user has registered with a room, the room MAY choose to restrict the user to use of the registered nickname only in that room. If it does so, it SHOULD return a <not-acceptable/> error to the user if the user attempts to join the room with a roomnick other than the user's registered roomnick (this enables a room to "lock down" roomnicks for consistent identification of occupants).

7.11 Getting Member List

If allowed in accordance with room configuration, an occupant MAY be allowed to retrieve the list of room members. For details, see the Modifying the Member List section of this document.

7.12 Discovering Reserved Room Nickname

A user MAY have a reserved room nickname, for example through explicit room registration, database integration, or nickname "lockdown". A user SHOULD discover his or her reserved nickname before attempting to enter the room. This is done by sending a Service Discovery information request to the room JID while specifying a well-known Service Discovery node of "x-roomuser-item".

Example 70. User Requests Reserved Nickname

<iq from='hag66@shakespeare.lit/pda'
    id='getnick1'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='x-roomuser-item'/>
</iq>
    

It is OPTIONAL for a multi-user chat service to support the foregoing service discovery node. If the room or service does not support the foregoing service discovery node, it MUST return a <feature-not-implemented/> error to the user. If it does and the user has a registered nickname, it MUST return the nickname to the user as the value of the 'name' attribute of a Service Discovery <identity/> element (for which the category/type SHOULD be "conference/text"):

Example 71. Room Returns Nickname

<iq from='darkcave@chat.shakespeare.lit'
    id='getnick1'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='x-roomuser-item'>
    <identity
        category='conference'
        name='thirdwitch'
        type='text'/>
  </query>
</iq>
    

If the user does not have a registered nickname, the room MUST return a service discovery <query/> element that is empty (in accordance with XEP-0030).

Even if a user has registered one room nickname, the service SHOULD allow the user to specify a different nickname on entering the room (e.g., in order to join from different client resources), although the service MAY choose to "lock down" nicknames and therefore deny entry to the user, including a <not-acceptable/> error. The service MUST NOT return an error to the user if his or her client sends the foregoing request after having already joined the room, but instead SHOULD reply as described above.

If another user attempts to join the room with a nickname reserved by the first user, the service MUST deny entry to the second user and return a <conflict/> error as previously described.

7.13 Requesting Voice

It is not possible for a visitor to speak (i.e., send a message to all occupants) in a moderated room. To request voice, a visitor SHOULD send a <message/> stanza containing a data form to the room itself, where data form contains only a 'muc#role' field with a value of "participant".

Example 72. Occupant Requests Voice

<message from='hag66@shakespeare.lit/pda'
         to='darkcave@chat.shakespeare.lit'>
  <x xmlns='jabber:x:data' type='submit'>
    <field var='FORM_TYPE'>
      <value>http://jabber.org/protocol/muc#request</value>
    </field>
    <field var='muc#role'
           type='text-single'
           label='Requested role'>
      <value>participant</value>
    </field>
  </x>
</message>
    

The service then SHOULD forward the request to the room moderator(s) as described in the Approving Voice Requests section of this document.

8. Moderator Use Cases

A moderator has privileges to perform certain actions within the room (e.g., to change the roles of some occupants) but does not have rights to change persistent information about affiliations (which may be changed only by an admin or owner) or defining information about the room. Exactly which actions may be performed by a moderator is subject to configuration. However, for the purposes of the MUC framework, moderators are stipulated to have privileges to perform the following actions:

  1. discover an occupant's full JID in a semi-anonymous room (occurs by default as shown above)
  2. modify the subject
  3. kick a participant or visitor from the room
  4. grant or revoke voice in a moderated room
  5. modify the list of occupants who have voice in a moderated room

These features shall be implemented with a request/response exchange using <iq/> elements that contain children qualified by the 'http://jabber.org/protocol/muc#admin' namespace. The examples below illustrate the protocol interactions to implement the desired functionality. (Except where explicitly noted below, any of the following administrative requests MUST be denied if the <user@host> of the 'from' address of the request does not match the bare JID portion of one of the moderators; in this case, the service MUST return a <forbidden/> error.)

8.1 Modifying the Room Subject

A common feature of multi-user chat rooms is the ability to change the subject within the room. By default, only users with a role of "moderator" SHOULD be allowed to change the subject in a room (although this SHOULD be configurable, with the result that a mere participant or even visitor may be allowed to change the subject if desired). The subject is changed by sending a message of type "groupchat" to the <room@service>, where the <message/> MUST contain a <subject/> element that specifies the new subject but SHOULD NOT contain any other element (e.g., no <body/> element or <thread/> element).

Example 73. Moderator Changes Subject

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit'
    type='groupchat'>
  <subject>Fire Burn and Cauldron Bubble!</subject>
</message>
    

If a MUC service receives such a message, it MUST reflect the message to all other occupants with a 'from' address equal to the room JID that corresponds to the sender of the subject change:

Example 74. Service Informs All Occupants of Subject Change

<message
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'
    type='groupchat'>
  <subject>Fire Burn and Cauldron Bubble!</subject>
</message>

[ ... ]
    

In addition, the room SHOULD include the last subject change in the discussion history sent when a new occupant joins the room.

A MUC client that receives such a message MAY choose to display an in-room message, such as the following:

Example 75. Client Displays Room Subject Change Message

* secondwitch has changed the subject to: Fire Burn and Cauldron Bubble!
    

If someone without appropriate privileges attempts to change the room subject, the service MUST return a message of type "error" specifying a <forbidden/> error condition:

Example 76. Service Returns Error Related to Unauthorized Subject Change

<message
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <subject>Fire Burn and Cauldron Bubble!</subject>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>
    

In order to remove the existing subject but not provide a new subject (i.e., set the subject to be empty), the client shall send an empty <subject/> element (i.e., either "<subject/>" or "<subject></subject>").

Example 77. Moderator Sets Empty Subject

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@chat.shakespeare.lit'
    type='groupchat'>
  <subject></subject>
</message>
    

8.2 Kicking an Occupant

A moderator has permissions kick certain kinds of occupants from a room (which occupants are "kickable" depends on service provisioning, room configuration, and the moderator's affiliation -- see below). The kick is normally performed based on the occupant's room nickname (though it MAY be based on the full JID) and is completed by setting the role of a participant or visitor to a value of "none".

Example 78. Moderator Kicks Occupant

<iq from='fluellen@shakespeare.lit/pda'
    id='kick1'
    to='harfleur@henryv.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='pistol' role='none'>
      <reason>Avaunt, you cullion!</reason>
    </item>
  </query>
</iq>
    

The service MUST remove the kicked occupant by sending a presence stanza of type "unavailable" to each kicked occupant, including status code 307 in the extended presence information, optionally along with the reason (if provided) and the bare JID of the user who initiated the kick.

Example 79. Service Removes Kicked Occupant

<presence
    from='harfleur@henryv.shakespeare.lit/pistol'
    to='pistol@shakespeare.lit/harfleur'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'>
      <actor jid='fluellen@shakespeare.lit'/>
      <reason>Avaunt, you cullion!</reason>
    </item>
    <status code='307'/>
  </x>
</presence>
    

The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality). The optional inclusion of the reason and actor enable the kicked user to understand why he or she was kicked, and by whom if the kicked occupant would like to discuss the matter. [18]

After removing the kicked occupant(s), the service MUST then inform the moderator of success:

Example 80. Service Informs Moderator of Success

<iq from='harfleur@henryv.shakespeare.lit'
    id='kick1'
    to='fluellen@shakespeare.lit/pda'
    type='result'/>
    

After informing the moderator, the service MUST then inform all of the remaining occupants that the kicked occupant is no longer in the room by sending presence stanzas of type "unavailable" from the individual's roomnick (<room@service/nick>) to all the remaining occupants (just as it does when occupants exit the room of their own volition), including the status code and optionally the reason and actor.

Example 81. Service Informs Remaining Occupants

<presence
    from='harfleur@henryv.shakespeare.lit/pistol'
    to='gower@shakespeare.lit/cell'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'/>
    <status code='307'/>
  </x>
</presence>

[ ... ]
    

A user cannot be kicked by a moderator with a lower affiliation. Therefore, if a moderator who is a participant attempts to kick an admin or a moderator who is a participant or admin attempts to kick an owner, the service MUST deny the request and return a <not-allowed/> error to the sender:

Example 82. Service Returns Error on Attempt to Kick User With Higher Affiliation

<iq from='darkcave@chat.shakespeare.lit'
    id='kicktest'
    to='wiccarocks@shakespeare.lit/laptop'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='firstwitch' role='none'>
      <reason>Be gone!</reason>
    </item>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If a moderator attempts to kick himself, the service MAY deny the request and return a <conflict/> error to the sender. (Although the act of kicking oneself may seem odd, it is common in IRC as a way of apologizing for one's actions in the room.)

8.3 Granting Voice to a Visitor

In a moderated room, a moderator may want to manage who does and does not have "voice" in the room (i.e., the ability to send messages to all occupants). Voice is granted based on the visitor's room nickname, which the service will convert into the visitor's full JID internally. The moderator grants voice to a visitor by changing the visitor's role to "participant".

Example 83. Moderator Grants Voice to a Visitor

<iq from='crone1@shakespeare.lit/desktop'
    id='voice1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='participant'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL:

Example 84. Moderator Grants Voice to a Visitor (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='voice1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='participant'>
      <reason>A worthy witch indeed!</reason>
    </item>
  </query>
</iq>
    

The service MUST then inform the moderator of success:

Example 85. Service Informs Moderator of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='voice1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence from this individual's <room@service/nick> to all occupants, indicating the addition of voice privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "participant".

Example 86. Service Sends Notice of Voice to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          nick='thirdwitch'
          role='participant'>
      <reason>A worthy witch indeed!</reason>
    </item>
  </x>
</presence>

[ ... ]
    

8.4 Revoking Voice from a Participant

In a moderated room, a moderator may want to revoke a participant's privileges to speak. The moderator can revoke voice from a participant by changing the participant's role to "visitor":

Example 87. Moderator Revokes Voice from a Participant

<iq from='crone1@shakespeare.lit/desktop'
    id='voice2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='visitor'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL:

Example 88. Moderator Revokes Voice from a Visitor (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='voice2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='visitor'>
      <reason>Not so worthy after all!</reason>
    </item>
  </query>
</iq>
    

The service MUST then inform the moderator of success:

Example 89. Service Informs Moderator of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='voice2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence from this individual to all occupants, indicating the removal of voice privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "visitor".

Example 90. Service Notes Loss of Voice

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='visitor'/>
  </x>
</presence>

[ ... ]
    

A moderator MUST NOT be able to revoke voice from a user whose affiliation is at or above the moderator's level. In addition, a service MUST NOT allow the voice privileges of an admin or owner to be removed by anyone. If a moderator attempts to revoke voice privileges from such a user, the service MUST deny the request and return a <not-allowed/> error to the sender along with the offending item(s):

Example 91. Service Returns Error on Attempt to Revoke Voice from an Admin, Owner, or User with a Higher Affiliation

<iq from='darkcave@chat.shakespeare.lit'
    id='voicetest'
    to='crone1@shakespeare.lit/desktop'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='secondwitch' role='visitor'/>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

8.5 Modifying the Voice List

A moderator in a moderated room may want to modify the voice list. To do so, the moderator first requests the voice list by querying the room for all occupants with a role of 'participant'.

Example 92. Moderator Requests Voice List

<iq from='bard@shakespeare.lit/globe'
    id='voice3'
    to='goodfolk@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item role='participant'/>
  </query>
</iq>
    

The service MUST then return the voice list to the moderator; each item MUST include the 'nick' and 'role' attributes and SHOULD include the 'affiliation' and 'jid' attributes:

Example 93. Service Sends Voice List to Moderator

<iq from='goodfolk@chat.shakespeare.lit'
    id='voice3'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='none'
          jid='polonius@hamlet/castle'
          nick='Polo'
          role='participant'/>
    <item affiliation='none'
          jid='horatio@hamlet/castle'
          nick='horotoro'
          role='participant'/>
    <item affiliation='member'
          jid='hecate@shakespeare.lit/broom'
          nick='Hecate'
          role='participant'/>
  </query>
</iq>
    

The moderator MAY then modify the voice list. In order to do so, the moderator MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'nick' attribute and 'role' attribute (normally set to a value of "participant" or "visitor") but SHOULD NOT include the 'jid' attribute and MUST NOT include the 'affiliation' attribute (which is used to manage affiliations such as owner rather than the participant role):

Example 94. Moderator Sends Modified Voice List to Service

<iq from='bard@shakespeare.lit/globe'
    id='voice4'
    to='goodfolk@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='Hecate'
          role='visitor'/>
    <item nick='rosencrantz'
          role='participant'>
      <reason>A worthy fellow.</reason>
    </item>
    <item nick='guildenstern'
          role='participant'>
      <reason>A worthy fellow.</reason>
    </item>
  </query>
</iq>
    

The service MUST then inform the moderator of success:

Example 95. Service Informs Moderator of Success

<iq from='goodfolk@chat.shakespeare.lit'
    id='voice1'
    to='bard@shakespeare.lit/globe'
    type='result'/>
    

The service MUST then send updated presence for any affected individuals to all occupants, indicating the change in voice privileges by sending the appropriate extended presence stanzas as described in the foregoing use cases.

As noted, voice privileges cannot be revoked from a room owner or room admin, nor from any user with a higher affiliation than the moderator making the request. If a room admin attempts to revoke voice privileges from such a user by modifying the voice list, the service MUST deny the request and return a <not-allowed/> error to the sender:

Example 96. Service Returns Error on Attempt to Revoke Voice from an Admin, Owner, or User with a Higher Affiliation

<iq from='goodfolk@chat.shakespeare.lit'
    id='voicetest'
    to='bard@shakespeare.lit/globe'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item jid='hecate@shakespeare.lit'
          nick='Hecate'
          role='visitor'/>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

8.6 Approving Voice Requests

As noted in the Requesting Voice section of this document, when a service receives a request for voice from an occupant it SHOULD forward that request to the room moderator(s). To do so, the service SHOULD send a <message/> stanza to the room moderator(s), where the <message/> stanza contains a data form asking for approval or denial of the request, as shown below.

Example 97. Voice Request Approval Form

<message from='darkcave@chat.shakespeare.lit'
         id='approve'
         to='crone1@shakespeare.lit/pda'>
  <x xmlns='jabber:x:data' type='form'>
    <title>Voice request</title>
    <instructions>
      To approve this request for voice, select 
      the &quot;Grant voice to this person?&quot;
      checkbox and click OK. To skip this request, 
      click the cancel button.
    </instructions>
    <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#request</value>
    </field>
    <field var='muc#role'
           type='text-single'
           label='Requested role'>
      <value>participant</value>
    </field>
    <field var='muc#jid'
           type='text-single'
           label='User ID'>
      <value>hag66@shakespeare.lit/pda</value>
    </field>
    <field var='muc#roomnick'
           type='text-single'
           label='Room Nickname'>
      <value>thirdwitch</value>
    </field>
    <field var='muc#request_allow'
           type='boolean'
           label='Grant voice to this person?'>
      <value>false</value>
    </field>
  </x>
</message>
    

In order to approve the request, a moderator shall submit the form:

Example 98. Voice Request Approval Submission

<message from='crone1@shakespeare.lit/pda'
         id='approve'
         to='darkcave@chat.shakespeare.lit'>
  <x xmlns='jabber:x:data' type='submit'>
    <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#request</value>
    </field>
    <field var='muc#role'>
      <value>participant</value>
    </field>
    <field var='muc#jid'>
      <value>hag66@shakespeare.lit/pda</value>
    </field>
    <field var='muc#roomnick'>
      <value>thirdwitch</value>
    </field>
    <field var='muc#request_allow'>
      <value>true</value>
    </field>
  </x>
</message>
    

If a moderator approves the voice request, the service shall grant voice to the occupant and send a presence update as described in the Granting Voice to a Visitor section of this document.

9. Admin Use Cases

A room administrator has privileges to modify persistent information about user affiliations (e.g., by banning users) and to grant and revoke moderator privileges, but does not have rights to change the defining features of the room, which are the sole province of the room owner(s). Exactly which actions may be performed by a room admin will be subject to configuration. However, for the purposes of the MUC framework, room admins are stipulated to at a minimum have privileges to perform the following actions:

  1. ban a user from the room
  2. modify the list of users who are banned from the room
  3. grant or revoke membership
  4. modify the member list
  5. grant or revoke moderator privileges
  6. modify the list of moderators

These features shall be implemented with a request/response exchange using <iq/> elements that contain children qualified by the 'http://jabber.org/protocol/muc#admin' namespace. The examples below illustrate the protocol interactions that implement the desired functionality. (Except where explicitly noted below, any of the following administrative requests MUST be denied if the <user@host> of the 'from' address of the request does not match the bare JID of one of the room admins; in this case, the service MUST return a <forbidden/> error.)

9.1 Banning a User

An admin or owner can ban one or more users from a room. The ban MUST be performed based on the occupant's bare JID. In order to ban a user, an admin MUST change the user's affiliation to "outcast".

Example 99. Admin Bans User

<iq from='kinghenryv@shakespeare.lit/throne'
    id='ban1'
    to='southampton@henryv.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 100. Admin Bans User (With a Reason)

<iq from='kinghenryv@shakespeare.lit/throne'
    id='ban1'
    to='southampton@henryv.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
  </query>
</iq>
    

The service MUST add that bare JID to the ban list, SHOULD remove the outcast's nickname from the list of registered nicknames, and MUST inform the admin or owner of success:

Example 101. Service Informs Admin or Owner of Success

<iq from='southampton@henryv.shakespeare.lit'
    id='ban1'
    to='kinghenryv@shakespeare.lit/throne'
    type='result'/>
    

The service MUST also remove any banned users who are in the room by sending a presence stanza of type "unavailable" to each banned occupant, including status code 301 in the extended presence information, optionally along with the reason (if provided) and the bare JID of the user who initiated the ban.

Example 102. Service Removes Banned User

<presence
    from='southampton@henryv.shakespeare.lit/cambridge'
    to='earlofcambridge@shakespeare.lit/stabber'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='outcast' role='none'>
      <actor jid='kinghenryv@shakespeare.lit'/>
      <reason>Treason</reason>
    </item>
    <status code='301'/>
  </x>
</presence>
    

The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality). The optional inclusion of the reason and actor enable the banned user to understand why he or she was banned, and by whom if the banned user would like to discuss the matter.

The service MUST then inform all of the remaining occupants that the banned user is no longer in the room by sending presence stanzas of type "unavailable" from the banned user to all remaining occupants (just as it does when occupants exit the room of their own volition), including the status code and optionally the reason and actor:

Example 103. Service Informs Remaining Occupants

<presence
    type='unavailable'
    from='southampton@henryv.shakespeare.lit/cambridge'
    to='exeter@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit/stabber'
          role='none'/>
    <status code='301'/>
  </x>
</presence>

[ ... ]
    

As with Kicking an Occupant, a user cannot be banned by an admin with a lower affiliation. Therefore, if an admin attempts to ban an owner, the service MUST deny the request and return a <not-allowed/> error to the sender:

Example 104. Service Returns Error on Attempt to Ban User With Higher Affiliation

<iq from='kinghenryv@shakespeare.lit/throne'
    id='ban1'
    to='southampton@henryv.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If an admin or owner attempts to ban himself, the service MUST deny the request and return a <conflict/> error to the sender. (Note: This is different from the recommended service behavior on kicking oneself, which a service may allow.)

9.2 Modifying the Ban List

A room admin may want to modify the ban list. Note: The ban list is always based on a user's bare JID. To modify the list of banned JIDs, the admin first requests the ban list by querying the room for all users with an affiliation of 'outcast'.

Example 105. Admin Requests Ban List

<iq from='kinghenryv@shakespeare.lit/throne'
    id='ban2'
    to='southampton@henryv.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'/>
  </query>
</iq>
    

The service MUST then return the list of banned users to the admin; each item MUST include the 'affiliation' and 'jid' attributes but SHOULD NOT include the 'nick' and 'role' attributes:

Example 106. Service Sends Ban List to Admin

<iq from='southampton@henryv.shakespeare.lit'
    id='ban2'
    to='kinghenryv@shakespeare.lit/throne'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
  </query>
</iq>
    

The admin MAY then modify the ban list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'affiliation' attribute (normally set to a value of "outcast" to ban or "none" to remove ban) and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the outcast affiliation); in addition, the reason and actor elements are OPTIONAL:

Example 107. Admin Sends Modified Ban List to Service

<iq from='kinghenryv@shakespeare.lit/throne'
    id='ban3'
    to='southampton@henryv.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='earlofcambridge@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
    <item affiliation='outcast'>
          jid='lordscroop@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
    <item affiliation='outcast'
          jid='sirthomasgrey@shakespeare.lit'>
      <reason>Treason</reason>
    </item>
  </query>
</iq>
    

After updating the ban list, the service MUST inform the admin of success:

Example 108. Service Informs Admin of Success

<iq from='southampton@henryv.shakespeare.lit'
    id='ban3'
    to='kinghenryv@shakespeare.lit/throne'
    type='result'/>
    

The service MUST then remove the affected occupants (if they are in the room) and send updated presence (including the appropriate status code) from them to all the remaining occupants as described in the "Banning a User" use case. (The service SHOULD also remove each banned user's reserved nickname from the list of reserved roomnicks, if appropriate.)

When an entity is banned from a room, an implementation SHOULD match JIDs in the following order (these matching rules are the same as those defined for privacy lists in RFC 3921):

  1. <user@domain/resource> (only that resource matches)
  2. <user@domain> (any resource matches)
  3. <domain/resource> (only that resource matches)
  4. <domain> (the domain itself matches, as does any user@domain or domain/resource)

Some administrators may wish to ban all users associated with a specific domain from all rooms hosted by a MUC service. Such functionality is a service-level feature and is therefore out of scope for this document, instead being defined in XEP-0133.

9.3 Granting Membership

An admin can grant membership to a user; this is done by changing the user's affiliation to "member" (normally based on nick if the user is in the room, or on bare JID if not; in either case, if the nick is provided, that nick becomes the user's default nick in the room if that functionality is supported by the implementation):

Example 109. Admin Grants Membership

<iq from='crone1@shakespeare.lit/desktop'
    id='member1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 110. Admin Grants Membership (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='member1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit'>
      <reason>A worthy witch indeed!</reason>
    </item>
  </query>
</iq>
    

The service MUST add the user to the member list and then inform the admin of success:

Example 111. Service Informs Admin of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='member1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of membership by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".

Example 112. Service Sends Notice of Membership to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

If the user is not in the room, the service MAY send a message from the room itself to the room occupants, indicating the granting of membership by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".

Example 113. Service Sends Notice of Membership to All Occupants

<message
    from='chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit'
          role='none'/>
  </x>
</message>

[ ... ]
    

9.4 Revoking Membership

An admin may want to revoke a user's membership; this is done by changing the user's affiliation to "none":

Example 114. Admin Revokes Membership

<iq from='crone1@shakespeare.lit/desktop'
    id='member2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 115. Admin Revokes Membership (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='member2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit'>
      <reason>Not so worthy after all!</reason> 
    </item>
  </query>
</iq>
    

The service MUST remove the user from the member list and then inform the moderator of success:

Example 116. Service Informs Moderator of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='member2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence from this individual to all occupants, indicating the loss of membership by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "none".

Example 117. Service Notes Loss of Membership

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

If the room is members-only, the service MUST remove the user from the room, including a status code of 321 to indicate that the user was removed because of an affiliation change, and inform all remaining occupants:

Example 118. Service Removes Non-Member

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'>
      <actor jid='bard@shakespeare.lit'/>
    </item>
    <status code='321'/>
  </x>
</presence>

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'/>
    <status code='321'/>
  </x>
</presence>

[ ... ]
    

9.5 Modifying the Member List

In the context of a members-only room, the member list is essentially a "whitelist" of people who are allowed to enter the room. Anyone who is not a member is effectively banned from entering the room, even if their affiliation is not "outcast".

In the context of an open room, the member list is simply a list of users (bare JID and reserved nick) who are registered with the room. Such users may appear in a room roster, have their room nickname reserved, be returned in search results or FAQ queries, and the like.

It is RECOMMENDED that only room admins have the privilege to modify the member list in members-only rooms. To do so, the admin first requests the member list by querying the room for all users with an affiliation of "member":

Example 119. Admin Requests Member List

<iq from='crone1@shakespeare.lit/desktop'
    id='member3'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'/>
  </query>
</iq>
    

Note: A service SHOULD also return the member list to any occupant in a members-only room; i.e., it SHOULD NOT generate a <forbidden/> error when a member in the room requests the member list. This functionality may assist clients in showing all the existing members even if some of them are not in the room, e.g. to help a member determine if another user should be invited. A service SHOULD also allow any member to retrieve the member list even if not yet an occupant.

The service MUST then return the full member list to the admin qualified by the 'http://jabber.org/protocol/muc#admin' namespace; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for each members that is currently an occupant.

Example 120. Service Sends Member List to Admin

<iq from='darkcave@chat.shakespeare.lit'
    id='member3'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit'
          nick='thirdwitch'
          role='participant'/>
  </query>
</iq>
    

The admin MAY then modify the member list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") to the service; each item MUST include the 'affiliation' attribute (normally set to a value of "member" or "none") and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the member affiliation):

Example 121. Admin Sends Modified Member List to Service

<iq from='crone1@shakespeare.lit/desktop'
    id='member4'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit'/>
    <item affiliation='member'
          jid='hecate@shakespeare.lit'/>
  </query>
</iq>
    

The service MUST modify the member list and then inform the moderator of success:

Example 122. Service Informs Moderator of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='member4'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST change the affiliation of any affected user. If the user has been removed from the member list, the service MUST change the user's affiliation from "member" to "none". If the user has been added to the member list, the service MUST change the user's affiliation to "member".

If a removed member is currently in a members-only room, the service SHOULD kick the occupant by changing the removed member's role to "none" and send appropriate presence to the removed member as previously described. No matter whether the removed member was in or out of a members-only room, the service MUST subsequently refuse entry to the user.

For all room types, the service MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "none".

Example 123. Service Sends Notice of Loss of Membership to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

In addition, the service SHOULD send an invitation to any user who has been added to the member list of a members-only room if the user is not currently affiliated with the room, for example as an admin or owner (such a user would by definition not be in the room; note also that this example includes a password but not a reason -- both child elements are OPTIONAL):

Example 124. Room Sends Invitation to New Member

<message
    from='darkcave@chat.shakespeare.lit'
    to='hecate@shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite from='bard@shakespeare.lit'/>
    <password>cauldronburn</password>
  </x>
</message>
    

While only admins and owners SHOULD be allowed to modify the member list, an implementation MAY provide a configuration option that opens invitation privileges to any member of a members-only room. In such a situation, any invitation sent SHOULD automatically trigger the addition of the invitee to the member list. However, if invitation privileges are restricted to admins and a mere member attempts to a send an invitation, the service MUST deny the invitation request and return a <forbidden/> error to the sender:

Example 125. Service Returns Error on Attempt by Mere Member to Invite Others to a Members-Only Room

<message
    from='darkcave@chat.shakespeare.lit'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'>
      <reason>
        Hey Hecate, this is the place for all good witches!
      </reason>
    </invite>
  </x>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>
    

Invitations sent through an open room MUST NOT trigger the addition of the invitee to the member list.

If a user is added to the member list of an open room and the user is in the room, the service MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".

Example 126. Service Sends Notice of Membership to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/hecate'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hecate@shakespeare.lit/broom'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

9.6 Granting Moderator Privileges

An admin may want to grant moderator privileges to a participant or visitor; this is done by changing the user's role to "moderator":

Example 127. Admin Grants Moderator Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='mod1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='moderator'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 128. Admin Grants Moderator Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='mod1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='moderator'>
      <reason>A worthy witch indeed!</reason> 
    </item>
  </query>
</iq>
    

The service MUST add the user to the moderator list and then inform the admin of success:

Example 129. Service Informs Admin of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='mod1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence from this individual to all occupants, indicating the addition of moderator privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "moderator".

Example 130. Service Sends Notice of Moderator Privileges to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

9.7 Revoking Moderator Privileges

An admin may want to revoke a user's moderator privileges. An admin MAY revoke moderator privileges only from a user whose affiliation is "member" or "none" (i.e., not from an owner or admin). The privilege is revoked by changing the user's role to "participant":

Example 131. Admin Revokes Moderator Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='mod2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='participant'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 132. Admin Revokes Moderator Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='mod2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='thirdwitch'
          role='participant'>
      <reason>Not so worthy after all!</reason> 
    </item>
  </query>
</iq>
    

The service MUST remove the user from the moderator list and then inform the admin of success:

Example 133. Service Informs Admin of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='mod2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence from this individual to all occupants, indicating the removal of moderator privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "participant".

Example 134. Service Notes Loss of Moderator Privileges

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

As noted, an admin MUST NOT be allowed to revoke moderator privileges from a user whose affiliation is "owner" or "admin". If an admin attempts to revoke moderator privileges from such a user, the service MUST deny the request and return a <not-allowed/> error to the sender:

Example 135. Service Returns Error on Attempt to Revoke Moderator Privileges from an Admin or Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='modtest'
    to='crone1@shakespeare.lit/desktop'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='secondwitch' role='participant'/>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

9.8 Modifying the Moderator List

An admin may want to modify the moderator list. To do so, the admin first requests the moderator list by querying the room for all users with a role of 'moderator'.

Example 136. Admin Requests Moderator List

<iq from='crone1@shakespeare.lit/desktop'
    id='mod3'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item role='moderator'/>
  </query>
</iq>
    

The service MUST then return the moderator list to the admin; each item MUST include the 'jid', 'nick', and 'role' attributes and SHOULD include the 'affiliation' attribute:

Example 137. Service Sends Moderator List to Admin

<iq from='darkcave@chat.shakespeare.lit'
    id='mod3'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='hag66@shakespeare.lit/pda'
          nick='thirdwitch'
          role='moderator'/>
  </query>
</iq>
    

The admin MAY then modify the moderator list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'jid' attribute and 'role' attribute (normally set to a value of "member" or "participant") but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'affiliation' attribute (which is used to manage affiliations such as admin rather than the moderator role):

Example 138. Admin Sends Modified Moderator List to Service

<iq from='crone1@shakespeare.lit/desktop'
    id='mod4'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item jid='hag66@shakespeare.lit/pda'
          role='participant'/>
    <item jid='hecate@shakespeare.lit/broom'
          role='moderator'/>
  </query>
</iq>
    

The service MUST modify the moderator list and then inform the admin of success:

Example 139. Service Informs Admin of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='mod4'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST then send updated presence for any affected individuals to all occupants, indicating the change in moderator privileges by sending the appropriate extended presence stanzas as described in the foregoing use cases.

As noted, moderator privileges cannot be revoked from a room owner or room admin. If a room admin attempts to revoke moderator privileges from such a user by modifying the moderator list, the service MUST deny the request and return a <not-allowed/> error to the sender:

Example 140. Service Returns Error on Attempt to Revoke Moderator Privileges from an Admin or Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='modtest'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item jid='hecate@shakespeare.lit/broom'
          nick='Hecate'
          role='participant'/>
  </query>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

9.9 Approving Registration Requests

If a service does not automatically accept requests to register with a room, it MAY provide a way for room admins to approve or deny registration requests over Jabber (alternatively, it could provide a web interface or some other admin tool). The simplest way to do so is for the service to send a <message/> stanza to the room admin(s) when the registration request is received, where the <message/> stanza contains a Data Form asking for approval or denial of the request. The following Data Form is RECOMMENDED but implementations MAY use a different form entirely, or supplement the following form with additional fields.

Example 141. Registration Request Approval Form

<message from='darkcave@chat.shakespeare.lit'
         id='approve'
         to='crone1@shakespeare.lit/pda'>
  <x xmlns='jabber:x:data' type='form'>
    <title>Registration request</title>
    <instructions>
      To approve this registration request, select the
      &quot;Allow this person to register with the room?&quot;
      checkbox and click OK. To skip this request, click the 
      cancel button.
    </instructions>
    <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#register</value>
    </field>
    <field var='muc#register_first'
           type='text-single'
           label='Given Name'>
      <value>Brunhilde</value>
    </field>
    <field var='muc#register_last'
           type="text-single"
           label="Family Name">
      <value>Entwhistle-Throckmorton</value>
    </field>
    <field var='muc#register_roomnick'
           type="text-single"
           label="Desired Nickname">
      <value>thirdwitch</value>
    </field>
    <field var='muc#register_url'
           type="text-single"
           label="User URL">
      <value>http://witchesonline/~hag66/</value>
    </field>
    <field var='muc#register_email'
           type="text-single"
           label="Email Address">
      <value>hag66@witchesonline</value>
    </field>
    <field var='muc#register_faqentry'
           type="text-single"
           label="FAQ Entry">
      <value>Just another witch.</value>
    </field>
    <field var='muc#register_allow'
           type='boolean'
           label='Allow this person to register with the room?'>
      <value>0</value>
    </field>
  </x>
</message>
    

If the admin approves the registration request, the service shall register the user with the room.

More advanced registration approval mechanisms (e.g., retrieving a list of registration requests using Ad-Hoc Commands [19] as is done in Publish-Subscribe [20]) are out of scope for this document.

10. Owner Use Cases

Every room MUST have at least one owner, and that owner (or a successor) is a long-lived attribute of the room for as long as the room exists (e.g., the owner does not lose ownership on exiting a persistent room). This document assumes that the (initial) room owner is the individual who creates the room and that only a room owner has the right to change defining room configuration settings such as the room type. Ideally, room owners will be able to specify not only the room types (password-protected, members-only, etc.) but also certain attributes of the room as listed in the Requirements section of this document. In addition, it would be good if an owner were able to specify the JIDs of other owners, but that shall be determined by the implementation.

In order to provide the necessary flexibility for a wide range of configuration options, Data Forms (XEP-0004) shall be used for room configuration, triggered by use of the 'http://jabber.org/protocol/muc' namespace. That is, if an entity does not include the MUC namespace in its room join/create request, then the service shall create the room and not wait for configuration via Data Forms before creating the room (this ensures backwards-compatibility with the old "groupchat 1.0" protocol); however, if the room join/create request includes the MUC extension, then the service shall require configuration via Data Forms before creating and unlocking the room.

Note: The configuration options shown below address all of the features and room types listed in the requirements section of this document; however, the exact configuration options and form layout shall be determined by the implementation or specific deployment. Also, these are examples only and are not intended to define the only allowed or required configuration options for rooms. A given implementation or deployment MAY choose to provide additional configuration options (profanity filters, setting the default language for a room, message logging, etc.), which is why the use of the 'jabber:x:data' protocol is valuable here.

10.1 Creating a Room

10.1.1 General Considerations

The privilege to create rooms MAY be restricted to certain users or MAY be reserved to an administrator of the service. If access is restricted and a user attempts to create a room, the service MUST return a <not-allowed/> error:

Example 142. Service Informs User of Inability to Create a Room

<presence
    from='darkcave@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <x xmlns='http://jabber.org/protocol/muc'/>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
      

If access is not restricted, the service MUST allow the user to create a room as described below.

From the perspective of room creation, there are in essence two kinds of rooms:

The workflow for creating and configuring such rooms is as follows:

  1. The user MUST send presence to <room@service/nick> and signal his or her support for the Multi-User Chat protocol by including extended presence information in an empty <x/> child element qualified by the 'http://jabber.org/protocol/muc' namespace (note the lack of an '#owner' or '#user' fragment).

  2. If this user is allowed to create a room and the room does not yet exist, the service MUST create the room according to some default configuration, assign the requesting user as the initial room owner, and add the owner to the room but not allow anyone else to enter the room (effectively "locking" the room). The initial presence stanza received by the owner from the room MUST include extended presence information indicating the user's status as an owner and acknowledging that the room has been created (via status code 201) and is awaiting configuration.

  3. If the initial room owner would like to create and configure a reserved room, the room owner MUST then request a configuration form by sending an IQ stanza of type "get" to the room containing an empty <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, then complete Steps 4 and 5. If the room owner would prefer to create an instant room, the room owner MUST send a query element qualified by the 'http://jabber.org/protocol/muc#owner' namespace and containing an empty <x/> element of type "submit" qualified by the 'jabber:x:data' namespace, then skip to Step 6.

  4. If the room owner requested a configuration form, the service MUST send an IQ to the room owner containing a configuration form qualified by the 'jabber:x:data' namespace. If there are no configuration options available, the room MUST return an empty query element to the room owner.

  5. The initial room owner SHOULD provide a starting configuration for the room (or accept the default configuration) by sending an IQ of type "set" containing the completed configuration form. Alternatively, the room owner MAY cancel the configuration process. (An implementation MAY set a timeout for initial configuration, such that if the room owner does not configure the room within the timeout period, the room owner is assumed to have accepted the default configuration or to have cancelled the configuration process.)

  6. Once the service receives the completed configuration form from the initial room owner (or receives a request for an instant room), the service MUST "unlock" the room (i.e., allow other users to enter the room) and send an IQ of type "result" to the room owner. If the service receives a cancellation, it MUST destroy the room.

The protocol for this workflow is shown in the examples below.

First, the Jabber user MUST send presence to the room, including an empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace (this is the same stanza sent when seeking to enter a room).

Example 143. Jabber User Creates a Room and Signals Support for Multi-User Chat

<presence
    from='crone1@shakespeare.lit/desktop'
    to='darkcave@chat.shakespeare.lit/firstwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>
      

If the room does not yet exist, the service SHOULD create the room (subject to local policies regarding room creation), assign the bare JID of the requesting user as the owner, add the owner to the room, and acknowledge successful creation of the room by sending a presence stanza of the following form:

Example 144. Service Acknowledges Room Creation

<presence
    from='darkcave@chat.shakespeare.lit/firstwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner'
          role='moderator'/>
    <status code='110'/>
    <status code='201'/>
  </x>
</presence>
      

After receiving notification that the room has been created, the room owner needs to decide whether to accept the default room configuration (i.e., create an "instant room") or configure the room to have something other than the default room configuration (i.e., create a "reserved room"). The protocol flows for completing those two use cases are shown in the following sections.

Note: If the presence stanza sent to a nonexistent room does not include an <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace as shown above, the service SHOULD create a default room without delay (i.e., it MUST assume that the client supports "groupchat 1.0" rather than Multi-User Chat and therefore it MUST NOT lock the room while waiting for the room creator to either accept an instant room or configure a reserved room).

10.1.2 Creating an Instant Room

If the initial room owner wants to accept the default room configuration (i.e., create an "instant room"), the room owner MUST decline an initial configuration form by sending an IQ set to the <room@service> itself containing a <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, where the only child of the <query/> is an empty <x/> element that is qualified by the 'jabber:x:data' namespace and that possesses a 'type' attribute whose value is "submit":

Example 145. Owner Requests Instant Room

<iq from='crone1@shakespeare.lit/desktop'
    id='create1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='submit'/>
  </query>
</iq>
      

The service MUST then unlock the room and allow other entities to join it.

10.1.3 Creating a Reserved Room

If the initial room owner wants to create and configure a reserved room, the room owner MUST request an initial configuration form by sending an IQ get to the <room@service> itself containing an empty <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace:

Example 146. Owner Requests Configuration Form

<iq from='crone1@shakespeare.lit/desktop'
    id='create1'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#owner'/>
</iq>
      

If the room does not already exist, the service MUST return an initial room configuration form to the user. (Note: The following example shows a representative sample of configuration options. A full list of x:data fields registered for use in room creation and configuration is maintained by the XMPP Registrar; see the XMPP Registrar Considerations section of this document.)

Example 147. Service Sends Configuration Form

<iq from='darkcave@chat.shakespeare.lit'
    id='create1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Configuration for "darkcave" Room</title>
      <instructions>
          Your room darkcave@macbeth has been created!
          The default configuration is as follows:
            - No logging
            - No moderation
            - Up to 20 occupants
            - No password required
            - No invitation required
            - Room is not persistent
            - Only admins may change the subject
            - Presence broadcasted for all users
          To accept the default configuration, click OK. To
          select a different configuration, please complete
          this form.
      </instructions>
      <field
          type='hidden'
          var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#roomconfig</value>
      </field>
      <field
          label='Natural-Language Room Name'
          type='text-single'
          var='muc#roomconfig_roomname'/>
      <field
          label='Short Description of Room'
          type='text-single'
          var='muc#roomconfig_roomdesc'/>
      <field
          label='Natural Language for Room Discussions'
          type='text-single'
          var='muc#roomconfig_lang'/>
      <field
          label='Enable Public Logging?'
          type='boolean'
          var='muc#roomconfig_enablelogging'>
        <value>0</value>
      </field>
      <field
          label='Allow Occupants to Change Subject?'
          type='boolean'
          var='muc#roomconfig_changesubject'>
        <value>0</value>
      </field>
      <field
          label='Allow Occupants to Invite Others?'
          type='boolean'
          var='muc#roomconfig_allowinvites'>
        <value>0</value>
      </field>
      <field
          label='Maximum Number of Occupants'
          type='list-single'
          var='muc#roomconfig_maxusers'>
        <value>20</value>
        <option label='10'><value>10</value></option>
        <option label='20'><value>20</value></option>
        <option label='30'><value>30</value></option>
        <option label='50'><value>50</value></option>
        <option label='100'><value>100</value></option>
        <option label='None'><value>none</value></option>
      </field>
      <field
          label='Roles for which Presence is Broadcast'
          type='list-multi'
          var='muc#roomconfig_presencebroadcast'>
        <value>moderator</value>
        <value>participant</value>
        <value>visitor</value>
        <option label='Moderator'><value>moderator</value></option>
        <option label='Participant'><value>participant</value></option>
        <option label='Visitor'><value>visitor</value></option>
      </field>
      <field
          label='Roles and Affiliations that May Retrieve Member List'
          type='list-multi'
          var='muc#roomconfig_getmemberlist'>
        <value>moderator</value>
        <value>participant</value>
        <value>visitor</value>
        <option label='Moderator'><value>moderator</value></option>
        <option label='Participant'><value>participant</value></option>
        <option label='Visitor'><value>visitor</value></option>
      </field>
      <field
          label='Make Room Publicly Searchable?'
          type='boolean'
          var='muc#roomconfig_publicroom'>
        <value>1</value>
      </field>
      <field
          label='Make Room Persistent?'
          type='boolean'
          var='muc#roomconfig_persistentroom'>
        <value>0</value>
      </field>
      <field
          label='Make Room Moderated?'
          type='boolean'
          var='muc#roomconfig_moderatedroom'>
        <value>0</value>
      </field>
      <field
          label='Make Room Members-Only?'
          type='boolean'
          var='muc#roomconfig_membersonly'>
        <value>0</value>
      </field>
      <field
          label='Password Required to Enter?'
          type='boolean'
          var='muc#roomconfig_passwordprotectedroom'>
        <value>0</value>
      </field>
      <field type='fixed'>
        <value>
          If a password is required to enter this room,
          you must specify the password below.
        </value>
      </field>
      <field
          label='Password'
          type='text-private'
          var='muc#roomconfig_roomsecret'/>
      <field
          label='Who May Discover Real JIDs?'
          type='list-single'
          var='muc#roomconfig_whois'>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Anyone'>
          <value>anyone</value>
        </option>
      </field>
      <field type='fixed'>
        <value>
          You may specify additional people who have
          administrative privileges in the room. Please
          provide one Jabber ID per line.
        </value>
      </field>
      <field
          label='Room Admins'
          type='jid-multi'
          var='muc#roomconfig_roomadmins'/>
      <field type='fixed'>
        <value>
          You may specify additional owners for this
          room. Please provide one Jabber ID per line.
        </value>
      </field>
      <field
          label='Room Owners'
          type='jid-multi'
          var='muc#roomconfig_roomowners'/>
    </x>
  </query>
</iq>
      

Note: The _whois configuration option specifies whether the room is non-anonymous (a value of "anyone"), semi-anonymous (a value of "moderators"), or fully anonmyous (a value of "none", not shown here).

If there are no configuration options available, the service MUST return an empty query element to the room owner:

Example 148. Service Informs Owner that No Configuration is Possible

<iq from='darkcave@chat.shakespeare.lit'
    id='create1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#owner'/>
</iq>
      

The room owner SHOULD then fill out the form and submit it to the service.

Example 149. Owner Submits Configuration Form

<iq from='crone1@shakespeare.lit/desktop'
    id='create2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#roomconfig</value>
      </field>
      <field var='muc#roomconfig_roomname'>
        <value>A Dark Cave</value>
      </field>
      <field var='muc#roomconfig_roomdesc'>
        <value>The place for all good witches!</value>
      </field>
      <field var='muc#roomconfig_enablelogging'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_changesubject'>
        <value>1</value>
      </field>
      <field var='muc#roomconfig_allowinvites'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_maxusers'>
        <value>10</value>
      </field>
      <field var='muc#roomconfig_publicroom'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_persistentroom'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_moderatedroom'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_membersonly'>
        <value>0</value>
      </field>
      <field var='muc#roomconfig_passwordprotectedroom'>
        <value>1</value>
      </field>
      <field var='muc#roomconfig_roomsecret'>
        <value>cauldronburn</value>
      </field>
      <field var='muc#roomconfig_whois'>
        <value>moderators</value>
      </field>
      <field var='muc#roomconfig_roomadmins'>
        <value>wiccarocks@shakespeare.lit</value>
        <value>hecate@shakespeare.lit</value>
      </field>
    </x>
  </query>
</iq>
      

If room creation is successful, the service MUST inform the new room owner of success:

Example 150. Service Informs New Room Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='create2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
      

If the room creation fails because the specified room configuration options violate one or more service policies (e.g., because the password for a password-protected room is blank), the service MUST return a <not-acceptable/> error.

Example 151. Service Informs Owner that Requested Configuration Options Are Unacceptable

<iq from='darkcave@chat.shakespeare.lit'
    id='create2'
    to='crone1@shakespeare.lit/desktop'
    type='error'>
  <error type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
      

Alternatively, the room owner MAY cancel the configuration process:

Example 152. Owner Cancels Initial Configuration

<iq from='crone1@shakespeare.lit/desktop'
    id='create2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='cancel'/>
  </query>
</iq>
      

If the room owner cancels the initial configuration, the service SHOULD destroy the room, making sure to send unavailable presence to the room owner (see the "Destroying a Room" use case for protocol details).

If the room owner becomes unavailable for any reason before submitting the form (e.g., a lost connection), the service will receive a presence stanza of type "unavailable" from the owner to the owner's <room@service/nick> or to <room@service> (or both). The service MUST then destroy the room, sending a presence stanza of type "unavailable" from the room to the owner including a <destroy/> element and reason (if provided) as defined in the Destroying a Room section of this document.

10.1.4 Requesting a Unique Room Name

In some situations (e.g., when Converting a One-to-One Chat Into a Conference), the room creator may want to request a unique room name before attempting to create the room (e.g., to avoid the possibility of a room conflict). In order to facilitate this, a service MAY support the feature described in this section. (If a service does support this feature, it MUST return a feature of "http://jabber.org/protocol/muc#unique" in its response to service discovery information requests.)

The room creator requests a unique room name by sending an IQ-get to the service itself, containing an empty <unique/> element qualified by the 'http://jabber.org/protocol/muc#unique' namespace:

Example 153. Entity Requests Unique Room Name

<iq from='crone1@shakespeare.lit/desktop'
    id='unique1'
    to='chat.shakespeare.lit'
    type='get'>
  <unique xmlns='http://jabber.org/protocol/muc#unique'/>
</iq>
      

If the service supports this feature, it SHOULD return a unique room name as the XML character data of the <unique/> element (but not create the room):

Example 154. Service Returns Unique Room Name

<iq from='chat.shakespeare.lit'
    id='unique1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <unique xmlns='http://jabber.org/protocol/muc#unique'>
    6d9423a55f499b29ad20bf7b2bdea4f4b885ead1
  </unique>
</iq>
      

The service MAY refuse to return a unique room name to entities that are not entitled to create rooms, entities that have sent an excessive number of requests for unique room names, etc.

The service MAY use any algorithm that ensures the creation of a room name that will be permanently unique in the context of the service (e.g., a SHA-1 hash of the requesting JID, datetime, and random salt).

The room creator would then use the XML character data of the <unique/> element as the node identifier portion of the room JID it requests:

Example 155. Owner Creates Room With Unique Name

<presence 
    from='crone1@shakespeare.lit/desktop'
    to='6d9423a55f499b29ad20bf7b2bdea4f4b885ead1@chat.shakespeare.lit/firstwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>
      

10.2 Subsequent Room Configuration

At any time after specifying the initial configuration of the room, a room owner may want to change the configuration. In order to initiate this process, a room owner MUST request a new configuration form from the room by sending an IQ to <room@service> containing an empty <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace.

Example 156. Owner Requests Configuration Form

<iq from='crone1@shakespeare.lit/desktop'
    id='config1'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#owner'/>
</iq>
    

If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a <forbidden/> error to the sender:

Example 157. Service Denies Configuration Access to Non-Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='configures'
    to='wiccarocks@shakespeare.lit/laptop'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#owner'/>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

Otherwise, the service MUST send a configuration form to the room owner with the current options set as defaults:

Example 158. Service Sends Configuration Form to Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='config1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Configuration for "darkcave" Room</title>
      <instructions>
        Complete this form to make changes to
        the configuration of your room.
      </instructions>
      <field
          type='hidden'
          var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#roomconfig</value>
      </field>
      <field
          label='Natural-Language Room Name'
          type='text-single'
          var='muc#roomconfig_roomname'>
        <value>A Dark Cave</value>
      </field>
      <field
          label='Short Description of Room'
          type='text-single'
          var='muc#roomconfig_roomdesc'>
        <value>The place for all good witches!</value>
      </field>
      <field
          label='Enable Public Logging?'
          type='boolean'
          var='muc#roomconfig_enablelogging'>
        <value>0</value>
      </field>
      <field
          label='Allow Occupants to Change Subject?'
          type='boolean'
          var='muc#roomconfig_changesubject'>
        <value>0</value>
      </field>
      <field
          label='Allow Occupants to Invite Others?'
          type='boolean'
          var='muc#roomconfig_allowinvites'>
        <value>0</value>
      </field>
      <field
          label='Maximum Number of Occupants'
          type='list-single'
          var='muc#roomconfig_maxusers'>
        <value>10</value>
        <option label='10'><value>10</value></option>
        <option label='20'><value>20</value></option>
        <option label='30'><value>30</value></option>
        <option label='50'><value>50</value></option>
        <option label='100'><value>100</value></option>
        <option label='None'><value>none</value></option>
      </field>
      <field
          label='Roles for which Presence is Broadcast'
          type='list-multi'
          var='muc#roomconfig_presencebroadcast'>
        <value>moderator</value>
        <value>participant</value>
        <value>visitor</value>
        <option label='Moderator'><value>moderator</value></option>
        <option label='Participant'><value>participant</value></option>
        <option label='Visitor'><value>visitor</value></option>
      </field>
      <field
          label='Roles and Affiliations that May Retrieve Member List'
          type='list-multi'
          var='muc#roomconfig_getmemberlist'>
        <value>moderator</value>
        <value>participant</value>
        <value>visitor</value>
        <option label='Moderator'><value>moderator</value></option>
        <option label='Participant'><value>participant</value></option>
        <option label='Visitor'><value>visitor</value></option>
      </field>
      <field
          label='Make Room Publicly Searchable?'
          type='boolean'
          var='muc#roomconfig_publicroom'>
        <value>0</value>
      </field>
      <field
          label='Make Room Persistent?'
          type='boolean'
          var='muc#roomconfig_persistentroom'>
        <value>0</value>
      </field>
      <field
          label='Make Room Moderated?'
          type='boolean'
          var='muc#roomconfig_moderatedroom'>
        <value>0</value>
      </field>
      <field
          label='Make Room Members Only?'
          type='boolean'
          var='muc#roomconfig_membersonly'>
        <value>0</value>
      </field>
      <field
          label='Password Required for Entry?'
          type='boolean'
          var='muc#roomconfig_passwordprotectedroom'>
        <value>1</value>
      </field>
      <field type='fixed'>
        <value>
          If a password is required to enter this room,
          you must specify the password below.
        </value>
      </field>
      <field
          label='Password'
          type='text-private'
          var='muc#roomconfig_roomsecret'>
        <value>cauldronburn</value>
      </field>
      <field
          label='Who May Discover Real JIDs?'
          type='list-single'
          var='muc#roomconfig_whois'>
        <value>moderators</value>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Anyone'>
          <value>anyone</value>
        </option>
      </field>
      <field type='fixed'>
        <value>
          You may specify additional people who have
          administrative privileges in the room. Please
          provide one Jabber ID per line.
        </value>
      </field>
      <field
          label='Room Admins'
          type='jid-multi'
          var='muc#roomconfig_roomadmins'>
        <value>wiccarocks@shakespeare.lit</value>
        <value>hecate@shakespeare.lit</value>
      </field>
      <field type='fixed'>
        <value>
          You may specify additional owners for this
          room. Please provide one Jabber ID per line.
        </value>
      </field>
      <field
          label='Room Owners'
          type='jid-multi'
          var='muc#roomconfig_roomowners'/>
    </x>
  </query>
</iq>
    

If there are no configuration options available, the service MUST return an empty query element to the room owner as shown in the previous use case.

The room owner SHOULD then submit the form with updated configuration information.

Alternatively, the room owner MAY cancel the configuration process:

Example 159. Owner Cancels Subsequent Configuration

<iq from='crone1@shakespeare.lit/desktop'
    id='config2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='cancel'/>
  </query>
</iq>
    

If the room owner cancels the subsequent configuration, the service MUST leave the configuration of the room as it was before the room owner initiated the subsequent configuration process.

If as a result of a change in the room configuration a room admin loses administrative privileges while the admin is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member" and the 'role' attribute set to a value of "participant" or "visitor" as appropriate for the affiliation level and the room type:

Example 160. Service Notes Loss of Admin Affiliation

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='wiccarocks@shakespeare.lit/laptop'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

If as a result of a change in the room configuration a user gains administrative privileges while the user is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to a value of "admin":

Example 161. Service Notes Gain of Admin Affiliation to All Users

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit/laptop'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

If as a result of a change in the room configuration a room owner loses owner privileges while that owner is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).

Example 162. Service Notes Loss of Owner Affiliation

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit/laptop'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a <conflict/> error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.

If as a result of a change in the room configuration a user gains ownership privileges while the user is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "owner" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).

Example 163. Service Notes Gain of Owner Affiliation to All Users

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner'
          jid='wiccarocks@shakespeare.lit/laptop'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

If as a result of a change in the room configuration the room type is changed to members-only but there are non-members in the room, the service MUST remove any non-members from the room and include a status code of 322 in the presence unavailable stanzas sent to those users as well as any remaining occupants.

10.2.1 Notification of Configuration Changes

A room MUST send notification to all occupants when the room configuration changes in a way that has an impact on the privacy or security profile of the room. This notification shall consist of a <message/> stanza containing an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace, which shall contain only a <status/> element with an appropriate value for the 'code' attribute. Here is an example:

Example 164. Configuration Status Code

<message from='darkcave@chat.shakespeare.lit'
         to='crone1@shakespeare.lit/desktop'
         type='groupchat'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <status code='170'/>
  </x>
</message>
      

The codes to be generated as a result of a privacy-related change in room configuration are as follows:

For any other configuration change, the room SHOULD send status code 104 so that interested occupants can retrieve the updated room configuration if desired.

10.3 Granting Ownership Privileges

If allowed by an implementation, an owner MAY grant ownership privileges to another user; this is done by changing the user's affiliation to "owner":

Example 165. Owner Grants Ownership Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='owner1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner'
          jid='hecate@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 166. Owner Grants Ownership Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='owner1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner'
          jid='hecate@shakespeare.lit'>
      <reason>A worthy witch indeed!</reason>
    </item>
  </query>
</iq>
    

The service MUST add the user to the owner list and then inform the owner of success:

Example 167. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='owner1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of ownership privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "owner" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).

Example 168. Service Sends Notice of Ownership Privileges to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/hecate'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner'
          jid='hecate@shakespeare.lit'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

If the user is not in the room, the service MAY send a message from the room itself to the room occupants, indicating the granting of ownership privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "owner".

Example 169. Service Sends Notice of Ownership Privileges to All Occupants

<message
    from='chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='hecate@shakespeare.lit'
          role='none'/>
  </x>
</message>

[ ... ]
    

10.4 Revoking Ownership Privileges

An implementation MAY allow an owner to revoke another user's ownership privileges; this is done by changing the user's affiliation to something other than "owner":

Example 170. Owner Revokes Ownership Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='owner2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'
          jid='hecate@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 171. Owner Revokes Ownership Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='owner2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'
          jid='hecate@shakespeare.lit'>
      <reason>Not so worthy after all!</reason> 
    </item>
  </query>
</iq>
    

A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a <conflict/> error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.

If an implementation does not allow one owner to revoke another user's ownership privileges, the implementation MUST return a <not-authorized/> error to the owner who made the request.

Note: Allowing an owner to remove another user's ownership privileges can compromise the control model for room management; therefore this feature is OPTIONAL, and implementations are encouraged to support owner removal through an interface that is open only to individuals with service-wide administrative privileges.

In all other cases, the service MUST remove the user from the owner list and then inform the owner of success:

Example 172. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='owner2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the loss of ownership privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "owner" and the 'role' attribute set to an appropriate value:

Example 173. Service Notes Loss of Owner Affiliation

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='hecate@shakespeare.lit'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

If the user is not in the room, the service MAY send a message from the room itself to the room occupants, indicating the loss of ownership privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "owner".

Example 174. Service Notes Loss of Owner Affiliation

<message
    from='chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='hecate@shakespeare.lit'
          role='none'/>
  </x>
</message>

[ ... ]
    

10.5 Modifying the Owner List

If allowed by an implementation, a room owner may want to modify the owner list. To do so, the owner first requests the owner list by querying the room for all users with an affiliation of 'owner'.

Example 175. Owner Requests Owner List

<iq from='bard@shakespeare.lit/globe'
    id='owner3'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner'/>
  </query>
</iq>
    

If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a <forbidden/> error to the sender.

Otherwise, the service MUST then return the owner list to the owner; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for any owner that is currently an occupant:

Example 176. Service Sends Owner List to Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='owner3'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner'
          jid='crone1@shakespeare.lit'/>
  </query>
</iq>
    

The owner MAY then modify the owner list. In order to do so, the owner MUST send the changed items (i.e., only the "delta") back to the service; [21] each item MUST include the 'affiliation' and 'jid' attributes but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the owner affiliation):

Example 177. Owner Sends Modified Owner List to Service

<iq from='bard@shakespeare.lit/globe'
    id='owner4'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner'
          jid='hecate@shakespeare.lit'/>
  </query>
</iq>
    

Only owners shall be allowed to modify the owner list. If a non-owner attempts to view or modify the owner list, the service MUST deny the request and return a <forbidden/> error to the sender:

Example 178. Service Returns Error on Attempt by Non-Owner to Modify Owner List

<iq from='darkcave@chat.shakespeare.lit'
    id='ownertest'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='owner' 
          jid='hecate@shakespeare.lit'/>
  </query>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a <conflict/> error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.

In all other cases, the service MUST modify owner list and then inform the owner of success:

Example 179. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='owner4'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST also send presence notifications related to any affiliation changes that result from modifying the owner list as previously described.

10.6 Granting Administrative Privileges

An owner can grant administrative privileges to a member or unaffiliated user; this is done by changing the user's affiliation to "admin":

Example 180. Owner Grants Admin Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='admin1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 181. Owner Grants Admin Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='admin1'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit'>
      <reason>A worthy witch indeed!</reason>
    </item>
  </query>
</iq>
    

The service MUST add the user to the admin list and then inform the owner of success:

Example 182. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='admin1'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of administrative privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to an appropriate value given the affiliation and room type.

Example 183. Service Sends Notice of Administrative Privileges to All Occupants

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit'
          role='moderator'/>
  </x>
</presence>

[ ... ]
    

If the user is not in the room, the service MAY send a message from the room itself to the room occupants, indicating the granting of administrative privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin".

Example 184. Service Sends Notice of Administrative Privileges to All Occupants

<message
    from='chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit'
          role='none'/>
  </x>
</message>

[ ... ]
    

10.7 Revoking Administrative Privileges

An owner may want to revoke a user's administrative privileges; this is done by changing the user's affiliation to something other than "admin" or "owner":

Example 185. Owner Revokes Administrative Privileges

<iq from='crone1@shakespeare.lit/desktop'
    id='admin2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='wiccarocks@shakespeare.lit'/>
  </query>
</iq>
    

The <reason/> element is OPTIONAL.

Example 186. Owner Revokes Administrative Privileges (With a Reason)

<iq from='crone1@shakespeare.lit/desktop'
    id='admin2'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='member'
          jid='wiccarocks@shakespeare.lit'>
      <reason>Not so worthy after all!</reason> 
    </item>
  </query>
</iq>
    

The service MUST remove the user from the admin list and then inform the owner of success:

Example 187. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='admin2'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the loss of administrative privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "admin" or "owner" and the 'role' attribute set to an appropriate value given the affiliation level and the room type:

Example 188. Service Notes Loss of Admin Affiliation

<presence
    from='darkcave@chat.shakespeare.lit/secondwitch'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='wiccarocks@shakespeare.lit'
          role='participant'/>
  </x>
</presence>

[ ... ]
    

If the user is not in the room, the service MAY send a message from the room itself to the room occupants, indicating the loss of administrative privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "admin".

Example 189. Service Notes Loss of Admin Affiliation

<message
    from='chat.shakespeare.lit'
    to='crone1@shakespeare.lit/desktop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member'
          jid='wiccarocks@shakespeare.lit'
          role='none'/>
  </x>
</message>

[ ... ]
    

10.8 Modifying the Admin List

A room owner may want to modify the admin list. To do so, the owner first requests the admin list by querying the room for all users with an affiliation of 'admin'.

Example 190. Owner Requests Admin List

<iq from='bard@shakespeare.lit/desktopaffiliation
    id='admin3'
    to='darkcave@chat.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'/>
  </query>
</iq>
    

If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a <forbidden/> error to the sender.

Otherwise, the service MUST then return the admin list to the owner; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for any admin that is currently an occupant:

Example 191. Service Sends Admin List to Owner

<iq from='darkcave@chat.shakespeare.lit'
    id='admin3'
    to='bard@shakespeare.lit/globe'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin'
          jid='wiccarocks@shakespeare.lit'
          nick='secondwitch'/>
    <item affiliation='admin'
          jid='hag66@shakespeare.lit'/>
  </query>
</iq>
    

The owner MAY then modify the admin list. In order to do so, the owner MUST send the changed items (i.e., only the "delta") back to the service; [22] each item MUST include the 'affiliation' attribute (normally set to a value of "admin" or "none") and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the admin affiliation):

Example 192. Owner Sends Modified Admin List to Service

<iq from='bard@shakespeare.lit/globe'
    id='admin4'
    to='darkcave@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='none'
          jid='hag66@shakespeare.lit'>
    </item>
    <item affiliation='admin'
          jid='hecate@shakespeare.lit'>
    </item>
  </query>
</iq>
    

Only owners shall be allowed to modify the admin list. If a non-owner attempts to view or modify the admin list, the service MUST deny the request and return a <forbidden/> error to the sender:

Example 193. Service Returns Error on Attempt by Non-Owner to Modify Admin List

<iq from='darkcave@chat.shakespeare.lit'
    id='admintest'
    to='hag66@shakespeare.lit/pda'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='admin' 
          jid='hecate@shakespeare.lit'/>
  </query>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

Otherwise, the service MUST modify the admin list and then inform the owner of success:

Example 194. Service Informs Owner of Success

<iq from='darkcave@chat.shakespeare.lit'
    id='admin4'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

The service MUST also send presence notifications related to any affiliation changes that result from modifying the admin list as previously described.

10.9 Destroying a Room

A room owner MUST be able to destroy a room, especially if the room is persistent. The workflow is as follows:

  1. The room owner requests that the room be destroyed, specifying a reason and an alternate venue if desired.

  2. The room removes all users from the room (including appropriate information about the alternate location and the reason for being removed) and destroys the room, even if it was defined as persistent.

Other than the foregoing, this document does not specify what (if anything) a MUC service implementation shall do as a result of a room destruction request. For example, if the room was defined as persistent, an implementation MAY choose to lock the room ID so that it cannot be re-used, redirect enter requests to the alternate venue, or invite the current participants to the new room; however, such behavior is OPTIONAL.

In order to destroy a room, the room owner MUST send an IQ set to the address of the room to be destroyed. The <iq/> stanza shall contain a <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, which in turn shall contain a <destroy/> element. The address of the alternate venue MAY be provided as the value of the <destroy/> element's 'jid' attribute. A password for the alternate venue MAY be provided as the XML character data of a <password/> child element of the <destroy/> element. The reason for the room destruction MAY be provided as the XML character data of a <reason/> child element of the <destroy/> element.

The following examples illustrate the protocol elements to be sent and received:

Example 195. Owner Submits Room Destruction Request

<iq from='crone1@shakespeare.lit/desktop'
    id='begone'
    to='heath@chat.shakespeare.lit'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <destroy jid='darkcave@chat.shakespeare.lit'>
      <reason>Macbeth doth come.</reason>
    </destroy>
  </query>
</iq>
    

The service is responsible for removing all the occupants. It SHOULD NOT broadcast presence stanzas of type "unavailable" from all occupants, instead sending only one presence stanza of type "unavailable" to each occupant so that the user knows he or she has been removed from the room. If extended presence information specifying the JID of an alternate location and the reason for the room destruction was provided by the room owner, the presence stanza MUST include that information.

Example 196. Service Removes Each Occupant

<presence
    from='heath@chat.shakespeare.lit/firstwitch'
    to='crone1@shakespeare.lit/desktop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'/>
    <destroy jid='darkcave@chat.shakespeare.lit'>
      <reason>Macbeth doth come.</reason>
    </destroy>
  </x>
</presence>

<presence
    from='heath@chat.shakespeare.lit/secondwitch'
    to='wiccarocks@shakespeare.lit/laptop'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'/>
    <destroy jid='darkcave@chat.shakespeare.lit'>
      <reason>Macbeth doth come.</reason>
    </destroy>
  </x>
</presence>

<presence
    from='heath@chat.shakespeare.lit/thirdwitch'
    to='hag66@shakespeare.lit/pda'
    type='unavailable'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='none'/>
    <destroy jid='darkcave@chat.shakespeare.lit'>
      <reason>Macbeth doth come.</reason>
    </destroy>
  </x>
</presence>
    

Example 197. Service Informs Owner of Successful Destruction

<iq from='heath@chat.shakespeare.lit'
    id='begone'
    to='crone1@shakespeare.lit/desktop'
    type='result'/>
    

If the <user@host> of the 'from' address received on a destroy request does not match the bare JID of a room owner, the service MUST return a <forbidden/> error to the sender:

Example 198. Service Denies Destroy Request Submitted by Non-Owner

<iq from='heath@chat.shakespeare.lit'
    id='destroytest'
    to='wiccarocks@shakespeare.lit/laptop'
    type='error'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <destroy jid='darkcave@chat.shakespeare.lit'>
      <reason>Macbeth doth come.</reason>
    </destroy>
  </query>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

11. Error and Status Codes

11.1 Error Codes

The error codes associated with the 'http://jabber.org/protocol/muc#user' namespace are fairly straightforward, as summarized in the following table. For detailed information about mapping legacy error codes to XMPP-style error types and conditions, refer to Error Condition Mappings [23]; implementations SHOULD support both legacy and XMPP error handling.

Table 9: Error Codes for http://jabber.org/protocol/muc#user Namespace

Code Type Element Context Purpose
401 Error Presence Entering a room Inform user that a password is required
403 Error Presence Entering a room Inform user that he or she is banned from the room
404 Error Presence Entering a room Inform user that the room does not exist
405 Error Presence Entering a room Inform user that room creation is restricted
406 Error Presence Entering a room Inform user that the reserved roomnick must be used
407 Error Presence Entering a room Inform user that he or she is not on the member list
409 Error Presence Entering a room Inform user that his or her desired room nickname is in use or registered by another user
503 Error Presence Entering a room Inform user that the maximum number of users has been reached

This document does not stipulate text strings (i.e., values of the XMPP <text/> element) associated with the foregoing error conditions.

11.2 Status Codes

Multi-User Chat uses a <status/> element (specifically, the 'code' attribute of the <status/> element) to communicate information about a user's status in a room. Over time, the number of status codes has grown quite large, and new status codes continue to be requested of the author. Therefore, these codes are now documented in a registry maintained by the XMPP Registrar. For details, refer to the Status Codes Registry section of this document.

Note: In general, MUC status codes tend to follow the "philosophy" of status codes that is implicit in RFC 2616 [24] and RFC 1893 [25] (1xx codes are informational, 2xx codes specify that it is fine to continue, 3xx codes specify redirects such as being kicked or banned, x3x codes refer to system status, x7x codes refer to security or policy matters, etc.).

Note: If the MUC protocol were being designed today, it would specify a more flexible, XML-friendly approach rather than hardcoded status numbers; however, at this point the pain of changing the status reporting system would be greater than the benefit of doing so, which is why the status code numbers remain in use. A future version of this document may define a more XMPP-like approach to status conditions, retaining the code numbers but supplementing them with more descriptive child elements as is done in RFC 3920.

12. Internationalization Considerations

As specified in RFC 3920, XMPP entities (including MUC rooms and MUC services) SHOULD respect the value of the 'xml:lang' attribute provided with any given stanza. However, simultaneous translation of groupchat messages is out of scope for this document.

The status and error codes defined herein enable a client implementation to present a localized interface; however, definition of the localized text strings for any given language community is out of scope for this document.

Although the labels for various data form fields are shown here in English, MUC clients SHOULD present localized text for these fields rather than the English text.

13. Security Considerations

13.1 User Authentication and Authorization

No room entrance authentication or authorization method more secure than cleartext passwords is defined or required by this document. However, the risks involved can mitigated by the use of channel encryption and strong authentication via TLS and SASL as described in RFC 3920.

13.2 End-to-End Encryption

No end-to-end message or session encryption method is specified herein. Users SHOULD NOT trust a service to keep secret any text sent through a room.

13.3 Privacy

Depending on room configuration, a room may publicly log all discussions held in the room. A service MUST warn the user that the room is publicly logged by returning a status code of "170" with the user's initial presence, and the user's client MUST so warn the user if the room discussion is logged (a user's client SHOULD also query the room for its configuration prior to allowing the user to enter in order to "pre-discover" whether the room is logged). A client MUST also warn the user if the room's configuration is subsequently modified to allow room logging (which the client will discover when the room sends status code 170). Note: In-room history is different from public room logging, and naturally a room cannot effectively prevent occupants from separately maintaining their own room logs, which may become public; users SHOULD exercise due caution and consider any room discussions to be effectively public.

13.4 Anonymity

Depending on room configuration, a room MAY expose each occupant's real JID to other occupants (if the room is non-anonymous) and will almost certainly expose each occupant's real JID to the room owners and administrators (if the room is not fully-anonymous). A service MUST warn the user that real JIDs are exposed in the room by returning a status code of "100" with the user's initial presence, and the user's client MUST so warn the user (a user's client SHOULD also query the room for its configuration prior to allowing the user to enter in order to "pre-discover" whether real JIDs are exposed in the room). A client MUST also warn the user if the room's configuration is subsequently modified from semi-anonymous or fully-anonymous to non-anonymous (which the client will discover when the room sends status code 172) and SHOULD warn the user if the room's configuration is subsequently modified from fully-anonymous to semi-anonymous (which the client will discover when the room sends status code 173).

13.5 Denial of Service

Public MUC rooms can be subject to a number of attacks, most of which reduce to denial of service attacks. Such attacks include but are not limited to:

  1. Stuffing the room with a large number of illegitimate occupants and therefore preventing legitimate users from joining the room.
  2. Sending abusive messages and then leaving the room before a kick or ban can be applied; such abusive messages include but are not limited to large messages that prevent participants from following the conversation thread or room history, personal attacks on participants (especially room administrators and moderators), offensive text, and links to spam sites.
  3. Making rapid and repeated presence changes.
  4. Using long nicknames to route around lack of voice.
  5. Abusing the room administrators or other room occupants.
  6. Registering multiple nicknames across a service and therefore denying the use of those nicknames.
  7. Mimicking another occupant's roomnick (e.g., by adding a space at the end or substituting visually similar characters), then sending messages from that roomnick in an effort to confuse the occupants.

These attacks can be mitigated but not completely prevented through the liberal use of administrative actions such as banning, the presence of automated room bots with administrative privileges, implementation of intelligent content filtering, checking the IP addresses of connected users (not always possible in a distributed system), applying voice rules to presence as well as messaging, matching room nicks using more stringent rules than the Resourceprep profile of stringprep, etc. However, experience has shown that it is impossible to fully prevent attacks of this kind.

13.6 Other Considerations

See XEP-0203 for security considerations regarding the inclusion and processing of delayed delivery notations.

14. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [26].

15. XMPP Registrar Considerations

The XMPP Registrar [27] includes the following information in its registries.

15.1 Protocol Namespaces

The XMPP Registrar includes the following MUC-related namespaces in its registry of protocol namespaces:

15.2 Service Discovery Category/Type

A Multi-User Chat service or room is identified by the "conference" category and the "text" type within Service Discovery.

15.3 Service Discovery Features

There are many features related to a MUC service or room that can be discovered by means of Service Discovery. The most fundamental of these is the 'http://jabber.org/protocol/muc' namespace. In addition, a MUC room SHOULD provide information about the specific room features it implements, such as password protection and room moderation.

Registry Submission

<var>
  <name>http://jabber.org/protocol/muc#register</name>
  <desc>Support for the muc#register FORM_TYPE</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>http://jabber.org/protocol/muc#roomconfig</name>
  <desc>Support for the muc#roomconfig FORM_TYPE</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>http://jabber.org/protocol/muc#roominfo</name>
  <desc>Support for the muc#roominfo FORM_TYPE</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_hidden</name>
  <desc>Hidden room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_membersonly</name>
  <desc>Members-only room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_moderated</name>
  <desc>Moderated room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_nonanonymous</name>
  <desc>Non-anonymous room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_open</name>
  <desc>Open room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_passwordprotected</name>
  <desc>Password-protected room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_persistent</name>
  <desc>Persistent room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_public</name>
  <desc>Public room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_rooms</name>
  <desc>List of MUC rooms (each as a separate item)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_semianonymous</name>
  <desc>Semi-anonymous room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_temporary</name>
  <desc>Temporary room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_unmoderated</name>
  <desc>Unmoderated room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
<var>
  <name>muc_unsecured</name>
  <desc>Unsecured room in Multi-User Chat (MUC)</desc>
  <doc>XEP-0045</doc>
</var>
    

15.4 Well-Known Service Discovery Nodes

The well-known Service Discovery node 'http://jabber.org/protocol/muc#rooms' enables discovery of the rooms in which a user is an occupant.

The well-known Service Discovery node 'x-roomuser-item' enables a user to discover his or her registered roomnick from outside the room.

The well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' enables discovery of the namespaces that are allowed in traffic sent through a room (see the Allowable Traffic section of this document).

15.5 Field Standardization

Field Standardization for Data Forms [28] defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. Within MUC, there are four uses of such forms: room registration (the "muc#register" FORM_TYPE), requesting voice and approving voice requests ("muc#request"), room configuration ("muc#roomconfig"), and service discovery extensions for room information ("muc#roominfo"). The reserved fields are defined below.

15.5.1 muc#register FORM_TYPE

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#register</name>
  <doc>XEP-0045</doc>
  <desc>
    Forms enabling user registration with a
    Multi-User Chat (MUC) room or admin approval
    of user registration requests.
  </desc>
  <field 
     var='muc#register_allow'
     type='boolean'
     label='Allow this person to register with the room?'/>
  <field
      var='muc#register_email'
      type='text-single'
      label='Email Address'/>
  <field
      var='muc#register_faqentry'
      type='text-multi'
      label='FAQ Entry'/>
  <field
      var='muc#register_first'
      type='text-single'
      label='Given Name'/>
  <field
      var='muc#register_last'
      type='text-single'
      label='Family Name'/>
  <field
      var='muc#register_roomnick'
      type='text-single'
      label='Desired Nickname'/>
  <field
      var='muc#register_url'
      type='text-single'
      label='Your URL'/>
</form_type>
      

15.5.2 muc#request FORM_TYPE

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#request</name>
  <doc>XEP-0045</doc>
  <desc>
    Forms enabling voice requests in a 
    Multi-User Chat (MUC) room or admin
    approval of such requests.
  </desc>
  <field var='muc#role'
         type='text-single'
         label='Requested role'/>
  <field var='muc#jid'
         type='text-single'
         label='User ID'/>
  <field var='muc#roomnick'
         type='text-single'
         label='Room Nickname'/>
  <field var='muc#request_allow'
         type='boolean'
         label='Whether to grant voice'/>
</form_type>
      

15.5.3 muc#roomconfig FORM_TYPE

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#roomconfig</name>
  <doc>XEP-0045</doc>
  <desc>
    Forms enabling creation and configuration of
    a Multi-User Chat (MUC) room.
  </desc>
  <field
      var='muc#roomconfig_allowinvites'
      type='boolean'
      label='Whether to Allow Occupants to Invite Others'/>
  <field
      var='muc#roomconfig_changesubject'
      type='boolean'
      label='Whether to Allow Occupants to Change Subject'/>
  <field
      var='muc#roomconfig_enablelogging'
      type='boolean'
      label='Whether to Enable Public Logging of Room Conversations'/>
  <field
      var='muc#roomconfig_getmemberlist'
      type='list-multi'
      label='Roles and Affiliations that May Retrieve Member List'/>
  <field
      var='muc#roomconfig_lang'
      type='text-single'
      label='Natural Language for Room Discussions'/>
  <field
      var='muc#roomconfig_pubsub'
      type='text-single'
      label='XMPP URI of Associated Publish-Subcribe Node'/>
  <field
      var='muc#roomconfig_maxusers'
      type='list-single'
      label='Maximum Number of Room Occupants'/>
  <field
      var='muc#roomconfig_membersonly'
      type='boolean'
      label='Whether an Make Room Members-Only'/>
  <field
      var='muc#roomconfig_moderatedroom'
      type='boolean'
      label='Whether to Make Room Moderated'/>
  <field
      var='muc#roomconfig_passwordprotectedroom'
      type='boolean'
      label='Whether a Password is Required to Enter'/>
  <field
      var='muc#roomconfig_persistentroom'
      type='boolean'
      label='Whether to Make Room Persistent'/>
  <field
      var='muc#roomconfig_presencebroadcast'
      type='list-multi'
      label='Roles for which Presence is Broadcast'/>
  <field
      var='muc#roomconfig_publicroom'
      type='boolean'
      label='Whether to Allow Public Searching for Room'/>
  <field
      var='muc#roomconfig_roomadmins'
      type='jid-multi'
      label='Full List of Room Admins'/>
  <field
      var='muc#roomconfig_roomdesc'
      type='text-single'
      label='Short Description of Room'/>
  <field
      var='muc#roomconfig_roomname'
      type='text-single'
      label='Natural-Language Room Name'/>
  <field
      var='muc#roomconfig_roomowners'
      type='jid-multi'
      label='Full List of Room Owners'/>
  <field
      var='muc#roomconfig_roomsecret'
      type='text-private'
      label='The Room Password'/>
  <field
      var='muc#roomconfig_whois'
      type='list-single'
      label='Affiliations that May Discover Real JIDs of Occupants'/>
</form_type>
      

15.5.4 muc#roominfo FORM_TYPE

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#roominfo</name>
  <doc>XEP-0045</doc>
  <desc>
    Forms enabling the communication of extended service discovery
    information about a Multi-User Chat (MUC) room.
  </desc>
  <field
      var='muc#roominfo_contactjid'
      type='jid-multi'
      label='Contact Addresses (normally, room owner or owners)'/>
  <field
      var='muc#roominfo_description'
      type='text-single'
      label='Short Description of Room'/>
  <field
      var='muc#roominfo_lang'
      type='text-single'
      label='Natural Language for Room Discussions'/>
  <field
      var='muc#roominfo_ldapgroup'
      type='text-single'
      label='An associated LDAP group that defines room membership; 
             this should be an LDAP Distinguished Name according to an
             implementation-specific or deployment-specific definition
             of a group.'/>
  <field
      var='muc#roominfo_logs'
      type='text-single'
      label='URL for Archived Discussion Logs'/>
  <field
      var='muc#roominfo_occupants'
      type='text-single'
      label='Current Number of Occupants in Room'/>
  <field
      var='muc#roominfo_subject'
      type='text-single'
      label='Current Subject or Discussion Topic in Room'/>
  <field
      var='muc#roominfo_subjectmod'
      type='boolean'
      label='The room subject can be modified by participants'/>
</form_type>
      

15.6 Status Codes Registry

15.6.1 Process

The XMPP Registrar maintains a registry of values for the 'code' attribute of the <status/> element when qualified by the 'http://jabber.org/protocol/muc#user' namespace.

In order to submit new values to this registry, the registrant shall define an XML fragment of the following form and either include it in the relevant XMPP Extension Protocol or send it to the email address <registrar@xmpp.org>:

<statuscode>
  <number>the three-digit code number</number>
  <stanza>the stanza type of which it is a child (message or presence)</stanza>
  <context>the use case or situation in which the status is used</context>
  <purpose>a natural-language description of the meaning</purpose>
  <child>the descriptive child element (reserved for future use)</child>
</statuscode>
      

The registrant may register more than one status code at a time, each contained in a separate <statuscode/> element.

15.6.2 Initial Submission

As part of this document, the following status codes are registered:

<statuscode>
  <number>100</number>
  <stanza>message or presence</stanza>
  <context>Entering a room</context>
  <purpose>Inform user that any occupant is allowed to see the user's full JID</purpose>
</statuscode>
<statuscode>
  <number>101</number>
  <stanza>message (out of band)</stanza>
  <context>Affiliation change</context>
  <purpose>Inform user that his or her affiliation changed while not in the room</purpose>
</statuscode>
<statuscode>
  <number>102</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that room now shows unavailable members</purpose>
</statuscode>
<statuscode>
  <number>103</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that room now does not show unavailable members</purpose>
</statuscode>
<statuscode>
  <number>104</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>
    Inform occupants that a non-privacy-related room configuration change has occurred
  </purpose>
</statuscode>
<statuscode>
  <number>110</number>
  <stanza>presence</stanza>
  <context>Any room presence</context>
  <purpose>Inform user that presence refers to one of its own room occupants</purpose>
</statuscode>
<statuscode>
  <number>170</number>
  <stanza>message or initial presence</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that room logging is now enabled</purpose>
</statuscode>
<statuscode>
  <number>171</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that room logging is now disabled</purpose>
</statuscode>
<statuscode>
  <number>172</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that the room is now non-anonymous</purpose>
</statuscode>
<statuscode>
  <number>173</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that the room is now semi-anonymous</purpose>
</statuscode>
<statuscode>
  <number>174</number>
  <stanza>message</stanza>
  <context>Configuration change</context>
  <purpose>Inform occupants that the room is now fully-anonymous</purpose>
</statuscode>
<statuscode>
  <number>201</number>
  <stanza>presence</stanza>
  <context>Entering a room</context>
  <purpose>Inform user that a new room has been created</purpose>
</statuscode>
<statuscode>
  <number>210</number>
  <stanza>presence</stanza>
  <context>Entering a room</context>
  <purpose>Inform user that service has assigned or modified occupant's roomnick</purpose>
</statuscode>
<statuscode>
  <number>301</number>
  <stanza>presence</stanza>
  <context>Removal from room</context>
  <purpose>Inform user that he or she has been banned from the room</purpose>
</statuscode>
<statuscode>
  <number>303</number>
  <stanza>presence</stanza>
  <context>Exiting a room</context>
  <purpose>Inform all occupants of new room nickname</purpose>
</statuscode>
<statuscode>
  <number>307</number>
  <stanza>presence</stanza>
  <context>Removal from room</context>
  <purpose>Inform user that he or she has been kicked from the room</purpose>
</statuscode>
<statuscode>
  <number>321</number>
  <stanza>presence</stanza>
  <context>Removal from room</context>
  <purpose>Inform user that he or she is being removed from the room 
    because of an affiliation change</purpose>
</statuscode>
<statuscode>
  <number>322</number>
  <stanza>presence</stanza>
  <context>Removal from room</context>
  <purpose>Inform user that he or she is being removed from the room 
    because the room has been changed to members-only and the user 
    is not a member</purpose>
</statuscode>
<statuscode>
  <number>332</number>
  <stanza>presence</stanza>
  <context>Removal from room</context>
  <purpose>Inform user that he or she is being removed from the room 
    because of a system shutdown</purpose>
</statuscode>
      

15.7 URI Query Types

As authorized by XMPP URI Query Components [29], the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see <http://xmpp.org/registrar/querytypes.html>).

15.7.1 join

The "join" querytype is registered as a MUC-related action, with an optional key of "password".

Example 199. Join Action: IRI/URI

xmpp:darkcave@chat.shakespeare.lit?join
      

The application MUST either present an interface enabling the user to provide a room nickname or populate the room nickname based on configured preferences or nickname discovery.

Example 200. Join Action: Resulting Stanza

<presence to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>
      

The join action MAY include a password for the room. Naturally, access to a URI that includes a room password MUST be appropriately controlled.

Example 201. Join Action with Password: IRI/URI

xmpp:darkcave@chat.shakespeare.lit?join;password=cauldronburn
      

Example 202. Join Action with Password: Resulting Stanza

<presence to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'>
    <password>cauldronburn</password>
  </x>
</presence>
      

The following submission registers the "join" querytype.

<querytype>
  <name>join</name>
  <proto>http://jabber.org/protocol/muc</proto>
  <desc>enables joining a multi-user chat room</desc>
  <doc>XEP-0045</doc>
  <keys>
    <key>
      <name>password</name>
      <desc>the password required to enter a multi-user chat room</desc>
    </key>
  </keys>
</querytype>
      

15.7.2 invite

The "invite" querytype is registered as a MUC-related action, with an optional key of "jid".

Example 203. Invite Action: IRI/URI

xmpp:darkcave@chat.shakespeare.lit?invite;jid=hecate@shakespeare.lit
      

If the joining user is not yet in the room, the application MUST send two stanzas: the first to join the room and the second to invite the other individual. If the joining user is in the room already, the application shall send only the invitation stanza.

Example 204. Invite Action: Resulting Stanza(s)

<presence to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>

<message to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'/>
  </x>
</message>
      

The URI may include multiple invitees:

Example 205. Invite Action With Multiple Invitees: IRI/URI

xmpp:darkcave@chat.shakespeare.lit?invite;jid=hecate@shakespeare.lit;jid=bard@shakespeare.lit
      

Example 206. Invite Action With Multiple Invitees: Resulting Stanza

<message to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'/>
    <invite to='bard@shakespeare.lit'/>
  </x>
</message>
      

The URI may also include a password:

Example 207. Invite Action With Password: IRI/URI

xmpp:darkcave@chat.shakespeare.lit?invite;jid=hecate@shakespeare.lit;password=cauldronburn
      

If the joining user is not yet in the room, the application MUST send two stanzas: the first to join the room and the second to invite the other individual. If the joining user is in the room already, the application shall send only the invitation stanza.

Example 208. Invite Action With Password: Resulting Stanza(s)

<presence to='darkcave@chat.shakespeare.lit/thirdwitch'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>

<message to='darkcave@chat.shakespeare.lit'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='hecate@shakespeare.lit'/>
    <password>cauldronburn</password>
  </x>
</message>
      

The following submission registers the "invite" querytype.

<querytype>
  <name>invite</name>
  <proto>http://jabber.org/protocol/muc</proto>
  <desc>enables simultaneously joining a groupchat room and inviting others</desc>
  <doc>XEP-0045</doc>
  <keys>
    <key>
      <name>jid</name>
      <desc>the Jabber ID of the invitee</desc>
    </key>
    <key>
      <name>password</name>
      <desc>the password required to enter a multi-user chat room</desc>
    </key>
  </keys>
</querytype>
      

16. Business Rules

16.1 Addresses

In order to provide consistency regarding the addresses captured in room JIDs, Room IDs MUST match the Nodeprep profile of Stringprep and Room Nicknames MUST match the Resourceprep profile of Stringprep (both of these are defined in RFC 3920). Although not explicitly stated in RFC 3920, both the Room ID (node) and Room Nickname (resource) portions of a Room JID MUST be of non-zero length. In addition, a MUC service MUST NOT allow empty or invisible Room Nicknames (i.e., Room Nicknames that consist only of one or more space characters).

It is up to the service implementation whether it will further restrict roomnicks (e.g., by applying case folding routines, the Nodeprep profile of stringprep, or other restrictions).

16.2 Message

  1. If an occupant wants to send a message to all other occupants, a MUC client MUST set the 'type' attribute to a value of "groupchat". A service MAY ignore messages that are improperly typed, or reject them with a <bad-request/> error.

  2. If a MUC service receives a message directed to the room or to a single occupant from a Jabber user who has a role of "none", the service MUST NOT deliver the message and SHOULD return the message to the sender with a <forbidden/> error.

  3. If a MUC service receives a message directed to a room that does not exist or is not yet unlocked, the service SHOULD return the message to the sender with an <item-not-found/> error.

  4. A MUC service SHOULD pass extended information (e.g., an XHTML version of the message body) through to occupants unchanged; however, a MUC service MAY disallow message specific extensions (see the Allowable Traffic section of this document).

  5. A MUC client MAY generate extensions that conform to the Message Events [30] or Chat State Notifications [31] specification; however, a MUC service MAY disallow these extensions (see the Allowable Traffic section of this document).

16.3 Presence

  1. A room MUST silently ignore unavailable presence received from a user who has a role of "none".

  2. Only the MUC service itself SHOULD generate extended presence information about roles, affiliations, full JIDs, or status codes qualified by the 'http://jabber.org/protocol/muc#user' namespace (based on information the service knows about occupants, e.g., roles, or as a result of actions taken by a moderator or room administrator). A client SHOULD NOT presume to generate such information. If a MUC service receives such extended presence information from an occupant, it MUST NOT reflect it to other occupants. (A client MAY generate extended presence information qualified by the 'http://jabber.org/protocol/muc#user' namespace in order to supply a password, but naturally this is not reflected to other occupants.)

  3. A MUC service SHOULD allow all other presence information to pass through, although it MAY choose to block extended presence information; see the Allowable Traffic section of this document.

  4. In order to appropriately inform occupants of room roles and affiliations, and to make it easier for Jabber clients to track the current state of all users in the room, MUC service implementations MUST provide extended presence information about roles and affiliations in all presence stanzas, including presence stanzas of type "unavailable" sent when a user exits the room for any reason.

  5. If a privilege is revoked, the service MUST note that by sending an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child element with the 'role' and/or 'affiliation' attributes set to a value that indicates the loss of the relevant privilege. All future presence stanzas for the occupant MUST include the updated role and affiliation, until and unless they change again.

  6. A MUC service MUST send extended presence to a client even if the client did not send an empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace on entering the room; naturally, a client MUST ignore such information if it does not understand it (in accordance with RFC 3920).

  7. Extended presence about roles and affiliations sent in the muc#user namespace MUST include the full JID (not the bare JID) as the value of the 'jid' attribute.

  8. A client MAY send a custom exit message if desired (as is often done in IRC channels) by including a <status/> element in the presence stanza of type "unavailable" sent when exiting a room.

16.4 IQ

  1. MUC is designed for sharing of messages and presence, not IQs. An IQ sent to the JID of the room itself is handled by the room and is not reflected to all of the room occupants.

  2. If an occupant wants to send an IQ stanza to another user in a non-anonymous room, the sender SHOULD send the request directly to the recipient's bare JID or full JID, rather than attempting to send the request through the room (i.e., via the recipient's room JID).

  3. If an occupant wants to send an IQ stanza to another user in a semi-anonymous room, the sender can direct the stanza to the recipient's room JID and the service MAY forward the stanza to the recipient's real JID. However, a MUC service MUST NOT reveal the sender's real JID to the recipient at any time, nor reveal the recipient's real JID to the sender.

  4. A MUC client MUST send only the 'affiliation' attribute or the 'role' attribute in the <item/> element contained within an IQ set qualified by the 'http://jabber.org/protocol/muc#admin' namespace; if a moderator, admin, or owner attempts to modify both the affiliation and role of the same item in the same IQ set, the service MUST return a <bad-request/> error to the sender. However, a MUC service MAY modify a role based on a change to an affiliation and thus MAY send presence updates that include both a modified role and a modified affiliation.

  5. In IQ sets regarding roles, a MUC client MUST include the 'nick' attribute only; in IQ results regarding roles, a MUC service MUST include the 'nick', 'role', 'affiliation', and 'jid' attributes (with the value of the latter set to the user's full JID).

  6. In IQ sets regarding affiliations, a MUC client MUST include the 'jid' attribute only (with the value set to the bare JID); in IQ results regarding affiliations, a MUC service MUST NOT include the 'role' attribute, MUST include the 'affiliation' attribute and the 'jid' attribute (with the value set to the bare JID), and SHOULD include the 'nick' attribute (except if the affiliation is "outcast", since outcasts SHOULD NOT have reserved nicknames).

17. Implementation Notes

The following guidelines may assist client and component developers in creating MUC implementations.

17.1 Services

  1. In handling messages sent by visitors in a moderated room, a MUC service MAY queue each message for approval by a moderator and MAY inform the sender that the message is being held for approval; however, such behavior is OPTIONAL, and definition of a message approval protocol (e.g., using Data Forms as defined in XEP-0004) is out of scope for this document.

  2. It is common for MUC services to provide in-room messages when certain events occur, such as when the subject changes, when an occupant enters or exits, or when a room is destroyed. Such messages are entirely OPTIONAL and are left up to the implementation or deployment, but if used MUST be messages of type "groupchat" sent from the room JID itself (<room@service>) rather than a specific occupant (<room@service/nick>). However, in general it is preferable for the receiving client to generate such messages based on events in the room (e.g., user entrances and exits) as well as specific status codes provided in MUC; this will help ensure correct localization of such messages.

  3. Out of courtesy, a MUC service MAY send an out-of-room <message/> to an occupant who is kicked or banned, and MAY broadcast an in-room <message/> to all remaining occupants informing them that the occupant has been kicked or banned from the room. However, such messages are OPTIONAL, and indeed are unnecessary since the information required for a receiving client to generate such messages is communicated in the presence stanzas (specifically the status codes) sent by a MUC service.

  4. Out of courtesy, a MUC service MAY send an out-of-room <message/> if a user's affiliation changes while the user is not in the room; the message SHOULD be sent from the room to the user's bare JID, MAY contain a <body/> element describing the affiliation change, and MUST contain a status code of 101.

  5. There is no requirement that a MUC service shall provide special treatment for users of the older "groupchat 1.0" protocol, such as messages that contain equivalents to the extended presence information that is qualified by the 'http://jabber.org/protocol/muc#user' namespace.

  6. Room types MAY be configured in any combination. A MUC service MAY support or allow any desired room types or combinations thereof.

  7. A MUC service MAY limit the number of configuration options presented to an owner after initial configuration has been completed, e.g. because certain options cannot take effect without restarting the service.

  8. A MUC service MAY provide an interface to room creation and configuration (e.g., in the form of a special Jabber user or a Web page), so that the ostensible room owner is actually the application instead of a human user.

  9. A MUC service MAY choose to make available a special in-room resource that provides an interface to administrative functionality (e.g., a "user" named "ChatBot"), which occupants could interact with directly, thus enabling admins to type '/command parameter' in a private message to that "user". Obviously this kind of implementation would require the service to add a 'ChatBot' user to the room when it is created, and to prevent any occupant from having the nickname 'ChatBot' in the room. This might be difficult to ensure in some implementations or deployments. In any case, any such interface is OPTIONAL.

  10. A MUC service SHOULD remove a user if the service receives a delivery-related error in relation to a stanza it has previously sent to the user; the delivery-related errors are <gone/>, <item-not-found/>, <recipient-unavailable/>, <redirect/>, <remote-server-not-found/>, and <remote-server-timeout/>.

  11. A MUC service MAY choose to discard extended presence information that is attached to a <presence/> stanza before reflecting the presence change to the occupants of a room. That is, an implementation MAY choose to reflect only the <show/>, <status/>, and <priority/> child elements of the presence element as specified in the XML schema for the 'jabber:client' namespace, with the result that presence "changes" in extended namespaces (e.g., gabber:x:music:info) are not passed through to occupants. If a service prohibits certain extended namespaces, it SHOULD provide a description of allowable traffic at the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' as described in the Allowable Traffic section of this document.

  12. A MUC service MAY choose to discard extended information attached to <message/> stanzas before reflecting the message to the occupants of a room. An example of such extended information is the lightweight text markup specified by XHTML-IM [32]. If a service prohibits certain extended namespaces, it SHOULD provide a description of allowable traffic at the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' as described in the Allowable Traffic section of this document.

  13. A MUC service MAY choose to "lock down" room nicknames (e.g., hardcoding the room nickname to the bare JID of the occupant). If so, the service MUST treat the locked down nickname as a reserved room nickname and MUST support the protocol specified in the Discovering Reserved Room Nickname section of this document.

17.1.1 Allowable Traffic

As noted, a service (more precisely, a properly-configured room) MAY discard some or all extended namespaces attached to <message/> and <presence/> stanzas that are intended for reflection from the sender through the room to all of the room occupants. If the room does so, it SHOULD enable senders to discover the list of allowable extensions by sending a disco#info query to the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic', returning one <feature/> element for each namespace supported in the result. If the room does not allow any extended namespaces, it MUST return an empty query as specified in XEP-0030. If the room does not support the "#traffic" node, it MUST return a <feature-not-implemented/> error in response to queries sent to the 'http://jabber.org/protocol/muc#traffic' node.

The following example shows a room that allows the 'http://jabber.org/protocol/xhtml-im' and 'http://jabber.org/protocol/rosterx' namespaces only, but no other extended namespaces.

Example 209. User Queries Service Regarding Allowable Namespaces

<iq from='wiccarocks@shakespeare.lit/laptop'
    to='heath@chat.shakespeare.lit'
    id='allow1'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='http://jabber.org/protocol/muc#traffic'/>
</iq>
      

Example 210. Service Returns Allowable Namespaces

<iq from='heath@chat.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    id='allow1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='http://jabber.org/protocol/muc#traffic'>
    <feature var='http://jabber.org/protocol/xhtml-im'/>
    <feature var='http://jabber.org/protocol/rosterx'/>
  </query>
</iq>
      

If a service does not discard any namespaces or does not implement this feature, it MUST return a <service-unavailable/> error:

Example 211. Service Returns Service Unavailable

<iq from='heath@chat.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    id='allow1'
    type='error'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='http://jabber.org/protocol/muc#traffic'/>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
      

17.2 Clients

  1. Jabber clients MAY present room roles by showing ad-hoc groups for each role within a room roster. This will enable occupants to clearly visualize which occupants are moderators, participants, and visitors. However, such a representation is OPTIONAL.

  2. Jabber clients MAY implement a variety of interface styles that provide "shortcuts" to functionality such as changing one's nickname, kicking or banning users, discovering an occupant's full JID, or changing the subject. One option consists of IRC-style commands such as '/nick', '/kick', '/ban', and '/whois'; another is to enable a user to right-click items in a room roster. All such interface styles are OPTIONAL. However, for convenience, a mapping of IRC commands to MUC protocols is provided below.

17.2.1 IRC Command Mapping

Internet Relay Chat clients use a number of common "shortcut" commands that begin with a forward slash, such as '/nick' and '/ban'. The following table provides a mapping of IRC-style commands to MUC protocols, for use by Jabber clients that wish to support such functionality.

Table 10: IRC Command Mapping

Command Function MUC protocol
/ban <roomnick> [comment] bans user with that roomnick from this room (client translates roomnick to bare JID)

<iq id='someid'
    to='room@service'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item affiliation='outcast'
          jid='bare-jid-of-user'>
      <reason>comment</reason>
    </item>
  </query>
</iq>
          
/invite <jid> [comment] invites user with that JID to this room

<message to='room@service'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <invite to='jid'>
      <reason>comment</reason>
    </invite>
  </x>
</message>
          
/join <roomname> [pass] joins room on this service (roomnick is same as nick in this room)

<presence to='room@service/nick'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <password>pass</password>
  </x>
</presence>
          
/kick <roomnick> [comment] kicks user with that roomnick from this room

<iq id='someid'
    to='room@service'
    type='set'>
  <query xmlns='http://jabber.org/protocol/muc#admin'>
    <item nick='roomnick' role='none'>
      <reason>comment</reason>
    </item>
  </query>
</iq>
          
/msg <roomnick> <foo> sends private message "foo" to roomnick

<message to='room@service/nick' type='chat'>
  <body>foo</body>
</message>
          
/nick <newnick> changes nick in this room to "newnick"

<presence to='room@service/newnick'/>
          
/part [comment] exits this room (some IRC clients also support /leave)

<presence to='room@service/nick'
          type='unavailable'>
  <status>comment</status>
</presence>
          
/topic <foo> changes subject of this room to "foo"

<message to='room@service' type='groupchat'>
  <subject>foo</subject>
</message>
          

Note: Because MUC roomnicks follow the Resourceprep profile of stringprep, they are allowed to contain a space character, whereas IRC nicknames do not. Although a given client MAY support quotation characters for this purpose (resulting in commands such as '/ban "king lear" insanity is no defense'), most common quotation characters (such as " and ') are also allowed by Resourceprep, thus leading to added complexity and potential problems with quotation of roomnicks that contain both spaces and quotation characters. Therefore it is NOT RECOMMENDED for Jabber clients to support IRC-style shortcut commands with roomnicks that contain space characters.

Note: Many Jabber clients also implement a '/me ' command as described in The /me Command [33]. This command does not result in any MUC or IRC protocol action and is therefore not shown in the foregoing table.

18. XML Schemas

18.1 http://jabber.org/protocol/muc

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc'
    xmlns='http://jabber.org/protocol/muc'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0045: http://www.xmpp.org/extensions/xep-0045.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='x'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='history' minOccurs='0'/>
        <xs:element name='password' type='xs:string' minOccurs='0'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='history'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='maxchars' type='xs:int' use='optional'/>
          <xs:attribute name='maxstanzas' type='xs:int' use='optional'/>
          <xs:attribute name='seconds' type='xs:int' use='optional'/>
          <xs:attribute name='since' type='xs:dateTime' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

18.2 http://jabber.org/protocol/muc#user

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc#user'
    xmlns='http://jabber.org/protocol/muc#user'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0045: http://www.xmpp.org/extensions/xep-0045.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='x'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='decline' minOccurs='0'/>
        <xs:element ref='destroy' minOccurs='0'/>
        <xs:element ref='invite' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='item' minOccurs='0'/>
        <xs:element name='password' type='xs:string' minOccurs='0'/>
        <xs:element ref='status' minOccurs='0' maxOccurs='unbounded'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:element name='decline'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='reason' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='from' type='xs:string' use='optional'/>
      <xs:attribute name='to' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='destroy'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='reason' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='invite'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='reason' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='from' type='xs:string' use='optional'/>
      <xs:attribute name='to' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='actor' minOccurs='0'/>
        <xs:element ref='reason' minOccurs='0'/>
        <xs:element ref='continue' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='affiliation' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='admin'/>
            <xs:enumeration value='member'/>
            <xs:enumeration value='none'/>
            <xs:enumeration value='outcast'/>
            <xs:enumeration value='owner'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
      <xs:attribute name='nick' type='xs:string' use='optional'/>
      <xs:attribute name='role' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='moderator'/>
            <xs:enumeration value='none'/>
            <xs:enumeration value='participant'/>
            <xs:enumeration value='visitor'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='actor'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='jid' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='continue'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='thread' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='status'>
    <xs:complexType>
      <xs:attribute name='code' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:int'>
            <xs:minInclusive value='100'/>
            <xs:maxInclusive value='999'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='reason' type='xs:string'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

18.3 http://jabber.org/protocol/muc#admin

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc#admin'
    xmlns='http://jabber.org/protocol/muc#admin'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0045: http://www.xmpp.org/extensions/xep-0045.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='item' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='actor' minOccurs='0'/>
        <xs:element ref='reason' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='affiliation' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='admin'/>
            <xs:enumeration value='member'/>
            <xs:enumeration value='none'/>
            <xs:enumeration value='outcast'/>
            <xs:enumeration value='owner'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
      <xs:attribute name='nick' type='xs:string' use='optional'/>
      <xs:attribute name='role' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='moderator'/>
            <xs:enumeration value='none'/>
            <xs:enumeration value='participant'/>
            <xs:enumeration value='visitor'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='actor'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='jid' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='reason' type='xs:string'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

18.4 http://jabber.org/protocol/muc#owner

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc#owner'
    xmlns='http://jabber.org/protocol/muc#owner'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0045: http://www.xmpp.org/extensions/xep-0045.html
    </xs:documentation>
  </xs:annotation>

  <xs:import 
      namespace='jabber:x:data'
      schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>

  <xs:element name='query'>
    <xs:complexType>
      <xs:choice xmlns:xdata='jabber:x:data' minOccurs='0'>
        <xs:element ref='xdata:x'/>
        <xs:element ref='destroy'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:element name='destroy'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='password' type='xs:string' minOccurs='0'/>
        <xs:element name='reason' type='xs:string' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

18.5 http://jabber.org/protocol/muc#unique

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc#unique'
    xmlns='http://jabber.org/protocol/muc#unique'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0045: http://www.xmpp.org/extensions/xep-0045.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='unique' type='xs:string'/>

</xs:schema>
    

19. Acknowledgements

The author would like to thank the following individuals for their many helpful comments on various drafts of this proposal: David Sutton, Peter Millard, Joe Hildebrand, Craig Kaes, Alexey Shchepin, David Waite, Jean-Louis Seguineau, Jacek Konieczny, Gaston Dombiak, and many others in the jdev@conference.jabber.org conference room and on the Standards mailing list.


Appendices


Appendix A: Document Information

Series: XEP
Number: 0045
Publisher: XMPP Standards Foundation
Status: Draft
Type: Standards Track
Version: 1.24
Last Updated: 2008-07-16
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-0004, XEP-0030, XEP-0068, XEP-0082, XEP-0128
Supersedes: None
Superseded By: None
Short Name: muc
XML Schema for muc namespace: <http://www.xmpp.org/schemas/muc.xsd>
XML Schema for muc#admin namespace: <http://www.xmpp.org/schemas/muc-admin.xsd>
XML Schema for muc#owner namespace: <http://www.xmpp.org/schemas/muc-owner.xsd>
XML Schema for muc#unique namespace: <http://www.xmpp.org/schemas/muc-unique.xsd>
XML Schema for muc#user namespace: <http://www.xmpp.org/schemas/muc-user.xsd>
Registry: <http://xmpp.org/registrar/muc.html>
Source Control: HTML
This document in other formats: XML  PDF


Appendix B: Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JabberID: stpeter@jabber.org
URI: https://stpeter.im/


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2011 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Appendix G: Notes

1. RFC 1459: Internet Relay Chat <http://tools.ietf.org/html/rfc1459>.

2. RFC 2810: Internet Relay Chat: Architecture <http://tools.ietf.org/html/rfc2810>.

3. RFC 2811: Internet Relay Chat: Channel Management <http://tools.ietf.org/html/rfc2811>.

4. RFC 2812: Internet Relay Chat: Client Protocol <http://tools.ietf.org/html/rfc2812>.

5. RFC 2813: Internet Relay Chat: Server Protocol <http://tools.ietf.org/html/rfc2813>.

6. XEP-0133: Service Administration <http://xmpp.org/extensions/xep-0133.html>.

7. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

8. XEP-0059: Result Set Management <http://xmpp.org/extensions/xep-0059.html>.

9. XEP-0128: Service Discovery Extensions <http://xmpp.org/extensions/xep-0128.html>.

10. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc3920>.

11. XEP-0203: Delayed Delivery <http://xmpp.org/extensions/xep-0203.html>.

12. XEP-0091: Legacy Delayed Delivery <http://xmpp.org/extensions/xep-0091.html>.

13. XEP-0082: XMPP Date and Time Profiles <http://xmpp.org/extensions/xep-0082.html>.

14. RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc6121>.

15. XEP-0249: Direct MUC Invitations <http://xmpp.org/extensions/xep-0249.html>.

16. XEP-0077: In-Band Registration <http://xmpp.org/extensions/xep-0077.html>.

17. XEP-0004: Data Forms <http://xmpp.org/extensions/xep-0004.html>.

18. Some commentors have complained that this opens room owners and administrators up to potential abuse; unfortunately, with great power comes great responsibility.

19. XEP-0050: Ad-Hoc Commands <http://xmpp.org/extensions/xep-0050.html>.

20. XEP-0060: Publish-Subscribe <http://xmpp.org/extensions/xep-0060.html>.

21. This is different from the behavior of room configuration, wherein the 'muc#roomconfig_roomowners' field specifies the full list of room owners, not the delta.

22. This is different from the behavior of room configuration, wherein the 'muc#roomconfig_roomadmins' field specifies the full list of room admins, not the delta.

23. XEP-0086: Error Condition Mappings <http://xmpp.org/extensions/xep-0086.html>.

24. RFC 2616: Hypertext Transport Protocol -- HTTP/1.1 <http://tools.ietf.org/html/rfc2616>.

25. RFC 1893: Enhanced Mail System Status Codes <http://tools.ietf.org/html/rfc1893>.

26. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

27. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

28. XEP-0068: Field Data Standardization for Data Forms <http://xmpp.org/extensions/xep-0068.html>.

29. XEP-0147: XMPP URI Query Components <http://xmpp.org/extensions/xep-0147.html>.

30. XEP-0022: Message Events <http://xmpp.org/extensions/xep-0022.html>.

31. XEP-0085: Chat State Notifications <http://xmpp.org/extensions/xep-0085.html>.

32. XEP-0071: XHTML-IM <http://xmpp.org/extensions/xep-0071.html>.

33. XEP-0245: The /me Command <http://xmpp.org/extensions/xep-0245.html>.


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 1.24 (2008-07-16)

Added more examples of the reason element; removed mention of nick inclusion with regard to ban lists; added denial of service considerations.

(psa)

Version 1.23 (2008-01-14)

(psa)

Version 1.22 (2007-04-10)

Updated delayed delivery reference to reflect advancement of XEP-0203 to Draft and deprecation of XEP-0091.

(psa)

Version 1.21 (2006-09-13)

(psa)

Version 1.20 (2005-09-08)

Harmonized ability to kick and ban users, and clarified that a user cannot be kicked or banned by a moderator or admin with a lower affiliation.

(psa)

Version 1.19 (2005-04-21)

Specified how to send multiple invitations simultaneously; corrected some errors regarding consistency of affiliation state changes; changed message events prohibition from MUST NOT to SHOULD NOT; corrected error handling related to the #traffic disco node; allowed <password/> as a child of <destroy/>; changed max users error from <not-allowed/> to <service-unavailable/>; specified that the maxchars attribute counts characters in complete XML stanzas; added disco features for FORM_TYPEs; defined registry for status codes; split Create Instant Room into separate use case for protocol compliance purposes; adjusted XML schemas to reflect the foregoing changes; re-wrote the introduction; clarified small textual matters throughout.

(psa)

Version 1.18 (2004-11-02)

Corrected several errors in the affiliation state chart and in the examples (wrong FORM_TYPE values); mentioned /me command.

(psa)

Version 1.17 (2004-10-04)

Added text about allowable extension namespaces and related service discovery mechanisms; specified well-known service discovery nodes; added conformance terms to clarify some descriptions; modified affiliation state chart to allow more flexible state changes; per list dicussion, added ability to convert a one-to-one chat into a conference, including sending of history; specified error to use when max users limit is reached; specified form for admin approval of user registration requests and modified FORM_TYPE from http://jabber.org/protocol/muc#user to http://jabber.org/protocol/muc#register; modified FORM_TYPE for room configuration from http://jabber.org/protocol/muc#owner to http://jabber.org/protocol/muc#roomconfig.

(psa)

Version 1.16 (2004-06-30)

Added example and registry submission for service discovery extension.

(psa)

Version 1.15 (2004-06-24)

Removed jabber:iq:browse references; clarified order of presence stanzas sent to new occupant on entering room; specified format of in-room messages (type='groupchat', from='room@service'); clarified allowable attributes in various list-related operations; made admin/owner revocation text and examples consistent with state chart; clarified ownership revocation conflict scenarios; changed the 'muc#roomconfig_inviteonly' field to 'muc#roomconfig_membersonly'; changed attribute order in examples to match XML canonicalization rules; corrected several errors in the schemas.

(psa)

Version 1.14 (2004-05-03)

Corrected discovery of registered roomnicks; added note about error to return if nicks are locked down.

(psa)

Version 1.13 (2004-03-31)

Fixed an error in the muc#user schema.

(psa)

Version 1.12 (2004-03-01)

Corrected a few errors in the examples; added IQ results in order to clarify workflows.

(psa)

Version 1.11 (2004-02-05)

Clarified JID matching rules (same as for privacy lists in XMPP IM).

(psa)

Version 1.10 (2004-01-07)

Added XMPP error handling; fully specified all conformance terms.

(psa)

Version 1.9 (2003-12-14)

Removed protocol for requesting voice in a moderated room (should be performed using Ad-Hoc Commands).

(psa)

Version 1.8 (2003-12-04)

Added protocol for requesting voice in a moderated room; added (informational) mapping of IRC commands to MUC protocols.

(psa)

Version 1.7 (2003-10-21)

Added room configuration option for restricting presence broadcast to certain roles.

(psa)

Version 1.6 (2003-10-03)

Added history management protocol on entering a room.

(psa)

Version 1.5 (2003-09-11)

Specified that ban occurs by JID, not roomnick; allowed privileged users to send messages to the room even if not present in the room; added note that service should remove occupant if a delivery-related stanza error occurs; enabled user to disco the room in order to discover registered roomnick; specified that "banning" by domain or regex is a service-level configuration matter and therefore out of scope for MUC; specified that role should be decremented as appropriate if affiliation is lowered; added some clarifying text to room creation workflow; added implementation note about sending an out-of-band message if a user's affiliation changes while the user is not in the room; fixed stringprep references (room nicks use Resourceprep); clarified relationship between Room ID (i.e., node identifier of Room JID, which may be opaque) and natural-language Room Name; specified Field Standardization profile per XEP-0068; defined XMPP Registrar submissions; added schema locations.

(psa)

Version 1.4 (2003-02-16)

Added XML schemas.

(psa)

Version 1.3 (2003-02-11)

Added reference to nodeprep Internet-Draft.

(psa)

Version 1.2 (2003-01-30)

Commented out revision history prior to version 1.0 (too long); clarified business rules regarding when nicks, full JIDs, and bare JIDs are used in reference to roles and affiliations; consistently specified that extended presence information in the muc#user namespace must include the full JID as the value of the 'jid' attribute in all cases; cleaned up text and examples throughout; added open issue regarding syntax of room nicknames.

(psa)

Version 1.1 (2002-12-16)

Added protocol for declining an invitation; replaced <created/> element with status code 201; modified the destroy room protocol so that <destroy/> is a child of <query/>; clarified usage of 'nick' attribute when adding members; prohibited use of message events.

(psa)

Version 1.0 (2002-11-21)

Per a vote of the Jabber Council, revision 0.23 was advanced to Draft on 2002-11-21. (For earlier revision history, refer to XML source.)

(psa)

Version 0.23 (2002-11-06)

Added examples for disco#items queries sent to a room; prohibited 'type' attribute on invite messages sent from client to room; added dependencies on browse and disco; changed 'room user' to 'occupant'; fixed many small errors throughout.

(psa)

Version 0.22 (2002-11-04)

Added example for disco#items; added support for cancellation of room configuration using type='cancel' from XEP-0004; noted 403 error for invites sent by non-admins in members-only room.

(psa)

Version 0.21 (2002-11-01)

Clarified several small ambiguities; made <body/> optional on invites sent from the service to the invitee; added error scenarios for changing nickname and for destroying the room; specified that the service must return the full member list for a members-only room (not only the members in the room); updated the disco examples to track protocol changes.

(psa)

Version 0.20 (2002-10-29)

Specified that messages sent to change the room subject must be of type "groupchat"; updated the legal notice to conform to the XSF IPR policy.

(psa)

Version 0.19 (2002-10-28)

Added ability to create an instant room within MUC (not by using gc-1.0 protocol); cleaned up disco examples.

(psa)

Version 0.18 (2002-10-27)

Added experimental support for disco; added sections for security, IANA, and JANA considerations; corrected typographical errors; cleaned up some DocBook formatting.

(psa)

Version 0.17 (2002-10-23)

Added the optional <actor/> element (with 'jid' attribute) to <item/> elements inside presence stanzas of type "unavailable" that are sent to users who are kicked or banned, as well as within IQs for tracking purposes; reverted all list editing use cases (ban, voice, member, moderator, admin, owner) to use of MUC format rather than 'jabber:x:data' namespace; added several guidelines regarding generation and handling of XML stanzas; cleaned up the change room subject use case; changed several ambiguous uses of 'would', 'can', and 'will' to 'should', 'may', or 'must'; fixed several small errors in the text, examples, and DTDs.

(psa)

Version 0.16 (2002-10-20)

Added the <item/> element to presence stanzas of type "unavailable" in order to improve the tracking of user states in the room; consolidated <invitee/> and <invitor/> elements into an <invite/> element with 'from' and 'to' attributes; made <reason/> element always a child of <item/> or <invite/> in the muc#user namespace; moved the alternate room location in room destruction to a 'jid' attribute of the <alt/> element; further specified several error messages; disallowed simultaneous modifications of both affiliations and roles by a moderator or admin; added several more rules regarding handling of XML stanzas; added use cases for granting and revoking administrative privileges; adjusted DTD to track all changes.

(psa)

Version 0.15 (2002-10-18)

Fully incorporated the change to affiliations + roles; moved a number of admin use cases to a new section for moderator use cases; added participant use case for requesting membership; added admin use cases for adding members, removing members, granting and revoking moderator privileges, and modifying the moderator list; organized the sections in a more logical manner.

(psa)

Version 0.14 (2002-10-17)

Significantly modified the privileges model by distinguishing between in-room "roles" and long-lived "affiliations"; specified the privileges of the various roles and affiliations; included state transition charts for both roles and affiliations; removed use of MUC protocol for editing ban, voice, and admin lists (but not for the actions of banning users and granting/revoking voice); added delivery rule regarding IQ stanzas; changed kick so that the action is based on changing the role to "none".

(psa)

Version 0.13 (2002-10-16)

Corrected the change nickname examples (newnick sent on unavailable, no nick sent on available).

(psa)

Version 0.12 (2002-10-16)

Removed SHA1 passwords; specified that room shall add passwords on invitations to password-protected rooms (not supplied by invitor).

(psa)

Version 0.11 (2002-10-16)

Changed 'participant' to 'room user' and 'discussant' to 'participant'; clarified presence rule about client generation of extended presence information; added role of 'none'.

(psa)

Version 0.10 (2002-10-15)

Fixed extended presence on entering or creating a room (plain '...muc' with no fragment); harmonized #user with #admin regarding the use of the <item/> element and associated attributes (jid, nick, etc.), and added 'role' attribute; modified management of voice, ban, admin, and member lists to use <query/> wrapper and new <item/> structure; changed the 'member' role to 'discussant', added 'outcast' role for banned users, and added new 'member' role to enable management of member lists; changed invitation-only rooms to members-only rooms and made appropriate adjustments to apply member lists to both members-only rooms and open rooms; modified nickname change protocol slightly to send the old nickname in the unavailable presence and the new nickname in the available presence; removed prohibition on members-only rooms that are password-protected; removed the <query/> wrapper for the <destroy/> element; updated the DTDs.

(psa)

Version 0.9 (2002-10-13)

Added extended presence ('...#user') on entering a room for MUC clients; changed namespace on room creation request to '...#owner'; added a service discovery example using jabber:iq:browse; added information about discussion history; made small fixes to several examples; further defined the presence rules; transferred all implementation notes to a dedicated section; added a Terminology section.

(psa)

Version 0.8 (2002-10-10)

Made further changes to the room creation workflow (finally correct); removed feature discovery use case (this needs to be addressed by a real service discovery protocol!); added ability for room owners to edit the admin list; removed <body/> from invitations generated by the service; removed messages sent to kicked and banned users (handled by unavailable presence with status code); added a number of implementation notes; converted all examples to Shakespeare style.

(psa)

Version 0.7.6 (2002-10-09)

Fixed the room creation workflow; changed some terminology ("join" to "enter" and "leave" to "exit").

(psa)

Version 0.7.5 (2002-10-08)

Specified and improved the handling of invitation-only rooms. In particular, added the ability for room admins to edit the invitation list and added a configuration option that limits the ability to send invitations to room admins only.

(psa)

Version 0.7.4 (2002-10-07)

Changed namespaces from http://jabber.org/protocol/muc/owner etc. to http://jabber.org/protocol/muc#owner etc. per Jabber Council discussion.

(psa)

Version 0.7.3 (2002-10-07)

Changed namespaces to HTTP URIs; left role handling up to the implementation; further clarified presence rules.

(psa)

Version 0.7.2 (2002-10-06)

Disallowed kicking, banning, and revoking voice with respect to room admins and room owners; replaced <x/> with <query/> in the Discovering Room Features and Destroying a Room use cases; corrected some small errors and made many clarifications throughout.

(psa)

Version 0.7.1 (2002-10-04)

Removed <whois/> command (unnecessary since participants with appropriate privileges receive the full JID of all participants in presence stanzas); completed many small fixes throughout.

(psa)

Version 0.7 (2002-10-03)

More clearly delineated participant roles and defined the hierarchy thereof (owner, admin, member, visitor); replaced <voice/> element in extended presence with <item role='member'/>; changed initial room configuration to use IQ rather than message; adjusted presence rules (especially regarding extended presence information); cleaned up examples throughout; updated DTD to track changes.

(psa)

Version 0.6 (2002-09-21)

More clearly defined the scope; removed fully anonymous rooms; changed meaning of semi-anonymous rooms and of non-anonymous rooms; added mechanism for notification of full JIDs in non-anonymous rooms; replaced the <admin/> element in extended presence with a <role/> element (more extensible); changed room passwords to cleartext; added status codes for various messages received from the service; added lists of valid error and status codes associated with the 'http://jabber.org/protocol/muc#user' namespace; added a <reason/> element for invitations; made kick and ban reasons child elements rather than attributes; replaced stopgap feature discovery mechanism with jabber:iq:negotiate; added extended presence element to room creation request and clarified the room creation process; specified presence reflection rules; added method for destroying a room; adjusted DTDs to track all changes.

(psa)

Version 0.5.1 (2002-09-20)

Added DTDs; changed feature discovery to use <x/> element rather than query and made service response come in IQ result; fixed reference to JID spec; changed 'grant' to 'add' and 'revoke' to 'remove' for consistency in the item attributes; made several other small changes.

(psa)

Version 0.5 (2002-09-19)

Changed the kick, ban, and voice protocols; added a few more configuration options; specified the restrictions for roomnicks; and added a stopgap service discovery protocol.

(psa)

Version 0.4 (2002-09-18)

Changed all non-GC-1.0 use cases to jabber:gc:* namespaces or jabber:x:data; added use cases for ban list management and room moderation; added protocol for sending notice of admin and voice privileges in presence; cleaned up text and many examples.

(psa)

Version 0.3 (2002-09-17)

Changed admin use cases; cleaned up participant and owner use cases.

(psa)

Version 0.2 (2002-09-12)

Broke content out into three actors (participant, owner, and admin) and added more detail to owner and admin use cases.

(psa)

Version 0.1 (2002-09-09)

Initial version.

(psa)

END