Converse converse.js

Namespace: _converse

_converse

A private, closured object containing the private api (via _converse.api) as well as private methods and internal data-structures.

Source:

Namespaces

api
ChatBox
ChatBoxView
ChatRoom
ChatRoomMessage
ChatRoomMessages
ChatRoomOccupant
ChatRoomView
DeviceList
DeviceLists
DiscoEntity
EmojiPicker
Message
MessageView
RegisterPanel
RosterContact
RosterContacts
RosterGroupView
RosterView

Methods

(private, static) __(str)

Translate the given string based on the current locale. Handles all MUC presence stanzas.

Parameters:
Name Type Description
str String

The string to translate

Source:

(private, static) initRoster()

Initialize the Bakcbone collections that represent the contats roster and the roster groups.

Source:

(private, static) log(message, level)

Logs messages to the browser's developer console. Available loglevels are 0 for 'debug', 1 for 'info', 2 for 'warn', 3 for 'error' and 4 for 'fatal'. When using the 'error' or 'warn' loglevels, a full stacktrace will be logged as well.

Parameters:
Name Type Description
message string

The message to be logged

level integer

The loglevel which allows for filtering of log messages

Source:

(private, static) onDisconnected()

Gets called once strophe's status reaches Strophe.Status.DISCONNECTED. Will either start a teardown process for converse.js or attempt to reconnect.

Source:

(private, static) populateRoster(ignore_cache)

Fetch all the roster groups, and then the roster contacts. Emit an event after fetching is done in each case.

Parameters:
Name Type Description
ignore_cache Bool

If set to to true, the local cache will be ignored it's guaranteed that the XMPP server will be queried for the roster.

Source:

(private, static) rejectPresenceSubscription(jid, message)

Reject or cancel another user's subscription to our presence updates.

Parameters:
Name Type Description
jid String

The Jabber ID of the user whose subscription is being canceled

message String

An optional message to the user

Source:

(private, static) sendCSI(stat)

Send out a Client State Indication (XEP-0352)

Parameters:
Name Type Description
stat String

The user's chat status

Source:

(private) getNicknameFromBookmark()

Check if the user has a bookmark with a saved nickanme for this groupchat and return it.

Source:

Events

addClientFeatures

Triggered in converse-disco once the core disco features of Converse have been added.

Source:
Example
_converse.api.listen.on('addClientFeatures', () => { ... });

afterMessageBodyTransformed

Synchronous event which provides a hook for transforming a chat message's body text after the default transformations have been applied.

Parameters:
Name Type Description
view _converse.MessageView

The view representing the message

text string

The message text

Source:
Example
_converse.api.listen.on('afterMessageBodyTransformed', (view, text) => { ... });

afterMessagesFetched

Triggered whenever a _converse.ChatBox instance has fetched its messages from sessionStorage but NOT from the server.

Type:
Source:
Example
_converse.api.listen.on('afterMessagesFetched', view => { ... });

afterResourceBinding

Synchronous event triggered after we've sent an IQ to bind the user's JID resource for this session.

Source:

beforeMessageBodyTransformed

Synchronous event which provides a hook for transforming a chat message's body text before the default transformations have been applied.

Parameters:
Name Type Description
view _converse.MessageView

The view representing the message

text string

The message text

Source:
Example
_converse.api.listen.on('beforeMessageBodyTransformed', (view, text) => { ... });

beforeResourceBinding

Synchronous event triggered before we send an IQ to bind the user's JID resource for this session.

Source:

beforeShowingChatView

Triggered just before a _converse.ChatBoxView or _converse.ChatRoomView will be shown.

Type:
  • object
Properties:
Name Type Description
view _converse.ChatBoxView | _converse.ChatRoomView
Source:

bookmarksInitialized

Triggered once the _converse.Bookmarks collection has been created and cached bookmarks have been fetched.

Source:
Example
_converse.api.listen.on('bookmarksInitialized', () => { ... });

bookmarkViewsInitialized

Triggered once the _converse.Bookmarks collection and _converse.BookmarksView view has been created and cached bookmarks have been fetched.

Source:
Example
_converse.api.listen.on('bookmarkViewsInitialized', () => { ... });

cachedRoster

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

Type:
Source:
Examples
_converse.api.listen.on('cachedRoster', (items) => { ... });
_converse.api.waitUntil('cachedRoster').then(items => { ... });

callButtonClicked

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

Type:
  • object
Properties:
Name Type Description
_converse.connection Strophe.Connection

The XMPP Connection object

_converse.connection _converse.ChatBox | _converse.ChatRoom

The XMPP Connection object

Source:
Example
_converse.api.listen.on('callButtonClicked', (connection, model) => { ... });

chatBoxBlurred

Triggered when the focus has been removed from a particular chat.

Type:
Source:
Example
_converse.api.listen.on('chatBoxBlurred', (view, event) => { ... });

chatBoxClosed

Triggered once a chatbox has been closed.

Type:
Source:
Example
_converse.api.listen.on('chatBoxClosed', view => { ... });

chatBoxesFetched

Triggered when a message stanza is been received and processed.

Type:
  • object
Properties:
Name Type Description
chatbox _converse.ChatBox | _converse.ChatRoom
stanza XMLElement
Source:
Examples
_converse.api.listen.on('message', obj => { ... });
_converse.api.waitUntil('chatBoxesFetched').then(() => { ... });

chatBoxesInitialized

Triggered once the _converse.ChatBoxes collection has been initialized.

Source:
Examples
_converse.api.listen.on('chatBoxesInitialized', () => { ... });
_converse.api.waitUntil('chatBoxesInitialized').then(() => { ... });

chatBoxFocused

Triggered when the focus has been moved to a particular chat.

Type:
Source:
Example
_converse.api.listen.on('chatBoxFocused', (view, event) => { ... });

chatBoxInitialized

Triggered once the _converse.ChatBoxView has been initialized

Type:
Source:
Example
_converse.api.listen.on('chatBoxInitialized', view => { ... });

chatBoxInsertedIntoDOM

Triggered once the _converse.ChatBoxView has been inserted into the DOM

Type:
Source:
Example
_converse.api.listen.on('chatBoxInsertedIntoDOM', view => { ... });

chatBoxMaximized

After the user has sent out a direct invitation (as per XEP-0249), to a roster contact, asking them to join a room.

Type:
  • object
Properties:
Name Type Description
room _converse.ChatRoom
recipient string

The JID of the person being invited

reason string

The original reason for the invitation

Source:
Example
_converse.api.listen.on('chatBoxMaximized', view => { ... });

chatBoxMaximized

Triggered once the _converse.RosterContacts and _converse.RosterGroups have been created, but not yet populated with data. This event is useful when you want to create views for these collections.

Source:
Examples
_converse.api.listen.on('rosterInitialized', () => { ... });
_converse.api.waitUntil('rosterInitialized').then(() => { ... });

chatBoxMaximized

Triggered when a previously minimized chat gets maximized

Type:
Source:
Example
_converse.api.listen.on('chatBoxMaximized', view => { ... });

chatBoxMinimized

Triggered when a previously maximized chat gets Minimized

Type:
Source:
Example
_converse.api.listen.on('chatBoxMinimized', view => { ... });

chatBoxScrolledDown

Triggered once the chat's message area has been scrolled down to the bottom.

Type:
  • object
Properties:
Name Type Description
chatbox _converse.ChatBox | _converse.ChatRoom

The chat model

Source:
Example
_converse.api.listen.on('chatBoxScrolledDown', obj => { ... });

chatBoxViewsInitialized

Triggered once the _converse.ChatBoxViews view-colleciton has been initialized

Source:
Example
_converse.api.listen.on('chatBoxViewsInitialized', () => { ... });

chatRoomOpened

Triggered once a groupchat has been opened

Type:
Source:
Example
_converse.api.listen.on('chatRoomOpened', view => { ... });

clearSession

Triggered once the user session has been cleared, for example when the user has logged out or when Converse has disconnected for some other reason.

Source:

clientConfigInitialized

Triggered once the XMPP-client configuration has been initialized. The client configuration is independent of any particular and its values persist across user sessions.

Source:
Example
_converse.api.listen.on('clientConfigInitialized', () => { ... });

connectionInitialized

Triggered once the Strophe.Connection constructor has been initialized, which will be responsible for managing the connection to the XMPP server.

Source:

contactPresenceChanged

When a contact's presence status has changed. The presence status is either online, offline, dnd, away or xa.

Type:
Source:
Example
_converse.api.listen.on('contactPresenceChanged', contact => { ... });

contactRequest

Triggered when someone has requested to subscribe to your presence (i.e. to be your contact).

Type:
Source:
Example
_converse.api.listen.on('contactRequest', contact => { ... });

contactStatusMessageChanged

When a contact's custom status message has changed.

Type:
  • object
Properties:
Name Type Description
contact object

The chat buddy

message string

The message text

Source:
Example
_converse.api.listen.on('contactStatusMessageChanged', obj => { ... });

controlBoxInitialized

Triggered when the _converse.ControlBoxView 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.

Type:
  • _converse.ControlBoxView
Source:
Example
_converse.api.listen.on('controlBoxInitialized', view => { ... });

controlBoxOpened

Triggered once the controlbox has been opened

Type:
  • _converse.ControlBox
Source:

controlBoxPaneInitialized

Triggered once the _converse.ControlBoxPane has been initialized

Type:
  • _converse.ControlBoxPane
Source:
Example
_converse.api.listen.on('controlBoxPaneInitialized', view => { ... });

discoExtensionFieldDiscovered

Triggered when Converse has learned of a disco extension field. See XEP-0030.

Source:
Example
_converse.api.listen.on('discoExtensionFieldDiscovered', () => { ... });

discoInitialized

Triggered 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.

Source:
Example
_converse.api.listen.on('discoInitialized', () => { ... });

disconnected

Triggered after converse.js has disconnected from the XMPP server.

Source:
Example
_converse.api.listen.on('disconnected', () => { ... });

emojisInitialized

Triggered once the JSON file representing emoji data has been fetched and its save to start calling emoji utility methods.

Source:

enteredNewRoom

Triggered when the user has entered a new MUC

Type:
Source:
Example
_converse.api.listen.on('enteredNewRoom', model => { ... });

initialized

Triggered once converse.js has been initialized. See also _converse#event:pluginsInitialized.

Source:

initialized

Triggered after the connection has been established and Converse has got all its ducks in a row.

Source:

logout

Triggered once the user has logged out.

Source:

message

Triggered when a message stanza is been received and processed

Type:
  • object
Properties:
Name Type Description
chatbox _converse.ChatBox | _converse.ChatRoom
stanza XMLElement
Source:
Example
_converse.api.listen.on('message', obj => { ... });

messageAdded

Triggered once a message has been added to a chatbox.

Type:
  • object
Properties:
Name Type Description
message _converse.Message

The message instance

chatbox _converse.ChatBox | _converse.ChatRoom

The chat model

Source:
Example
_converse.api.listen.on('messageAdded', data => { ... });

messageNotification

Triggered when a notification (sound or HTML5 notification) for a new message has will be made.

Type:
  • XMLElement
Source:
Example
_converse.api.listen.on('messageNotification', stanza => { ... });

messageSend

Triggered whenever a message is sent by the user

Type:
Source:
Example
_converse.api.listen.on('messageSend', message => { ... });

minimizedChatsInitialized

Triggered once the _converse.MinimizedChats instance has been * initialized

Source:
Example
_converse.api.listen.on('minimizedChatsInitialized', () => { ... });

noResumeableBOSHSession

Triggered when fetching prebind tokens failed

Type:
Source:
Example
_converse.api.listen.on('noResumeableBOSHSession', _converse => { ... });

OMEMOInitialized

Triggered once OMEMO support has been initialized

Source:
Example
_converse.api.listen.on('OMEMOInitialized', () => { ... });

onChatReconnected

Triggered whenever a _converse.ChatBox instance has reconnected after an outage

Type:
Source:
Example
_converse.api.listen.on('onChatReconnected', chatbox => { ... });

pluginsInitialized

Triggered 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`.

Also available as an ES2015 Promise which can be listened to with _converse.api.waitUntil.

Source:
Examples
_converse.api.listen.on('pluginsInitialized', () => { ... });
_converse.api.waitUntil('pluginsInitialized').then(() => { ... });

presencesInitialized

Triggered once the _converse.Presences collection has been initialized and its cached data fetched. Returns a boolean indicating whether this event has fired due to Converse having reconnected.

Type:
  • bool
Source:
Example
_converse.api.listen.on('presencesInitialized', reconnecting => { ... });

privateChatsAutoJoined

Triggered once any private chats have been automatically joined as specified by the auto_join_private_chats setting. See: https://conversejs.org/docs/html/configuration.html#auto-join-private-chats

Source:
Examples
_converse.api.listen.on('privateChatsAutoJoined', () => { ... });
_converse.api.waitUntil('privateChatsAutoJoined').then(() => { ... });

profileModalInitialized

Triggered when the _converse.ProfileModal has been created and initialized.

Type:
  • _converse.XMPPStatus
Source:
Example
_converse.api.listen.on('profileModalInitialized', status => { ... });

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.

Source:
Example
_converse.api.listen.on('reconnected', () => { ... });

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.

Source:
Example
_converse.api.listen.on('registeredGlobalEventHandlers', () => { ... });

renderToolbar

Triggered once the _converse.ChatBoxView's toolbar has been rendered

Type:
Source:
Example
_converse.api.listen.on('renderToolbar', view => { ... });

roomsAutoJoined

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

Source:
Examples
_converse.api.listen.on('roomsAutoJoined', () => { ... });
_converse.api.waitUntil('roomsAutoJoined').then(() => { ... });

roomsListInitialized

Triggered once the _converse.RoomsListView has been created and initialized.

Source:
Example
_converse.api.listen.on('roomsListInitialized', status => { ... });

roomsPanelRendered

Triggered once the section of the _converse.ControlBoxView which shows gropuchats has been rendered.

Source:
Example
_converse.api.listen.on('roomsPanelRendered', () => { ... });

roster

When the roster has been received from the XMPP server. See also the cachedRoster event further up, which gets called instead of roster if its already in sessionStorage.

Type:
  • XMLElement
Source:
Examples
_converse.api.listen.on('roster', iq => { ... });
_converse.api.waitUntil('roster').then(iq => { ... });

rosterContactInitialized

Synchronous event which provides a hook for further initializing a RosterContact

Parameters:
Name Type Description
contact _converse.RosterContact
Source:

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.

Source:
Example
_converse.api.listen.on('rosterContactsFetched', () => { ... });

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.

Source:
Examples
_converse.api.listen.on('rosterGroupsFetched', () => { ... });
_converse.api.waitUntil('rosterGroupsFetched').then(() => { ... });

rosterPush

When the roster receives a push event from server (i.e. new entry in your contacts roster).

Type:
  • XMLElement
Source:
Example
_converse.api.listen.on('rosterPush', iq => { ... });

rosterReadyAfterReconnection

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

Source:
Example
_converse.api.listen.on('rosterReadyAfterReconnection', () => { ... });

rosterViewInitialized

Triggered once the _converse.RosterView instance has been created and initialized.

Source:
Example
_converse.api.listen.on('rosterViewInitialized', () => { ... });

serviceDiscovered

Triggered when Converse has learned of a service provided by the XMPP server. See XEP-0030.

Type:
  • Backbone.Model
Source:
Example
_converse.api.listen.on('featuresDiscovered', feature => { ... });

setUserJID

Triggered whenever the user's JID has been updated

Source:

startDiagonalResize

Triggered once the user starts to diagonally resize a _converse.ChatBoxView

Source:
Example
_converse.api.listen.on('startDiagonalResize', (view) => { ... });

startHorizontalResize

Triggered once the user starts to horizontally resize a _converse.ChatBoxView

Source:
Example
_converse.api.listen.on('startHorizontalResize', (view) => { ... });

startVerticalResize

Triggered once the user starts to vertically resize a _converse.ChatBoxView

Source:
Example
_converse.api.listen.on('startVerticalResize', (view) => { ... });

statusInitialized

Triggered when the user's own chat status has been initialized.

Source:
Examples
_converse.api.listen.on('statusInitialized', status => { ... });
_converse.api.waitUntil('statusInitialized').then(() => { ... });

streamFeaturesAdded

Triggered 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.

Source:
Example
_converse.api.listen.on('streamFeaturesAdded', () => { ... });

userDetailsModalInitialized

Triggered once the _converse.UserDetailsModal has been initialized

Type:
Source:
Example
_converse.api.listen.on('userDetailsModalInitialized', chatbox => { ... });

userSessionInitialized

Triggered once the user's session has been initialized. The session is a cache which stores information about the user's current session.

Source:

will-reconnect

Triggered when the connection has dropped, but Converse will attempt to reconnect again.

Source:

windowStateChanged

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

Type:
  • object
Source:
Example
_converse.api.listen.on('windowStateChanged', obj => { ... });