Converse converse.js

API Documentation

Namespace: ChatRoom

_converse.ChatRoom

Represents an open/ongoing groupchat conversation.

Source:

Methods

(private) addFieldValue() → {Element}

Given a element, return a copy with a child if we can find a value for it in this rooms config.

Source:
Returns:
Type
Element

(private) autoConfigureChatRoom() → {Promise.<XMLElement>}

Automatically configure the groupchat based on this model's 'roomconfig' data.

Source:
Returns:

Returns a promise which resolves once a response IQ has been received.

Type
Promise.<XMLElement>

(private) createInfoMessage(code, stanza, is_self)

Create an info message based on a received MUC status code

Parameters:
Name Type Description
code string

The MUC status code
stanza XMLElement

The original stanza that contains the code
is_self Boolean

Whether this stanza refers to our own presence
Source:

(private) createInfoMessages(stanza)

Create info messages based on a received presence or message stanza

Parameters:
Name Type Description
stanza XMLElement
Source:

(private) directInvite(recipient, reasonopt)

Send a direct invitation as per XEP-0249

Parameters:
Name Type Attributes Description
recipient String

JID of the person being invited
reason String <optional>

Reason for the invitation
Source:

(private) fetchRoomConfiguration() → {Promise.<XMLElement>}

Send an IQ stanza to fetch the groupchat configuration data. Returns a promise which resolves once the response IQ has been received.

Source:
Returns:
Type
Promise.<XMLElement>

(private) findDanglingModeration(attrs) → {_converse.ChatRoomMessage}

Looks whether we already have a moderation message for this incoming message. If so, it's considered "dangling" because it probably hasn't been applied to anything yet, given that the relevant message is only coming in now.

Parameters:
Name Type Description
attrs object

Attributes representing a received message, as returned by st.parseMUCMessage
Source:
Returns:
Type
_converse.ChatRoomMessage

(private) getAffiliationList(affiliation) → {Promise.<Array.<MemberListItem>>}

Sends an IQ stanza to the server, asking it for the relevant affiliation list . Returns an array of MemberListItem objects, representing occupants that have the given affiliation. See: https://xmpp.org/extensions/xep-0045.html#modifymember

Parameters:
Name Type Description
affiliation "admin" | "owner" | "member"
Source:
Returns:
Type
Promise.<Array.<MemberListItem>>

(private) getAllKnownNicknames() → {Array.<String>}

Return an array of unique nicknames based on all occupants and messages in this MUC.

Source:
Returns:
Type
Array.<String>

(private) getAndPersistNickname() → {Promise.<string>}

Given a nick name, save it to the model state, otherwise, look for a server-side reserved nickname or default configured nickname and if found, persist that to the model state.

Source:
Returns:

A promise which resolves with the nickname

Type
Promise.<string>

(private) getDiscoInfo() → {Promise}

Fetch the extended MUC info from the server and cache it locally https://xmpp.org/extensions/xep-0045.html#disco-roominfo

Source:
Returns:
Type
Promise

(private) getDiscoInfoFields() → {Promise}

Fetch the extended MUC info fields from the server and store them locally in the config Model attribute. See: https://xmpp.org/extensions/xep-0045.html#disco-roominfo

Source:
Returns:
Type
Promise

(private) getOccupant(nickname_or_jid) → {_converse.ChatRoomOccupant}

Parameters:
Name Type Description
nickname_or_jid String

The nickname or JID of the occupant to be returned
Source:
Returns:
Type
_converse.ChatRoomOccupant

(private) getOccupantsSortedBy(attr) → {Array.<_converse.ChatRoomOccupant>}

Return an array of occupant models, sorted according to the passed-in attribute.

Parameters:
Name Type Description
attr String

The attribute to sort the returned array by
Source:
Returns:
Type
Array.<_converse.ChatRoomOccupant>

(private) getOccupantsWithAffiliation(affiliation) → {Array.<_converse.ChatRoomOccupant>}

Return an array of occupant models that have the required affiliation

Parameters:
Name Type Description
affiliation String
Source:
Returns:
Type
Array.<_converse.ChatRoomOccupant>

(private) getOccupantsWithRole(role) → {Array.<_converse.ChatRoomOccupant>}

Return an array of occupant models that have the required role

Parameters:
Name Type Description
role String
Source:
Returns:
Type
Array.<_converse.ChatRoomOccupant>

(private) getOwnAffiliation() → {'none'|'outcast'|'member'|'admin'|'owner'}

Returns the affiliation which the current user has in this MUC

Source:
Returns:
Type
'none' | 'outcast' | 'member' | 'admin' | 'owner'

(private) getOwnOccupant() → {_converse.ChatRoomOccupant}

Get the _converse.ChatRoomOccupant instance which represents the current user.

Source:
Returns:
Type
_converse.ChatRoomOccupant

(private) getOwnRole() → {'none'|'visitor'|'participant'|'moderator'}

Returns the role which the current user has in this MUC

Source:
Returns:
Type
'none' | 'visitor' | 'participant' | 'moderator'

(private) getReservedNick() → {Promise.<string>}

Use service-discovery to ask the XMPP server whether this user has a reserved nickname for this groupchat. If so, we'll use that, otherwise we render the nickname form.

Source:
Returns:

A promise which resolves with the reserved nick or null

Type
Promise.<string>

(private) getRoomJIDAndNick() → {string}

Utility method to construct the JID for the current user as occupant of the groupchat.

Source:
Returns:
  • The groupchat JID with the user's nickname added at the end.
Type
string
Example
groupchat@conference.example.org/nickname

(private) handleMessageStanza(stanza)

Parses an incoming message stanza and queues it for processing.

Parameters:
Name Type Description
stanza XMLElement
Source:

(private) handleModeration(attrs) → {Boolean}

Handles message moderation based on the passed in attributes.

Parameters:
Name Type Description
attrs object

Attributes representing a received message, as returned by st.parseMUCMessage
Source:
Returns:

Returns true or false depending on whether a message was moderated or not.

Type
Boolean

(private) handleSubjectChange(attrs)

Handle a possible subject change and return true if so.

Parameters:
Name Type Description
attrs object

Attributes representing a received message, as returned by st.parseMUCMessage
Source:

(private) ignorableCSN(attrs)

Is this a chat state notification that can be ignored, because it's old or because it's from us.

Parameters:
Name Type Description
attrs Object

The message attributes
Source:

(async, private) isJoined() → {Promise.<boolean>}

Send a MUC-0410 MUC Self-Ping stanza to room to determine whether we're still joined.

Source:
Returns:
Type
Promise.<boolean>

(private) isOwnMessage(msg) → {boolean}

Determines whether the message is from ourselves by checking the from attribute. Doesn't check the type attribute.

Parameters:
Name Type Description
msg Object | XMLElement | _converse.Message
Source:
Returns:
Type
boolean

(private) isSameUser(jid1, jid2) → {Boolean}

Given two JIDs, which can be either user JIDs or MUC occupant JIDs, determine whether they belong to the same user.

Parameters:
Name Type Description
jid1 String
jid2 String
Source:
Returns:
Type
Boolean

(private) isUserMentioned()

Returns a boolean to indicate whether the current user was mentioned in a message.

Parameters:
Type Description
String

The text message
Source:

(private) join(nick, passwordopt)

Join the MUC

Parameters:
Name Type Attributes Description
nick String

The user's nickname
password String <optional>

Optional password, if required by the groupchat. Will fall back to the password value stored in the room model (if available).
Source:

(private) leave(exit_msgopt)

Leave the groupchat.

Parameters:
Name Type Attributes Description
exit_msg string <optional>

Message to indicate your reason for leaving
Source:

(private) onDirectMUCInvitation(message)

A direct MUC invitation to join a groupchat has been received See XEP-0249: Direct MUC invitations.

Parameters:
Name Type Description
message XMLElement

The message stanza containing the invitation.
Source:

(private) onMessage(attrs)

Handler for all MUC messages sent to this groupchat. This method shouldn't be called directly, instead _converse.ChatRoom#queueMessage should be called.

Parameters:
Name Type Description
attrs MessageAttributes

A promise which resolves to the message attributes.
Source:

(async, private) onMessage(attrs_promse)

Parameters:
Name Type Description
attrs_promse MessageAttributes

A promise which resolves to the message attributes.
Source:

(private) onOwnPresence(pres)

Handles a received presence relating to the current user.

For locked groupchats (which are by definition "new"), the groupchat will either be auto-configured or created instantly (with default config) or a configuration groupchat will be rendered.

If the groupchat is not locked, then the groupchat will be auto-configured only if applicable and if the current user is the groupchat's owner.

Parameters:
Name Type Description
pres XMLElement

The stanza
Source:

(private) onPresence(stanza)

Handles all MUC presence stanzas.

Parameters:
Name Type Description
stanza XMLElement
Source:

(async, private) queueMessage(attrs)

Queue an incoming chat message stanza for processing.

Parameters:
Name Type Description
attrs Promise.<MessageAttributes>

A promise which resolves to the message attributes
Source:

(async, private) queueMessageCreation(attrs)

Queue the creation of a message, to make sure that we don't run into a race condition whereby we're creating a new message before the collection has been fetched.

Parameters:
Name Type Description
attrs Object
Source:

(private) rejoin()

Clear stale cache and re-join a MUC we've been in before.

Source:

(async, private) rejoinIfNecessary()

Check whether we're still joined and re-join if not

Source:

(private) restoreFromCache() → {Boolean}

Checks whether we're still joined and if so, restores the MUC state from cache.

Source:
Returns:

Returns true if we're still joined, otherwise returns false.

Type
Boolean

(private) retractOtherMessage(message, reasonopt)

Retract someone else's message in this groupchat.

Parameters:
Name Type Attributes Description
message _converse.Message

The message which we're retracting.
reason string <optional>

The reason for retracting the message.
Source:

(private) retractOwnMessage(message)

Retract one of your messages in this groupchat

Parameters:
Name Type Description
message _converse.Message

The message which we're retracting.
Source:

(private) sendChatState()

Sends a message with the current XEP-0085 chat state of the user as taken from the chat_state attribute of the _converse.ChatRoom.

Source:

(private) sendConfiguration(config) → {Promise.<XMLElement>}

Sends an IQ stanza with the groupchat configuration.

Parameters:
Name Type Description
config Array

The groupchat configuration
Source:
Returns:
  • A promise which resolves with the result stanza received from the XMPP server.
Type
Promise.<XMLElement>

(private) sendDestroyIQ(reasonopt, new_jidopt)

Sends an IQ stanza to the XMPP server to destroy this groupchat. Not to be confused with the _converse.ChatRoom#destroy method, which simply removes the room from the local browser storage cache.

Parameters:
Name Type Attributes Description
reason string <optional>

The reason for destroying the groupchat.
new_jid string <optional>

The JID of the new groupchat which replaces this one.
Source:

(private) sendRetractionIQ(message, reasonopt)

Sends an IQ stanza to the XMPP server to retract a message in this groupchat.

Parameters:
Name Type Attributes Description
message _converse.Message

The message which we're retracting.
reason string <optional>

The reason for retracting the message.
Source:

(private) sendTimedMessage(message) → {Promise.<XMLElement>|Promise.<_converse.TimeoutError>}

Sends a message stanza to the XMPP server and expects a reflection or error message within a specific timeout period.

Parameters:
Name Type Description
message _converse.Message | XMLElement
Source:
Returns:

Returns a promise which resolves with the reflected message stanza or rejects with an error stanza or with a _converse.TimeoutError.

Type
Promise.<XMLElement> | Promise.<_converse.TimeoutError>

(private) setAffiliation(affiliation, members) → {Promise}

Send IQ stanzas to the server to set an affiliation for the provided JIDs. See: https://xmpp.org/extensions/xep-0045.html#modifymember

Prosody doesn't accept multiple JIDs' affiliations being set in one IQ stanza, so as a workaround we send a separate stanza for each JID. Related ticket: https://issues.prosody.im/345

Parameters:
Name Type Description
affiliation string

The affiliation
members object

A map of jids, affiliations and optionally reasons. Only those entries with the same affiliation as being currently set will be considered.
Source:
Returns:

A promise which resolves and fails depending on the XMPP server response.

Type
Promise

(private) setAffiliations(members) → {Promise}

Send IQ stanzas to the server to modify affiliations for users in this groupchat.

See: https://xmpp.org/extensions/xep-0045.html#modifymember

Parameters:
Name Type Description
members Array.<Object>
Properties
Name Type Attributes Description
jid string

The JID of the user whose affiliation will change
affiliation Array

The new affiliation for this user
reason string <optional>

An optional reason for the affiliation change
Source:
Returns:
Type
Promise

(private) setRole(occupant, role, reason, onSuccess, onError)

Send an IQ stanza to modify an occupant's role

Parameters:
Name Type Description
occupant _converse.ChatRoomOccupant
role String
reason String
onSuccess function

callback for a succesful response
onError function

callback for an error response
Source:

(private) setSubject(value)

Set the subject for this _converse.ChatRoom

Parameters:
Name Type Description
value String
Source:

(private) shouldShowErrorMessage() → {Promise.<boolean>}

Source:
Returns:
Type
Promise.<boolean>

(private) updateMemberLists(members) → {Promise}

Fetch the lists of users with the given affiliations. Then compute the delta between those users and the passed in members, and if it exists, send the delta to the XMPP server to update the member list.

Parameters:
Name Type Description
members object

Map of member jids and affiliations.
Source:
Returns:

A promise which is resolved once the list has been updated or once it's been established there's no need to update the list.

Type
Promise

(private) updateOccupantsOnPresence(pres)

Given a presence stanza, update the occupant model based on its contents.

Parameters:
Name Type Description
pres XMLElement

The presence stanza
Source:

Events

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 _converse.ChatRoomView in order to know when to render the configuration form for a new room.

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