Events and promises

Converse and its plugins emit various events which you can listen to via the The listen grouping.

Some of these events are also available as ES2015 Promises, although not all of them could logically act as promises, since some events might be fired multpile times whereas promises are to be resolved (or rejected) only once.

The core events, which are also promises are:

For more info on how to use (or add promises), you can read the The promises grouping in the API documentation.

Below we will now list all events and also specify whether they are available as promises.

List of global events (and promises)

Hooking into events that Converse.js emits is a great way to extend or customize its functionality.

From version 3.0.0 and up, it’s only possible to register event handlers inside a plugin, by using the closured _converse object. When writing a plugin, remember that it will also have to be whitelisted, before it will be loaded. Refer to the whitelisted_plugins setting.

Here follows the different events that are emitted:

afterMessagesFetched

Emitted whenever a chatbox has fetched its messages from sessionStorage and NOT from the server.

This event is listened to by the converse-mam plugin to know when it can fetch archived messages from the server.

The event handler is passed the Backbone.View instance of the relevant chat box.

_converse.api.listen.on('afterMessagesFetched', function (chatboxview) { ... });

cachedRoster

The contacts roster has been retrieved from the local cache (sessionStorage).

_converse.api.listen.on('cachedRoster', function (items) { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('cachedRoster').then(function () {
    // Your code here...
});

See also the roster event further down.

callButtonClicked

When a call button (i.e. with class .toggle-call) on a chatbox has been clicked.

_converse.api.listen.on('callButtonClicked', function (connection, model) { ... });

chatBoxesFetched

Any open chatboxes (from this current session) has been retrieved from the local cache (sessionStorage).

You should wait for this event or promise before attempting to do things related to open chatboxes.

_converse.api.listen.on('chatBoxesFetched', function (items) { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('chatBoxesFetched').then(function () {
    // Your code here...
});

chatBoxInitialized

When a chatbox has been initialized. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatBoxInitialized', function (chatbox) { ... });

chatBoxOpened

When a chatbox has been opened. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatBoxOpened', function (chatbox) { ... });

chatRoomOpened

When a chatroom has been opened. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatRoomOpened', function (chatbox) { ... });

chatBoxClosed

When a chatbox has been closed. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatBoxClosed', function (chatbox) { ... });

chatBoxFocused

When the focus has been moved to a chatbox. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatBoxFocused', function (chatbox) { ... });

chatBoxToggled

When a chatbox has been minimized or maximized. Relevant to converse-chatview.js plugin.

_converse.api.listen.on('chatBoxToggled', function (chatbox) { ... });

clearSession

Called when the user is logging out and provides the opportunity to remove session data.

connected

After connection has been established and converse.js has got all its ducks in a row.

_converse.api.listen.on('connected', function () { ... });

contactRequest

Someone has requested to subscribe to your presence (i.e. to be your contact).

The Backbone.Model instance representing the roster contact is passed to the event listener.

_converse.api.listen.on('contactRequest', function (contact) { ... });

contactRemoved

The user has removed a contact.

_converse.api.listen.on('contactRemoved', function (data) { ... });

contactPresenceChanged

When a chat buddy’s presence status has changed. The presence status is either online, offline, dnd, away or xa.

_converse.api.listen.on('contactPresenceChanged', function (presence) { ... });

contactStatusMessageChanged

When a chat buddy’s custom status message has changed.

_converse.api.listen.on('contactStatusMessageChanged', function (data) { ... });

controlboxInitialized

Called when the controlbox has been initialized and therefore exists.

The controlbox contains the login and register forms when the user is logged out and a list of the user’s contacts and group chats when logged in.

_converse.api.listen.on('controlboxInitialized', function () { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('controlboxInitialized').then(function () {
    // Your code here...
});

discoInitialized

Emitted once the converse-disco plugin has been initialized and the _converse.disco_entities collection will be available and populated with at least the service discovery features of the user’s own server.

_converse.api.listen.on('discoInitialized', function () { ... });

disconnected

After converse.js has disconnected from the XMPP server.

_converse.api.listen.on('disconnected', function () { ... });

initialized

Once converse.js has been initialized.

_converse.api.listen.on('initialized', function () { ... });

See also pluginsInitialized.

logout

The user has logged out.

_converse.api.listen.on('logout', function () { ... });

messageAdded

Once a message has been added to a chatbox. The passed in data object contains a chatbox attribute, referring to the chatbox receiving the message, as well as a message attribute which refers to the Message model.

_converse.api.listen.on('messageAdded', function (data) {
    // The message is at `data.message`
    // The original chatbox is at `data.chatbox`.
});

messageSend

When a message will be sent out.

_converse.api.listen.on('messageSend', function (messageText) { ... });

noResumeableSession

When keepalive=true but there aren’t any stored prebind tokens.

_converse.api.listen.on('noResumeableSession', function () { ... });

pluginsInitialized

Emitted once all plugins have been initialized. This is a useful event if you want to register event handlers but would like your own handlers to be overridable by plugins. In that case, you need to first wait until all plugins have been initialized, so that their overrides are active. One example where this is used is in converse-notifications.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-notification.js>.

_converse.api.listen.on('pluginsInitialized', function () { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('pluginsInitialized').then(function () {
    // Your code here...
});

privateChatsAutoJoined

Emitted once any private chats have been automatically joined as specified by the auto_join_private_chats settings.

_converse.api.listen.on('privateChatsAutoJoined', function () { ... });

Also available as an ES2015 Promise.

_converse.api.waitUntil('privateChatsAutoJoined').then(function () {
    // Your code here...
});

reconnecting

Fired once converse.js has determined that it will attempt to reconnect (and each subsequent time, if it attempts repeatedly).

reconnected

After the connection has dropped and converse.js has reconnected. Any Strophe stanza handlers (as registered via converse.listen.stanza) will have to be registered anew.

_converse.api.listen.on('reconnected', function () { ... });

registeredGlobalEventHandlers

Called once Converse has registered its global event handlers (for events such as window resize or unload).

Plugins can listen to this event as cue to register their own global event handlers.

roomsAutoJoined

Emitted once any rooms that have been configured to be automatically joined, specified via the auto_join_rooms setting, have been entered.

_converse.api.listen.on('roomsAutoJoined', function () { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('roomsAutoJoined').then(function () {
    // Your code here...
});

roomInviteSent

After the user has sent out a direct invitation, to a roster contact, asking them to join a room.

_converse.api.listen.on('roomInvite', function (data) { ... });

roomInviteReceived

After the user has sent out a direct invitation, to a roster contact, asking them to join a room.

_converse.api.listen.on('roomInvite', function (data) { ... });

roomsPanelRendered

Emitted once the “Rooms” panel in the control box has been rendered. Used by converse-bookmarks and converse-roomslist to know when they can render themselves in that panel.

_converse.api.listen.on('roomsPanelRendered', function (data) { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('roomsPanelRendered').then(function () {
    // Your code here...
});

roster

When the roster has been received from the XMPP server.

_converse.api.listen.on('roster', function (items) { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('roster').then(function () {
    // Your code here...
});

See also the cachedRoster event further up, which gets called instead of roster if its already in sessionStorage.

rosterContactsFetched

Triggered once roster contacts have been fetched. Used by the converse-rosterview.js plugin to know when it can start to show the roster.

Also available as an ES2015 Promise:

_converse.api.waitUntil('rosterContactsFetched').then(function () {
    // Your code here...
});

rosterGroupsFetched

Triggered once roster groups have been fetched. Used by the converse-rosterview.js plugin to know when it can start alphabetically position roster groups.

Also available as an ES2015 Promise:

_converse.api.waitUntil('rosterGroupsFetched').then(function () {
    // Your code here...
});

rosterInitialized

The Backbone collections RosterContacts and RosterGroups have been created, but not yet populated with data.

This event is useful when you want to create views for these collections.

Also available as an ES2015 Promise:

_converse.api.waitUntil('rosterInitialized').then(function () {
    // Your code here...
});

rosterPush

When the roster receives a push event from server. (i.e. New entry in your buddy list)

_converse.api.listen.on('rosterPush', function (items) { ... });

rosterReadyAfterReconnection

Similar to rosterInitialized, but instead pertaining to reconnection. This event indicates that the Backbone collections representing the roster and its groups are now again available after converse.js has reconnected.

serviceDiscovered

When converse.js has learned of a service provided by the XMPP server. See XEP-0030.

_converse.api.listen.on('serviceDiscovered', function (service) { ... });

statusInitialized

When the user’s own chat status has been initialized.

_converse.api.listen.on('statusInitialized', function (status) { ... });

Also available as an ES2015 Promise:

_converse.api.waitUntil('statusInitialized').then(function () {
    // Your code here...
});

statusChanged

When own chat status has changed.

_converse.api.listen.on('statusChanged', function (status) { ... });

statusMessageChanged

When own custom status message has changed.

_converse.api.listen.on('statusMessageChanged', function (message) { ... });

streamFeaturesAdded

Emitted as soon as Converse has processed the stream features as advertised by the server. If you want to check whether a stream feature is supported before proceeding, then you’ll first want to wait for this event.

windowStateChanged

When window state has changed. Used to determine when a user left the page and when came back.

_converse.api.listen.on('windowStateChanged', function (data) { ... });

List of events on the ChatRoom Backbone.Model

configurationNeeded

Triggered when a new room has been created which first needs to be configured and when auto_configure is set to false.

Used by the core ChatRoomView view in order to know when to render the configuration form for a new room.