XMPP For The Web/Win ::: XMPP-FTW (1.18.0) Flattr this

XEP-0045 Multi-user Chat (MUC)

Join a room

        socket.send(
            'xmpp.muc.join',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "nick": "MyNickname",
             /* "history": {
                  "maxchars": "65550",
                  "since": "2014-04-03T22:18:00.000Z",
                  "maxstanzas": "15",
                  "seconds": "3600"
                },
                "password": "tellnoone" */
            }
        )
        

Retrieve reserved nickname

A user may have a reserved nickname for a specific MUC room. In order to retrieve this we make a discovery request to the room.

        socket.send(
            'xmpp.muc.room.nick',
            {
                "room": "test@conference.evilprofessor.co.uk"
            },
            function(error, data) { console.log(error, data) }
        )
        

If the user has a reserved nickname then the response will be as follows:

        {
            nick: 'evilprofessor'
        }
        

Should the user not have a reserved nickname then an error response of item-not-found will be returned.

Receive room roster

        socket.on('xmpp.muc.roster', function(data) { console.log(data) })
        

Example: You may receive many of these messages

          {
              room: 'test@conference.evilprofessor.co.uk',
              nick: 'TheirNickname',
           /* affiliation: 'member', */
           /* role: 'member', */
           /* status: [] *
          }
        

'Affilition' and 'role' tend to be sent on affiliation or role changes. A nickname change will have a status code of 303.

Receive a message

        socket.on('xmpp.muc.message', function(data) { console.log(data) })
        

Example:

          {
              room: 'test@conference.evilprofessor.co.uk',
              nick: 'TheirNickname',
              content: '<p>Hello <b>world</b>!</p>',
              format: 'xhtml',
           /* delay: { when: '2012-03-03T20:22:00Z' }, */
           /* private: false, */
           /* state: 'composing' */
          }
        

For plain text IMs the 'format' attribute will be plain, for XEP-0071 messages it will be xhtml. You will only ever receive a plain or XHTML message, not both.

It is also possible to receive just a chat state notification where only the 'state' property will be included.

Send a message

        socket.send(
            'xmpp.muc.message',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "content": "Hello XMPP people!",
             /* "format": "plain" */
             /* "to": "TheirNickname", */
             /* "state": "composing" */
            }
        )
        

If 'to' is provided then message becomes a private message.

If a user wishes to send a formatted message (i.e. XEP-0071) then the value of 'format' will be xhtml. XMPP-FTW will generate a plain text version of an XHTML message for sending.

It is possible to send chat state notifications by just sending the 'state' property.

Leave a room

        socket.send(
            'xmpp.muc.leave',
            {
                "room": "test@conference.evilprofessor.co.uk"
             /* "reason": "Heading off for lunch..." */
            }
        )
        

Errors

Message Errors

        socket.on('xmpp.muc.error', function(data) { console.log(data) })
        

Example:

          {
              type:  'message',
              error : {
                  type: 'service-unavailable',
                  condition: 'wait'
              },
              room:  'test@conference.evilprofessor.co.uk',
           /* content: 'Original message content' */
          }
        

Code will attempt to grab the extended reason from the 'xmpp-stanzas' namespaced element, otherwise it will grab the 'type' attribute from the error tag.

Room subject

The room subject can be updated as follows:

        socket.send(
            'xmpp.muc.subject',
            {
             /* "subject": "XMPP-FTW Chat room" */
            }
        }
        

By not providing the 'subject' the room subject will be disabled.

Updates to room subject will be recieved as follows:

        socket.on('xmpp.muc.subject', function(data) { console.log(data) })
        

Where the data format is as follows:

        {
            room: "test@conference.evilprofessor.co.uk",
            subject: "XMPP-FTW Chat room",
        }
        

A value of false for the subject key signifies that the room subject has been disabled.

Retrieve a list of users with specified role

        socket.send(
            'xmpp.muc.role.get', 
            {   
                "room": "xmpp@muc.evilprofessor.co.uk",
                "role": "participant"
            }, 
            function(error, data) { console.log(error, data) }
        )
        

Response will look as follows:

        [
            {
                affiliation: 'member',
                jid: {
                    user: 'megan',
                    domain: 'evilprofessor.co.uk',
                    resource: 'home'
                },
                nick: 'livelifevegan',
                role: 'participant'
            }
        ]
        

Change a user's role

        socket.send(
            'xmpp.muc.role.set', 
            {
                "room": "test@conference.evilprofessor.co.uk",
                "nick": "TheirNickname",
                "role": "participant",
             /* "reason": "Trusted friend" */
            },
            function(error, data) { console.log(error, data) }
        )
        

`data` will be true and error null if all is ok.

Change a user's affiliation

        socket.send(
            'xmpp.muc.role',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "jid": "user@evilprofessor.co.uk",
                "affiliation": "outcast"
            }
            function(error, data) { console.log(error, data) }
        )
        

Register with a room

Get registration information

        socket.send(
            'xmpp.muc.register.info',
            {
                "room": "test@conference.evilprofessor.co.uk"
            },
            function(error, data) { console.log(error, data) }
        )
        

Example:

        {
            'instructions': 'Reply with the following form',
            'form': {
                title: 'Register with the dev room!',
                instructions: 'Please fill out all required fields',
                fields: [
                    {
                        type: 'hidden',
                        value: '',
                        var: 'muc#register_email',
                        required: true,
                     /* label: 'Email address' */
                    }
                ] 
            }
        }
        

If the user is already registerd then the response will look as follows:

        {
            registered: true,
            nick: 'lloydwatkin'
        }
        

Perform registration

        socket.send(
            'xmpp.muc.register',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "form": [ ]
            },
            function(error, data) { console.log(error, data) }
        )
        

Room Invites

Mediated Invitation

        socket.send(
            'xmpp.muc.invite',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "to": "megan@evilprofessor.co.uk",
             /* "reason": "Come join us for some cool chat!" */
            }
        )
        

Direct Invitation

XEP-0249 not currently supported but coming soon, https://github.com/xmpp-ftw/xmpp-ftw-muc/issues/38.

Incoming invites

        socket.on('xmpp.muc.invite', function(data) { 
            console.log(data)
            /* {
                   room: "test@conference.evilprofessor.co.uk",
                   from: { domain: "evilprofessor.co.uk", user: "lloyd" },
                /* reason: "Come join us for some cool chat!", */
                /* password: "donttellanyone" */
               } */
        })
        

Decline invitation

        socket.send(
            'xmpp.muc.invite.decline',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "to": "lloyd@evilprofessor.co.uk",
                /* "reason": "I'm busy right now..." */
            }
        )
        

Incoming invitation decline

        socket.on('xmpp.muc.invite.decline', function(data) { 
            console.log(data)
            /* {
                   room: "test@conference.evilprofessor.co.uk",
                   from: { domain: "evilprofessor.co.uk", user: "megan" },
                /* reason: "I'm busy right now...", */

               } */
        })
        

Update room configuration

Get room configuration

        socket.send(
            'xmpp.muc.room.config.get',
            { "room": "test@conference.evilprofessor.co.uk" },
            function(error, data) { console.log(error, data) }
        )
        

Response (can) look like this:

        {
            title: "Configuration for test@conference.evilprofessor.co.uk",
            instructions: "Configuration for test@conference.evilprofessor.co.uk",
            fields: [
                { var: "muc#roomconfig_roomname", type: "text-single", required: false, value: "test2", label: "Name" },
                { var: "muc#roomconfig_persistentroom", type: "boolean", required: false, value: false, label: "Make Room Persistent?" },
                { var: "muc#roomconfig_roomsecret", type: "text-private", required: false, value: "", label: "Password" },
                { 
                  var:      "muc#roomconfig_whois",
                  type:     "list-single",
                  required: false,
                  value:    "moderators,
                  label:    "Who May Discover Real JIDs?",
                  options:  [{ label: "Moderators", value: "moderators" }, { label: "Anyone", value: "anyone" }]
                },
            ],
        }
        

Making a request on a room which doesn't already exist creates a reserved room. In order to cancel this request see cancel request.

Set room configuration

        socket.send(
            'xmpp.muc.room.config.set',
            { "room": "test@conference.evilprofessor.co.uk", "form": [ ] },
            function(error, data) { console.log(error, data) }
        )
        

Form data example:

        {
            room: 'test@conference.evilprofessor.co.uk',
            form: [
                { field: 'muc#roomconfig_membersonly', value: true },
                { field: 'muc#roomconfig_roomname', value: 'Cool XMPP-FTW configured room' },
                { field: 'muc#roomconfig_roomsecret', value: 'abracadabra' }
            ]
        }
        

Updates to room configuration

        socket.on('xmpp.muc.room.config', function(data) { console.log(data) })
        

Example confguration updates:

        {
            room: test@conference.evilprofessor.co.uk',
            status: [ 100, 110, 104 ]
        }
        

Request voice

In order to request the ability to speak in a moderated room the user must request a voice. This is done as follows:

        socket.send(
            'xmpp.muc.voice',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "role": "participant"
            }
        )
        

Create a room

        socket.send(
            'xmpp.muc.create',
            {
                "room": "test@conference.evilprofessor.co.uk",
                "nick": "megan",
             /* "instant": true */
            }
        )
        

On success you will receive an 'xmpp.muc.roster' event with a status of 201 for your own JID informing you that the room has been created. The room will be locked so you can then set configuration.

Any errors will be delivered via 'xmpp.muc.error' event.

Delete a room

        socket.send(
            'xmpp.muc.destroy',
            {
                "room": "test@conference.evilprofessor.co.uk",
             /* "reason": "Was just a test room" */
            },
            function(error, data) { console.log(error, data) }
        )
        

On success data will simply be true.

Clients will be informed of a room destroy via the incoming `xmpp.muc.destroy` event as follows:

        socket.on('xmpp.muc.destroy', function(data) {
            console.log(data)
            /* {
                 room: "test@conference.evilprofessor.co.uk",
              /* reason: "Killed test room" */
              /* alternative: "test2@conference.evilprofessor.co.uk" */
               } */
        })
        

Cancel Request

Cancel a request to update room configuration, or to create a reserved room using xmpp.muc.cancel:

        socket.send(
            'xmpp.muc.cancel',
            {
                "room": "test@conference.evilprofessor.co.uk"
            },
            function(error, data) { console.log(error, data) }
        )
        

On success data will simply be true.

Pages

Fork me on GitHub