Class: MatrixClient

client~MatrixClient(opts)

new MatrixClient(opts)

Construct a Matrix Client. Only directly construct this if you want to use custom modules. Normally, createClient should be used as it specifies 'sensible' defaults for these modules.
Parameters:
Name Type Description
opts Object The configuration options for this client.
Properties
Name Type Attributes Default Description
baseUrl string Required. The base URL to the client-server HTTP API.
idBaseUrl string Optional. The base identity server URL for identity server requests.
request function Required. The function to invoke for HTTP requests. The value of this property is typically require("request") as it returns a function which meets the required interface. See requestFunction for more information.
accessToken string The access_token for this user.
userId string The user ID for this user.
store Object <optional>
The data store to use. If not specified, this client will not store any HTTP responses.
deviceId string <optional>
A unique identifier for this device; used for tracking things like crypto keys and access tokens. If not specified, end-to-end crypto will be disabled.
sessionStore Object <optional>
A store to be used for end-to-end crypto session data. This should be a WebStorageSessionStore, or an object implementing the same interface. If not specified, end-to-end crypto will be disabled.
scheduler Object Optional. The scheduler to use. If not specified, this client will not retry requests on failure. This client will supply its own processing function to module:scheduler~MatrixScheduler#setProcessFunction.
queryParams Object Optional. Extra query parameters to append to all requests with this client. Useful for application services which require ?user_id=.
localTimeoutMs Number <optional>
Optional. The default maximum amount of time to wait before timing out HTTP requests. If not specified, there is no timeout.
useAuthorizationHeader boolean <optional>
false Set to true to use Authorization header instead of query param to send the access token to the server.
timelineSupport boolean <optional>
false Set to true to enable improved timeline support (getEventTimeline). It is disabled by default for compatibility with older clients - in particular to maintain support for back-paginating the live timeline after a '/sync' result with a gap.
cryptoStore module:crypto.store.base~CryptoStore crypto store implementation.
Source:

Extends

Methods

_createMessagesRequest(roomId, fromToken, limit, dir, timelineFilter) → {Promise}

Makes a request to /messages with the appropriate lazy loading filter set. XXX: if we do get rid of scrollback (as it's not used at the moment), we could inline this method again in paginateEventTimeline as that would then be the only call-site
Parameters:
Name Type Description
roomId string
fromToken string
limit number the maximum amount of events the retrieve
dir string 'f' or 'b'
timelineFilter Filter the timeline filter to pass
Source:
Returns:
Type
Promise

_requestTokenFromEndpoint(endpoint, params) → {module:client.Promise}

Internal utility function for requesting validation tokens from usage-specific requestToken endpoints.
Parameters:
Name Type Description
endpoint string The endpoint to send the request to
params object Parameters for the POST request
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

_storeClientOptions(opts) → {Promise}

store client options with boolean/string/numeric values to know in the next session what flags the sync data was created with (e.g. lazy loading)
Parameters:
Name Type Description
opts object the complete set of client options
Source:
Returns:
for store operation
Type
Promise

_wasLazyLoadingToggled(lazyLoadMembers) → {bool}

Is the lazy loading option different than in previous session?
Parameters:
Name Type Description
lazyLoadMembers bool current options for lazy loading
Source:
Returns:
whether or not the option has changed compared to the previous session
Type
bool

acceptGroupInvite(groupId, opts) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
opts Object Additional options to send alongside the acceptance.
Inherited From:
Source:
Returns:

addListener(event, listener) → {EventEmitter}

Parameters:
Name Type Description
event string The event to listen for.
listener function The function to invoke.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

addPushRule(scope, kind, ruleId, body, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
scope string
kind string
ruleId string
body Object
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

addRoomToGroup(groupId, roomId, isPublic) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
roomId string
isPublic bool Whether the room-group association is visible to non-members
Inherited From:
Source:
Returns:

addRoomToGroupSummary(groupId, roomId, categoryId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
roomId string
categoryId string Optional.
Inherited From:
Source:
Returns:

addThreePid(creds, bind, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
creds Object
bind boolean
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

addUserToGroupSummary(groupId, userId, roleId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
userId string
roleId string Optional.
Inherited From:
Source:
Returns:

backPaginateRoomEventsSearch(searchResults) → {module:client.Promise|Error}

Take a result from an earlier searchRoomEvents call, and backfill results.
Parameters:
Name Type Description
searchResults object the results object to be updated
Source:
Returns:
  • Resolves: updated result object
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    Error

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

Parameters:
Name Type Description
roomId string
userId string
reason string Optional.
callback module:client.callback Optional.
Source:
Returns:

cancelAndResendEventRoomKeyRequest(event)

Cancel a room key request for this event if one is ongoing and resend the request.
Parameters:
Name Type Description
event MatrixEvent event of which to cancel and resend the room key request.
Source:

cancelPendingEvent(event)

Cancel a queued or unsent event.
Parameters:
Name Type Description
event MatrixEvent Event to cancel
Source:
Throws:
Error if the event is not in QUEUED or NOT_SENT state

cancelUpload(promise) → {boolean}

Cancel a file upload in progress
Parameters:
Name Type Description
promise module:client.Promise The promise returned from uploadContent
Inherited From:
Source:
Returns:
true if canceled, otherwise false
Type
boolean

claimOneTimeKeys(devices, key_algorithmopt) → {module:client.Promise}

Claim one-time keys
Parameters:
Name Type Attributes Default Description
devices Array.<string> a list of [userId, deviceId] pairs
key_algorithm string <optional>
signed_curve25519 desired key type
Inherited From:
Source:
Returns:
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Type
module:client.Promise

clearStores() → {Promise}

Clear any data out of the persistent stores used by the client.
Source:
Returns:
Promise which resolves when the stores have been cleared.
Type
Promise

createAlias(alias, roomId, callback) → {module:client.Promise|module:http-api.MatrixError}

Create an alias to room ID mapping.
Parameters:
Name Type Description
alias string The room alias to create.
roomId string The room ID to link the alias to.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

createFilter(content) → {Filter|module:http-api.MatrixError}

Create a new filter.
Parameters:
Name Type Description
content Object The HTTP body for the request
Source:
Returns:

createGroup(content) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
content Object Request content
Properties
Name Type Description
localpart string The local part of the desired group ID
profile Object Group profile object
Inherited From:
Source:
Returns:
  • Resolves: Object with key group_id: id of the created group
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

createRoom(options, callback) → {module:client.Promise|module:http-api.MatrixError}

Create a new room.
Parameters:
Name Type Description
options Object a list of options to pass to the /createRoom API.
Properties
Name Type Description
room_alias_name string The alias localpart to assign to this room.
visibility string Either 'public' or 'private'.
invite Array.<string> A list of user IDs to invite to this room.
name string The name to give this room.
topic string The topic to give this room.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
  • Resolves: {room_id: {string}, room_alias: {string(opt)}}
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

deactivateAccount(auth, erase) → {module:client.Promise}

Deactivates the logged-in account. Obviously, further calls that require authorisation should fail after this method is called. The state of the MatrixClient object is not affected: it is up to the caller to either reset or destroy the MatrixClient after this method succeeds.
Parameters:
Name Type Description
auth object Optional. Auth data to supply for User-Interactive auth.
erase boolean Optional. If set, send as `erase` attribute in the JSON request body, indicating whether the account should be erased. Defaults to false.
Inherited From:
Source:
Returns:
Resolves: On success, the empty object
Type
module:client.Promise

deleteAlias(alias, callback) → {module:client.Promise|module:http-api.MatrixError}

Delete an alias to room ID mapping. This alias must be on your local server and you must have sufficient access to do this operation.
Parameters:
Name Type Description
alias string The room alias to delete.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

deleteDevice(device_id, auth) → {module:client.Promise|module:http-api.MatrixError}

Delete the given device
Parameters:
Name Type Description
device_id string device to delete
auth object Optional. Auth data to supply for User-Interactive auth.
Inherited From:
Source:
Returns:

deleteMultipleDevices(devices, auth) → {module:client.Promise|module:http-api.MatrixError}

Delete multiple device
Parameters:
Name Type Description
devices Array.<string> IDs of the devices to delete
auth object Optional. Auth data to supply for User-Interactive auth.
Inherited From:
Source:
Returns:

deletePushRule(scope, kind, ruleId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
scope string
kind string
ruleId string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

deleteRoomTag(roomId, tagName, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
tagName string name of room tag to be removed
callback module:client.callback Optional.
Source:
Returns:

deleteThreePid(medium, address) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
medium string The threepid medium (eg. 'email')
address string The threepid address (eg. 'bob@example.com') this must be as returned by getThreePids.
Inherited From:
Source:
Returns:
  • Resolves: The server response on success (generally the empty JSON object)
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

downloadKeys(userIds, forceDownload) → {Promise}

Download the keys for a list of users and stores the keys in the session store.
Parameters:
Name Type Description
userIds Array The users to fetch.
forceDownload bool Always download the keys even if cached.
Source:
Returns:
A promise which resolves to a map userId->deviceId->DeviceInfo.
Type
Promise

downloadKeysForUsers(userIds, optsopt) → {module:client.Promise}

Download device keys
Parameters:
Name Type Attributes Description
userIds Array.<string> list of users to get keys for
opts Object <optional>
Properties
Name Type Attributes Description
token string <optional>
sync token to pass in the query request, to help the HS give the most recent results
Inherited From:
Source:
Returns:
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Type
module:client.Promise

dropFromPresenceList(callback, userIds) → {module:client.Promise|module:http-api.MatrixError}

Drop users from the current user presence list.
Parameters:
Name Type Description
callback module:client.callback Optional.
userIds Array.<string>
Source:
Returns:

emit(event, listener) → {boolean}

Execute each of the listeners in order with the supplied arguments.
Parameters:
Name Type Description
event string The event to emit.
listener function The function to invoke.
Inherited From:
Source:
Returns:
true if event had listeners, false otherwise.
Type
boolean

exportRoomKeys() → {module:client.Promise}

Get a list containing all of the room keys This should be encrypted before returning it to the user.
Source:
Returns:
a promise which resolves to a list of session export objects
Type
module:client.Promise

fetchRoomEvent(roomId, eventId, callback) → {Promise|module:http-api.MatrixError}

Get an event in a room by its event id.
Parameters:
Name Type Description
roomId string
eventId string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

forceDiscardSession(roomId)

Forces the current outbound group session to be discarded such that another one will be created next time an event is sent.
Parameters:
Name Type Description
roomId string The ID of the room to discard the session for This should not normally be necessary.
Source:

forget(roomId, deleteRoom, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
deleteRoom boolean True to delete the room from the store on success. Default: true.
callback module:client.callback Optional.
Source:
Returns:

generateClientSecret() → {string}

Generates a random string suitable for use as a client secret. This method is experimental and may change.
Source:
Returns:
A new client secret
Type
string

getAccessToken() → (nullable) {String}

Get the access token associated with this account.
Inherited From:
Source:
Returns:
The access_token or null
Type
String

getAccountData(eventType) → (nullable) {object}

Get account data event of given type for the current user.
Parameters:
Name Type Description
eventType string The event type
Source:
Returns:
The contents of the given account data event
Type
object

getCanResetTimelineCallback() → (nullable) {function}

Get the callback set via `setCanResetTimelineCallback`.
Source:
Returns:
The callback or null
Type
function

getCasLoginUrl(redirectUrl) → {string}

Parameters:
Name Type Description
redirectUrl string The URL to redirect to after the HS authenticates with CAS.
Inherited From:
Source:
Returns:
The HS URL to hit to begin the CAS login process.
Type
string

getCurrentUploads() → {array}

Get a list of all file uploads in progress
Inherited From:
Source:
Returns:
Array of objects representing current uploads. Currently in progress is element 0. Keys: - promise: The promise associated with the upload - loaded: Number of bytes uploaded - total: Total number of bytes to upload
Type
array

getDeviceEd25519Key() → (nullable) {string}

Get the Ed25519 key for this device
Source:
Returns:
base64-encoded ed25519 key. Null if crypto is disabled.
Type
string

getDeviceId() → (nullable) {string}

Get the device ID of this client
Source:
Returns:
device ID
Type
string

getDevices() → {module:client.Promise|module:http-api.MatrixError}

Gets all devices recorded for the logged-in user
Inherited From:
Source:
Returns:

getDomain() → (nullable) {string}

Get the domain for this client's MXID
Source:
Returns:
Domain of this MXID
Type
string

getEventMapper() → {function}

Source:
Returns:
Type
function

getEventSenderDeviceInfo(event) → {Promise.<?module:crypto/deviceinfo>}

Get e2e information on the device that sent an event
Parameters:
Name Type Description
event MatrixEvent event to be checked
Source:
Returns:
Type
Promise.<?module:crypto/deviceinfo>

getEventTimeline(timelineSet, eventId) → {module:client.Promise}

Get an EventTimeline for the given event

If the EventTimelineSet object already has the given event in its store, the corresponding timeline will be returned. Otherwise, a /context request is made, and used to construct an EventTimeline.

Parameters:
Name Type Description
timelineSet EventTimelineSet The timelineSet to look for the event in
eventId string The ID of the event to look for
Source:
Returns:
Resolves: module:models/event-timeline~EventTimeline including the given event
Type
module:client.Promise

getFallbackAuthUrl(loginType, authSessionId) → {string}

Get the fallback URL to use for unknown interactive-auth stages.
Parameters:
Name Type Description
loginType string the type of stage being attempted
authSessionId string the auth session ID provided by the homeserver
Inherited From:
Source:
Returns:
HS URL to hit to for the fallback interface
Type
string

getFilter(userId, filterId, allowCached) → {module:client.Promise|module:http-api.MatrixError}

Retrieve a filter.
Parameters:
Name Type Description
userId string The user ID of the filter owner
filterId string The filter ID to retrieve
allowCached boolean True to allow cached filters to be returned. Default: True.
Source:
Returns:

getGlobalBlacklistUnverifiedDevices() → {boolean}

Source:
Returns:
whether to blacklist all unverified devices by default
Type
boolean

getGroup(groupId) → {Group}

Get the group for the given group ID. This function will return a valid group for any group for which a Group event has been emitted.
Parameters:
Name Type Description
groupId string The group ID
Source:
Returns:
The Group or null if the group is not known or there is no data store.
Type
Group

getGroupInvitedUsers(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

getGroupProfile(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

getGroupRooms(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

getGroups() → {Array.<Group>}

Retrieve all known groups.
Source:
Returns:
A list of groups, or an empty list if there is no data store.
Type
Array.<Group>

getGroupSummary(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

getGroupUsers(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

getHomeserverUrl() → {string}

Get the Homeserver URL of this client
Inherited From:
Source:
Returns:
Homeserver URL of this client
Type
string

getIdentityServerUrl(stripProto) → {string}

Get the Identity Server URL of this client
Parameters:
Name Type Description
stripProto boolean whether or not to strip the protocol from the URL
Inherited From:
Source:
Returns:
Identity Server URL of this client
Type
string

getIgnoredUsers() → {Array.<string>}

Gets the users that are ignored by this client
Source:
Returns:
The array of users that are ignored (empty if none)
Type
Array.<string>

getJoinedGroups() → {module:client.Promise|module:http-api.MatrixError}

Inherited From:
Source:
Returns:
  • Resolves: The groups to which the user is joined
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

getKeyChanges(oldToken, newToken) → {module:client.Promise}

Ask the server for a list of users who have changed their device lists between a pair of sync tokens
Parameters:
Name Type Description
oldToken string
newToken string
Inherited From:
Source:
Returns:
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Type
module:client.Promise

getMediaConfig(callback) → {module:client.Promise}

Get the config for the media repository.
Parameters:
Name Type Description
callback module:client.callback Optional.
Source:
Returns:
Resolves with an object containing the config.
Type
module:client.Promise

getNotifTimelineSet() → {EventTimelineSet}

Return the global notification EventTimelineSet, if any
Source:
Returns:
the globl notification EventTimelineSet
Type
EventTimelineSet

getOpenIdToken() → {module:client.Promise|module:http-api.MatrixError}

Gets a bearer token from the Home Server that the user can present to a third party in order to prove their ownership of the Matrix account they are logged into.
Source:
Returns:

getOrCreateFilter(filterName, filter) → {Promise.<String>}

Parameters:
Name Type Description
filterName string
filter Filter
Source:
Returns:
Filter ID
Type
Promise.<String>

getPresenceList(callback) → {module:client.Promise|module:http-api.MatrixError}

Retrieve current user presence list.
Parameters:
Name Type Description
callback module:client.callback Optional.
Source:
Returns:

getProfileInfo(userId, info, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
userId string
info string The kind of info to retrieve (e.g. 'displayname', 'avatar_url').
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

getPublicisedGroups(userIds) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
userIds Array.<string> List of user IDs
Inherited From:
Source:
Returns:
  • Resolves: Object as exmaple below { "users": { "@bob:example.com": { "+example:example.com" } } }
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

getPushActionsForEvent(event) → {module:pushprocessor~PushAction}

Obtain a dict of actions which should be performed for this event according to the push rules for this user. Caches the dict on the event.
Parameters:
Name Type Description
event MatrixEvent The event to get push actions for.
Source:
Returns:
A dict of actions to perform.
Type
module:pushprocessor~PushAction

getPushers(callback) → {module:client.Promise|module:http-api.MatrixError}

Gets all pushers registered for the logged-in user
Parameters:
Name Type Description
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
  • Resolves: Array of objects representing pushers
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

getPushRules(callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

getRoom(roomId) → {Room}

Get the room for the given room ID. This function will return a valid room for any room for which a Room event has been emitted. Note in particular that other events, eg. RoomState.members will be emitted for a room before this function will return the given room.
Parameters:
Name Type Description
roomId string The room ID
Source:
Returns:
The Room or null if it doesn't exist or there is no data store.
Type
Room

getRoomDirectoryVisibility(roomId, callback) → {module:client.Promise|module:http-api.MatrixError}

Get the visibility of a room in the current HS's room directory
Parameters:
Name Type Description
roomId string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

getRoomIdForAlias(alias, callback) → {module:client.Promise|module:http-api.MatrixError}

Get room info for the given alias.
Parameters:
Name Type Description
alias string The room alias to resolve.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
  • Resolves: Object with room_id and servers.
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

getRoomPushRule(scope, roomId) → {object}

Get the room-kind push rule associated with a room.
Parameters:
Name Type Description
scope string "global" or device-specific.
roomId string the id of the room.
Source:
Returns:
the rule or undefined.
Type
object

getRooms() → {Array.<Room>}

Retrieve all known rooms.
Source:
Returns:
A list of rooms, or an empty list if there is no data store.
Type
Array.<Room>

getRoomTags(roomId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
callback module:client.callback Optional.
Source:
Returns:

getScheduler() → (nullable) {module:scheduler~MatrixScheduler}

Return the provided scheduler, if any.
Source:
Returns:
The scheduler or null
Type
module:scheduler~MatrixScheduler

getStateEvent(roomId, eventType, stateKey, callback) → {module:client.Promise|module:http-api.MatrixError}

Retrieve a state event.
Parameters:
Name Type Description
roomId string
eventType string
stateKey string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

getStoredDevice(userId, deviceId) → {Promise.<?module:crypto-deviceinfo>}

Get the stored device key for a user id and device id
Parameters:
Name Type Description
userId string the user to list keys for.
deviceId string unique identifier for the device
Source:
Returns:
device or null
Type
Promise.<?module:crypto-deviceinfo>

getStoredDevicesForUser(userId) → {Promise.<Array.<module:crypto-deviceinfo>>}

Get the stored device keys for a user id
Parameters:
Name Type Description
userId string the user to list keys for.
Source:
Returns:
list of devices
Type
Promise.<Array.<module:crypto-deviceinfo>>

getSyncState() → (nullable) {string}

Get the current sync state.
Source:
See:
  • module:client~MatrixClient#event:"sync"
Returns:
the sync state, which may be null.
Type
string

getSyncStateData() → (nullable) {Object}

Returns the additional data object associated with the current sync state, or null if there is no such data. Sync errors, if available, are put in the 'error' key of this object.
Source:
Returns:
Type
Object

getThirdpartyLocation(protocol, params) → {module:client.Promise}

Get information on how a specific place on a third party protocol may be reached.
Parameters:
Name Type Description
protocol string The protocol given in getThirdpartyProtocols()
params object Protocol-specific parameters, as given in th response to getThirdpartyProtocols()
Inherited From:
Source:
Returns:
Resolves to the result object
Type
module:client.Promise

getThirdpartyProtocols() → {module:client.Promise}

Get the third party protocols that can be reached using this HS
Inherited From:
Source:
Returns:
Resolves to the result object
Type
module:client.Promise

getThreePids(callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

getTurnServers() → {Array.<Object>}

Get the TURN servers for this home server.
Source:
Returns:
The servers or an empty list.
Type
Array.<Object>

getUrlPreview(url, ts, callback) → {module:client.Promise|module:http-api.MatrixError}

Get a preview of the given URL as of (roughly) the given point in time, described as an object with OpenGraph keys and associated values. Attributes may be synthesized where actual OG metadata is lacking. Caches results to prevent hammering the server.
Parameters:
Name Type Description
url string The URL to get preview data for
ts Number The preferred point in time that the preview should describe (ms since epoch). The preview returned will either be the most recent one preceding this timestamp if available, or failing that the next most recent available preview.
callback module:client.callback Optional.
Source:
Returns:
  • Resolves: Object of OG metadata.
    Type
    module:client.Promise
  • Rejects: with an error response. May return synthesized attributes if the URL lacked OG meta.
    Type
    module:http-api.MatrixError

getUser(userId) → (nullable) {User}

Retrieve a user.
Parameters:
Name Type Description
userId string The user ID to retrieve.
Source:
Returns:
A user or null if there is no data store or the user does not exist.
Type
User

getUserId() → (nullable) {string}

Get the user-id of the logged-in user
Source:
Returns:
MXID for the logged-in user, or null if not logged in
Type
string

getUserIdLocalpart() → (nullable) {string}

Get the local part of the current user ID e.g. "foo" in "@foo:bar".
Source:
Returns:
The user ID localpart or null.
Type
string

getUsers() → {Array.<User>}

Retrieve all known users.
Source:
Returns:
A list of users, or an empty list if there is no data store.
Type
Array.<User>

getVisibleRooms() → {Array.<Room>}

Retrieve all rooms that should be displayed to the user This is essentially getRooms() with some rooms filtered out, eg. old versions of rooms that have been replaced or (in future) other rooms that have been marked at the protocol level as not to be displayed to the user.
Source:
Returns:
A list of rooms, or an empty list if there is no data store.
Type
Array.<Room>

importRoomKeys(keys) → {module:client.Promise}

Import a list of room keys previously exported by exportRoomKeys
Parameters:
Name Type Description
keys Array.<Object> a list of session export objects
Source:
Returns:
a promise which resolves when the keys have been imported
Type
module:client.Promise

initCrypto()

Initialise support for end-to-end encryption in this client You should call this method after creating the matrixclient, but *before* calling `startClient`, if you want to support end-to-end encryption. It will return a Promise which will resolve when the crypto layer has been successfully initialised.
Source:

invite(roomId, userId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
userId string
callback module:client.callback Optional.
Source:
Returns:

inviteByEmail(roomId, email, callback) → {module:client.Promise|module:http-api.MatrixError}

Invite a user to a room based on their email address.
Parameters:
Name Type Description
roomId string The room to invite the user to.
email string The email address to invite.
callback module:client.callback Optional.
Source:
Returns:

inviteByThreePid(roomId, medium, address, callback) → {module:client.Promise|module:http-api.MatrixError}

Invite a user to a room based on a third-party identifier.
Parameters:
Name Type Description
roomId string The room to invite the user to.
medium string The medium to invite the user e.g. "email".
address string The address for the specified medium.
callback module:client.callback Optional.
Source:
Returns:

inviteToPresenceList(callback, userIds) → {module:client.Promise|module:http-api.MatrixError}

Add users to the current user presence list.
Parameters:
Name Type Description
callback module:client.callback Optional.
userIds Array.<string>
Source:
Returns:

inviteUserToGroup(groupId, userId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
userId string
Inherited From:
Source:
Returns:

isCryptoEnabled() → {boolean}

Is end-to-end crypto enabled for this client.
Source:
Returns:
True if end-to-end is enabled.
Type
boolean

isEventSenderVerified(event) → {boolean}

Check if the sender of an event is verified
Parameters:
Name Type Description
event MatrixEvent event to be checked
Source:
Returns:
true if the sender of this event has been verified using setDeviceVerified.
Type
boolean

isGuest() → {boolean}

Return whether the client is configured for a guest account.
Source:
Returns:
True if this is a guest access_token (or no token is supplied).
Type
boolean

isLoggedIn() → {boolean}

Inherited From:
Source:
Returns:
true if there is a valid access_token for this client.
Type
boolean

isRoomEncrypted(roomId) → {bool}

Whether encryption is enabled for a room.
Parameters:
Name Type Description
roomId string the room id to query.
Source:
Returns:
whether encryption is enabled.
Type
bool

isUserIgnored(userId) → {boolean}

Gets whether or not a specific user is being ignored by this client.
Parameters:
Name Type Description
userId string the user ID to check
Source:
Returns:
true if the user is ignored, false otherwise
Type
boolean

isUsernameAvailable(username) → {module:client.Promise}

Check whether a username is available prior to registration. An error response indicates an invalid/unavailable username.
Parameters:
Name Type Description
username string The username to check the availability of.
Inherited From:
Source:
Returns:
Resolves: to `true`.
Type
module:client.Promise

joinGroup(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

joinRoom(roomIdOrAlias, opts, callback) → {module:client.Promise|module:http-api.MatrixError}

Join a room. If you have already joined the room, this will no-op.
Parameters:
Name Type Description
roomIdOrAlias string The room ID or room alias to join.
opts Object Options when joining the room.
Properties
Name Type Description
syncRoom boolean True to do a room initial sync on the resulting room. If false, the returned Room object will have no current state. Default: true.
inviteSignUrl boolean If the caller has a keypair 3pid invite, the signing URL is passed in this parameter.
callback module:client.callback Optional.
Source:
Returns:

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

Parameters:
Name Type Description
roomId string
userId string
reason string Optional.
callback module:client.callback Optional.
Source:
Returns:

leave(roomId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
callback module:client.callback Optional.
Source:
Returns:

leaveGroup(groupId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
Inherited From:
Source:
Returns:

login(loginType, data, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
loginType string
data Object
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

loginFlows(callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

loginWithPassword(user, password, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
user string
password string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

loginWithSAML2(relayState, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
relayState string URL Callback after SAML2 Authentication
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

loginWithToken(token, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
token string Login token previously received from homeserver
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

logout(callback) → {module:client.Promise}

Logs out the current session. Obviously, further calls that require authorisation should fail after this method is called. The state of the MatrixClient object is not affected: it is up to the caller to either reset or destroy the MatrixClient after this method succeeds.
Parameters:
Name Type Description
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
Resolves: On success, the empty object
Type
module:client.Promise

lookupThreePid(medium, address, callback) → {module:client.Promise|module:http-api.MatrixError}

Looks up the public Matrix ID mapping for a given 3rd party identifier from the Identity Server
Parameters:
Name Type Description
medium string The medium of the threepid, eg. 'email'
address string The textual address of the threepid
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
  • Resolves: A threepid mapping object or the empty object if no mapping exists
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

makeTxnId() → {string}

Make up a new transaction id
Inherited From:
Source:
Returns:
a new, unique, transaction id
Type
string

members(roomId, includeMembership, excludeMembership, atEventId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
includeMembership string the membership type to include in the response
excludeMembership string the membership type to exclude from the response
atEventId string the id of the event for which moment in the timeline the members should be returned for
callback module:client.callback Optional.
Inherited From:
Source:
Returns:
  • Resolves: dictionary of userid to profile information
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

mxcUrlToHttp(mxcUrl, width, height, resizeMethod, allowDirectLinks) → (nullable) {string}

Turn an MXC URL into an HTTP one. This method is experimental and may change.
Parameters:
Name Type Description
mxcUrl string The MXC URL
width Number The desired width of the thumbnail.
height Number The desired height of the thumbnail.
resizeMethod string The thumbnail resize method to use, either "crop" or "scale".
allowDirectLinks Boolean If true, return any non-mxc URLs directly. Fetching such URLs will leak information about the user to anyone they share a room with. If false, will return null for such URLs.
Source:
Returns:
the avatar URL or null.
Type
string

on(event, listener) → {EventEmitter}

Adds a listener to the end of the listeners array for the specified event. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added multiple times.
Parameters:
Name Type Description
event string The event to listen for.
listener function The function to invoke.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

once(event, listener) → {EventEmitter}

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.
Parameters:
Name Type Description
event string The event to listen for.
listener function The function to invoke.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

paginateEventTimeline(eventTimeline, optsopt) → {module:client.Promise}

Take an EventTimeline, and back/forward-fill results.
Parameters:
Name Type Attributes Description
eventTimeline module:models/event-timeline~EventTimeline timeline object to be updated
opts Object <optional>
Properties
Name Type Attributes Default Description
backwards bool <optional>
false true to fill backwards, false to go forwards
limit number <optional>
30 number of events to request
Source:
Returns:
Resolves to a boolean: false if there are no events and we reached either end of the timeline; else true.
Type
module:client.Promise

peekInRoom(roomId) → {module:client.Promise|module:http-api.MatrixError}

Peek into a room and receive updates about the room. This only works if the history visibility for the room is world_readable.
Parameters:
Name Type Description
roomId String The room to attempt to peek into.
Source:
Returns:

publicRooms(options, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
options Object Options for this request
Properties
Name Type Description
server string The remote server to query for the room list. Optional. If unspecified, get the local home server's public room list.
limit number Maximum number of entries to return
since string Token to paginate from
filter object Filter parameters
Properties
Name Type Description
generic_search_term string String to search for
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

redactEvent(roomId, eventId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
eventId string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

register(username, password, sessionId, auth, bindThreepids, guestAccessToken, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
username string
password string
sessionId string
auth Object
bindThreepids Object Set key 'email' to true to bind any email threepid uses during registration in the ID server. Set 'msisdn' to true to bind msisdn.
guestAccessToken string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

registerGuest(optsopt, callback) → {module:client.Promise|module:http-api.MatrixError}

Register a guest account.
Parameters:
Name Type Attributes Description
opts Object <optional>
Registration options
Properties
Name Type Description
body Object JSON HTTP body to provide.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

registerRequest(data, kindopt, callbackopt) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Attributes Description
data Object parameters for registration request
kind string <optional>
type of user to register. may be "guest"
callback module:client.callback <optional>
Inherited From:
Source:
Returns:

removeAllListeners(event) → {EventEmitter}

Removes all listeners, or those of the specified event. It's not a good idea to remove listeners that were added elsewhere in the code, especially when it's on an emitter that you didn't create (e.g. sockets or file streams).
Parameters:
Name Type Description
event string Optional. The event to remove listeners for.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

removeListener(event, listener) → {EventEmitter}

Remove a listener from the listener array for the specified event. Caution: changes array indices in the listener array behind the listener.
Parameters:
Name Type Description
event string The event to listen for.
listener function The function to invoke.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

removeRoomFromGroup(groupId, roomId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
roomId string
Inherited From:
Source:
Returns:

removeRoomFromGroupSummary(groupId, roomId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
roomId string
Inherited From:
Source:
Returns:

removeUserFromGroup(groupId, userId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
userId string
Inherited From:
Source:
Returns:

removeUserFromGroupSummary(groupId, userId) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
userId string
Inherited From:
Source:
Returns:

requestAdd3pidEmailToken(email, clientSecret, sendAttempt, nextLink) → {module:client.Promise}

Requests an email verification token for the purposes of adding a third party identifier to an account. This API proxies the Identity Server /validate/email/requestToken API, adding specific behaviour for the addition of email addresses to an account. Specifically, if an account with the given email address already exists, it will either send an email to the address informing them of this or return M_THREEPID_IN_USE (which one is up to the Home Server). requestEmailToken calls the equivalent API directly on the ID server, therefore bypassing the email addition specific logic.
Parameters:
Name Type Description
email string As requestEmailToken
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

requestAdd3pidMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink) → {module:client.Promise}

Requests a text message verification token for the purposes of adding a third party identifier to an account. This API proxies the Identity Server /validate/email/requestToken API, adding specific behaviour for the addition of phone numbers to an account, as requestAdd3pidEmailToken.
Parameters:
Name Type Description
phoneCountry string As requestRegisterMsisdnToken
phoneNumber string As requestRegisterMsisdnToken
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

requestEmailToken(email, clientSecret, sendAttempt, nextLink, callback) → {module:client.Promise|module:http-api.MatrixError}

Requests an email verification token directly from an Identity Server. Note that the Home Server offers APIs to proxy this API for specific situations, allowing for better feedback to the user.
Parameters:
Name Type Description
email string The email address to request a token for
clientSecret string A secret binary string generated by the client. It is recommended this be around 16 ASCII characters.
sendAttempt number If an identity server sees a duplicate request with the same sendAttempt, it will not send another email. To request another email to be sent, use a larger value for the sendAttempt param as was used in the previous request.
nextLink string Optional If specified, the client will be redirected to this link after validation.
callback module:client.callback Optional.
Inherited From:
Source:
Throws:
Error if No ID server is set
Returns:

requestPasswordEmailToken(email, clientSecret, sendAttempt, nextLink, callback) → {module:client.Promise}

Requests an email verification token for the purposes of resetting the password on an account. This API proxies the Identity Server /validate/email/requestToken API, adding specific behaviour for the password resetting. Specifically, if no account with the given email address exists, it may either return M_THREEPID_NOT_FOUND or send an email to the address informing them of this (which one is up to the Home Server). requestEmailToken calls the equivalent API directly on the ID server, therefore bypassing the password reset specific logic.
Parameters:
Name Type Description
email string As requestEmailToken
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
callback module:client.callback Optional. As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

requestPasswordMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink) → {module:client.Promise}

Requests a text message verification token for the purposes of resetting the password on an account. This API proxies the Identity Server /validate/email/requestToken API, adding specific behaviour for the password resetting, as requestPasswordEmailToken.
Parameters:
Name Type Description
phoneCountry string As requestRegisterMsisdnToken
phoneNumber string As requestRegisterMsisdnToken
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

requestRegisterEmailToken(email, clientSecret, sendAttempt, nextLink) → {module:client.Promise}

Requests an email verification token for the purposes of registration. This API proxies the Identity Server /validate/email/requestToken API, adding registration-specific behaviour. Specifically, if an account with the given email address already exists, it will either send an email to the address informing them of this or return M_THREEPID_IN_USE (which one is up to the Home Server). requestEmailToken calls the equivalent API directly on the ID server, therefore bypassing the registration-specific logic. Parameters and return value are as for requestEmailToken
Parameters:
Name Type Description
email string As requestEmailToken
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

requestRegisterMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink) → {module:client.Promise}

Requests a text message verification token for the purposes of registration. This API proxies the Identity Server /validate/msisdn/requestToken API, adding registration-specific behaviour, as with requestRegisterEmailToken.
Parameters:
Name Type Description
phoneCountry string The ISO 3166-1 alpha-2 code for the country in which phoneNumber should be parsed relative to.
phoneNumber string The phone number, in national or international format
clientSecret string As requestEmailToken
sendAttempt number As requestEmailToken
nextLink string As requestEmailToken
Source:
Returns:
Resolves: As requestEmailToken
Type
module:client.Promise

resendEvent(event, room) → {module:client.Promise|module:http-api.MatrixError}

Resend an event.
Parameters:
Name Type Description
event MatrixEvent The event to resend.
room Room Optional. The room the event is in. Will update the timeline entry if provided.
Source:
Returns:

resetNotifTimelineSet()

Reset the notifTimelineSet entirely, paginating in some historical notifs as a starting point for subsequent pagination.
Source:

resolveRoomAlias(roomAlias, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomAlias string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

retryImmediately() → {boolean}

Retry a backed off syncing request immediately. This should only be used when the user explicitly attempts to retry their lost connection.
Source:
Returns:
True if this resulted in a request being retried.
Type
boolean

roomInitialSync(roomId, limit, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
limit Number
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

roomState(roomId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

scrollback(room, limit, callback) → {module:client.Promise|module:http-api.MatrixError}

Retrieve older messages from the given room and put them in the timeline. If this is called multiple times whilst a request is ongoing, the same Promise will be returned. If there was a problem requesting scrollback, there will be a small delay before another request can be made (to prevent tight-looping when there is no connection).
Parameters:
Name Type Description
room Room The room to get older messages in.
limit Integer Optional. The maximum number of previous events to pull in. Default: 30.
callback module:client.callback Optional.
Source:
Returns:
  • Resolves: Room. If you are at the beginning of the timeline, Room.oldState.paginationToken will be null.
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError
Perform a server-side search.
Parameters:
Name Type Description
opts Object
Properties
Name Type Description
next_batch string the batch token to pass in the query string
body Object the JSON object to pass to the request body.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

searchMessageText(opts, callback) → {module:client.Promise|module:http-api.MatrixError}

Perform a server-side search for messages containing the given text.
Parameters:
Name Type Description
opts Object Options for the search.
Properties
Name Type Attributes Description
query string The text to query.
keys string <optional>
The keys to search on. Defaults to all keys. One of "content.body", "content.name", "content.topic".
callback module:client.callback Optional.
Source:
Returns:

searchRoomEvents(opts) → {module:client.Promise|module:http-api.MatrixError}

Perform a server-side search for room events. The returned promise resolves to an object containing the fields: * {number} count: estimate of the number of results * {string} next_batch: token for back-pagination; if undefined, there are no more results * {Array} highlights: a list of words to highlight from the stemming algorithm * {Array} results: a list of results Each entry in the results list is a {module:models/search-result.SearchResult}.
Parameters:
Name Type Description
opts Object
Properties
Name Type Description
term string the term to search for
filter Object a JSON filter object to pass in the request
Source:
Returns:

searchUserDirectory(opts) → {module:client.Promise}

Query the user directory with a term matching user IDs, display names and domains.
Parameters:
Name Type Description
opts object options
Properties
Name Type Description
term string the term with which to search.
limit number the maximum number of results to return. The server will apply a limit if unspecified.
Inherited From:
Source:
Returns:
Resolves: an array of results.
Type
module:client.Promise

sendEmoteMessage(roomId, body, txnId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
txnId string Optional.
callback module:client.callback Optional.
Source:
Returns:

sendEvent(roomId, eventType, content, txnId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
eventType string
content Object
txnId string Optional.
callback module:client.callback Optional.
Source:
Returns:

sendHtmlEmote(roomId, body, htmlBody, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
htmlBody string
callback module:client.callback Optional.
Source:
Returns:

sendHtmlMessage(roomId, body, htmlBody, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
htmlBody string
callback module:client.callback Optional.
Source:
Returns:

sendHtmlNotice(roomId, body, htmlBody, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
htmlBody string
callback module:client.callback Optional.
Source:
Returns:

sendImageMessage(roomId, url, info, text, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
url string
info Object
text string
callback module:client.callback Optional.
Source:
Returns:

sendMessage(roomId, content, txnId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
content Object
txnId string Optional.
callback module:client.callback Optional.
Source:
Returns:

sendNotice(roomId, body, txnId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
txnId string Optional.
callback module:client.callback Optional.
Source:
Returns:

sendReadReceipt(event, callback) → {module:client.Promise|module:http-api.MatrixError}

Send a read receipt.
Parameters:
Name Type Description
event Event The event that has been read.
callback module:client.callback Optional.
Source:
Returns:

sendReceipt(event, receiptType, callback) → {module:client.Promise|module:http-api.MatrixError}

Send a receipt.
Parameters:
Name Type Description
event Event The event being acknowledged
receiptType string The kind of receipt e.g. "m.read"
callback module:client.callback Optional.
Source:
Returns:

sendStateEvent(roomId, eventType, content, stateKey, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
eventType string
content Object
stateKey string
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

sendStickerMessage(roomId, url, info, text, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
url string
info Object
text string
callback module:client.callback Optional.
Source:
Returns:

sendTextMessage(roomId, body, txnId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
body string
txnId string Optional.
callback module:client.callback Optional.
Source:
Returns:

sendToDevice(eventType, contentMap, txnIdopt) → {module:client.Promise}

Send an event to a specific list of devices
Parameters:
Name Type Attributes Description
eventType string type of event to send
contentMap Object.<string, Object.<string, Object>> content to send. Map from user_id to device_id to content object.
txnId string <optional>
transaction id. One will be made up if not supplied.
Inherited From:
Source:
Returns:
Resolves to the result object
Type
module:client.Promise

sendTyping(roomId, isTyping, timeoutMs, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
isTyping boolean
timeoutMs Number
callback module:client.callback Optional.
Source:
Returns:

setAccountData(eventType, contents, callback) → {module:client.Promise|module:http-api.MatrixError}

Set account data event for the current user.
Parameters:
Name Type Description
eventType string The event type
contents Object the contents object for the event
callback module:client.callback Optional.
Source:
Returns:

setAvatarUrl(url, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
url string
callback module:client.callback Optional.
Source:
Returns:

setDeviceBlocked(userId, deviceId, blockedopt) → {Promise}

Mark the given device as blocked/unblocked
Parameters:
Name Type Attributes Description
userId string owner of the device
deviceId string unique identifier for the device
blocked boolean <optional>
whether to mark the device as blocked. defaults to 'true'.
Source:
Fires:
Returns:
Type
Promise

setDeviceDetails(device_id, body) → {module:client.Promise|module:http-api.MatrixError}

Update the given device
Parameters:
Name Type Description
device_id string device to update
body Object body of request
Inherited From:
Source:
Returns:

setDeviceKnown(userId, deviceId, knownopt) → {Promise}

Mark the given device as known/unknown
Parameters:
Name Type Attributes Description
userId string owner of the device
deviceId string unique identifier for the device
known boolean <optional>
whether to mark the device as known. defaults to 'true'.
Source:
Fires:
Returns:
Type
Promise

setDeviceVerified(userId, deviceId, verifiedopt) → {Promise}

Mark the given device as verified
Parameters:
Name Type Attributes Description
userId string owner of the device
deviceId string unique identifier for the device
verified boolean <optional>
whether to mark the device as verified. defaults to 'true'.
Source:
Fires:
Returns:
Type
Promise

setDisplayName(name, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
name string
callback module:client.callback Optional.
Source:
Returns:

setForceTURN(forceTURN)

Set whether VoIP calls are forced to use only TURN candidates. This is the same as the forceTURN option when creating the client.
Parameters:
Name Type Description
forceTURN bool True to force use of TURN servers
Source:

setGlobalBlacklistUnverifiedDevices(value)

Set the global override for whether the client should ever send encrypted messages to unverified devices. This provides the default for rooms which do not specify a value.
Parameters:
Name Type Description
value boolean whether to blacklist all unverified devices by default
Source:

setGroupJoinPolicy(groupId, policy) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
policy object The join policy for the group. Must include at least a 'type' field which is 'open' if anyone can join the group the group without prior approval, or 'invite' if an invite is required to join.
Inherited From:
Source:
Returns:

setGroupProfile(groupId, profile) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
profile Object The group profile object
Properties
Name Type Attributes Description
name string <optional>
Name of the group
avatar_url string <optional>
MXC avatar URL
short_description string <optional>
A short description of the room
long_description string <optional>
A longer HTML description of the room
Inherited From:
Source:
Returns:

setGroupPublicity(groupId, isPublic) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
groupId string
isPublic bool Whether the user's membership of this group is made public
Inherited From:
Source:
Returns:

setGuest(isGuest)

Set whether this client is a guest account. This method is experimental and may change without warning.
Parameters:
Name Type Description
isGuest boolean True if this is a guest account.
Source:

setGuestAccess(roomId, opts) → {module:client.Promise|module:http-api.MatrixError}

Set r/w flags for guest access in a room.
Parameters:
Name Type Description
roomId string The room to configure guest access in.
opts Object Options
Properties
Name Type Description
allowJoin boolean True to allow guests to join this room. This implicitly gives guests write access. If false or not given, guests are explicitly forbidden from joining the room.
allowRead boolean True to set history visibility to be world_readable. This gives guests read access *from this point forward*. If false or not given, history visibility is not modified.
Source:
Returns:

setIgnoredUsers(userIds, callbackopt) → {module:client.Promise|module:http-api.MatrixError}

Sets the users that the current user should ignore.
Parameters:
Name Type Attributes Description
userIds Array.<string> the user IDs to ignore
callback module:client.callback <optional>
Optional.
Source:
Returns:

setMaxListeners(n) → {EventEmitter}

By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This function allows that to be increased. Set to zero for unlimited.
Parameters:
Name Type Description
n Number The max number of listeners.
Inherited From:
Source:
Returns:
for call chaining.
Type
EventEmitter

setNotifTimelineSet(notifTimelineSet)

Set the global notification EventTimelineSet
Parameters:
Name Type Description
notifTimelineSet EventTimelineSet
Source:

setPassword(authDict, newPassword, callback) → {module:client.Promise|module:http-api.MatrixError}

Make a request to change your password.
Parameters:
Name Type Description
authDict Object
newPassword string The new desired password.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setPowerLevel(roomId, userId, powerLevel, event, callback) → {module:client.Promise|module:http-api.MatrixError}

Set a user's power level.
Parameters:
Name Type Description
roomId string
userId string
powerLevel Number
event MatrixEvent
callback module:client.callback Optional.
Source:
Returns:

setPresence(opts, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
opts Object Options to apply
Properties
Name Type Description
presence string One of "online", "offline" or "unavailable"
status_msg string The status message to attach.
callback module:client.callback Optional.
Source:
Throws:
If 'presence' isn't a valid presence enum value.
Returns:

setProfileInfo(info, data, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
info string The kind of info to set (e.g. 'avatar_url')
data Object The JSON object to set.
callback module:client.callback Optional.
Source:
Returns:

setPusher(pusher, callback) → {module:client.Promise|module:http-api.MatrixError}

Adds a new pusher or updates an existing pusher
Parameters:
Name Type Description
pusher Object Object representing a pusher
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setPushRuleActions(scope, kind, ruleId, actions, callback) → {module:client.Promise|module:http-api.MatrixError}

Set the actions for a push notification rule.
Parameters:
Name Type Description
scope string
kind string
ruleId string
actions array
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setPushRuleEnabled(scope, kind, ruleId, enabled, callback) → {module:client.Promise|module:http-api.MatrixError}

Enable or disable a push notification rule.
Parameters:
Name Type Description
scope string
kind string
ruleId string
enabled boolean
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setRoomAccountData(roomId, eventType, content, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
eventType string event type to be set
content object event content
callback module:client.callback Optional.
Source:
Returns:

setRoomDirectoryVisibility(roomId, visibility, callback) → {module:client.Promise|module:http-api.MatrixError}

Set the visbility of a room in the current HS's room directory
Parameters:
Name Type Description
roomId string
visibility string "public" to make the room visible in the public directory, or "private" to make it invisible.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setRoomDirectoryVisibilityAppService(networkId, roomId, visibility, callback) → {module:client.Promise|module:http-api.MatrixError}

Set the visbility of a room bridged to a 3rd party network in the current HS's room directory.
Parameters:
Name Type Description
networkId string the network ID of the 3rd party instance under which this room is published under.
roomId string
visibility string "public" to make the room visible in the public directory, or "private" to make it invisible.
callback module:client.callback Optional.
Inherited From:
Source:
Returns:

setRoomEncryption(roomId, config) → {Promise}

Enable end-to-end encryption for a room.
Parameters:
Name Type Description
roomId string The room ID to enable encryption in.
config object The encryption config for the room.
Source:
Returns:
A promise that will resolve when encryption is set up.
Type
Promise

setRoomMutePushRule(scope, roomId, mute) → {module:client.Promise|module:http-api.MatrixError}

Set a room-kind muting push rule in a room. The operation also updates MatrixClient.pushRules at the end.
Parameters:
Name Type Description
scope string "global" or device-specific.
roomId string the id of the room.
mute string the mute state.
Source:
Returns:

setRoomName(roomId, name, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
name string
callback module:client.callback Optional.
Source:
Returns:

setRoomReadMarkers(roomId, eventId, rrEvent) → {module:client.Promise}

Set a marker to indicate the point in a room before which the user has read every event. This can be retrieved from room account data (the event type is `m.fully_read`) and displayed as a horizontal line in the timeline that is visually distinct to the position of the user's own read receipt.
Parameters:
Name Type Description
roomId string ID of the room that has been read
eventId string ID of the event that has been read
rrEvent string the event tracked by the read receipt. This is here for convenience because the RR and the RM are commonly updated at the same time as each other. The local echo of this receipt will be done if set. Optional.
Source:
Returns:
Resolves: the empty object, {}.
Type
module:client.Promise

setRoomReadMarkersHttpRequest(roomId, rmEventId, rrEventId) → {module:client.Promise}

Set a marker to indicate the point in a room before which the user has read every event. This can be retrieved from room account data (the event type is `m.fully_read`) and displayed as a horizontal line in the timeline that is visually distinct to the position of the user's own read receipt.
Parameters:
Name Type Description
roomId string ID of the room that has been read
rmEventId string ID of the event that has been read
rrEventId string ID of the event tracked by the read receipt. This is here for convenience because the RR and the RM are commonly updated at the same time as each other. Optional.
Inherited From:
Source:
Returns:
Resolves: the empty object, {}.
Type
module:client.Promise

setRoomTag(roomId, tagName, metadata, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
tagName string name of room tag to be set
metadata object associated with that tag to be stored
callback module:client.callback Optional.
Source:
Returns:

setRoomTopic(roomId, topic, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
topic string
callback module:client.callback Optional.
Source:
Returns:

startClient(optsopt)

High level helper method to begin syncing and poll for new events. To listen for these events, add a listener for module:client~MatrixClient#event:"event" via module:client~MatrixClient#on. Alternatively, listen for specific state change events.
Parameters:
Name Type Attributes Description
opts Object <optional>
Options to apply when syncing.
Properties
Name Type Attributes Description
initialSyncLimit Number <optional>
The event limit= to apply to initial sync. Default: 8.
includeArchivedRooms Boolean <optional>
True to put archived=true on the /initialSync request. Default: false.
resolveInvitesToProfiles Boolean <optional>
True to do /profile requests on every invite event if the displayname/avatar_url is not known for this user ID. Default: false.
pendingEventOrdering String <optional>
Controls where pending messages appear in a room's timeline. If "chronological", messages will appear in the timeline when the call to sendEvent was made. If "detached", pending messages will appear in a separate list, accessbile via module:models/room#getPendingEvents. Default: "chronological".
pollTimeout Number <optional>
The number of milliseconds to wait on /sync. Default: 30000 (30 seconds).
filter Filter <optional>
The filter to apply to /sync calls. This will override the opts.initialSyncLimit, which would normally result in a timeline limit filter.
disablePresence Boolean <optional>
True to perform syncing without automatically updating presence.
lazyLoadMembers Boolean <optional>
True to not load all membership events during initial sync but fetch them when needed by calling `loadOutOfBandMembers` This will override the filter option at this moment.
Source:

stopClient()

High level helper method to stop the client from polling and allow a clean shutdown.
Source:

stopPeeking()

Stop any ongoing room peeking.
Source:

submitMsisdnToken(sid, clientSecret, token) → {module:client.Promise|module:http-api.MatrixError}

Submits an MSISDN token to the identity server This is used when submitting the code sent by SMS to a phone number. The ID server has an equivalent API for email but the js-sdk does not expose this, since email is normally validated by the user clicking a link rather than entering a code.
Parameters:
Name Type Description
sid string The sid given in the response to requestToken
clientSecret string A secret binary string generated by the client. This must be the same value submitted in the requestToken call.
token string The token, as enetered by the user.
Inherited From:
Source:
Throws:
Error if No ID server is set
Returns:
  • Resolves: Object, currently with no parameters.
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

supportsVoip() → {boolean}

Check if the runtime environment supports VoIP calling.
Source:
Returns:
True if VoIP is supported.
Type
boolean

syncLeftRooms() → {module:client.Promise|module:http-api.MatrixError}

Populate the store with rooms the user has left.
Source:
Returns:
  • Resolves: TODO - Resolved when the rooms have been added to the data store.
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

turnServer(callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
callback module:client.callback Optional.
Source:
Returns:

unban(roomId, userId, callback) → {module:client.Promise|module:http-api.MatrixError}

Parameters:
Name Type Description
roomId string
userId string
callback module:client.callback Optional.
Source:
Returns:

updateGroupRoomVisibility(groupId, roomId, isPublic) → {module:client.Promise|module:http-api.MatrixError}

Configure the visibility of a room-group association.
Parameters:
Name Type Description
groupId string
roomId string
isPublic bool Whether the room-group association is visible to non-members
Inherited From:
Source:
Returns:

upgradeRoom(roomId, newVersion) → {module:client.Promise|module:http-api.MatrixError}

Upgrades a room to a new protocol version
Parameters:
Name Type Description
roomId string
newVersion string The target version to upgrade to
Inherited From:
Source:
Returns:
  • Resolves: Object with key 'replacement_room'
    Type
    module:client.Promise
  • Rejects: with an error response.
    Type
    module:http-api.MatrixError

uploadContent(file, opts) → {module:client.Promise}

Upload a file to the media repository on the home server.
Parameters:
Name Type Description
file object The object to upload. On a browser, something that can be sent to XMLHttpRequest.send (typically a File). Under node.js, a a Buffer, String or ReadStream.
opts object options object
Properties
Name Type Attributes Description
name string <optional>
Name to give the file on the server. Defaults to file.name.
includeFilename boolean <optional>
if false will not send the filename, e.g for encrypted file uploads where filename leaks are undesirable. Defaults to true.
type string <optional>
Content-type for the upload. Defaults to file.type, or applicaton/octet-stream.
rawResponse boolean <optional>
Return the raw body, rather than parsing the JSON. Defaults to false (except on node.js, where it defaults to true for backwards compatibility).
onlyContentUri boolean <optional>
Just return the content URI, rather than the whole body. Defaults to false (except on browsers, where it defaults to true for backwards compatibility). Ignored if opts.rawResponse is true.
callback function <optional>
Deprecated. Optional. The callback to invoke on success/failure. See the promise return values for more information.
progressHandler function <optional>
Optional. Called when a chunk of data has been uploaded, with an object containing the fields `loaded` (number of bytes transferred) and `total` (total size, if known).
Inherited From:
Source:
Returns:
Resolves to response object, as determined by this.opts.onlyData, opts.rawResponse, and opts.onlyContentUri. Rejects with an error (usually a MatrixError).
Type
module:client.Promise

uploadKeys() → {object}

Upload the device keys to the homeserver.
Source:
Returns:
A promise that will resolve when the keys are uploaded.
Type
object

uploadKeysRequest(content, optsopt, callbackopt) → {module:client.Promise}

Upload keys
Parameters:
Name Type Attributes Description
content Object body of upload request
opts Object <optional>
Properties
Name Type Attributes Description
device_id string <optional>
explicit device_id to use for upload (default is to use the same as that used during auth).
callback module:client.callback <optional>
Inherited From:
Source:
Returns:
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Type
module:client.Promise