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

XMPP Core

Authentication

Login

        socket.send(
             'xmpp.login',
             {
                 "jid": "test@evilprofessor.co.uk",
                 "password": "password",
              /* "resource": "xmpp-ftw", */
              /* "host": "127.0.0.1" */
             }
        )
        

You can also add an optional parameter of resource, if not provided the XMPP server will add this automatically.

On succesful connection an incoming message comes in as follows:

        socket.on('xmpp.connection', function(data) {
            console.log(data)
            /* {
             *   status: 'online',
             *   jid: {
             *     domain: 'evilprofessor.co.uk',
             *     user: 'lloyd',
             *     resource: 'desktop'
             *   }
             * }
             */
        })
        

A failed login will be reported via the xmpp.error event as follows:

        {
            type: "auth",
            condition: "login-fail",
            description: "XMPP authentication fail"
        }
        

Anonymous Login

        socket.send(
            'xmpp.login.anonymous',
            {
                "jid": "anon.evilprofessor.co.uk",
             /* "host": "evilprofessor.co.uk" */
            }
        )
        

Logout

Logout is performed with the following call:

        socket.send(
            'xmpp.logout',
            {},
            function(error, data) { console.log(error, data) }
        )
        

If no callback is provided then the socket will be terminated.

Messaging

Send a message

        socket.send(
            'xmpp.chat.message',
            {
                "to": "other@evilprofessor.co.uk",
                "content": "Hello world",
             /* "format": "plain", */
             /* "state": "composing" */
            },
            function(error, data) { console.log(error, data) }
        )
        

The callback here is entirely optional apart from under certain circumstances (for example when using message delivery receipts. If provided then the value of `data` will be an object containing the ID of the outgoing message stanza, e.g.:

        { "id": "1230" }
        

By setting the value of 'format' to 'xhtml' the client can invoke XEP-0071 a missing or not-'xhtml' value results in a plain message. A plain text version of XHTML messages are generated by XMPP-FTW and sent alongside XHTML messages.

It is also possible to send just a chat state notification by adding the 'state' key or by sending the 'state' key by itself.

Receive a chat message

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

Example:

        {
            from: {
                domain: 'evilprofessor.co.uk',
                user: 'megan'
            },
            content: 'Hello fine Lady!',
            format: 'plain',
         /* delay: {
                from: 'evilprofessor.co.uk',
                when: '2013-06-03T19:56Z',
                reason: 'Offline storage'
            }, */
         /* state: 'active' */
         /* archived: [
              { by: { domain: 'evilprofessor.co.uk' }, id: 'archive:1' }
            ] */
        }
        

The value of 'format' will be xhtml for XEP-0071 type messages. You will only ever receive a plain text or XHTML message, not both. 'state' represents a chat state notification.

The archived key can only be present if your server supports and is using XEP-313 (MAM).

Alternatively a chat state notification may be received as follows:

        {
            state: 'active'
        }
        

Message delivery receipts

It is possible to request a message delivery receipt using XMPP-FTW. In order to do this a message must be sent using a callback (in order to determine the outgoing message's ID), and the outgoing payload should also include a key of `receipt` who's value should be true.

        {
            "to": "megan@evilprofessor.co.uk/laptop",
            "content": "Are you reading this?",
            "receipt": true
        }
        

Incoming chat messages will then also include the `receipt` key with a value of true.

Sending a message delivery receipt

A message delivery receipt can be sent by using the `xmpp.chat.receipt` event as follows:

        socket.send(
            'xmpp.chat.receipt',
            {
                "to": "other@evilprofessor.co.uk/laptop",
                "id": "message-number-5"
            }
        )
        

Receiving a message delivery receipt

Message delivery receipts are received via the `xmpp.chat.receipt` event:

        socket.on('xmpp.chat.receipt', function(data) {
            console.log(data);
            /*
             * {
             *   from: { domain: 'evilprofessor.co.uk', user: 'lloyd', resource: 'laptop' },
             *   id: 'message-number-5'
             * }
             */
        }
        

Last message correction

To send a last message correction simply include a `replace` key in your JSON payload with the ID of the message you would like to correct.

        {
            "to": "megan@evilprofessor.co.uk/mobile",
            "content": "Will be home at 11pm",
            "replace": "last-message-id"
        }
        

Incoming message corrections will also include a `replace` key informing your client which message is being corrected.

Presence

Set presence

        socket.send(
            'xmpp.presence',
            {
                "show": "online",
                "status": "I'm using xmpp-ftw!",
                "priority": 10,
             /* "to": "megan@evilprofessor.co.uk/mobile" */
            }
        )
        

Each of the parameters for presence are optional. You can include entity capabilities by adding a key of `client` as follows:

        client: {
            hash: 'sha-1',
            ver: 'QgafEg5pkPSDYmwT/WFggBguAlu0+',
            node: 'http://xmpp-ftw.jit.su/chat-client'
        }
        

Receive presence

        socket.on('xmpp.presence', function(data) {
            console.log(data);
            /*
             * {
             *   from: { domain: 'evilprofessor.co.uk', user: 'lloyd'},
             *   show: 'away',
             *   status: "I'm going away",
             *   priority: 10
             * }
             * ...each of these are optional...
             */
        })
        

Again entity capabilities can be received on a `client` key as with the example abolve.

Directed presence

        socket.send('xmpp.presence.get', { "to": "user@evilprofessor.co.uk" })
        

Go offline

        socket.send('xmpp.presence.offline' /*, {} */ )
        

Subscribe

Request to subscribe to a user

        socket.send('xmpp.presence.subscribe', { "to": "user@evilprofessor.co.uk" })
        

User requests to subscribe to your presence

        socket.on('xmpp.presence.subscribe', function(data) {
            console.log(data)
        })
        

Example:

        {
            from: { user: 'user', domain: 'evilprofessor.co.uk' },
            nick: 'Example user' // ...optional...
        }
        

Respond with subscribed or unsubscribed

        socket.send(
            'xmpp.presence.subscribed',
            {
                "to": "user@evilprofessor.co.uk"
            }
        )
        
        socket.send(
            'xmpp.presence.unsubscribed',
            {
                "to": "user@evilprofessor.co.uk"
            }
        )
        

Unsubscribing from another entity's presence

        socket.send(
            'xmpp.presence.unsubscribe',
            {
                "to": "user@evilprofessor.co.uk"
            }
        )
        

Presence Errors

Presence errors are emitting using the 'xmpp.presence.error' event name, for example:

        {
            error: "remote-server-not-found",
         /* from: {
                user: "user",
                domain: "niceprofessor.co.uk"
            } */
        }
        

Roster

Add user to roster

        socket.send(
            'xmpp.roster.add',
            {
                "jid": "user@evilprofessor.co.uk",
             /* "name": "Example user", */
             /* "groups": [ "example-users" ] */
            },
            function(error, data) { console.log(error, data) }
        )
        

Remove a user from roster

        socket.send(
            'xmpp.roster.remove',
            {
                "jid": "user@evilprofessor.co.uk"
            },
            function(error, data) { console.log(error, data) }
        )
        

Get

        socket.send(
            'xmpp.roster.get',
            {},
            function(error, data) { console.log(error, data) }
        )
        

Data returns as array of objects, e.g.

          [ {
               jid: { user: 'user', domain: 'evilprofessor.co.uk' },
               subscription: 'both',
               name: 'Example user',
               groups: [ 'Buddies', 'XMPP' ]
            /* ask = 'subscribe' */
          } ]
        

New incoming Roster request

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

Example:

          {
               jid: { user: 'user', domain: 'evilprofessor.co.uk' },
               subscription: 'both',
               name: 'Example user',
               groups: [ 'Buddies' ],
            /* ask = 'subscribe' */
          }
        

Edit a user

Note: Existing groups will be erased, therefore you must include all roster groups in this list. Existing name will be erased too if not provided.

        socket.send(
            'xmpp.roster.edit',
            {
                "jid": "user@evilprofessor.co.uk",
                "groups": [ "buddies", "colleagues" ],
             /* "name": "Evil User" */
            },
            function(error, data) { console.log(error, data) }
        )
        

On success `data` will simply be true.