Converse converse.js

Namespace: _converse

_converse

Custom error for indicating timeouts

Source:

Namespaces

api
ChatBox
ChatBoxView
ChatRoom
ChatRoomMessage
ChatRoomMessages
ChatRoomOccupant
ChatRoomOccupants
Device
DeviceList
DeviceLists
EmojiPicker
HeadlinesBox
HeadlinesPanel
Message
RegisterPanel
RosterView
VCard

Members

(static, constant) STANZA_TIMEOUT :integer

Type:
  • integer
Source:

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:

(static) exports.isInfoVisible(code)

Determines info message visibility based on muc_show_info_messages configuration setting

Parameters:
Name Type Description
code *
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:

Events

addClientFeatures

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

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

afterFileUploaded

Hook which allows plugins to change the attributes saved on the message once a file has been uploaded.

Source:

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
text RichText

A RichText instance. You can call RichText#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:

beforeFetchLoginCredentials

Hook which allows modifying the server request

Source:

beforeFileUpload

Hook which allows plugins to transform files before they'll be uploaded. The main use-case is to encrypt the files.

Source:

beforeLogout

Triggered before the user is logged out

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
text RichText

A RichText instance. You can call RichText#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', () => { ... });

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

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

chatBoxMaximized

Triggered when a previously minimized chat gets maximized

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

chatBoxMaximized

Triggered once the _converse.RosterContacts 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

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 converse-chat-content element 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:
  • _converse.HeadlinesBoxView
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:
  • _converse.RosterContact
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:
  • _converse.RosterContact
Source:
Example
_converse.api.listen.on('contactRequest', contact => { ... });

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:

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:
Example
api.listen.on('getHeadingButtons', (view, buttons) => {
     buttons.push({
         'i18n_title': __('Foo'),
         'i18n_text': __('Foo Bar'),
         'handler': ev => alert('Foo!'),
         'a_class': 'toggle-foo',
         'icon_class': 'fa-foo',
         'name': 'foo'
     });
     return buttons;
 });

getMessageActionButtons

Hook which allows plugins to add more message action buttons

Source:
Example
api.listen.on('getMessageActionButtons', (el, buttons) => {
     buttons.push({
         'i18n_text': 'Foo',
         'handler': ev => alert('Foo!'),
         'button_class': 'chat-msg__action-foo',
         'icon_class': 'fa fa-check',
         'name': 'foo'
     });
     return buttons;
 });

getToolbarButtons

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

Source:
Example
api.listen.on('getToolbarButtons', (toolbar_el, buttons) {
     buttons.push(html`
         <button @click=${() => alert('Foo!')}>Foo</button>`
     );
     return buttons;
 }

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

historyPruned

Triggered once the message history has been pruned, i.e. once older messages have been removed to keep the number of messages below the value set in prune_messages_above.

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

initialized

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

Source:

initialized

Triggered once converse.initialize has finished.

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 message stanza is been received and processed.

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

message

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

Type:
  • object
Properties:
Name Type Description
data module:converse-muc~MUCMessageData
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:
Source:
Example
_converse.api.listen.on('messageNotification', data => { ... });

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

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

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

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:

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:

shouldNotifyOfGroupMessage

Hook which allows plugins to run further logic to determine whether a notification should be sent out for this message.

Source:
Example
api.listen.on('shouldNotifyOfGroupMessage', (should_notify) => {
     return should_notify && flurb === floob;
 });

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 UserDetailsModal has been initialized

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

userDetailsModalInitialized

Triggered once the OccupantModal 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 => { ... });

_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
Device
DeviceList
DeviceLists
EmojiPicker
HeadlinesBox
HeadlinesPanel
Message
RegisterPanel
RosterView
VCard

Members

(static, constant) STANZA_TIMEOUT :integer

Type:
  • integer
Source:

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:

(static) exports.isInfoVisible(code)

Determines info message visibility based on muc_show_info_messages configuration setting

Parameters:
Name Type Description
code *
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:

Events

addClientFeatures

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

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

afterFileUploaded

Hook which allows plugins to change the attributes saved on the message once a file has been uploaded.

Source:

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
text RichText

A RichText instance. You can call RichText#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:

beforeFetchLoginCredentials

Hook which allows modifying the server request

Source:

beforeFileUpload

Hook which allows plugins to transform files before they'll be uploaded. The main use-case is to encrypt the files.

Source:

beforeLogout

Triggered before the user is logged out

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
text RichText

A RichText instance. You can call RichText#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', () => { ... });

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

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

chatBoxMaximized

Triggered when a previously minimized chat gets maximized

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

chatBoxMaximized

Triggered once the _converse.RosterContacts 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

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 converse-chat-content element 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:
  • _converse.HeadlinesBoxView
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:
  • _converse.RosterContact
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:
  • _converse.RosterContact
Source:
Example
_converse.api.listen.on('contactRequest', contact => { ... });

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:

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:
Example
api.listen.on('getHeadingButtons', (view, buttons) => {
     buttons.push({
         'i18n_title': __('Foo'),
         'i18n_text': __('Foo Bar'),
         'handler': ev => alert('Foo!'),
         'a_class': 'toggle-foo',
         'icon_class': 'fa-foo',
         'name': 'foo'
     });
     return buttons;
 });

getMessageActionButtons

Hook which allows plugins to add more message action buttons

Source:
Example
api.listen.on('getMessageActionButtons', (el, buttons) => {
     buttons.push({
         'i18n_text': 'Foo',
         'handler': ev => alert('Foo!'),
         'button_class': 'chat-msg__action-foo',
         'icon_class': 'fa fa-check',
         'name': 'foo'
     });
     return buttons;
 });

getToolbarButtons

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

Source:
Example
api.listen.on('getToolbarButtons', (toolbar_el, buttons) {
     buttons.push(html`
         <button @click=${() => alert('Foo!')}>Foo</button>`
     );
     return buttons;
 }

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

historyPruned

Triggered once the message history has been pruned, i.e. once older messages have been removed to keep the number of messages below the value set in prune_messages_above.

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

initialized

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

Source:

initialized

Triggered once converse.initialize has finished.

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 message stanza is been received and processed.

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

message

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

Type:
  • object
Properties:
Name Type Description
data module:converse-muc~MUCMessageData
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:
Source:
Example
_converse.api.listen.on('messageNotification', data => { ... });

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

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

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

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:

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:

shouldNotifyOfGroupMessage

Hook which allows plugins to run further logic to determine whether a notification should be sent out for this message.

Source:
Example
api.listen.on('shouldNotifyOfGroupMessage', (should_notify) => {
     return should_notify && flurb === floob;
 });

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 UserDetailsModal has been initialized

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

userDetailsModalInitialized

Triggered once the OccupantModal 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 => { ... });