add

Registers a new plugin.

var plugin = {
    initialize: function () {
        // method on any plugin (if it exists) as soon as the plugin has
        // been loaded.

        // Inside this method, you have access to the closured
        // _converse object, which contains the core logic and data
        // structures of converse.js
    }
}
converse.plugins.add('myplugin', plugin);

remove

Removes a plugin from the registry.

converse.plugins.remove('myplugin');

query

The query method is used to query for archived messages.

It accepts the following optional parameters:

• options an object containing the query parameters. Valid query parameters are with, start, end, first, last, after, before, index and count.
• callback is the callback method that will be called when all the messages have been received.
• errback is the callback method to be called when an error is returned by the XMPP server, for example when it doesn’t support message archiving.

converse.plugins.add('myplugin', {
    initialize: function () {

        var errback = function (iq) {
            // The query was not successful, perhaps inform the user?
            // The IQ stanza returned by the XMPP server is passed in, so that you
            // may inspect it and determine what the problem was.
        }
        var callback = function (messages) {
            // Do something with the messages, like showing them in your webpage.
        }
        this._converse.api.archive.query(callback, errback))

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        _converse.api.listen.on('serviceDiscovered', function (feature) {
            if (feature.get('var') === converse.env.Strophe.NS.MAM) {
                _converse.api.archive.query()
            }
        });

converse.listen.on('serviceDiscovered', function (feature) {
    if (feature.get('var') === converse.env.Strophe.NS.MAM) {
        converse.archive.query()
    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        // For a particular user
        this._converse.api.archive.query({'with': 'john@doe.net'}, callback, errback);)

        // For a particular room
        this._converse.api.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        var options = {
            'with': 'john@doe.net',
            'start': '2010-06-07T00:00:00Z',
            'end': '2010-07-07T13:23:54Z'
        };
        this._converse.api.archive.query(options, callback, errback);

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        // Return maximum 10 archived messages
        this._converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        var callback = function (messages, rsm) {
            // Do something with the messages, like showing them in your webpage.
            // ...
            // You can now use the returned "rsm" object, to fetch the next batch of messages:
            _converse.api.archive.query(rsm.next(10), callback, errback))

        }
        _converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        _converse.api.archive.query({'before': '', 'max':5}, function (message, rsm) {
            // Do something with the messages, like showing them in your webpage.
            // ...
            // You can now use the returned "rsm" object, to fetch the previous batch of messages:
            rsm.previous(5); // Call previous method, to update the object's parameters,
                            // passing in a limit value of 5.
            // Now we query again, to get the previous batch.
            _converse.api.archive.query(rsm, callback, errback);
        }

    }
});

connected

A boolean attribute (i.e. not a callable) which is set to true or false depending on whether there is an established connection.

disconnect

Terminates the connection.

jid

Return’s the current user’s full JID (Jabber ID).

converse.plugins.add('myplugin', {
    initialize: function () {

        alert(this._converse.api.user.jid());

    }
});

login

Logs the user in. This method can accept a map with the credentials, like this:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.user.login({
            'jid': 'dummy@example.com',
            'password': 'secret'
        });

    }
});

or it can be called without any parameters, in which case converse.js will try to log the user in by calling the prebind_url or credentials_url depending on whether prebinding is used or not.

logout

Log the user out of the current XMPP session.

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.user.logout();

    }
});

The status sub-grouping

Set and get the user’s chat status, also called their availability.

converse.plugins.add('myplugin', {
    initialize: function () {

        alert(this._converse.api.user.status.get()); // For example "dnd"

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.user.status.set('dnd');

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.user.status.set('dnd', 'In a meeting');

    }
});

converse.plugins.add('myplugin', {
    initialize: function () {
        this._converse.api.user.status.message.set('In a meeting');
        // Returns "In a meeting"
        return this._converse.api.user.status.message.get();
    }
});

get

This method is used to retrieve roster contacts.

To get a single roster contact, call the method with the contact’s JID (Jabber ID):

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        _converse.api.listen.on('rosterContactsFetched', function () {
            var contact = _converse.api.contacts.get('buddy@example.com')
        });

    }
});

To get multiple contacts, pass in an array of JIDs:

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        _converse.api.listen.on('rosterContactsFetched', function () {
            var contacts = _converse.api.contacts.get(
                ['buddy1@example.com', 'buddy2@example.com']
            )
        });

    }
});

To return all contacts, simply call get without any parameters:

converse.plugins.add('myplugin', {
    initialize: function () {

        var _converse = this._converse;
        _converse.api.listen.on('rosterContactsFetched', function () {
            var contacts = _converse.api.contacts.get();
        });

    }
});

The returned roster contact objects have these attributes:

add

Add a contact.

Provide the JID of the contact you want to add:

_converse.api.contacts.add('buddy@example.com')

You may also provide the fullname. If not present, we use the jid as fullname:

_converse.api.contacts.add('buddy@example.com', 'Buddy')

get

Returns an object representing a chat box.

To return a single chat box, provide the JID of the contact you’re chatting with in that chat box:

_converse.api.chats.get('buddy@example.com')

To return an array of chat boxes, provide an array of JIDs:

_converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com'])

To return all open chat boxes, call the method without any JIDs:

_converse.api.chats.get()

open

Opens a chat box and returns a Backbone.View object representing a chat box.

To open a single chat box, provide the JID of the contact:

converse.plugins.add('myplugin', {
    initialize: function () {
        this._converse.api.chats.open('buddy@example.com')
    }
});

To return an array of chat boxes, provide an array of JIDs:

converse.plugins.add('myplugin', {
    initialize: function () {
        this._converse.api.chats.open(['buddy1@example.com', 'buddy2@example.com'])
    }
});

The returned chat box object contains the following methods:

The get and set methods can be used to retrieve and change the following attributes:

get

Returns an object representing a multi user chat box (room). It takes 3 parameters:

• the room JID (if not specified, all rooms will be returned).
• a map (object) containing any extra room attributes For example, if you want to specify the nickname, use {'nick': 'bloodninja'}. Previously (before version 1.0.7, the second parameter only accepted the nickname (as a string value). This is currently still accepted, but then you can’t pass in any other room attributes. If the nickname is not specified then the node part of the user’s JID will be used.
• a boolean, indicating whether the room should be created if not found (default: false)

converse.plugins.add('myplugin', {
    initialize: function () {
        var nick = 'dread-pirate-roberts';
        var create_if_not_found = true;
        this._converse.api.rooms.open(
            'group@muc.example.com',
            {'nick': nick},
            create_if_not_found
        )
    }
});

open

Opens a multi user chat box and returns an object representing it. Similar to the chats.get API.

It takes 2 parameters:

• The room JID or JIDs (if not specified, all currently open rooms will be returned).
• A map (object) containing any extra room attributes. For example, if you want to specify the nickname, use {'nick': 'bloodninja'}.

To open a single multi user chat box, provide the JID of the room:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.rooms.open('group@muc.example.com')

    }
});

To return an array of rooms, provide an array of room JIDs:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])

    }
});

To setup a custom nickname when joining the room, provide the optional nick argument:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})

    }
});

Room attributes that may be passed in:

• nick: The nickname to be used
• auto_configure: A boolean, indicating whether the room should be configured automatically or not. If set to true, then it makes sense to pass in configuration settings.
• roomconfig: A map of configuration settings to be used when the room gets configured automatically. Currently it doesn’t make sense to specify roomconfig values if auto_configure is set to false. For a list of configuration values that can be passed in, refer to these values in the XEP-0045 MUC specification. The values should be named without the muc#roomconfig_ prefix.
• maximize: A boolean, indicating whether minimized rooms should also be maximized, when opened. Set to false by default.

For example, opening a room with a specific default configuration:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.rooms.open(
            'myroom@conference.example.org',
            { 'nick': 'coolguy69',
              'auto_configure': true,
              'roomconfig': {
                  'changesubject': false,
                  'membersonly': true,
                  'persistentroom': true,
                  'publicroom': true,
                  'roomdesc': 'Comfy room for hanging out',
                  'whois': 'anyone'
              }
            },
            true
        );

    }
});

close

Lets you close open chat rooms. You can call this method without any arguments to close all open chat rooms, or you can specify a single JID or an array of JIDs.

get(key)

Returns the value of a configuration settings. For example:

converse.plugins.add('myplugin', {
    initialize: function () {

        // default value would be false;
        alert(this._converse.api.settings.get("play_sounds"));

    }
});

set(key, value) or set(object)

Set one or many configuration settings. For example:

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.settings.set("play_sounds", true);

    }
});

or :

converse.plugins.add('myplugin', {
    initialize: function () {

        this._converse.api.settings.set({
            "play_sounds", true,
            "hide_offline_users" true
        });

    }
});

Note, this is not an alternative to calling converse.initialize, which still needs to be called. Generally, you’d use this method after converse.js is already running and you want to change the configuration on-the-fly.

get

Returns a token, either the RID or SID token depending on what’s asked for.

Example:

converse.plugins.add('myplugin', {
    initialize: function () {

        alert(this._converse.api.tokens.get('rid'));

    }
});