Module: client

This is an internal module. See MatrixClient for the public class.
Source:

Classes

MatrixClient

Members

(static) CRYPTO_ENABLED

Source:

(static) MatrixClient

Source:

Methods

(inner) _decryptEvent(client, raw) → {MatrixEvent}

Decrypt a received event according to the algorithm specified in the event.
Parameters:
Name Type Description
client MatrixClient
raw object event
Source:
Returns:
Type
MatrixEvent

(inner) _membershipChange(client, roomId, userId, membership, reason, callback) → {module:client.Promise|module:http-api.MatrixError}

This is an internal method.
Parameters:
Name Type Description
client MatrixClient
roomId string
userId string
membership string
reason string
callback module:client.callback Optional.
Source:
Returns:

(inner) _setMembershipState(client, roomId, userId, membershipValue, reason, callback) → {module:client.Promise|module:http-api.MatrixError}

This is an internal method.
Parameters:
Name Type Description
client MatrixClient
roomId string
userId string
membershipValue string
reason string
callback module:client.callback Optional.
Source:
Returns:

Type Definitions

callback(err, data)

The standard MatrixClient callback interface. Functions which accept this will specify 2 return arguments. These arguments map to the 2 parameters specified in this callback.
Parameters:
Name Type Description
err Object The error value, the "rejected" value or null.
data Object The data returned, the "resolved" value.
Source:

Promise

A promise implementation (Q). Functions which return this will specify 2 return arguments. These arguments map to the "onFulfilled" and "onRejected" values of the Promise.
Type:
  • Object
Properties:
Name Type Description
then function promise.then(onFulfilled, onRejected, onProgress)
catch function promise.catch(onRejected)
finally function promise.finally(callback)
done function promise.done(onFulfilled, onRejected, onProgress)
Source:

Events

MatrixClient"Call.incoming"

Fires whenever an incoming call arrives.
Parameters:
Name Type Description
call module:webrtc/call~MatrixCall The incoming call.
Source:
Example
matrixClient.on("Call.incoming", function(call){
  call.answer(); // auto-answer
});

MatrixClient"deleteRoom"

Fires whenever a Room is removed. This will fire when you forget a room. This event is experimental and may change.
Parameters:
Name Type Description
roomId string The deleted room ID.
Source:
Example
matrixClient.on("deleteRoom", function(roomId){
  // update UI from getRooms()
});

MatrixClient"deviceVerificationChanged"

Fires when a device is marked as verified/unverified/blocked/unblocked by MatrixClient.setDeviceVerified or MatrixClient.setDeviceBlocked.
Parameters:
Name Type Description
userId string the owner of the verified device
deviceId string the id of the verified device
Source:

MatrixClient"event"

Fires whenever the SDK receives a new event.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
Source:
Example
matrixClient.on("event", function(event){
  var sender = event.getSender();
});

MatrixClient"Room.accountData"

Fires whenever a room's account_data is updated.
Parameters:
Name Type Description
event event The account_data event
room Room The room whose account_data was updated.
Source:
Example
matrixClient.on("Room.accountData", function(event, room){
  if (event.getType() === "m.room.colorscheme") {
      applyColorScheme(event.getContents());
  }
});

MatrixClient"Room.localEchoUpdated"

Fires when the status of a transmitted event is updated.

When an event is first transmitted, a temporary copy of the event is inserted into the timeline, with a temporary event id, and a status of 'SENDING'.

Once the echo comes back from the server, the content of the event (MatrixEvent.event) is replaced by the complete event from the homeserver, thus updating its event id, as well as server-generated fields such as the timestamp. Its status is set to null.

Once the /send request completes, if the remote echo has not already arrived, the event is updated with a new event id and the status is set to 'SENT'. The server-generated fields are of course not updated yet.

If the /send fails, In this case, the event's status is set to 'NOT_SENT'. If it is later resent, the process starts again, setting the status to 'SENDING'. Alternatively, the message may be cancelled, which removes the event from the room, and sets the status to 'CANCELLED'.

This event is raised to reflect each of the transitions above.

Parameters:
Name Type Description
event MatrixEvent The matrix event which has been updated
room Room The room containing the redacted event
oldEventId string The previous event id (the temporary event id, except when updating a successfully-sent event when its echo arrives)
oldStatus EventStatus The previous event status.
Source:

MatrixClient"Room.name"

Fires whenever the name of a room is updated.
Parameters:
Name Type Description
room Room The room whose Room.name was updated.
Source:
Example
matrixClient.on("Room.name", function(room){
  var newName = room.name;
});

MatrixClient"Room.receipt"

Fires whenever a receipt is received for a room
Parameters:
Name Type Description
event event The receipt event
room Room The room whose receipts was updated.
Source:
Example
matrixClient.on("Room.receipt", function(event, room){
  var receiptContent = event.getContent();
});

MatrixClient"Room.redaction"

Fires when an event we had previously received is redacted. (Note this is *not* fired when the redaction happens before we receive the event).
Parameters:
Name Type Description
event MatrixEvent The matrix event which was redacted
room Room The room containing the redacted event
Source:

MatrixClient"Room.tags"

Fires whenever a room's tags are updated.
Parameters:
Name Type Description
event event The tags event
room Room The room whose Room.tags was updated.
Source:
Example
matrixClient.on("Room.tags", function(event, room){
  var newTags = event.getContent().tags;
  if (newTags["favourite"]) showStar(room);
});

MatrixClient"Room.timeline"

Fires whenever the timeline in a room is updated.
Parameters:
Name Type Attributes Description
event MatrixEvent The matrix event which caused this event to fire.
room Room <nullable>
The room, if any, whose timeline was updated.
toStartOfTimeline boolean True if this event was added to the start
removed boolean True if this event has just been removed from the timeline (beginning; oldest) of the timeline e.g. due to pagination.
data object more data about the event
Properties
Name Type Description
timeline module:event-timeline.EventTimeline the timeline the event was added to/removed from
liveEvent boolean true if the event was a real-time event added to the end of the live timeline
Source:
Example
matrixClient.on("Room.timeline",
                function(event, room, toStartOfTimeline, removed, data) {
  if (!toStartOfTimeline && data.liveEvent) {
    var messageToAppend = room.timeline.[room.timeline.length - 1];
  }
});

MatrixClient"Room.timelineReset"

Fires whenever the live timeline in a room is reset. When we get a 'limited' sync (for example, after a network outage), we reset the live timeline to be empty before adding the recent events to the new timeline. This event is fired after the timeline is reset, and before the new events are added.
Parameters:
Name Type Description
room Room The room whose live timeline was reset, if any
timelineSet EventTimelineSet timelineSet room whose live timeline was reset
Source:

MatrixClient"Room"

Fires whenever a new Room is added. This will fire when you are invited to a room, as well as when you join a room. This event is experimental and may change.
Parameters:
Name Type Description
room Room The newly created, fully populated room.
Source:
Example
matrixClient.on("Room", function(room){
  var roomId = room.roomId;
});

MatrixClient"Room"

Fires whenever new user-scoped account_data is added.
Parameters:
Name Type Description
event MatrixEvent The event describing the account_data just added
Source:
Example
matrixClient.on("accountData", function(event){
  myAccountData[event.type] = event.content;
});

MatrixClient"RoomMember.membership"

Fires whenever any room member's membership state changes.
Parameters:
Name Type Attributes Description
event MatrixEvent The matrix event which caused this event to fire.
member RoomMember The member whose RoomMember.membership changed.
oldMembership string <nullable>
The previous membership state. Null if it's a new member.
Source:
Example
matrixClient.on("RoomMember.membership", function(event, member, oldMembership){
  var newState = member.membership;
});

MatrixClient"RoomMember.name"

Fires whenever any room member's name changes.
Parameters:
Name Type Attributes Description
event MatrixEvent The matrix event which caused this event to fire.
member RoomMember The member whose RoomMember.name changed.
oldName string <nullable>
The previous name. Null if the member didn't have a name previously.
Source:
Example
matrixClient.on("RoomMember.name", function(event, member){
  var newName = member.name;
});

MatrixClient"RoomMember.powerLevel"

Fires whenever any room member's power level changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
member RoomMember The member whose RoomMember.powerLevel changed.
Source:
Example
matrixClient.on("RoomMember.powerLevel", function(event, member){
  var newPowerLevel = member.powerLevel;
  var newNormPowerLevel = member.powerLevelNorm;
});

MatrixClient"RoomMember.typing"

Fires whenever any room member's typing state changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
member RoomMember The member whose RoomMember.typing changed.
Source:
Example
matrixClient.on("RoomMember.typing", function(event, member){
  var isTyping = member.typing;
});

MatrixClient"RoomState.events"

Fires whenever the event dictionary in room state is updated.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
state RoomState The room state whose RoomState.events dictionary was updated.
Source:
Example
matrixClient.on("RoomState.events", function(event, state){
  var newStateEvent = event;
});

MatrixClient"RoomState.members"

Fires whenever a member in the members dictionary is updated in any way.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
state RoomState The room state whose RoomState.members dictionary was updated.
member RoomMember The room member that was updated.
Source:
Example
matrixClient.on("RoomState.members", function(event, state, member){
  var newMembershipState = member.membership;
});

MatrixClient"RoomState.newMember"

Fires whenever a member is added to the members dictionary. The RoomMember will not be fully populated yet (e.g. no membership state).
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
state RoomState The room state whose RoomState.members dictionary was updated with a new entry.
member RoomMember The room member that was added.
Source:
Example
matrixClient.on("RoomState.newMember", function(event, state, member){
  // add event listeners on 'member'
});

MatrixClient"Session.logged_out"

Fires whenever the login session the JS SDK is using is no longer valid and the user must log in again. NB. This only fires when action is required from the user, not when then login session can be renewed by using a refresh token.
Source:
Example
matrixClient.on("Session.logged_out", function(call){
  // show the login screen
});

MatrixClient"sync"

Fires whenever the SDK's syncing state is updated. The state can be one of:
  • PREPARED : The client has synced with the server at least once and is ready for methods to be called on it. This will be immediately followed by a state of SYNCING. This is the equivalent of "syncComplete" in the previous API.
  • SYNCING : The client is currently polling for new events from the server. This will be called after processing latest events from a sync.
  • ERROR : The client has had a problem syncing with the server. If this is called before PREPARED then there was a problem performing the initial sync. If this is called after PREPARED then there was a problem polling the server for updates. This may be called multiple times even if the state is already ERROR. This is the equivalent of "syncError" in the previous API.
  • RECONNECTING: The sync connedtion has dropped, but not in a way that should be considered erroneous.
  • STOPPED: The client has stopped syncing with server due to stopClient being called.
State transition diagram:
                                         +---->STOPPED
                                         |
             +----->PREPARED -------> SYNCING <--+
             |        ^                  ^       |
             |        |                  |       |
             |        |                  V       |
  null ------+        |  +-RECONNECTING<-+       |
             |        |  V                       |
             +------->ERROR ---------------------+

NB: 'null' will never be emitted by this event.
Transitions:
  • null -> PREPARED : Occurs when the initial sync is completed first time. This involves setting up filters and obtaining push rules.
  • null -> ERROR : Occurs when the initial sync failed first time.
  • ERROR -> PREPARED : Occurs when the initial sync succeeds after previously failing.
  • PREPARED -> SYNCING : Occurs immediately after transitioning to PREPARED. Starts listening for live updates rather than catching up.
  • SYNCING -> ERROR : Occurs the first time a client cannot perform a live update.
  • ERROR -> SYNCING : Occurs when the client has performed a live update after having previously failed.
  • ERROR -> ERROR : Occurs when the client has failed to sync for a second time or more.
  • SYNCING -> SYNCING : Occurs when the client has performed a live update. This is called after processing.
  • * -> STOPPED : Occurs once the client has stopped syncing or trying to sync after stopClient has been called.
Parameters:
Name Type Attributes Description
state string An enum representing the syncing state. One of "PREPARED", "SYNCING", "ERROR", "STOPPED".
prevState string <nullable>
An enum representing the previous syncing state. One of "PREPARED", "SYNCING", "ERROR", "STOPPED" or null.
data Object <nullable>
Data about this transition.
Properties
Name Type Description
err MatrixError The matrix error if state=ERROR.
Source:
Example
matrixClient.on("sync", function(state, prevState, data) {
  switch (state) {
    case "ERROR":
      // update UI to say "Connection Lost"
      break;
    case "SYNCING":
      // update UI to remove any "Connection Lost" message
      break;
    case "PREPARED":
      // the client instance is ready to be queried.
      var rooms = matrixClient.getRooms();
      break;
  }
});

MatrixClient"toDeviceEvent"

Fires whenever the SDK receives a new to-device event.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
Source:
Example
matrixClient.on("toDeviceEvent", function(event){
  var sender = event.getSender();
});

MatrixClient"User.avatarUrl"

Fires whenever any user's avatar URL changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
user User The user whose User.avatarUrl changed.
Source:
Example
matrixClient.on("User.avatarUrl", function(event, user){
  var newUrl = user.avatarUrl;
});

MatrixClient"User.currentlyActive"

Fires whenever any user's currentlyActive changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
user User The user whose User.currentlyActive changed.
Source:
Example
matrixClient.on("User.currentlyActive", function(event, user){
  var newCurrentlyActive = user.currentlyActive;
});

MatrixClient"User.displayName"

Fires whenever any user's display name changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
user User The user whose User.displayName changed.
Source:
Example
matrixClient.on("User.displayName", function(event, user){
  var newName = user.displayName;
});

MatrixClient"User.lastPresenceTs"

Fires whenever any user's lastPresenceTs changes, ie. whenever any presence event is received for a user.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
user User The user whose User.lastPresenceTs changed.
Source:
Example
matrixClient.on("User.lastPresenceTs", function(event, user){
  var newlastPresenceTs = user.lastPresenceTs;
});

MatrixClient"User.presence"

Fires whenever any user's presence changes.
Parameters:
Name Type Description
event MatrixEvent The matrix event which caused this event to fire.
user User The user whose User.presence changed.
Source:
Example
matrixClient.on("User.presence", function(event, user){
  var newPresence = user.presence;
});