Documentation
Tutorials
Appservice (bridge) usage Bot usage Encryption Room upgrades

Class

MatrixClient

MatrixClient(homeserverUrl, accessToken, storage, cryptoStore)

A client that is capable of interacting with a matrix homeserver.
Constructor

# new MatrixClient(homeserverUrl, accessToken, storage, cryptoStore)

Creates a new matrix client
Parameters:
Name Type Default Description
homeserverUrl string The homeserver's client-server API URL
accessToken string The access token for the homeserver
storage IStorageProvider null The storage provider to use. Defaults to MemoryStorageProvider.
cryptoStore ICryptoStorageProvider null Optional crypto storage provider to use. If not supplied, end-to-end encryption will not be functional in this client.

View Source MatrixClient.ts, line 46

Classes

MatrixClient
MatrixClient

Members

# adminApis

Gets the admin API access class.

View Source MatrixClient.ts, line 179

# contentScannerInstance

The Content Scanner API instance for this client. This is set if `opts.enableContentScanner` is true. The `downloadContent` and `crypto.decryptMedia` methods automatically go via the content scanner when this is set.

View Source MatrixClient.ts, line 77

MatrixContentScannerClient

# contentScannerInstance

The Content Scanner API instance for this client. This is set if `opts.enableContentScanner` is true. The `downloadContent` and `crypto.decryptMedia` methods automatically go via the content scanner when this is set.

View Source MatrixClient.ts, line 2316

# crypto

The crypto manager instance for this client. Generally speaking, this shouldn't need to be accessed but is made available. Will be null/undefined if crypto is not possible.

View Source MatrixClient.ts, line 71

CryptoClient

# crypto

The crypto manager instance for this client. Generally speaking, this shouldn't need to be accessed but is made available. Will be null/undefined if crypto is not possible.

View Source MatrixClient.ts, line 2308

# dms

The DM manager instance for this client.

View Source MatrixClient.ts, line 81

DMs

# dms

The DM manager instance for this client.

View Source MatrixClient.ts, line 2322

# metrics

The metrics instance for this client

View Source MatrixClient.ts, line 155

# metrics

Assigns a new metrics instance, overwriting the old one.

View Source MatrixClient.ts, line 162

# persistTokenAfterSync

Set this to true to have the client only persist the sync token after the sync has been processed successfully. Note that if this is true then when the sync loop throws an error the client will not persist a token.

View Source MatrixClient.ts, line 103

# protected persistTokenAfterSync

Set this to true to have the client only persist the sync token after the sync has been processed successfully. Note that if this is true then when the sync loop throws an error the client will not persist a token.

View Source MatrixClient.ts, line 2329

# storageProvider

The storage provider for this client. Direct access is usually not required.

View Source MatrixClient.ts, line 149

# syncingPresence

The presence status to use while syncing. The valid values are "online" to set the account as online, "offline" to set the user as offline, "unavailable" for marking the user away, and null for not setting an explicit presence (the default). Has no effect if the client is not syncing. Does not apply until the next sync request.

View Source MatrixClient.ts, line 58

PresenceState | null

# syncingPresence

The presence status to use while syncing. The valid values are "online" to set the account as online, "offline" to set the user as offline, "unavailable" for marking the user away, and null for not setting an explicit presence (the default). Has no effect if the client is not syncing. Does not apply until the next sync request.

View Source MatrixClient.ts, line 2292

# syncingTimeout

The number of milliseconds to wait for new events for on the next sync. Has no effect if the client is not syncing. Does not apply until the next sync request.

View Source MatrixClient.ts, line 64

# syncingTimeout

The number of milliseconds to wait for new events for on the next sync. Has no effect if the client is not syncing. Does not apply until the next sync request.

View Source MatrixClient.ts, line 2299

# unstableApis

Gets the unstable API access class. This is generally not recommended to be used by clients.

View Source MatrixClient.ts, line 172

Methods

# addPreprocessor(preprocessor) → {void}

Adds a preprocessor to the event pipeline. When this client encounters an event, it will try to run it through the preprocessors it can in the order they were added.
Parameters:
Name Type Description
preprocessor IPreprocessor the preprocessor to add

View Source MatrixClient.ts, line 2420

void

# adminApis() → {AdminApis}

Gets the admin API access class.

View Source MatrixClient.ts, line 2376

The admin API access class.
AdminApis

# banUser(userId, roomId, reasonnullable) → {Promise.<any>}

Bans a user from a room.
Parameters:
Name Type Attributes Description
userId string the user ID to ban
roomId string the room ID to set the ban in
reason string <nullable>
 optional reason for the ban

View Source MatrixClient.ts, line 2656

resolves when completed
Promise.<any>

# async calculatePowerLevelChangeBoundsOn(targetUserId, roomId) → {Promise.<PowerLevelBounds>}

Determines the boundary conditions for this client's ability to change another user's power level in a given room. This will identify the maximum possible level this client can change the user to, and if that change could even be possible. If the returned object indicates that the client can change the power level of the user, the client is able to set the power level to any value equal to or less than the maximum value.
Parameters:
Name Type Description
targetUserId string The user ID to compare against.
roomId string The room ID to compare within.

View Source MatrixClient.ts, line 3135

The bounds of the client's ability to change the user's power level.
Promise.<PowerLevelBounds>

# async checkOneTimeKeyCounts() → {Promise.<OTKCounts>}

Gets the current One Time Key counts.

View Source MatrixClient.ts, line 3270

Resolves to the One Time Key counts.
Promise.<OTKCounts>

# async claimOneTimeKeys(userDeviceMap, federationTimeoutMs) → {Promise.<OTKClaimResponse>}

Claims One Time Keys for a set of user devices, returning those keys. The caller is expected to verify and validate the returned keys. Failures with federation are reported in the returned object.
Parameters:
Name Type Description
userDeviceMap Record.<string, Record.<string, OTKAlgorithm>> The map of user IDs to device IDs to OTKAlgorithm to request a claim for.
federationTimeoutMs number The default timeout for claiming keys over federation. Defaults to 10 seconds.

View Source MatrixClient.ts, line 3322

Promise.<OTKClaimResponse>

# createRoom(properties) → {Promise.<string>}

Creates a room. See the RoomCreateOptions interface for more information on what to provide for `properties`. Note that creating a room may cause the bot/appservice to raise a join event.
Parameters:
Name Type Description
properties RoomCreateOptions the properties of the room.

View Source MatrixClient.ts, line 3088

resolves to the room ID that represents the room
Promise.<string>

# createRoomAlias(alias, roomId) → {Promise}

Adds a new room alias to the room directory
Parameters:
Name Type Description
alias string The alias to add (eg: "#my-room:matrix.org")
roomId string The room ID to add the alias to

View Source MatrixClient.ts, line 2582

resolves when the alias has been added
Promise

# async createSpace(opts) → {Promise.<Space>}

Creates a Space room.
Parameters:
Name Type Description
opts SpaceCreateOptions The creation options.

View Source MatrixClient.ts, line 3241

Resolves to the created space.
Promise.<Space>

# deleteRoomAlias(alias) → {Promise}

Removes a room alias from the room directory
Parameters:
Name Type Description
alias string The alias to remove

View Source MatrixClient.ts, line 2590

resolves when the alias has been deleted
Promise

# disableKeyBackup() → {Promise.<void>}

Disable backing up of room keys.

View Source MatrixClient.ts, line 3377

Promise.<void>

# doRequest(method, endpoint, qs, body, timeout, raw, contentType, noEncoding) → {Promise.<any>}

Performs a web request to the homeserver, applying appropriate authorization headers for this client.
Parameters:
Name Type Description
method "GET" | "POST" | "PUT" | "DELETE" The HTTP method to use in the request
endpoint string The endpoint to call. For example: "/_matrix/client/v3/account/whoami"
qs any The query string to send. Optional.
body any The request body to send. Optional. Will be converted to JSON unless the type is a Buffer.
timeout number The number of milliseconds to wait before timing out.
raw boolean If true, the raw response will be returned instead of the response body.
contentType string The content type to send. Only used if the `body` is a Buffer.
noEncoding string Set to true to disable encoding, and return a Buffer. Defaults to false

View Source MatrixClient.ts, line 3414

Resolves to the response (body), rejected if a non-2xx status code was returned.
Promise.<any>

# async doesServerSupportAnyOneVersion(versions) → {Promise.<boolean>}

Determines if the server supports at least one of the given specification versions or not.
Parameters:
Name Type Description
versions Array.<string> The versions to look for. Eg: ["v1.1"]

View Source MatrixClient.ts, line 2464

Resolves to true if the server supports any of the versions, false otherwise.
Promise.<boolean>

# async doesServerSupportUnstableFeature(feature) → {Promise.<boolean>}

Determines if the server supports a given unstable feature flag. Useful for determining if the server can support an unstable MSC.
Parameters:
Name Type Description
feature string The feature name to look for.

View Source MatrixClient.ts, line 2446

Resolves to true if the server supports the flag, false otherwise.
Promise.<boolean>

# async doesServerSupportVersion(version) → {Promise.<boolean>}

Determines if the server supports a given version of the specification or not.
Parameters:
Name Type Description
version string The version to look for. Eg: "v1.1"

View Source MatrixClient.ts, line 2455

Resolves to true if the server supports the version, false otherwise.
Promise.<boolean>

# async downloadContent(mxcUrl, allowRemote) → {Promise.<{data: Buffer, contentType: string}>}

Download content from the homeserver's media repository. Note that this will not automatically decrypt media as it cannot determine if the media is encrypted.
Parameters:
Name Type Description
mxcUrl string The MXC URI for the content.
allowRemote string Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. This is IGNORED if the content scanner is configured, as the API has no compatible option.

View Source MatrixClient.ts, line 3196

Resolves to the downloaded content.
Promise.<{data: Buffer, contentType: string}>

# enableKeyBackup(info) → {Promise.<void>}

Enable backing up of room keys.
Parameters:
Name Type Description
info IKeyBackupInfoRetrieved The configuration for key backup behaviour, as returned by getKeyBackupVersion.

View Source MatrixClient.ts, line 3370

Resolves when complete.
Promise.<void>

# exportRoomKeysForSession(roomId, sessionId)

Exports a set of keys for a given session.
Parameters:
Name Type Description
roomId The room ID for the session.
sessionId The session ID.

View Source MatrixClient.ts, line 3386

An array of session keys.

# forgetRoom(roomId) → {Promise.<{}>}

Forgets the given room
Parameters:
Name Type Description
roomId string the room ID to forget

View Source MatrixClient.ts, line 2918

Resolves when forgotten
Promise.<{}>

# async getAccountData(eventType) → {Promise.<any>}

Retrieves content from account data.
Parameters:
Name Type Description
eventType string The type of account data to retrieve.

View Source MatrixClient.ts, line 2481

Resolves to the content of that account data.
Promise.<any>

# getAllRoomMembers(roomId, atToken) → {Promise.<Array.<MembershipEvent>>}

Gets all room members in the room, optionally at a given point in time.
Parameters:
Name Type Description
roomId string The room ID to get members of.
atToken string Optional batch token to get members at. Leave falsy for "now".

View Source MatrixClient.ts, line 2878

Resolves to the member events in the room.
Promise.<Array.<MembershipEvent>>

# async getCapabilities() → {Promise.<MatrixCapabilities>}

Get the set of capabilites for the authenticated client.

View Source MatrixClient.ts, line 2428

Resolves to the server's supported versions.
Promise.<MatrixCapabilities>

# getDirectoryVisibility(roomId) → {Promise.<("public"|"private")>}

Gets the visibility of a room in the directory.
Parameters:
Name Type Description
roomId string The room ID to query the visibility of

View Source MatrixClient.ts, line 2607

The visibility of the room
Promise.<("public"|"private")>

# async getEvent(roomId, eventId) → {Promise.<any>}

Gets an event for a room. If the event is encrypted, and the client supports encryption, and the room is encrypted, then this will return a decrypted event.
Parameters:
Name Type Description
roomId string the room ID to get the event in
eventId string the event ID to look up

View Source MatrixClient.ts, line 2707

resolves to the found event
Promise.<any>

# async getEventContext(roomId, eventId, limit) → {Promise.<EventContext>}

Gets the context surrounding an event.
Parameters:
Name Type Description
roomId string The room ID to get the context in.
eventId string The event ID to get the context of.
limit number The maximum number of events to return on either side of the event.

View Source MatrixClient.ts, line 2782

The context of the event
Promise.<EventContext>

# async getEventNearestToTimestamp(roomId, ts, dir)

Get the nearest event to a given timestamp, either forwards or backwards.
Parameters:
Name Type Description
roomId The room ID to get the context in.
ts The event ID to get the context of.
dir The maximum number of events to return on either side of the event.

View Source MatrixClient.ts, line 2793

The ID and origin server timestamp of the event.

# async getIdentityServerClient(identityServerName) → {Promise.<IdentityClient>}

Acquires an identity server client for communicating with an identity server. Note that this will automatically do the login portion to establish a usable token with the identity server provided, but it will not automatically accept any terms of service. The identity server name provided will in future be resolved to a server address - for now that resolution is assumed to be prefixing the name with `https://`.
Parameters:
Name Type Description
identityServerName string The domain of the identity server to connect to.

View Source MatrixClient.ts, line 2403

Resolves to a prepared identity client.
Promise.<IdentityClient>

# getJoinedRoomMembers(roomId) → {Promise.<string>}

Gets the joined members in a room. The client must be in the room to make this request.
Parameters:
Name Type Description
roomId string The room ID to get the joined members of.

View Source MatrixClient.ts, line 2844

The joined user IDs in the room
Promise.<string>

# async getJoinedRoomMembersWithProfiles(roomId) → {Object}

Gets the joined members in a room, as an object mapping userIds to profiles. The client must be in the room to make this request.
Parameters:
Name Type Description
roomId string The room ID to get the joined members of.

View Source MatrixClient.ts, line 2853

The joined user IDs in the room as an object mapped to a set of profiles.
Object

# getJoinedRooms() → {Promise.<Array.<string>>}

Gets a list of joined room IDs

View Source MatrixClient.ts, line 2836

resolves to a list of room IDs the client participates in
Promise.<Array.<string>>

# async getKeyBackupVersion() → {Promise.<(IKeyBackupInfoRetrieved|null)>}

Get information about the latest room key backup version.

View Source MatrixClient.ts, line 3342

Resolves to the retrieved key backup info, or null if there is no existing backup.
Promise.<(IKeyBackupInfoRetrieved|null)>

# async getOpenIDConnectToken() → {Promise.<OpenIDConnectToken>}

Retrieves an OpenID Connect token from the homeserver for the current user.

View Source MatrixClient.ts, line 2472

Resolves to the token.
Promise.<OpenIDConnectToken>

# async getOwnDevices() → {Promise.<Array.<OwnUserDevice>>}

Gets a device list for the client's own account, with metadata. The devices are not verified in this response, but should be active on the account.

View Source MatrixClient.ts, line 3307

Resolves to the active devices on the account.
Promise.<Array.<OwnUserDevice>>

# async getPresenceStatus() → {Promise.<Presence>}

Gets the presence information for the current user.

View Source MatrixClient.ts, line 2543

Resolves to the presence status of the user.
Promise.<Presence>

# async getPresenceStatusFor(userId) → {Promise.<Presence>}

Gets the presence information for a given user.
Parameters:
Name Type Description
userId string The user ID to look up the presence of.

View Source MatrixClient.ts, line 2552

Resolves to the presence status of the user.
Promise.<Presence>

# async getPublishedAlias(roomIdOrAlias) → {Promise.<string>}

Gets a published alias for the given room. These are supplied by the room admins and should point to the room, but may not. This is primarily intended to be used in the context of rendering a mention (pill) for a room.
Parameters:
Name Type Description
roomIdOrAlias string The room ID or alias to get an alias for.

View Source MatrixClient.ts, line 2573

Resolves to a published room alias, or falsey if none found.
Promise.<string>

# getRawEvent(roomId, eventId) → {Promise.<any>}

Gets an event for a room. Returned as a raw event.
Parameters:
Name Type Description
roomId string the room ID to get the event in
eventId string the event ID to look up

View Source MatrixClient.ts, line 2716

resolves to the found event
Promise.<any>

# async getRelationsForEvent(roomId, eventId, relationTypenullable, eventTypenullable) → {Promise.<{chunk: Array.<any>}>}

Get relations for a given event.
Parameters:
Name Type Attributes Description
roomId string The room ID to for the given event.
eventId string The event ID to list relations for.
relationType string <nullable>
 The type of relations (e.g. `m.room.member`) to filter for. Optional.
eventType string <nullable>
 The type of event to look for (e.g. `m.room.member`). Optional.

View Source MatrixClient.ts, line 3398

Resolves to an object containing the chunk of relations
Promise.<{chunk: Array.<any>}>

# async getRoomAccountData(eventType, roomId) → {Promise.<any>}

Retrieves content from room account data.
Parameters:
Name Type Description
eventType string The type of room account data to retrieve.
roomId string The room to read the account data from.

View Source MatrixClient.ts, line 2491

Resolves to the content of that account data.
Promise.<any>

# async getRoomCreateEvent(roomId)

Get the m.room.create event for a room, using the cached value if stored by the client.
Parameters:
Name Type Description
roomId The room ID

View Source MatrixClient.ts, line 3098

If the room does not exist, or you are not able to access the room.
A create event.

# getRoomMembers(roomId, batchToken, membership, notMembership) → {Promise.<Array.<MembershipEvent>>}

Gets the membership events of users in the room. Defaults to all membership types, though this can be controlled with the membership and notMembership arguments. To change the point in time, use the batchToken.
Parameters:
Name Type Description
roomId string The room ID to get members in.
batchToken string The point in time to get members at (or null for 'now')
membership Array.<string> The membership kinds to search for.
notMembership Array.<string> The membership kinds to not search for.
See:
  • getRoomMembersByMembership
  • getRoomMembersWithoutMembership
  • getAllRoomMembers

View Source MatrixClient.ts, line 2869

Resolves to the membership events of the users in the room.
Promise.<Array.<MembershipEvent>>

# getRoomMembersByMembership(roomId, membership, atTokennullable) → {Promise.<Array.<MembershipEvent>>}

Gets the membership events of users in the room which have a particular membership type. To change the point in time the server should return membership events at, use `atToken`.
Parameters:
Name Type Attributes Description
roomId string The room ID to get members in.
membership Membership The membership to search for.
atToken string <nullable>
 Optional batch token to use, or null for "now".

View Source MatrixClient.ts, line 2889

Resolves to the membership events of the users in the room.
Promise.<Array.<MembershipEvent>>

# async getRoomMembersWithoutMembership(roomId, notMembership, atTokennullable) → {Promise.<Array.<MembershipEvent>>}

Gets the membership events of users in the room which lack a particular membership type. To change the point in time the server should return membership events at, use `atToken`.
Parameters:
Name Type Attributes Description
roomId string The room ID to get members in.
notMembership Membership The membership to NOT search for.
atToken string <nullable>
 Optional batch token to use, or null for "now".

View Source MatrixClient.ts, line 2901

Resolves to the membership events of the users in the room.
Promise.<Array.<MembershipEvent>>

# getRoomState(roomId) → {Promise.<Array.<any>>}

Gets the room state for the given room. Returned as raw events.
Parameters:
Name Type Description
roomId string the room ID to get state for

View Source MatrixClient.ts, line 2724

resolves to the room's state
Promise.<Array.<any>>

# getRoomStateEvent(roomId, type, stateKey)

Gets a state event for a given room of a given type under the given state key.
Parameters:
Name Type Description
roomId the room ID
type the event type
stateKey the state key
Deprecated:
  • Use getRoomStateEventContent instead.

View Source MatrixClient.ts, line 2747

If the event could not be found or you do not have access to the room.
resolves to the state event

# async getRoomStateEventBody(roomId, type, stateKey)

Gets a state event's full event body for a given room of a given type under the given state key.
Parameters:
Name Type Description
roomId the room ID
type the event type
stateKey the state key

View Source MatrixClient.ts, line 2771

If the event could not be found or you do not have access to the room.
resolves to the state event body

# async getRoomStateEventContent(roomId, type, stateKey)

Gets a state event's `content` for a given room of a given type under the given state key.
Parameters:
Name Type Description
roomId the room ID
type the event type
stateKey the state key.

View Source MatrixClient.ts, line 2759

If the event could not be found or you do not have access to the room.
resolves to the state event content

# getRoomStateEvents(roomId, type, stateKey) → {Promise.<(any|Array.<any>)>}

Gets the state events for a given room of a given type under the given state key.
Parameters:
Name Type Description
roomId string the room ID
type string the event type
stateKey String the state key, falsey if not needed
Deprecated:
  • It is not possible to get an array of events - use getRoomStateEventContent instead

View Source MatrixClient.ts, line 2735

resolves to the state event(s)
Promise.<(any|Array.<any>)>

# async getRoomUpgradeHistory(roomId) → {Promise.<{previous: Array.<RoomReference>, newer: Array.<RoomReference>}>}

Determines the upgrade history for a given room as a doubly-linked list styled structure. Given a room ID in the history of upgrades, the resulting `previous` array will hold any rooms which are older than the given room. The resulting `newer` array will hold any rooms which are newer versions of the room. Both arrays will be defined, but may be empty individually. Element zero of each will always be the nearest to the given room ID and the last element will be the furthest from the room. The given room will never be in either array.
Parameters:
Name Type Description
roomId string the room ID to get the history of

View Source MatrixClient.ts, line 3232

Resolves to the room's upgrade history
Promise.<{previous: Array.<RoomReference>, newer: Array.<RoomReference>}>

# async getSafeAccountData(eventType, defaultContent) → {Promise.<any>}

Retrieves content from account data. If the account data request throws an error, this simply returns the default provided.
Parameters:
Name Type Description
eventType string The type of account data to retrieve.
defaultContent any The default value. Defaults to null.

View Source MatrixClient.ts, line 2502

Resolves to the content of that account data, or the default.
Promise.<any>

# async getSafeRoomAccountData(eventType, roomId, defaultContent) → {Promise.<any>}

Retrieves content from room account data. If the account data request throws an error, this simply returns the default provided.
Parameters:
Name Type Description
eventType string The type of room account data to retrieve.
roomId string The room to read the account data from.
defaultContent any The default value. Defaults to null.

View Source MatrixClient.ts, line 2514

Resolves to the content of that room account data, or the default.
Promise.<any>

# async getServerVersions() → {Promise.<ServerVersions>}

Retrieves the server's supported specification versions and unstable features.

View Source MatrixClient.ts, line 2436

Resolves to the server's supported versions.
Promise.<ServerVersions>

# async getSpace(roomIdOrAlias) → {Promise.<Space>}

Gets a Space. This API does not work with unstable spaces (e.g. org.matrix.msc.1772.space)
Parameters:
Name Type Description
roomIdOrAlias string

View Source MatrixClient.ts, line 3253

If the room is not a space or there was an error
Resolves to the space.
Promise.<Space>

# async getUserDevices(userIds, federationTimeoutMs) → {Promise.<MultiUserDeviceListResponse>}

Gets unverified device lists for the given users. The caller is expected to validate and verify the device lists, including that the returned devices belong to the claimed users. Failures with federation are reported in the returned object. Users which did not fail a federation lookup but have no devices will not appear in either the failures or in the returned devices. See https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-keys-query for more information.
Parameters:
Name Type Description
userIds Array.<string> The user IDs to query.
federationTimeoutMs number The default timeout for requesting devices over federation. Defaults to 10 seconds.

View Source MatrixClient.ts, line 3298

Resolves to the device list/errors for the requested user IDs.
Promise.<MultiUserDeviceListResponse>

# async getUserId() → {Promise.<string>}

Gets the current user ID for this client

View Source MatrixClient.ts, line 2673

The user ID of this client
Promise.<string>

# getUserProfile(userId) → {Promise.<any>}

Gets the profile for a given user
Parameters:
Name Type Description
userId string the user ID to lookup

View Source MatrixClient.ts, line 2801

the profile of the user
Promise.<any>

# async getWhoAmI() → {Promise.<IWhoAmI>}

Gets the user's information from the server directly.

View Source MatrixClient.ts, line 2681

The "who am I" response.
Promise.<IWhoAmI>

# impersonateUserId(userId, deviceId) → {void}

Sets a user ID to impersonate as. This will assume that the access token for this client is for an application service, and that the userId given is within the reach of the application service. Setting this to null will stop future impersonation. The user ID is assumed to already be valid
Parameters:
Name Type Description
userId string The user ID to masquerade as, or `null` to clear masquerading.
deviceId string Optional device ID to impersonate under the given user, if supported by the server. Check the whoami response after setting.

View Source MatrixClient.ts, line 2389

void

# inviteUser(userId, roomId) → {Promise.<any>}

Invites a user to a room.
Parameters:
Name Type Description
userId string the user ID to invite
roomId string the room ID to invite the user to

View Source MatrixClient.ts, line 2636

resolves when completed
Promise.<any>

# async joinRoom(roomIdOrAlias, viaServers) → {Promise.<string>}

Joins the given room
Parameters:
Name Type Description
roomIdOrAlias string the room ID or alias to join
viaServers Array.<string> the server names to try and join through

View Source MatrixClient.ts, line 2829

resolves to the joined room ID
Promise.<string>

# kickUser(userId, roomId, reasonnullable) → {Promise.<any>}

Kicks a user from a room.
Parameters:
Name Type Attributes Description
userId string the user ID to kick
roomId string the room ID to kick the user in
reason string <nullable>
 optional reason for the kick

View Source MatrixClient.ts, line 2646

resolves when completed
Promise.<any>

# leaveRoom(roomId, reasonopt) → {Promise.<any>}

Leaves the given room
Parameters:
Name Type Attributes Description
roomId string the room ID to leave
reason string <optional>
 Optional reason to be included as the reason for leaving the room.

View Source MatrixClient.ts, line 2910

resolves when left
Promise.<any>

# lookupRoomAlias(roomAlias) → {Promise.<RoomDirectoryLookupResponse>}

Does a room directory lookup for a given room alias
Parameters:
Name Type Description
roomAlias string the room alias to look up in the room directory

View Source MatrixClient.ts, line 2627

resolves to the room's information
Promise.<RoomDirectoryLookupResponse>

# metrics(metrics)

Assigns a new metrics instance, overwriting the old one.
Parameters:
Name Type Description
metrics Metrics The new metrics instance.

View Source MatrixClient.ts, line 2361

# async mxcToHttp(mxc) → {string}

Converts a MXC URI to an HTTP URL.
Parameters:
Name Type Description
mxc string The MXC URI to convert

View Source MatrixClient.ts, line 3158

The HTTP URL for the content.
string

# async mxcToHttpThumbnail(mxc, width, height, method) → {string}

Converts a MXC URI to an HTTP URL for downsizing the content.
Parameters:
Name Type Description
mxc string The MXC URI to convert and downsize.
width number The width, as an integer, for the thumbnail.
height number The height, as an intenger, for the thumbnail.
method "crop" | "scale" Whether to crop or scale (preserve aspect ratio) the content.

View Source MatrixClient.ts, line 3170

The HTTP URL for the downsized content.
string

# redactEvent(roomId, eventId, reason) → {Promise.<string>}

Redact an event in a given room
Parameters:
Name Type Description
roomId string the room ID to send the redaction to
eventId string the event ID to redact
reason String an optional reason for redacting the event

View Source MatrixClient.ts, line 3078

resolves to the event ID that represents the redaction
Promise.<string>

# replyHtmlNotice(roomId, event, html) → {Promise.<string>}

Replies to a given event with the given HTML. The event is sent with a msgtype of m.notice. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to reply in
event any the event to reply to
html string the HTML to reply with.

View Source MatrixClient.ts, line 2984

resolves to the event ID which was sent
Promise.<string>

# replyHtmlText(roomId, event, html) → {Promise.<string>}

Replies to a given event with the given HTML. The event is sent with a msgtype of m.text. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to reply in
event any the event to reply to
html string the HTML to reply with.

View Source MatrixClient.ts, line 2961

resolves to the event ID which was sent
Promise.<string>

# replyNotice(roomId, event, text, html) → {Promise.<string>}

Replies to a given event with the given text. The event is sent with a msgtype of m.notice. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to reply in
event any the event to reply to
text string the text to reply with
html string the HTML to reply with, or falsey to use the `text`

View Source MatrixClient.ts, line 2973

resolves to the event ID which was sent
Promise.<string>

# replyText(roomId, event, text, html) → {Promise.<string>}

Replies to a given event with the given text. The event is sent with a msgtype of m.text. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to reply in
event any the event to reply to
text string the text to reply with
html string the HTML to reply with, or falsey to use the `text`

View Source MatrixClient.ts, line 2950

resolves to the event ID which was sent
Promise.<string>

# async resolveRoom(roomIdOrAlias) → {Promise.<string>}

Resolves a room ID or alias to a room ID. If the given ID or alias looks like a room ID already, it will be returned as-is. If the room ID or alias looks like a room alias, it will be resolved to a room ID if possible. If the room ID or alias is neither, an error will be raised.
Parameters:
Name Type Description
roomIdOrAlias string the room ID or alias to resolve to a room ID

View Source MatrixClient.ts, line 2619

resolves to the room ID
Promise.<string>

# async sendEvent(roomId, eventType, content) → {Promise.<string>}

Sends an event to the given room. This will encrypt the event before sending if the room is encrypted and the client supports encryption. Use sendRawEvent() to avoid this behaviour.
Parameters:
Name Type Description
roomId string the room ID to send the event to
eventType string the type of event to send
content string the event body to send

View Source MatrixClient.ts, line 3046

resolves to the event ID that represents the event
Promise.<string>

# sendHtmlNotice(roomId, html) → {Promise.<string>}

Sends a notice to the given room with HTML content. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to send the notice to
html string the HTML to send

View Source MatrixClient.ts, line 3004

resolves to the event ID that represents the message
Promise.<string>

# sendHtmlText(roomId, html) → {Promise.<string>}

Sends a text message to the given room with HTML content. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to send the text to
html string the HTML to send

View Source MatrixClient.ts, line 3024

resolves to the event ID that represents the message
Promise.<string>

# sendMessage(roomId, content) → {Promise.<string>}

Sends a message to the given room. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to send the message to
content object the event content to send

View Source MatrixClient.ts, line 3034

resolves to the event ID that represents the message
Promise.<string>

# sendNotice(roomId, text) → {Promise.<string>}

Sends a notice to the given room. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to send the notice to
text string the text to send

View Source MatrixClient.ts, line 2994

resolves to the event ID that represents the message
Promise.<string>

# async sendRawEvent(roomId, eventType, content) → {Promise.<string>}

Sends an event to the given room.
Parameters:
Name Type Description
roomId string the room ID to send the event to
eventType string the type of event to send
content string the event body to send

View Source MatrixClient.ts, line 3057

resolves to the event ID that represents the event
Promise.<string>

# sendReadReceipt(roomId, eventId) → {Promise.<any>}

Sends a read receipt for an event in a room
Parameters:
Name Type Description
roomId string the room ID to send the receipt to
eventId string the event ID to set the receipt at

View Source MatrixClient.ts, line 2927

resolves when the receipt has been sent
Promise.<any>

# sendStateEvent(roomId, type, stateKey, content) → {Promise.<string>}

Sends a state event to the given room
Parameters:
Name Type Description
roomId string the room ID to send the event to
type string the event type to send
stateKey string the state key to send, should not be null
content string the event body to send

View Source MatrixClient.ts, line 3068

resolves to the event ID that represents the message
Promise.<string>

# sendText(roomId, text) → {Promise.<string>}

Sends a text message to the given room. The message will be encrypted if the client supports encryption and the room is encrypted.
Parameters:
Name Type Description
roomId string the room ID to send the text to
text string the text to send

View Source MatrixClient.ts, line 3014

resolves to the event ID that represents the message
Promise.<string>

# async sendToDevices(type, messages) → {Promise.<void>}

Sends to-device messages to the respective users/devices.
Parameters:
Name Type Description
type string The message type being sent.
messages Record.<string, Record.<string, any>> The messages to send, mapped as user ID to device ID (or "*" to denote all of the user's devices) to message payload (content).

View Source MatrixClient.ts, line 3333

Resolves when complete.
Promise.<void>

# async setAccountData(eventType, content) → {Promise.<any>}

Sets account data.
Parameters:
Name Type Description
eventType string The type of account data to set
content any The content to set

View Source MatrixClient.ts, line 2524

Resolves when updated
Promise.<any>

# async setAvatarUrl(avatarUrl) → {Promise.<any>}

Sets a new avatar url for the user.
Parameters:
Name Type Description
avatarUrl string the new avatar URL for the user, in the form of a Matrix Content URI

View Source MatrixClient.ts, line 2819

resolves when complete
Promise.<any>

# setDirectoryVisibility(roomId, visibility) → {Promise}

Sets the visibility of a room in the directory.
Parameters:
Name Type Description
roomId string The room ID to manipulate the visibility of
visibility "public" | "private" The visibility to set for the room

View Source MatrixClient.ts, line 2599

resolves when the visibility has been updated
Promise

# async setDisplayName(displayName) → {Promise.<any>}

Sets a new display name for the user.
Parameters:
Name Type Description
displayName string the new display name for the user, or null to clear

View Source MatrixClient.ts, line 2810

resolves when complete
Promise.<any>

# setJoinStrategy(strategy) → {void}

Sets the strategy to use for when joinRoom is called on this client
Parameters:
Name Type Description
strategy IJoinRoomStrategy The strategy to use, or null to use none

View Source MatrixClient.ts, line 2411

void

# async setPresenceStatus(presence, statusMessagenullable) → {Promise.<any>}

Sets the presence status for the current user.
Parameters:
Name Type Attributes Description
presence PresenceState The new presence state for the user.
statusMessage string <nullable>
 Optional status message to include with the presence.

View Source MatrixClient.ts, line 2562

Resolves when complete.
Promise.<any>

# async setRoomAccountData(eventType, roomId, content) → {Promise.<any>}

Sets room account data.
Parameters:
Name Type Description
eventType string The type of room account data to set
roomId string The room to set account data in
content any The content to set

View Source MatrixClient.ts, line 2535

Resolves when updated
Promise.<any>

# async setTyping(roomId, typing, timeout) → {Promise.<any>}

Sets the typing status of the current user in a room
Parameters:
Name Type Description
roomId string the room ID the user is typing in
typing boolean is the user currently typing
timeout number how long should the server preserve the typing state, in milliseconds

View Source MatrixClient.ts, line 2938

resolves when the typing state has been set
Promise.<any>

# async setUserPowerLevel(userId, roomId, newLevel) → {Promise.<any>}

Sets the power level for a given user ID in the given room. Note that this is not safe to call multiple times concurrently as changes are not atomic. This will throw an error if the user lacks enough permission to change the power level, or if a power level event is missing from the room.
Parameters:
Name Type Description
userId string The user ID to change
roomId string The room ID to change the power level in
newLevel number The integer power level to set the user to.

View Source MatrixClient.ts, line 3149

Resolves when complete.
Promise.<any>

# async signAndCreateKeyBackupVersion(info) → {Promise.<IKeyBackupVersion>}

Create a new room key backup.
Parameters:
Name Type Description
info IKeyBackupInfoUnsigned The properties of the key backup to create, with its auth_data left unsigned.

View Source MatrixClient.ts, line 3352

Resolves to the version id of the new backup.
Promise.<IKeyBackupVersion>

# async start(filter) → {Promise.<any>}

Starts syncing the client with an optional filter
Parameters:
Name Type Description
filter any The filter to use, or null for none

View Source MatrixClient.ts, line 2696

Resolves when the client has started syncing
Promise.<any>

# stop()

Stops the client from syncing.

View Source MatrixClient.ts, line 2687

# storageProvider() → {IStorageProvider}

The storage provider for this client. Direct access is usually not required.

View Source MatrixClient.ts, line 2347

IStorageProvider

# unbanUser(userId, roomId) → {Promise.<any>}

Unbans a user in a room.
Parameters:
Name Type Description
userId string the user ID to unban
roomId string the room ID to lift the ban in

View Source MatrixClient.ts, line 2665

resolves when completed
Promise.<any>

# unstableApis() → {UnstableApis}

Gets the unstable API access class. This is generally not recommended to be used by clients.

View Source MatrixClient.ts, line 2369

The unstable API access class.
UnstableApis

# updateKeyBackupVersion(version, info) → {Promise.<void>}

Update an existing room key backup.
Parameters:
Name Type Description
version KeyBackupVersion The key backup version to update.
info IKeyBackupInfoUpdate The properties of the key backup to be applied.

View Source MatrixClient.ts, line 3361

Resolves when complete.
Promise.<void>

# async upgradeRoom(roomId, newVersion)

Upgrade a room. This will call the room upgrade endpoint on the homeserver, which will create a new room with some of the state carried over. See the spec for which state will be carried over.
Parameters:
Name Type Description
roomId The room to upgrade
newVersion The room version of the new room.
See:

View Source MatrixClient.ts, line 3217

The new room ID

# async uploadContent(data, contentType, filename) → {Promise.<string>}

Uploads data to the homeserver's media repository. Note that this will not automatically encrypt media as it cannot determine if the media should be encrypted.
Parameters:
Name Type Description
data Buffer the content to upload.
contentType string the content type of the file. Defaults to application/octet-stream
filename string the name of the file. Optional.

View Source MatrixClient.ts, line 3182

resolves to the MXC URI of the content
Promise.<string>

# uploadContentFromUrl(url) → {Promise.<string>}

Uploads data to the homeserver's media repository after downloading it from the provided URL.
Parameters:
Name Type Description
url string The URL to download content from.

View Source MatrixClient.ts, line 3205

Resolves to the MXC URI of the content
Promise.<string>

# async uploadDeviceOneTimeKeys(keys) → {Promise.<OTKCounts>}

Uploads One Time Keys for the current device.
Parameters:
Name Type Description
keys OTKs The keys to upload.

View Source MatrixClient.ts, line 3262

Resolves to the current One Time Key counts when complete.
Promise.<OTKCounts>

# async uploadFallbackKey(fallbackKey) → {Promise.<OTKCounts>}

Uploads a fallback One Time Key to the server for usage. This will replace the existing fallback key.
Parameters:
Name Type Description
fallbackKey FallbackKey The fallback key.

View Source MatrixClient.ts, line 3280

Resolves to the One Time Key counts.
Promise.<OTKCounts>

# async userHasPowerLevelFor(userId, roomId, eventType, isState)

Checks if a given user has a required power level required to send the given event.
Parameters:
Name Type Description
userId the user ID to check the power level of
roomId the room ID to check the power level in
eventType the event type to look for in the `events` property of the power levels
isState true to indicate the event is intended to be a state event

View Source MatrixClient.ts, line 3110

resolves to true if the user has the required power level, resolves to false otherwise

# async userHasPowerLevelForAction(userId, roomId, action) → {Promise.<boolean>}

Checks if a given user has a required power level to perform the given action
Parameters:
Name Type Description
userId string the user ID to check the power level of
roomId string the room ID to check the power level in
action PowerLevelAction the action to check power level for

View Source MatrixClient.ts, line 3121

resolves to true if the user has the required power level, resolves to false otherwise
Promise.<boolean>