XEP-0369: Mediated Information eXchange (MIX)

Table 1: JID Visibility Modes

Table 2: JID Visibility Preference Options

Table 3: Standard MIX Nodes

Table 4: MIX Nodes for Avatar Support

3.8.1 Roles

There are a number of MIX roles for each channel, listed in the following table. Rights will be assigned to the various roles in the channel configuration node.

There will always be at lease one owner and "anyone" will always have role occupants. Other roles may not have any role occupants. Rights are defined in a strictly hierarchical manner, so that for example Owners will always have rights that Administrators have.

3.8.2 Messages Node

Items in this node will contain a message identified by a unique ID. A MIX implementation SHOULD NOT make messages available for retrieval from this node using pubsub and MUST NOT allow direct pubsub publishing to this node. Messages are published by sending messages to the channel. Zero history is held in the messages node. Message history is retrieved by use of MAM. Users subscribe to this node to indicate that messages from the channel are to be sent to them.

Private Messages are not stored in the messages node.

3.8.3 Participants Node

Each channel participant is represented as an item of the 'urn:xmpp:mix:nodes:participants' channel node. Each item is named by the bare proxy JID of the participant. For example 'coven+123456@mix.shakespeare.example' might name the node item associated with participant 'hag66@shakespeare.example'. The nick associated with the user is mandatory and is stored in the item. The nick for each channel participant MUST be different to the nick of other participants.

When a user joins a channel, the user's bare JID is added to the participants node by the MIX service. When a user leaves a channel, they are removed from the participants node. The participants node MUST NOT be directly modified using pubsub. This node MAY be subscribed to for jid-visible channels that permit subscription to this node - this will allow users to see changes to the channel participants.

The participants node is optional. If the Participants Node is not used, information on channel participants is not shared. If there is no participants node, the access control value 'participants' MUST NOT be used.

Example 1. Value of Participants Node

<items node='urn:xmpp:mix:nodes:participants'>
  <item id='coven+123456@mix.shakespeare.example'>
    <participant xmlns='urn:xmpp:mix:0'
                 nick='thirdwitch'/>
  </item>
</items>

3.8.4 JID Map Node

The JID Map node is used to associate a proxy bare JID to its corresponding real bare JID. The JID Map node MUST have one entry for each entry in the Participants node. This value is added when a user joins the channel and is removed when the user leaves the channel. Each item is identified by proxy bare JID, mapping to the real bare JID. This node is used to give administrator access to real JIDs and participant access to real JIDs in jid-visible channels. This node MUST NOT be modified directly using pubsub. In JID visible channels, all participants may subscribe to this node. In JID hidden channels, only administrators can subscribe.

Example 2. Value of JID Map Node

<items node='urn:xmpp:mix:nodes:jidmap'>
  <item id='coven+123456@mix.shakespeare.example'>
    <participant xmlns='urn:xmpp:mix:0'
                 jid='hecate@mix.shakespeare.example'/>
  </item>
</items>

3.8.5 Presence Node

The presence node contains the presence value for clients belonging to participants that choose to publish presence to the channel. A MIX channel MAY require that all participants publish presence. Each item in the presence node is identified by the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza. The full JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control may be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.

This node may be subscribed to by users and this subscription MUST use the users bare JID. So presence of online clients is sent to the MIX Proxy for each user subscribed to this node. Presence is always sent using standard presence protocol and NOT using pubsub protocol. Clients MUST NOT directly access the presence node using pubsub.

Example 3. Value of Presence Node

<items node='urn:xmpp:mix:nodes:presence'>
  <item id='coven+123456@mix.shakespeare.example/8765'>
    <presence xmlns='jabber:client'>
      <show>dnd</show>
      <status>Making a Brew</status>
    </presence>
  </item>
</items>

3.8.6 Information Node

The Information node holds information about the channel. The information node contains a single item with the current information. Information node history is held in MAM. The information node is named by the date/time at which the item was created. The information node is accessed and managed using standard pubsub. Users MAY subscribe to this node to receive information updates. The Information node item may contain the following attributes, each of which is optional:

The name and description values MUST contain a "text" element and MAY contain additional text elements. Where multiple text elements are provided, each MUST posses an xml:lang attribute that describes the natural language of the subject. The format of the Information node follows Data Forms (XEP-0004) [13]. This allows configuration to be updated by MIX defined commands and that the results of update commands are the same as the PubSub node. The following example shows the format of a item in the information node for the example coven@mix.shakespeare.example channel.

Example 4. Information Node

<items node='urn:xmpp:mix:nodes:info'>
  <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'>
      <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Name'>
            <value>Witches Coven</value>
        </field>
        <field var='Description'>
           <value>A location not far from the blasted heath where the three witches meet</value>
         </field>
        <field var='Contact'>
           <value>greymalkin@shakespeare.lit</value>
         </field>
         </x>
  </item>
</items>

3.8.7 Subject Node

The subject node publishes the current subject of channel. Subject history is stored in MAM. A single item is stored in this node at a time which MUST contain a "text" element and MAY contain additional text elements. Where multiple text elements are provided, each MUST posses an xml:lang attribute that describes the natural language of the subject.

Setting and sharing subject uses a message with subject element, in a manner compatible with Multi-User Chat (XEP-0045) [14]. Clients MAY also write or access this node using pubsub. Writes to this node will lead to update of subject by sending messages. Setting the subject is controlled by configuration; in some channels it may be set by all users and in others restricted to administrators. The following example shows the format of a item in the subject node.

Example 5. Subject Node

        <items node='urn:xmpp:mix:nodes:subject'>
  <item>
    <text xml:lang="en">How to use Toads</text>
    <text xml:lang="de">Wie benutzt man Kröten</text>
  </item>
</items>

When a user subscribes to the Subject Node, this will cause the channel to send Subject messages to the user through the MIX Proxy. This is done on initial user subscription and on subject change. Clients MAY directly read the channel subject from the Subject Node using PubSub.

3.8.8 Allowed

This node represents a list of JIDs that are allowed to become participants. If the allowed node is not present, all JIDs are allowed. This node is accessed and managed using standard pubsub. The allowed list is always considered in conjunction with the banned list, stored in the banned node. Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID. The following example shows how the allowed list can specify single JIDs and domains.

Example 6. Allowed Node

<items node='urn:xmpp:mix:nodes:allowed'>
  <item id='@shakespeare.lit'/>
  <item id='alice@wonderland.lit'/>
</items>

3.8.9 Banned

This node represents a list of JIDs that are explicitly not allowed to become participants. The values in this list take priority over values in the allowed node. This node is accessed and managed using standard pubsub Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID.

Example 7. Banned Node

<items node='urn:xmpp:mix:nodes:banned'>
  <item id='lear@shakespeare.lit'/>
  <item id='macbeth@shakespeare.lit'/>
</items>

3.8.10 Configuration Node

The Configuration node holds the configuration of the channel as a single item, named by the date-time of the last update to the configuration. A single item is stored in the node, with previous configuration history accessed by MAM. Users with read access to the configuration node MAY subscribe to the configuration node to get notification of configuration change. This node is accessed and managed using standard pubsub. The configuration node is optional for a MIX channel. For example, configuration choices could be fixed and not exposed. A subset of the defined configuration options may be used and additional non-standard configuration options may be added. JIDs in the configuration MUST be real bare JIDs and not proxy JIDs. If configuration options to control functionality of the nature described here are provided, the options defined in this standard MUST be used. The following configuration attributes are defined:

The configuration node is in Data Forms (XEP-0004) [15] format and includes all of the options used by the channel, including values for options using default values. This means that the value in the form can be directly mapped with the form returned by configuration administration commands. Configuration nodes will typically have a large number of elements. The following short example is provided to illustrate the syntax of the configuration node.

Example 8. Configuration Node

<items node='urn:xmpp:mix:nodes:config'>
  <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'>
      <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Owner'>
            <value>hecate@shakespeare.lit</value>
        </field>
        <field var='Owner'>
            <value>greymalkin@shakespeare.lit</value>
        </field>
        <field var='Message Node Subscription'>
           <value>allowed</value>
         </field>
        <field var='JID Visibility'>
           <value>jid-mandatory-visible</value>
         </field>
         <field var='No Private Messages'>
            <value>true</value>
         </field>
         </x>
  </item>
</items>

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='shakespeare.example'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>

<iq from='shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='mix.shakespeare.example'
          name='Shakespearean Chat Service'/>
    <item jid='mix2.shakespeare.example'
          name='Another Shakespearean Chat Service'/>
  </query>
</iq>

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='Shakespearean Chat Service'
        type='text'/>
    <feature var='urn:xmpp:mix:0'/>
    <feature var='searchable' xmlns='urn:xmpp:mix:0'>
  </query>
</iq>

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

<iq from='mix.shakespeare.lit'
    id='kl2fax27'
    to='hag66@shakespeare.lit'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='coven@mix.shakespeare.example' />
    <item jid='spells@mix.shakespeare.example' />
    <item jid='wizards@mix.shakespeare.example' />
  </query>
</iq>

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

<iq from='coven@mix.shakespeare.lit'
    id='ik3vs715'
    to='hag66@shakespeare.lit'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info' node='mix'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='mix'/>
    <feature var='urn:xmpp:mix:0'/>
    <feature var='urn:xmpp:mam:1'/>
  </query>
</iq>

<iq from='hag66@shakespeare.lit'
    id='kl2fax27'
    to='coven@mix.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/ node='mix'>
</iq>

<iq from='coven@mix.shakespeare.lit'
    id='kl2fax27'
    to='hag66@shakespeare.lit'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items' node='mix'>
    <item jid='coven@mix.shakespeare.example'
          node='urn:xmpp:mix:nodes:presence'/>
    <item jid='coven@mix.shakespeare.example'
          node='urn:xmpp:mix:nodes:participants'/>
    <item jid='coven@mix.shakespeare.example'
          node='urn:xmpp:mix:nodes:messages'/>
    <item jid='coven@mix.shakespeare.example'
          node='urn:xmpp:mix:nodes:subject'/>
    <item jid='coven@mix.shakespeare.example'
          node='urn:xmpp:mix:nodes:config'/>
  </query>
</iq>

<iq from='hag66@shakespeare.lit'
    id='kl2fax27'
    to='coven@mix.shakespeare.lit'
    type='get'>
  <query xmlns='urn:xmpp:mix:0#channel-info'/ node='mix'>
</iq>

<iq from='coven@mix.shakespeare.lit'
    id='kl2fax27'
    to='hag66@shakespeare.lit'
    type='result'>
  <query xmlns='urn:xmpp:mix:0#channel-info' node='mix'>
      <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Name'>
            <value>Witches Coven</value>
        </field>
        <field var='Description'>
           <value>A location not far from the blasted heath where the three witches meet</value>
         </field>
        <field var='Contact'>
           <value>greymalkin@shakespeare.lit</value>
         </field>
      </x>
  </query>
</iq>

<iq from='hag66@shakespeare.lit'
    id='kl2fax27'
    to='coven@mix.shakespeare.lit'
    type='get'>
  <query xmlns='urn:xmpp:mix:0#get-participants'/ node='mix'>
</iq>

<iq from='coven@mix.shakespeare.lit'
    id='kl2fax27'
    to='hag66@shakespeare.lit'
    type='result'>
  <query xmlns='urn:xmpp:mix:0#get-participants' node='mix'>
  <items>
      <item jid='hag66@shakespeare.lit' nick='thirdwitch'>
      <item jid='hag01@shakespeare.lit' nick='top witch'>
</items>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='disco1'
    to='juliet@capulet.lit/chamber'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'
         node='http://code.google.com/p/exodus#QgayPKawpkPSDYmwT/WM94uAlu0='>
    <identity category='client' name='Exodus 0.9.1' type='pc'/>
    <feature var='http://jabber.org/protocol/caps'/>
    <feature var='http://jabber.org/protocol/disco#info'/>
    <feature var='http://jabber.org/protocol/disco#items'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='http://jabber.org/protocol/mix'/>
  </query>
</iq>

5.1.1 Joining a Channel

A user joins a channel by sending a MIX "join" command. There is no default set of nodes, so user MUST specify the set of nodes to be subscribed to. To achieve the equivalent service to MUC, a user would subscribe to messages, presence and subject. This will lead to the server subscribing the user to each of the requested nodes associated with the channel. The MIX service will also add the user to the participant list by injecting a new item into the "urn:xmpp:mix:nodes:participants" node automatically.

The default MIX model is that only channel participants may subscribe to nodes. A MIX channel MAY allow non-participant subscription. This will be handled by clients directly subscribing to the desired PubSub nodes.

Example 23. User Joins a Channel

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <join xmlns='urn:xmpp:mix:0'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <subscribe node='urn:xmpp:mix:nodes:presence'/>
    <subscribe node='urn:xmpp:mix:nodes:participants'/>
    <subscribe node='urn:xmpp:mix:nodes:subject'/>
    <subscribe node='urn:xmpp:mix:nodes:config'/>
  </join>
</iq>

The channel responds with an IQ-result. This stanza includes the nodes to which the user has been successfully subscribed, as well as the bare JID that will be used for the user in this channel and added to the participant list. The JID returned in the join is the user's bare proxy JID. The following example shows the result of the above request when the request is completed in full.

Example 24. Channel Processes Join Request in Full

<iq type='result'
    from='coven@mix.shakespeare.example'
    to='hag66@shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <join xmlns='urn:xmpp:mix:0' jid='coven+123456@mix.shakespeare.example'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <subscribe node='urn:xmpp:mix:nodes:presence'/>
    <subscribe node='urn:xmpp:mix:nodes:participants'/>
    <subscribe node='urn:xmpp:mix:nodes:subject'/>
    <subscribe node='urn:xmpp:mix:nodes:config'/>
  </join>
</iq>

If a user cannot be subscribed to one or more of the requested nodes (e.g., because the node does not exist), but can be subscribed to some the response simply lists the nodes successfully subscribed. If none of the nodes requested are successfully subscribed to, an error response is sent indicating the reason that the first node requested was not subscribed to. This response will also include other nodes requested where subscription failed for the same reason. The following response example shows a response to the initial request example where the participant is not be subscribed to all nodes associated with the channel (in this case only messages, participants, and subject).

Example 25. Channel Processes Join With Some Nodes Not Subscribed To

<iq type='result'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <join xmlns='urn:xmpp:mix:0' jid='coven+123456@mix.shakespeare.example'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <subscribe node='urn:xmpp:mix:nodes:participants'/>
    <subscribe node='urn:xmpp:mix:nodes:subject'/>
  </join>
</iq>

The channel also adds the user to the participants node and sends a notification to subscribers to the participants node.

Example 26. Channel Adds User to Participants Node

<message from='coven@mix.shakespeare.example'
         to='hecate@shakespeare.example'
         id='5A9C7398-DB13-4BFA-A091-2D466C710AAF'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:mix:nodes:participants'>
      <item id='coven+123456@mix.shakespeare.example'>
        <participant xmlns='urn:xmpp:mix:0'/>
      </item>
    </items>
  </event>
</message>

The user that has been added to the channel is identified by the item id of the item added to the pubsub node, which is the proxy JID of the new channel participant. Note that the <participant> element does not include a nick of the user being added. The nick MAY be set after the join.

A user may subsequently modify subscription to nodes in a channel by sending a subscription modification request, as shown in the following example.

Example 27. User Modifies Subscription Request

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <update-subscription xmlns='urn:xmpp:mix:0'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
  </update-subscription>
</iq>

<iq type='result'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <update-subscription xmlns='urn:xmpp:mix:0' jid='hag66@shakespeare.example'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
  </update-subscription>
</iq>

5.1.2 Roster Management

After the user has jointed the channel, the user's MIX Proxy MAY add the MIX channel to the user's roster using standard XMPP to update the roster. This is done to share the user's presence status with the channel and so the MIX channel will get presence information from the user. This roster entry will lead to the user's server correctly sending user's presence from all clients to the MIX channel. The roster subscription is configured with one way presence, as presence is sent to the MIX channel but no presence information is sent about the MIX channel. The user's MIX Proxy MUST remove this roster entry after the user leaves the channel.

If the user does not wish to publish presence information to the channel, the user will not add the roster entry. A channel may require presence to be provided by all channel participants, which is controlled by the 'Participants Must Provide Presence' option. The channel MAY check that channel participants have done this and MAY remove participants that do not do this.

A channel MAY publish an Avatar following User Avatar (XEP-0084) [20]. A client MAY make use of this information to associate an Avatar with the roster entry for a channel.

5.1.3 User Preferences and Additional Information

A channel MAY store user preferences and parameters with each user. There are two preference options.

A user JID visibility preference have the following values:

1. 'Default'. In this setting, the channel default value will be used. This value is used if another value is not explicitly set.
2. 'Never'. If this is set, JID will never be shared and user will be removed from the channel if its mode changes to JID-visible-mandatory.
3. 'Prefer Not'. If this is set, JID will only be shared if mode is JID-visible-mandatory.

The user may specify that no Private Messages are to be sent from the channel, and allow vCard retrieval.

The user may specify that presence is not to be shared, which will prevent the MIX Channel from sending a presence probe for the user on channel start-up. The user will also choose to not include the MIX channel in the user's roster, so that presence will not be updated. Where the channel configuration sets 'Participants Must Provide Presence', this variable MUST be set to 'Share'.

The following table sets out the standardized user preference values. A MIX implementation may use other values.

When joining a channel, the client may specify one or more preference options as a Data Forms (XEP-0004) [21] form. In the response, the server MUST specify all of the user preferences supported by the server, with default values if the user has not requested a different value. The following example shows joining a channel and setting a preference.

Example 28. User Joins a Channel and Specifies a preference

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
    <join xmlns='urn:xmpp:mix:0'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <subscribe node='urn:xmpp:mix:nodes:presence'/>
    <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='JID Visibility'>
            <value>Never</value>
        </field>
     </x>
  </join>
</iq>

The following example shows a successful join, which also reports all the user preferences.

Example 29. Channel Successfully Processes Join and returns the preferences set

<iq type='result'
    from='coven@mix.shakespeare.example'
    to='hag66@shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <join xmlns='urn:xmpp:mix:0' jid='hag66@shakespeare.example'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <subscribe node='urn:xmpp:mix:nodes:presence'/>
    <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='JID Visibility'>
            <value>Never</value>
        </field>
        <field var='Private Messages'>
           <value>Allow</value>
         </field>
        <field var='vCard'>
          <value>Block</value>
         </field>
     </x>
  </join>
</iq>

The client may also query the channel in order to find out which user preferences are supported and the options available. This will allow users to set options not specified in the standard, by providing a form template in the result.

Example 30. User Requests and Recieves Preferences Template Form

<iq type='get'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
    <user-preference xmlns='urn:xmpp:mix:0'/>
</iq>

<iq type='result'
    from='coven@mix.shakespeare.example'
    to='hag66@shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
    <user-preference xmlns='urn:xmpp:mix:0'>
    <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field type='list-single' label='Preference for JID Visibility' var='JID Visibility'>
            <option label='JID Never Shown'><value>Never</value></option>
            <option label='Default Behaviour'><value>Default</value></option>
            <option label='Try not to show JID'><value>Prefer Not</value></option>
         </field>
         <field type='list-single' label='Example Custom Preference' var='Custom Preference'>
            <option label='One Option'><value>A</value></option>
            <option label='Another Option'><value>B</value></option>
         </field>
     </x>
  </user-preference>
</iq>

A user may modify preferences using the corresponding set operation. The set may specify values for some or all attributes. All attributes are returned in the result.

Example 31. User Updates Preferences

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
    <user-preference xmlns='urn:xmpp:mix:0'/>
     <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='JID Visibility'>
            <value>Never</value>
        </field>
        <field var='Private Messages'>
           <value>Allow</value>
         </field>
        <field var='vCard'>
          <value>Block</value>
         </field>
     </x>
</iq>

<iq type='result'
    from='coven@mix.shakespeare.example'
    to='hag66@shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
    <user-preference xmlns='urn:xmpp:mix:0'>
    <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='JID Visibility'>
            <value>Never</value>
        </field>
        <field var='Private Messages'>
           <value>Allow</value>
         </field>
        <field var='vCard'>
          <value>Block</value>
         </field>
     </x>
  </user-preference>
</iq>

5.1.4 Leaving a Channel

Users generally remain in a channel for an extended period of time. In particular the user remains as a participant the channel does not change when the user goes offline as happens with Multi-User Chat (XEP-0045) [22]. So, leaving the channel is a permanent action for a user across all clients, not just a matter of telling the channel that the user is not currently available or for a single client. In order to leave a channel, a user sends a MIX "leave" command to the channel. When a user leaves the channel, the user's client will remove the channel from the user's roster.

Example 32. User Leaves a Channel

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <leave xmlns='urn:xmpp:mix:0'/>
</iq>

When the user leaves the channel, the MIX service is responsible for unsubscribing the user from all nodes in the channel and for removing the user from the participants and presence list. If the user has online presence when the user leaves the channel, the change of presence status caused by removing the user's entry or entries from the presence node will ensure that subscribers to the presence node are correctly updated on presence status. Deletion from the participants and presence functions as if the item (channel participant) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the deletion is sent to clients subscribed to the participants PubSub nodes, as shown in the example below.

Example 33. Reporting when User Leaves a Channel

<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:mix:nodes:participants'>
      <retract id='coven+123456@mix.shakespeare.example'/>
    </items>
  </event>
</message>

<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='bar'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:mix:nodes:presence'>
      <retract id='coven+123456@mix.shakespeare.example/8765'/>
    </items>
  </event>
</message>

5.1.5 Setting a Nick

Each participant of a channel may have a nick, which is how other users in the channel will see the user. In some cases a nick is not needed, for example where a user reads messages in a channel but does not send messages or share presence information. A nick MUST be present for a user to send a message to a channel or for a user's presence to be shared on a channel. There are four ways that a user's nick can be obtained. The choice of mechanism or mechanisms is dependent on channel policy:

1. The nick is registered with the user account in some way, for example as part of user provisioning with nick configured as an attribute in a directory service. This may be chosen by corporate services that wish to ensure consistent nick values for a set of users and channels.
2. The nick is registered with the MIX service, as described in Registering a Nick .
3. The user explicitly sets the nick, as described in this section.
4. The MIX service generates the nick. In this case it is recommended that the assigned nick is a UUID following RFC 4122 [23].

A user will typically set a nick when joining a channel and may update this nick from time to time. The user does this by sending a command to the channel to set the nick. If the user wishes the channel to assign a nick (or knows that the channel will assign a nick) the nick field can be left blank, so that the user can see what is assigned in the result.

Example 34. User sets Nick on Channel

<iq type='set'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='7nve413p'>
  <query xmlns='urn:xmpp:mix:0'>
    <nick>thirdwitch</nick>
  </query>
</iq>

The channel will return the nick that is to be used, noting that this may be different to the requested nick. MIX services SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, as defined in RFC 7700 [24].

Example 35. Channel informs user of Nick

<iq type='result'
    from='hag66@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='7nve413p'>
  <query xmlns='urn:xmpp:mix:0'>
    <nick>thirdwitch</nick>
  </query>
</iq>

5.1.6 Registering a Nick

A user can register a nick with the MIX service. Nick registration can be used ensure that a user is able to use the same nick in all channels in the service and to prevent other users from using a registered nick. This can help achieve a consistent experience across a set of channels and prevent user confusion. Support for nick registration by a MIX service is optional. Where nick registration is supported, nick registration may be optional or mandatory. Where a user has registered a Nick with the MIX service, it may be used by each channel according to policy for the channel. A nick is associated with the user's bare JID.

In order to determine if a Nick may be registered, the user may use disco to determine capabilities of the MIX service.

Example 36. User Determines features of the MIX service

<iq type='get'
    from='hag66@shakespeare.example/pda'
    to='mix.shakespeare.example'
    id='7nve413p'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq type='result'
    to='hag66@shakespeare.example/pda'
    from='mix.shakespeare.example'
    id='7nve413p'>
    <query xmlns='http://jabber.org/protocol/disco#info'/>
        <feature xmlns='urn:xmpp:mix:0' var='mix_nick_register'/>
    </query>
</iq>

The response will be a list of features of the MIX channel. If Nick Registration is supported, then the result set will include <feature var="mix_nick_register"/>.

To register a nick with the MIX service the user sends a <register/> command to the service.

Example 37. User Registers with Service

<iq type='set'
    from='hag66@shakespeare.example'
    to='mix.shakespeare.example'
    id='7nve413p'>
  <register xmlns='urn:xmpp:mix:0'>
    <nick>thirdwitch</nick>
  </register>
</iq>

On success, the service informs the user of its nick. MIX SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, as defined in RFC 7700 [25] to the requested nick. This means that nick that is issued might be different from the nick that was requested.

Example 38. Service Returns User of Nick

<iq type='result'
    to='mix.shakespeare.example'
    from='hag66@shakespeare.example'
    id='7nve413p'>
  <register xmlns='urn:xmpp:mix:0'>
    <nick>thirdwitch</nick>
  </register>
</iq>

If the requested nick is already taken, the MIX service returns a <conflict/> error:

Example 39. Nick is Taken

<iq type='error'
    to='mix.shakespeare.example'
    from='hag66@shakespeare.example'
    id='7nve413p'>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If the register request does not contain a <nick/> element, then the MIX service assigns one. It is recommended that the assigned nick is a UUID following RFC 4122 [26].

5.1.7 Setting User Presence

A user joins a channel over an extended period, and participation in a channel does not generally change when user goes online or offline. The user's participation in a channel is reflected by the user's bare JID in the participant node. All messages to the channel are sent to this JID.

A user may share presence information with the channel, for one or more online clients. Where a user shares presence information with a channel, the channel is entered by the user's server into the user's roster when the user subscribes to the channel. When an XMPP client comes online or changes presence status, this will be communicated by the user to the user's server using broadcast presence. The user's XMPP server is then responsible to share this presence information to each entry in the roster and in particular to each MIX channel in the roster. The MIX channel will update the "urn:xmpp:mix:nodes:presence" node with any change of status and the updated presence information and then share this updated presence with users subscribed to this node, as described below. When the user sets an explicit status, this is used to modify the presence node in the channel. When a client being used by the user goes offline, the associated server will send presence status "unavailable" to the MIX channel, which will cause the full JID for that client to be removed from the presence node.

A channel may require that all channel participants share presence information with the channel, which is represented in the "urn:xmpp:mix:nodes:presence" node. If sharing presences is required by the channel, an XMPP client conforming to this specification SHALL share presence with the channel by including the channel in the user's roster. Note that the MIX service cannot generally enforce this, but it can require and enforce that when a message is sent to the channel, that the sender of the message is in the presence list.

Presence status and availability is set in a MIX channel by standard presence stanzas sent to the MIX channel by the user's server. User's wishing to receive presence updates will subscribe to the MIX channel presence node. Presence updates are sent out to subscribing participants using standard presence stanzas.

A user setting status is now used as an example. Unlike in Multi-User Chat (XEP-0045) [27] where coming online is a special action, coming online in MIX is implicit when presence status is set. Going offline is a achieved by setting presence status to unavailable, which removes the client full JID entry from the presence node. When a user sets a presence status, the user's server sends updated presence to the MIX channel, and the MIX service then publishes the user's availability to the "urn:xmpp:mix:nodes:presence" node. If there is not an item named by the full JID of the client with updated presence status, this item is created. If there is not an item named by the full JID of the client with updated presence status, then an item is created.

Example 40. User Setting Presence Status

<presence xmlns='jabber:client' from=‘hag66@shakespeare.example/pda’ to='coven@mix.shakespeare.example'>
  <show>dnd</show>
  <status>Making a Brew</status>
</presence>

The user's presence information is then published by the service to the "urn:xmpp:mix:nodes:presence" node, with the 'publisher' attribute set to the user's participant identifier (the proxy JID. The MIX channel then broadcasts the presence change to all users who are subscribed to the "urn:xmpp:mix:nodes:presence" node. The presence stanza is sent from the proxy (anonymized) full JID of the user. Note that presence is associated with a client and so will have a full JID as it comes directly from the client and not through the MIX Proxy.

Example 41. Channel Distributes Presence

<presence from='coven+123435@mix.shakespeare.example/678'
          to='coven@mix.shakespeare.example'
          id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
  <nick xmlns='http://jabber.org/protocol/nick'>thirdwitch</nick>
  <show>dnd</show>
  <status>Making a Brew</status>
</presence>

The presence is distributed to those subscribing to the MIX channel presence node using a standard XMPP presence stanza. The presence change is recorded on the "urn:xmpp:mix:nodes:presence" node in the item for the full JID of the client to which the presence relates. The history of this node will be held as PubSub format in the MAM archive, so that presence history may be viewed.

5.1.8 Client Coming Online and Obtaining Presence from MIX Proxy

The presence information for a channel is stored in the urn:xmpp:mix:nodes:presence node and distributed using standard presence stanzas to the MIX Proxy of users subscribing to this presence node. The user's MIX Proxy will then pass this presence information on to all online clients. This ensures that an online client is kept updated with presence. When a client goes offline, it will cease getting presence updates. Presence updates will continue to flow to the user's MIX Proxy, and so the MIX Proxy will maintain up to date presence state for the channel.

When the client comes online, it will activate use of the MIX Proxy. The MIX Proxy will then send full presence status to the client using standard presence messages. This will enable the client to update presence information for the channel. Note that this does not need any interaction with the channel.

5.1.9 MIX Proxy Presence Update

In normal operation the MIX Proxy will hold accurate presence status for the channel which it provides to clients when they are activated. Incoming presence updates are immediately sent to active MIX clients.

There are two situations where the MIX Proxy will need to get presence status from the channel. The first time is when a user joins the channel as a participant and subscribes to presence. Upon this subscription the MIX channel will send to the MIX Proxy (the user's bare JID) presence for all of the items in the presence node using standard presence stanzas. This will give the MIX Proxy full current presence for the channel.

The second scenario is when the MIX Proxy needs to load or refresh presence status for a channel. This will be needed when the MIX Proxy and associated server are started. This MIX Proxy requests presence update by sending a directed presence stanza to the MIX channel from the user's bare JID. The MIX channel can distinguish this from a presence update, which will always be sent from the clients full JID. This special presence stanza will send to the MIX Proxy (the user's bare JID) presence for all of the items in the presence node using standard presence stanzas.

5.1.10 Determining Real JIDs

Presence information will provide a MIX client with the nicks and anonymized proxy JIDs for participants. For JID visible rooms, the user may look up the real JID using the "urn:xmpp:mix:nodes:jidmap" node. The items in this node are identified by proxy JID, and so the real JID can be retrieved using a straightforward PubSub query. While a user may subscribe to the jidmap node, it is more likely to be used to directly look up JIDs as and when needed.

5.1.11 Coming Online: Synchronizing Message History

A MIX client will typically display message history of the channel to the user. When a client comes online it will need to obtain this message history from the MAM archive associated with the channel. There are three basic approaches a client will take:

1. If the client has previously displayed message history and has been offline for a reasonably small time, the client will wish to retrieve all messages since the last one displayed to the user.
2. The client may wish to display a fixed number of messages, perhaps finding more messages if the client subsequently requests.
3. The client may wish to display messages from a recent time period, perhaps finding more messages if the client subsequently requests.

To achieve this, the client will query the user's own MAM archive using Message Archive Management (XEP-0313) [28], with the query filtered by the channel JID. This gives the client flexibility to retrieve and display message history in a manner appropriate to the client implementation.

5.1.12 Going Offline

When a client goes offline, this presence update is sent by the client's server to the MIX channel. From the client perspective, this is the same as any other presence change. Handling by the MIX channel is slightly different.

Example 42. Client Goes Offline in the Channel

<presence type='unavailable'
          from='hag66@shakespeare.example/pda'
          to='coven@mix.shakespeare.example'/>

The MIX channel will retract (remove) the item in the presence node of the MIX channel identified by the client's full JID. The MIX channel will notify subscribers to the presence node of the user going offline by sending a presence stanza to the full proxy JID of each client.

Example 43. Channel Distributes Notification of Client going Offline

<presence from='coven+12345@mix.shakespeare.example/678'
          to='hecate@shakespeare.example'
          id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
          type='unavailable'/>

There is the possibility that the message associated with the user going offline will be lost. If this happens, "ghost" entries will appear in the presence node. A MIX service may take steps to address this, for example by probing client with a disco for presence items that remain unchanged for a long period.

It is desirable to prevent clients from going offline briefly and then coming back online again, as this will lead to "flapping presence". The recommended approach to achieve this is use of Stream Management (XEP-0198) [29] to maintain an XMPP client connection in the event of short term TCP failure.

5.1.13 Sending a Message

A client sends a message directly to a MIX channel as a standard groupchat message, in exactly the same way as for Multi-User Chat (XEP-0045) [30]. Messages are sent directly to the channel and do not use the MIX Proxy. The message id is selected by the client.

Example 44. User Sends Message to Channel

<message from='hag66@shakespeare.example/pda'
         to='coven@mix.shakespeare.example'
         id='92vax143g'
         type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
</message>

The MIX channel then puts a copy of the message into the MAM archive for the channel and sends a copy of the message to each participant in standard groupchat format. These messages sent by the channel are addressed to the bare JID of each participant and this will be handled by the participant's MIX Proxy. The message from value is the JID of the channel. To enable sender identification, the Nick and bare proxy JID of the sender are included in the message as MIX parameters. The id of the message is the ID from the MAM archive and NOT the id used by the sender.

Example 45. Channel Reflects Message to Participants

<message from='coven@mix.shakespeare.example'
         to='hecate@shakespeare.example'
         id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
         type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
  <nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
  <jid xmlns='urn:xmpp:mix:0'>coven+123456@mix.shakespeare.example</jid>
</message>

The messages sent to participants have a different message id to the originally submitted message. This does not impact most recipients, but it does not allow the message originator to correlate the message with the submitted message. To address this the MIX channel MUST include an additional element of the message copy going back to the originator's bare JID that includes the original id. This enables the originator to correlate the received message with the message submitted.

Example 46. Channel Reflects Message back to Originator

<message from='coven@mix.shakespeare.example'
         to='hag66@shakespeare.example'
         id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
         type='groupchat'>
  <body>Harpier cries: 'tis time, 'tis time.</body>
  <nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
  <jid xmlns='urn:xmpp:mix:0'>coven+123456@mix.shakespeare.example</jid>
  <submission-id xmlns='urn:xmpp:mix:0'>92vax143g</submission-id>
</message>

5.1.14 Retracting a Message

A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. If this is done the original message MAY be replaced by a tombstone. The protocol to request retraction does this by a message with a <retract> element as shown in the following example.

Example 47. User Retracts a Message

<message from='hag66@shakespeare.example/pda'
         to='coven@mix.shakespeare.example'
         id='92vax143g'>
  <retract id='28482-98726-73623' xmlns='urn:xmpp:mix:0'/>
</message>

The MIX channel will allow a user to retract a message sent by the user if the 'Allow User Message Retraction' option is configured. The MIX channel will allow an administrative user to retract any message if the user is in the group specified by the 'Administrator Message Retraction Rights' option.

If the retraction message is accepted, it will be distributed to channel participants. This will allow retraction to happen in the MAM archive of each channel participant and to reflect the retraction in client GUI. A client receiving a retraction message SHOULD ensure that the retracted message is no longer displayed to the end user.

Two approaches to message retraction may be used. In the first approach, the retracted message is simply removed. This is appropriate where retraction is provided as a user service and the user has rights to remove messages sent from the record.

The second approach is to leave a tombstone, which if taken MUST be done in the following manner. This is appropriate where it is desired to leave a record of the message that was redacted. With this approach, the original message <body> is removed and replaced with a tombstone using the <retracted> element that shows the JID of user performing the retraction and the time of the retraction.

Example 48. Retracted message tombstone in a MAM result

<message id='aeb213' to='juliet@capulet.lit/chamber'>
  <result xmlns='urn:xmpp:mam:1' queryid='f27' id='28482-98726-73623'>
    <forwarded xmlns='urn:xmpp:forward:0'>
      <delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
      <message xmlns='jabber:client' from="hag66@shakespeare.example" to="macbeth@shakespeare.lit">
        <retracted xmlns='urn:xmpp:mix:0' by='hag66@shakespeare.example' time='2010-07-10T23:08:25Z'/>
      </message>
    </forwarded>
  </result>
</message>

5.1.15 Setting the Channel Subject

Setting the subject for a channel follows a similar procedure to sending a message. An XMPP client will send a message setting the subject directly to the MIX channel.

Example 49. User Sets Channel Subject

<message from='hag66@shakespeare.example/pda'
         to='coven@mix.shakespeare.example'
         id='92vax143g'
         type='groupchat'>
  <subject>
   <item>
    <text xml:lang="en">How to use Toads</text>
    <text xml:lang="de">Wie benutzt man Kröten</text>
  </item>
  </subject>
</message>

This message is received by the MIX channel, which will set the Subject Node for the channel, and then distribute the message to participants that are subscribed to the Subject Node, with the message addressed to the MIX Proxy.

Example 50. Channel Reflects New Subject to Participants

<message from='coven+12345@mix.shakespeare.example/678'
         to='hecate@shakespeare.example'
         id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
         type='groupchat'>
           <subject>
            <item>
                <text xml:lang="en">How to use Toads</text>
               <text xml:lang="de">Wie benutzt man Kröten</text>
            </item>
          </subject>
</message>

When a new Participant joins a channel and subscribes to the Subject Node, the channel MUST send to the user's MIX Proxy a message with the current subject. An XMPP Client MAY directly read the Subject node using Publish-Subscribe (XEP-0060) [31].

5.1.16 Telling another User about a Channel

A convenient way to reference another channel is to use References (XEP-0372) [32] which enables the JID of a channel to be shared. This might be used simply to inform the message recipient about the channel or as mechanism to invite the user to join the channel. This is useful as an invitation mechanism to a channel that any user can join or where the invitee knows that the user may join (e.g., because the channel is for all users in an organization).

5.1.17 Inviting another User to join a Channel that the user does not have Permission to Join

Invitation by reference, as described in the previous section, is a convenient approach to invite a user to join a channel that the user has permission to join. This section describes the approach used when the inviter has permission to grant rights for the invitee to become a channel participant. This might be because the inviter is an administrator of the channel or the channel may have a special mode where channel participants may grant rights for other users to join a channel ('Participation Addition by Invitation from Participant' enabled). This approach is used to avoid cluttering the allowed node with JIDs of users who are invited to join, but do not accept the invitation. When a channel participant(the inviter) invites another user (the invitee) to join a channel, the following sequence of steps is followed:

1. The channel inviter sends to the channel requesting an invite for the invitee.
2. The channel sends an invitation to the inviter.
3. The inviter sends the invitation to the invitee.
4. The invitee MAY use the invitation to join the channel.
5. The invitee MAY send a response to the inviter, indicating if the invitation was accepted or declined.

The first step is for the inviter to request an invitation from the channel. The invitation contains inviter, invitee and a token. The channel will evaluate if the inviter has rights to issue the invitation. This will be because the inviter is a channel administrator or if the inviter is a channel participant and the channel has 'Participation Addition by Invitation from Participant' mode enable. If the inviter has rights to make the invitation, the channel will return a token. The token is a string that the channel can subsequently use to validate an invitation. The format of the token is not specified in this standard. The encoded token MAY reflect a validity time.

Example 51. Inviter Requests and Receives Invitation

<iq from='hag66@shakespeare.lit/pda'
    id='kl2fax27'
    to='coven@mix.shakespeare.lit'
    type='get'>
  <query xmlns='urn:xmpp:mix:0#request-invitation'/>
  <invitee>cat@shakespeare.lit</invitee>
</iq>


<iq from='coven@mix.shakespeare.lit'
    id='kl2fax27'
    to='hag66@shakespeare.lit/pda'
    type='result'>
  <query xmlns='urn:xmpp:mix:0#request-invitation'>
        <invitation>
           <inviter>hag66@shakespeare.lit</inviter>
           <invitee>cat@shakespeare.lit</invitee>
           <channel>coven@mix.shakespeare.lit</channel>
           <token>ABCDEF</token>
        </invitation>
</iq>

The inviter can now send the invitee a message containing the invitation, as shown in the following example.

Example 52. Inviter sends Invitation to Invitee

<message from='hag66@shakespeare.lit/pda'
    id='foo'
    to='cat@shakespeare.lit'>
    <body>Would you like to join the coven?<body>
    <invitation xmlns='urn:xmpp:mix:0'>
        <inviter>hag66@shakespeare.lit</inviter>
        <invitee>cat@shakespeare.lit</invitee>
        <channel>coven@mix.shakespeare.lit</channel>
        <token>ABCDEF</token>
   </invitation>
</iq>

The invitation can now be used by the invitee to join a channel. The invitation is simply added to the standard channel join, so that the channel can validate the invitation using the token. If the allowed node is present and the invitee is not matched against any item, the channel MUST add the invitee to the allowed node as part of the join.

Example 53. User Joins a Channel with an Invitation

<iq type='set'
    from='cat@shakespeare.example'
    to='coven@mix.shakespeare.example'
    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
  <join xmlns='urn:xmpp:mix:0'>
    <subscribe node='urn:xmpp:mix:nodes:messages'/>
    <invitation>
        <inviter>hag66@shakespeare.lit</inviter>
        <invitee>cat@shakespeare.lit</invitee>
        <channel>coven@mix.shakespeare.lit</channel>
        <token>ABCDEF</token>
   </invitation>
  </join>
</iq>

The invitee may send an acknowledgement back to the inviter, noting the status of the invitation. Values are:

• 'Joined': The invitee has joined the channel.
• 'Declined': The invitee is not taking up the invitation.
• 'Acknowledged': The invitation is acknowledged, without information on action taken or planned.

Example 54. Invitee sends Acknowledgement to Inviter

<message from='cat@shakespeare.lit/miaow'
    id='bar'
    to='hag66@shakespeare.lit/pda'>
    <body>No Thanks - too busy chasing mice....<body>
    <invitation-ack xmlns='urn:xmpp:mix:0'>
        <value>Declined</value>
        <invitation>
             <inviter>hag66@shakespeare.lit</inviter>
             <invitee>cat@shakespeare.lit</invitee>
              <channel>coven@mix.shakespeare.lit</channel>
              <token>ABCDEF</token>
         </invitation>
     </invitation-ack>
</iq>

5.1.18 Sending Private Messages

Private Messages are used to provide communication with another channel participant through the MIX channel, without the initiating user knowing the real JID of the channel participant. A channel MAY support use of Private Messages. Private messages are standard XMPP messages. A message goes through a number of stages with different addressing. This is set out in the following table.

Private Messages MAY be archived using MAM by the XMPP servers associated with initiator and responder. Private Messages MUST NOT be archived by the MIX channel.

5.1.19 Requesting vCard

A user may request the vCard of a channel participant by sending a request through the channel. The request may be sent directly by the client or through a MIX Proxy. The MIX channel MAY pass this request on or may block it. vCard requests MAY use vcard-temp (XEP-0054) [33] (vcard-temp) or vCard4 over XMPP (XEP-0292) [34] (vCard4 over XMPP). Where a MIX service supports one or both of these protocols, the protocol MUST be advertized as a feature of the MIX service. In the following example, using vcard-temp, the requesting client sends a message to the anonymized bare JID of the channel participant for which the vCard is desired.

Example 55. Client directly requests vCard through channel

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='coven+989898@mix.shakespeare.example'
    type='get'>
  <vCard xmlns='vcard-temp'/>
</iq>

The MIX channel MAY pass on the vCard request or may reject with an error, dependent on channel policy. The MIX service will then address the vCard request to the MIX proxy (bare JID) using an anonymous full proxy JID to hide the requester.

Example 56. Channel passes on vCard request to MIX Proxy

<iq from='coven+123456@mix.shakespeare.example/6789'
    id='lx09df27'
    to='peter@shakespeare.lit'
    type='get'>
  <vCard xmlns='vcard-temp'/>
</iq>

The MIX Proxy, on behalf of the user, MAY send a response or reject with an error. The MIX Proxy will send the vCard back to the channel.

Example 57. Service responds with Disco Info result

<iq from='peter@shakespeare.lit'
    id='lx09df27'
    to='coven+123456@mix.shakespeare.example/6789'
    type='result'>
    <vCard xmlns='vcard-temp'>
    <FN>Peter Saint-Andre</FN>
    <N>
      <FAMILY>Saint-Andre</FAMILY>
      <GIVEN>Peter</GIVEN>
      <MIDDLE/>
    </N>
    <NICKNAME>stpeter</NICKNAME>
    <URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
  </vCard>
  <query xmlns='http://jabber.org/protocol/disco#info'>
</iq>

The MIX channel will then send the vCard response to the requesting client on behalf of the client sending the response.

Example 58. Service responds with Disco Info result

<iq from='coven+989898@mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
 <vCard xmlns='vcard-temp'>
    <FN>Peter Saint-Andre</FN>
    <N>
      <FAMILY>Saint-Andre</FAMILY>
      <GIVEN>Peter</GIVEN>
      <MIDDLE/>
    </N>
    <NICKNAME>stpeter</NICKNAME>
    <URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
  </vCard>
</iq>

 <iq from='coven@mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example'
    type='get'>
  <marker xmlns='urn:xmpp:mix:0'/>
</iq>


<iq from='hag66@shakespeare.example'
    id='lx09df27'
    to='coven@mix.shakespeare.example'
    type='result'>
 <marker xmlns='urn:xmpp:mix:0'/>
</iq>

5.4.1 Archive of Messages

Messages sent to participants MUST be archived by both the MIX channel and by the user's server. This MUST include messages setting subject and MAY include presence messages. Correct MIX operation relies on messages being archived.

5.4.2 Retrieving Messages

Clients will retrieve MIX messages using standard MAM protocol from the user's archive. The MAM query will filter based on the channel JID to enable access to messages from a given channel. This gives the user a simple mechanism to access all messages sent to the channel. MAM can be used to retrieve older messages that have not been cached by the client.

Messages may also be retrieved from the channel by addressing MAM queries to the channel JID. This will behave like a standard MAM archive. This can be useful for administrators to access archived messages. It can also be useful for new channel participants to access the historical archives.

5.4.3 MAM Use with other Channel Nodes

A MIX Channel MAY use MAM to archive nodes other than message nodes. Clients with rights to access these archives may use MAM to do this, specifying the PubSub node in the MAM query addressed to the channel.

5.5.1 Checking For Permission To Create a Channel

MIX does not standardize an access control model for creating and deleting MIX channels. The choice is left to the MIX implementer, and could be a very simple or complex approach. A client can determine if it has permission to create a channel on a MIX service, which may be used to control options presented to the user. This is achieved by a disco command on the MIX service. If the 'create-channel' feature is returned, the user is able to create a channel.

Example 60. Client determines Capability to Create a Channel

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='Shakespearean Chat Service'
        type='text'/>
    <feature var='urn:xmpp:mix:0'/>
    <feature var='create-channel' xmlns='urn:xmpp:mix:0'>
  </query>
</iq>

5.5.2 Creating a Channel

A client creates a channel by sending a simple request to the MIX service. A channel may be created with default parameters, as shown in the following example. The result MUST include the name of the channel which MUST match the channel name in the request (if present).

Example 61. Creating a Channel with Default Parameters

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
  <create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>

The client may also include parameters in Data Forms (XEP-0004) [37] format as part of channel creation. If the client wishes to inspect configuration, channel administration procedures should be used.

Example 62. Creating a Channel with Client Specified Parameters

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
  <create channel='coven' xmlns='urn:xmpp:mix:0'>
     <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Owner'>
            <value>hecate@shakespeare.lit</value>
        </field>
        <field var='Owner'>
            <value>greymalkin@shakespeare.lit</value>
        </field>
        <field var='Message Node Subscription'>
           <value>allowed</value>
         </field>
        <field var='JID Visibility'>
           <value>jid-mandatory-visible</value>
         </field>
         <field var='No Private Messages'>
            <value>true</value>
         </field>
         </x>
  </create>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>

5.5.3 Creating a Channel for Ad Hoc Use

Rooms may be created for ad hoc use between a set of users. Channels of this nature will have channel name created by the server and will not be addressable or discoverable. Here a channel is created without specifying the channel name. Parameters for the channel may also be specified.

Example 63. Creating a Channel for Ad Hoc Use

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
  <create xmlns='urn:xmpp:mix:0'/>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <create channel='A1B2C345' xmlns='urn:xmpp:mix:0'/>
</iq>

5.5.4 Converting a 1:1 Conversation to a Channel

A common use case for an ad hoc channel is where two users are engaged in a 1:1 chat and wish to broaden the discussion. Prior to bringing more users into a channel, using standard invitation process, there is a need to move a dialogue. The first step is for one of the two users to create an ad hoc channel, as described in the previous section. The other user will then be invited, and can switch to the new channel.

It may also be useful to share some or all of the messages from the 1:1 discussion into the new channel. The mechanism to do this is to forward messages to be shared in the MUC using Stanza Forwarding (XEP-0297) [38]. A body SHOULD not be used in the outer message// This will generally be done by the user creating the channel before the other user is invited, but may be sent by either the user creating the channel or the 1:1 chat partner at any time subsequently.

Example 64. Forwarding a message to create History

<message from='hag66@shakespeare.example/pda'
         to='A1B2C345@mix.shakespeare.example'
         id='92vax143g'
         type='groupchat'>
         <forwarded xmlns='urn:xmpp:forward:0'>
          <delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
          <message from='hag67@shakespeare.example/pda'
                   id='0202197'
                   to='hag66@shakespeare.example/pda'
                   type='chat'
                   xmlns='jabber:client'>
              <body>Harpier cries: 'tis time, 'tis time.</body>
          </message>
        </forwarded>
</message>

5.5.5 Destroying a Channel

MIX channels are always explicitly destroyed by an owner of the channel or by a server operator. There is no concept of temporary channel, equivalent to Multi-User Chat (XEP-0045) [39] temporary room which is automatically destroyed by the server when the users leave. However, channels MAY be configured with an explicit lifetime, after which the channel MUST be removed by the MIX service. Where a channel is created for ad hoc use, it may be desirable to keep the channel for history reference or for re-use by the same set of users. Note that the owner of the channel does not need to have presence registered in the channel in order to destroy it.

A client destroys a channel using a simple set operation, as shown in the following example.

Example 65. Client Destroys a Channel

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
  <destroy channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
</iq>

5.5.6 Server Destroying a Channel

A server MUST destroy a channel that has exceeded its specified explicit lifetime. Servers may destroy channels which have no participants and/or presence according to local policy. There will often be good reasons to not destroy rooms in these scenarios, in particular to facilitate channel re-use and history access.

5.5.7 Modifying Channel Information

Authorized users, typically owners and sometimes administrators, may modify the channel information. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the information node. The values in the form show current values, which be defaults or may have been explicitly set. In the following example, the channel name was previously set, but other values were not.

Example 66. Getting Information Form

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
     <pubsub xmlns='http://jabber.org/protocol/'>
         <items node='urn:xmpp:mix:nodes:info'/>
     </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/'>
     <items node='urn:xmpp:mix:nodes:info'>
       <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <title>Information Node Modification</title>
        <field type='text-multi'
               label='Channel Name'
               var='Name'>
            <value>Witches Coven</value>
        </field>
        <field type='text-multi'
               label='Channel Description'
               var='Description'/>
         <field type=jid-single'
                label='Channel Administrative Contact'
                var='Contact'/>
      </x>
    </items>
  </pubsub>
</iq>

Updating the information node is done using a pubsub set command. The MIX channel MUST update the fields with values provided, leaving other fields unchanged. The result returns the id used in the information node item, which is the date/time of the modification.

Example 67. Modifying Channel Information

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
     <publish node='urn:xmpp:mix:nodes:info'>
       <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Name'>
            <value>Witches Coven</value>
        </field>
        <field var='Description'>
           <value>A location not far from the blasted heath where the three witches meet</value>
         </field>
         <field var='Contact'>
           <value>greymalkin@shakespeare.lit</value>
         </field>
      </x>
     </publish>
  </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:info'>
        <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'/>
       </publish>
   </pubsub>
</iq>

5.5.8 Modifying Channel Configuration

Channel owners may modify the channel configuration. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the configuration node. Other clients MAY be authorized to use this command to see the channel configuration, but only owners may update the configuration. The values in the form show current values, which be defaults or may have been explicitly set. The following example shows a short form returned to illustrate the syntax. A typical configuration form will be much larger with many fields.

Example 68. Getting Configuration Form

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <items node='urn:xmpp:mix:nodes:config'/>
     </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
     <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <items xmlns='urn:xmpp:mix:0'  node='urn:xmpp:mix:nodes:config'>
       <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <title>Configuration Node Modification</title>
         <field type=jid-multi'
                label='Channel Administrator'
                var='Administrator'/>
      </x>
     </items>
   </pubsub>
</iq>

Updating the information node is done using a pubsub set command. The MIX channel MUST update the fields with values provided, leaving other fields unchanged. The result returns the id used in the configuration node item, which is the date/time of the modification.

Example 69. Modifying Channel Configuration

 <iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:config'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:0</value>
        </field>
        <field var='Owner'>
            <value>hecate@shakespeare.lit</value>
        </field>
        <field var='Owner'>
            <value>greymalkin@shakespeare.lit</value>
        </field>
        <field var='Message Node Subscription'>
           <value>allowed</value>
         </field>
        <field var='JID Visibility'>
           <value>jid-mandatory-visible</value>
         </field>
         <field var='No Private Messages'>
            <value>true</value>
         </field>
      </x>
     </publish>
   </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:config'>
        <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'/>
       </publish>
   </pubsub>
</iq>

5.5.9 Controlling Channel Partipcipants

Owners and Administrators may control which users can participate in a channel by use of Allowed and Banned lists using PubSub. These operations follow Publish-Subscribe (XEP-0060) [40] which sets out detailed protocol use and error handling. Allowed and Banned lists may be read by PubSub get of the Banned and Allowed Nodes. This operation may be used by users as controlled by 'Allowed Node Subscription' and 'Banned Node Subscription' configuration node options (default Administrators).

Example 70. Client Reads Allowed Node

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
         <items node='urn:xmpp:mix:nodes:allowed'/>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
         <items node='urn:xmpp:mix:nodes:allowed'>
            <item id='@shakespeare.lit'/>
            <item id='alice@wonderland.lit'/>
         </items>
    </pubsub>
</iq>

JIDs can be added to the Allowed and Banned nodes by a pubsub set command. This is used to add one item to a node.

Example 71. Client Adds a JID to the Allowed Node

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <publish node='urn:xmpp:mix:nodes:allowed'>
            <item id='@marlow.lit'/>
         </items>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>

JIDs can be removed from the Allowed and Banned nodes by pubsub retract command.

Example 72. Client Removes a JID to the Banned Node

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <retract node='urn:xmpp:mix:nodes:banned'>
            <item id='lear@shakespeare.lit'/>
         </items>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>

When the MIX channel adds a JID to the banned node, other nodes in the MIX channel will be appropriately updated to reflect this change. In particular, the participants nodes and presence nodes will be updated to remove matching JIDs. This will have the effect of immediately removing the user from the channel. For this reason, there is no requirement to have the "kick" functionality of MUC, as this is achieved by banning the user.

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    type='set'>
  <activate xmlns='urn:xmpp:mix:0'>
      <channel>coven@mix.shakespeare.lit</channel>
      <channel>spells@mix.shakespeare.lit</channel>
  </activate>
</iq>

<iq from='shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <activate xmlns='urn:xmpp:mix:0'/>
</iq>

<iq from='hag66@shakespeare.example/intibo24'
    id='lx09df27'
    type='set'>
  <deactivate xmlns='urn:xmpp:mix:0'/>
</iq>

<iq from='shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/intibo24'
    type='result'>
  <deactivate xmlns='urn:xmpp:mix:0'/>
</iq>

Add node='mix' to channel disco to facilitate MIX and MUC co-existence on same node; Return Proxy JID on Join; Adjustment to message reflection

Add Update and Distribution to Table 3; Correct from in messages from channel; Use XEP-0297 in message forwarding; Update Dependent XEPs

Editorial Changes (Georg Lukas Review); Improve 1:1 Conversion; Sort out MIX Proxy and Presence Update

Clarify Direct PubSub access to each node type.

Added Internationalization Consideration section, and various I18n edits; Added Security Considerations section; Tombstoning of Redaction changes made optional; Added a section specifying MIX Proxy; Change configuration and information node management to directly use PubSub; Provide for XEP-0202 (vCard4 over XMPP) in addition to vcard-temp support.

Complete and restructure Administration Section: Creating Channels and modifying configuration; Add avatar nodes; Add section on roster handling; Discovering MIX Services; Resolve questions on future capabilities; Administration of Allowed/Banned; clarify Kick functionality is replaced; User Presence Probes on Channel Start-up; Add user Presence preference; Clarify and Expand MAM Archiving; Sort Retraction; Add Marker IQ; Conversion 1:1

Clarification of MIX Proxy concept; Clarify node definitions; Make all nodes optional; Merge ACL node into configuration node; Add information node including avatar; Resolve 4.1 question by accepting provisional answer; Add discovery examples; setting and sharing Subject; Protocol to request channel information and participants; vCard Request; Private Messages; Set user preferences with XEP-0004; Remove references to member and occupant; Add Role Definition; Add Banned and Allowed Nodes; Update Configuration Definition;Add information on original id to message reflected back to sender Add XEP-0372 mechanism to reference channel and informal invite; Channel Invitations

Introduce MIX Proxy concept. Add MIX capability in client discovery.

Addressing comments from review of 0.2 and expansion/clarification of MUC/MIX dual working

Cleanup, use precis nickname for nicknames, and allow multiple subject languages.

Phrasing and grammar.

Includes Link Mauve (Emmanuel Gil PEYROT) editorial changes

Significant update based on XMPP Summit discussions

Fix XML in join example.

Initial published version approved by the XMPP Council.

First draft.