Converse converse.js

API Documentation

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
ChatRoomOccupants
ChatRoomView
Device
DeviceList
DeviceLists
DiscoEntity
EmojiPicker
HeadlinesBox
HeadlinesPanel
Message
RegisterPanel
RoomsPanel
RosterContact
RosterContacts
RosterGroups
RosterGroupView
RosterView
VCard

Methods

(private, static) __(str)

Translate the given string based on the current locale.

Parameters:
Name Type Description
str String
Source:

(private, static) ___(str)

A no-op method which is used to signal to gettext that the passed in string should be included in the pot translation file.

In contrast to the double-underscore method, the triple underscore method doesn't actually translate the strings.

One reason for this method might be because we're using strings we cannot send to the translation function because they require variable interpolation and we don't yet have the variables at scan time.

Parameters:
Name Type Description
str String
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:

(private) handleMessageStanza(attrs)

Handler method for all incoming single-user chat "message" stanzas.

Parameters:
Name Type Description
attrs MessageAttributes

The message attributes
Source:

(private) isMessageToHiddenChat(attrs)

Given parsed attributes for a message stanza, get the related chatbox and check whether it's hidden.

Parameters:
Name Type Description
attrs MUCMessageAttributes
Source:

(private) playSoundNotification()

Plays a notification sound

Source:

setUserJID()

Stores the passed in JID for the current user, potentially creating a resource if the JID is bare.

Given that we can only create an XMPP connection if we know the domain of the server connect to and we only know this once we know the JID, we also call _converse.initConnection (if necessary) to make sure that the connection is set up.

Source:
Fires:

(private) shouldNotifyOfGroupMessage(attrs)

Is this a group message for which we should notify the user?

Parameters:
Name Type Description
attrs MUCMessageAttributes
Source:

(private) shouldNotifyOfMessage(data)

Parameters:
Name Type Description
data MessageData | MUCMessageData
Source:

(private) showMessageNotification(data)

Shows an HTML5 Notification with the passed in message

Parameters:
Name Type Description
data MessageData | MUCMessageData
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
model _converse.Message

The model representing the message
text MessageText

A MessageText instance. You can call MessageText#addTemplateResult on it in order to add TemplateResult objects meant to render rich parts of the message.
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 => { ... });

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
model _converse.Message

The model representing the message
text MessageText

A MessageText instance. You can call MessageText#addTemplateResult on it in order to add TemplateResult objects meant to render rich parts of the message.
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:

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 once all chat boxes have been recreated from the browser cache

Type:
  • object
Properties:
Name Type Description
chatbox _converse.ChatBox | _converse.ChatRoom
stanza XMLElement
Source:
Examples
_converse.api.listen.on('chatBoxesFetched', 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 a _converse.ChatBox has been created and initialized.

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

chatBoxInsertedIntoDOM

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

Type:
Source:
Example
_converse.api.listen.on('chatBoxInsertedIntoDOM', 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 => { ... });

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 => { ... });

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 => { ... });

chatBoxScrolledUp

Triggered once the chat's message area has been scrolled to the top

Properties:
Name Type Description
view _converse.ChatBoxView | _converse.ChatRoomView
Source:
Example
_converse.api.listen.on('chatBoxScrolledUp', obj => { ... });

chatBoxViewInitialized

Triggered once the _converse.ChatBoxView has been initialized

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

chatBoxViewsInitialized

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

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

chatRoomInitialized

Triggered once a _converse.ChatRoom has been created and initialized.

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

chatRoomMessageInitialized

Triggered once a _converse.ChatRoomMessageInitialized has been created and initialized.

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

chatRoomViewInitialized

Triggered once a { @link _converse.ChatRoomView } has been opened

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

clearSession

Synchronouse event 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 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:
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', () => { ... });

enteredNewRoom

Triggered when the user has entered a new MUC

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

getHeadingButtons

Hook which allows plugins to add more buttons to a chat's heading.

Source:

getToolbarButtons

Hook which allows plugins to add more buttons to a chat's toolbar

Source:

headlinesBoxInitialized

Triggered once a _converse.HeadlinesBox has been created and initialized.

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

headlinesBoxViewInitialized

Triggered once the _converse.HeadlinesBoxView has been initialized

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

headlinesPanelRendered

Triggered once the section of the { @link _converse.ControlBoxView } which shows announcements has been rendered.

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

initialized

Triggered once converse.initialize has finished.

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:

MAMResult

Synchronous event which allows listeners to first do some work based on the MAM result before calling the handlers here.

Source:

membersFetched

Triggered once the member lists for this MUC have been fetched and processed.

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

message

Triggered when a groupchat message stanza has been received and parsed.

Type:
  • object
Properties:
Name Type Description
data module:converse-muc~MUCMessageData
Source:

message

Triggered when a message stanza is been received and processed.

Type:
  • object
Properties:
Name Type Description
data module:converse-chat~MessageData
Source:

messageInitialized

Triggered once a _converse.Message has been created and initialized.

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

messageNotification

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

Type:
  • MessageData | MUCMessageData
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 => { ... });

parseMessage

Hook which allows plugins to add additional parsing

Source:

parseMUCMessage

Hook which allows plugins to add additional parsing

Source:

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:
Example
_converse.api.listen.on('pluginsInitialized', () => { ... });

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 { @link _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:

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', () => { ... });

sendMessage

Triggered when a message is being sent out

Type:
  • Object
Parameters:
Name Type Description
data Object
Properties:
Name Type Description
data.chatbox _converse.ChatBox | _converse.ChatRoom
data.message _converse.Message | _converse.ChatRoomMessage
Source:

serviceDiscovered

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

Type:
  • 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 the stream features are known. 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', () => { ... });

streamResumptionFailed

Triggered when the XEP-0198 stream could not be resumed.

Source:

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:

VCardsInitialized

Triggered as soon as the _converse.vcards collection has been initialized and populated from cache.

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 => { ... });