XEP-0045: Multi-User Chat

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.

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.

Table 1: Dramatis Personae

Table 2: Roles

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).

* 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.

* 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.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.

* 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.

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

<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>
    

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

<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>
    

<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>
    

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

<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>
    

<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>
    

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

<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>
    

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

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

<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>
    

<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>
    

<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>
    

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

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).

* 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 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:

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>
      

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

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

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

<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>
    

<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>
    

<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>
    

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

<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.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.

<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>
    

<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>
    

<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>
    

<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>
    

<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>
    

<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>
    

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

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

<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>