Skip to content

# Getting started with MIX

MIX stands for Mediated Information eXchange and defined in MIX-CORE (XEP-0369), MIX-PRESENCE (XEP-0403) and MIX-PAM (XEP-0405). More concretely, ejabberd supports MIX 0.14.1.

It is a work in progress extension for the XMPP protocol to build a group messaging protocol that does not rely on the presence mechanism. It is designed to overcome the limitation of Multi-User Chat (XEP-0045) , in a context where most clients are mobile clients.

To do so, MIX is built on top of PubSub (XEP-0060) and use different nodes per channel to separate event types. There is five nodes to support five different types of event for each MIX channel:

- Messages
- Presence
- Participant list changes
- Subject update
- Conversion configuration changes

This is a work in progress, but this is a very important task and we are happy to provide the very first server implementation of the Mix protocol to get up to speed on that specification.

Here is a short walk through what can already be done.

Also note that the specification can (and will) change significantly before it becomes stable. These examples are based on XEP-0369 v0.1.

## Configuration

Configuration is simple:

- Install a recent ejabberd version (19.02 or newer)

- You need to add mod_mix and mod_mix_pam in ejabberd configuration, modules section:

      modules:
        mod_mix: {}
        mod_mix_pam: {}

- Make sure you have PubSub enabled. Default configuration is fine:

      modules:
        mod_pubsub:
          access_createnode: pubsub_createnode
          plugins:
            - "flat"
            - "pep"

- The examples assume you have this virtual host:

      hosts:
        - shakespeare.example

## Usage

There is no client supporting MIX yet so here is how it works directly at XMPP stream level.

Here are real-life examples from playing with our MIX implementation:

### Creating a MIX Channel

First of all, create a new MIX channel following 7.3.2 Creating a Channel:

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

### Joining a MIX Channel

Now tell your server that you want your account to join that MIX channel, using MIX-PAM: 2.7 Joining a Channel:

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

You receive IQ that confirms success:

    <iq type="result"
        from="hag66@shakespeare.example"
        to="hag66@shakespeare.example/MacBook-Pro-de-Mickael"
        id="E6E10350-76CF-40C6-B91B-1EA08C332FC7">
      <client-join xmlns='urn:xmpp:mix:pam:0'>
        <join xmlns="urn:xmpp:mix:core:0"
              jid='d79d011852b97adfaad6#coven@mix.shakespeare.example'>
          <nick>third witch</nick>
          <subscribe node="urn:xmpp:mix:nodes:messages"></subscribe>
          <subscribe node="urn:xmpp:mix:nodes:presence"></subscribe>
          <subscribe node="urn:xmpp:mix:nodes:participants"></subscribe>
          <subscribe node="urn:xmpp:mix:nodes:subject"></subscribe>
          <subscribe node="urn:xmpp:mix:nodes:config"></subscribe>
       </join>
      </client-join>
    </iq>

Subscribers on the participants node for that channel will also receive the new list of participants (so, including ourselves in that case):

    <message from="coven@mix.shakespeare.example"
             type="headline"
             to="hag66@shakespeare.example/MacBook-Pro-de-Mickael">
     <event xmlns="http://jabber.org/protocol/pubsub#event">
      <items node="urn:xmpp:mix:nodes:participants">
       <item id="3d1766e2bd1b02167104f350f84b0668f850ef92">
        <participant xmlns="urn:xmpp:mix:core:0" jid="hag66@shakespeare.example"></participant>
       </item>
      </items>
     </event>
    </message>

### Setting a nick

You may want to set a nick for this channel (see 7.1.4 Setting a Nick):

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

Note: Support for MIX nickname registration is not implemented in ejabberd.

### Sending and receiving messages

You can now start chatting with your peers, by publishing on the message node (see 7.1.6 Sending a Message):

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

The message is received by all subscribers on the message node on that MIX channel:

    <message
     to='hag77@shakespeare.example'
     from='coven@mix.shakespeare.example/19be8c262ed618e078b7'
     type='groupchat'
     id='1625493702877370'>
      <mix xmlns='urn:xmpp:mix:core:0'>
        <nick>thirdwitch</nick>
        <jid>hag66@shakespeare.example</jid>
      </mix>
      <body>Harpier cries: &apos;tis time, &apos;tis time.</body>
    </message>

### Querying participants list

A participant can always get list of participants with a PubSub query on node items for the channel (see 6.6 Determining the Participants in a Channel):

    <iq type='get'
        to='coven@mix.shakespeare.example'
        id='mix4'>
      <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <items node='urn:xmpp:mix:nodes:participants'></items>
      </pubsub>
    </iq>

The channel will reply with list of participants:

    <iq to='hag66@shakespeare.example/tka1'
        from='coven@mix.shakespeare.example'
        type='result'
        id='kl2fax27'>
      <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <items node='urn:xmpp:mix:nodes:participants'>
          <item id='19be8c262ed618e078b7'>
            <participant nick='thirdwitch'
     jid='hag66@shakespeare.example'
     xmlns='urn:xmpp:mix:core:0'/>
          </item>
          <item id='6be2b26cbf4d7108f1fb'>
            <participant jid='hag77@shakespeare.example'
     xmlns='urn:xmpp:mix:core:0'/>
          </item>
        </items>
      </pubsub>
    </iq>

## Caveats

At the moment it is unclear from XEP-0369 example how you match a message you receive to a participant. We are going to improve our implementation in the following way:

1. Add a participant id on the item tag when broadcasting new participant.
2. Add the participant id on the published items.
3. Add the participant id in participants list on the publisher

Another issue is that the current specification and implementation will have trouble scaling and offer plenty of opportunities for "Denial of Service" attacks. This is something that will change in the future as the specification matures. However, currently, do not deploy or rely on this implementation for large-scale production services. The work is still an experiment to progress on the specifications by offering client developers to give real life feedback on a reference implementation of the current specification.

## Conclusion

We are only at the beginning of MIX. However, we are excited to have reached a point where it is already usable in some cases.

It is still missing on administrative tasks, right management, user invitations, relationship with MAM archiving and probably a lot more. And we need consolidations on participants message attribution. However, we want to iterate fast with client developers to prototype implementation changes and have meaningful and real life feedback to improve XEP-0359.

Send us your feedback !