Optional cachedOptional callProtected Optional canProtected canProtected Optional checkProtected Optional clientProtected Optional clientProtected Optional clientProtected Optional clientOptional cryptoProtected Optional cryptoProtected Optional exportedProtected fallbackICEServerOptional groupOptional idOptional identityReadonly ignoredProtected isProtected mediaProtected notifProtected ongoingProtected peekProtected pendingOptional pickleProtected pushOptional pushProtected roomOptional roomMethod to generate room names for empty rooms and rooms names based on membership. Defaults to a built-in English handler with basic pluralisation.
Optional schedulerProtected Optional serverProtected sessionProtected Optional syncProtected Optional syncProtected syncedPrivate toProtected turnProtected turnProtected txnPrivate useProtected Optional verificationStatic Readonly RESTORE_Gets a set of room IDs in common with another user
Resolves to a set of rooms
Rejects: with an error response.
The userId to check.
Resolves: an empty object {}
Rejects: with an error response.
Add a key for encrypting secrets.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
An object with: keyId: {string} the ID of the key keyInfo: {object} details about the key (iv, mac, passphrase)
the algorithm used by the key
the options for the algorithm. The properties used depend on the algorithm given.
Optional keyName: stringthe name of the key. If not given, a random name will be generated.
Add a 3PID to your homeserver account and optionally bind it to an identity
server as well. An identity server is required as part of the creds object.
This API is deprecated, and you should instead use addThreePidOnly
for homeservers that support it.
Resolves: on success
Rejects: with an error response.
Add a 3PID to your homeserver account. This API does not use an identity server, as the homeserver is expected to handle 3PID ownership validation.
You can check whether a homeserver supports this API via
doesServerSupportSeparateAddAndBind.
Resolves: to an empty object {}
Rejects: with an error response.
A object with 3PID validation data from having called
account/3pid/<medium>/requestToken on the homeserver.
Take a result from an earlier searchRoomEvents call, and backfill results.
Resolves: updated result object
Rejects: with an error response.
the results object to be updated
Begin a key verification.
a verification object
Use requestVerification instead.
the verification method to use
the user to verify keys with
the device to verify
Bind a 3PID for discovery onto an identity server via the homeserver. The identity server handles 3PID ownership validation and the homeserver records the new binding to track where all 3PIDs for the account are bound.
You can check whether a homeserver supports this API via
doesServerSupportSeparateAddAndBind.
Resolves: to an empty object {}
Rejects: with an error response.
A object with 3PID validation data from having called
validate/<medium>/requestToken on the identity server. It should also
contain id_server and id_access_token fields as well.
Bootstrap cross-signing by creating keys if needed. If everything is already set up, then no changes are made, so this is safe to run to ensure cross-signing is ready for use.
This function:
The cross-signing API is currently UNSTABLE and may change without notice.
Bootstrap Secure Secret Storage if needed by creating a default key. If everything is already set up, then no changes are made, so this is safe to run to ensure secret storage is ready for use.
This function
Looks up the public Matrix ID mappings for multiple 3PIDs.
Resolves: Lookup results from IS.
Rejects: with an error response.
Array of arrays containing [medium, address]
The access_token field of the Identity
Server /account/register response (see registerWithIdentityServer).
Cancel a room key request for this event if one is ongoing and resend the request.
A promise that will resolve when the key request is queued
event of which to cancel and resend the room key request.
Cancel a queued or unsent event.
Error if the event is not in QUEUED, NOT_SENT or ENCRYPTING state
Event to cancel
Cancel a file upload in progress
true if canceled, otherwise false
The object returned from uploadContent
Checks that a given cross-signing private key matches a given public key. This can be used by the getCrossSigningKey callback to verify that the private key it is about to supply is the one that was requested.
true if the key matches, otherwise false
The private key
The public key
Check whether a given device is trusted.
The cross-signing API is currently UNSTABLE and may change without notice.
module:client~MatrixClient#checkDeviceTrust
The ID of the user whose devices is to be checked.
The ID of the device to check
Force a re-check of the local key backup status against what's on the server.
Object with backup info (as returned by getKeyBackupVersion) in backupInfo and trust information (as returned by isKeyBackupTrusted) in trustInfo.
Check the copy of our cross-signing key that we have in the device list and see if we can get the private key. If so, mark it as trusted.
Optional opts: ICheckOwnCrossSigningTrustOptsICheckOwnCrossSigningTrustOpts object
Checks that a given secret storage private key matches a given public key. This can be used by the getSecretStorageKey callback to verify that the private key it is about to supply is the one that was requested.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
true if the key matches, otherwise false
The private key
The public key
Check whether a given user is trusted.
The cross-signing API is currently UNSTABLE and may change without notice.
The ID of the user to check.
Claim one-time keys
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
a list of [userId, deviceId] pairs
Optional keyAlgorithm: string = "signed_curve25519"Optional timeout: numberthe time (in milliseconds) to wait for keys from remote servers
Creates a new call. The place*Call methods on the returned call can be used to actually place a call
the call or null if the browser doesn't support calling.
The room the call is to be placed in.
Creates a new dehydrated device (without queuing periodic dehydration)
the device id of the newly created dehydrated device
the dehydration key
Optional keyInfo: IDehydratedDeviceKeyInfoInformation about the key. Primarily for information about how to generate the key from a passphrase.
Optional deviceDisplayName: stringThe device display name for the dehydrated device.
Create a new filter.
Resolves to a Filter object.
Rejects: with an error response.
The HTTP body for the request
Creates a new group call and sends the associated state event to alert other members that the room now has a group call.
The room the call is to be placed in.
Optional dataChannelsEnabled: booleanOptional dataChannelOptions: IGroupCallDataChannelOptionsCreate a new key backup version and enable it, using the information return from prepareKeyBackupVersion.
Object with 'version' param indicating the version created
Info object from prepareKeyBackupVersion
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
Create a recovery key from a user-supplied passphrase.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
Object with public key metadata, encoded private recovery key which should be disposed of after displaying to the user, and raw private key to avoid round tripping if needed.
Optional password: stringPassphrase string that can be entered by the user when restoring the backup as an alternative to entering the recovery key. Optional.
Create a new room.
Resolves: {room_id: {string}}
Rejects: with an error response.
a list of options to pass to the /createRoom API.
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
the maximum amount of events the retrieve
'f' or 'b'
Optional timelineFilter: Filterthe timeline filter to pass
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.
Resolves: On success, the empty object
Optional auth: anyOptional. Auth data to supply for User-Interactive auth.
Optional erase: booleanOptional. If set, send as erase attribute in the
JSON request body, indicating whether the account should be erased. Defaults
to false.
Deactivates a user using Synapse's administrator API. This function is implementation specific and may change as a result.
the deactivate response - see Synapse docs for information.
the User ID to deactivate.
Attempts to decrypt an event
A decryption promise
The event to decrypt
Optional options: IDecryptOptionsDelete an alias to room ID mapping. This alias must be on your local server, and you must have sufficient access to do this operation.
Resolves: an empty object {}.
Rejects: with an error response.
The room alias to delete.
Delete the given device
Resolves: result object
Rejects: with an error response.
device to delete
Optional auth: IAuthDictOptional. Auth data to supply for User-Interactive auth.
Optional version: stringOptional version: stringOptional version: stringDelete multiple device
Resolves: result object
Rejects: with an error response.
IDs of the devices to delete
Optional auth: IAuthDictOptional. Auth data to supply for User-Interactive auth.
Resolves: an empty object {}
Rejects: with an error response.
Resolves: The server response on success (generally the empty JSON object)
Rejects: with an error response.
The threepid medium (eg. 'email')
The threepid address (eg. 'bob@example.com') this must be as returned by getThreePids.
Query the server to see if the id_access_token parameter can be safely
passed to the homeserver. Some homeservers may trigger errors if they are not
prepared for the new parameter.
true if id_access_token can be sent
Query the server to see if it is forcing encryption to be enabled for a given room preset, based on the /versions response.
true if the server is forcing encryption for the preset.
The name of the preset to check.
Query the server to see if it supports separate 3PID add and bind functions. This affects the sequence of API calls clients should use for these operations, so it's helpful to be able to check for support.
true if separate functions are supported
Download the keys for a list of users and stores the keys in the session store.
A promise which resolves to a map userId->deviceId->* module:crypto~DeviceInfo|DeviceInfo.
The users to fetch.
Optional forceDownload: booleanAlways download the keys even if cached.
Download device keys
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
list of users to get keys for
Optional token?: stringsync token to pass in the query request, to help the HS give the most recent results
Rest ...args: Parameters<ClientEventHandlerMap[T]>Rest ...args: Parameters<ClientEventHandlerMap[T]>Enable backing up of keys, using data previously returned from getKeyBackupVersion.
Resolves when complete.
Backup information object as returned by getKeyBackupVersion
Protected encryptencrypts the event if necessary; adds the event to the queue, or sends it; marks the event as sent/unsent
returns a promise which resolves with the result of the send request
Encrypts and sends a given object via Olm to-device messages to a given set of devices.
Promise which resolves once the message has been encrypted and sent to the given userDeviceMap, and returns the { contentMap, deviceInfoByDeviceId } of the successfully sent messages.
mapping from userId to deviceInfo
fields to include in the encrypted payload *
Private encryptOptional room: RoomGet a list containing all of the room keys
This should be encrypted before returning it to the user.
a promise which resolves to a list of session export objects
Private fetchFetches relations for a given event
the response, with chunk, prev_batch and, next_batch.
the room of the event
the id of the event
Optional relationType: null | stringthe rel_type of the relations requested
Optional eventType: null | stringthe event type of the relations requested
Optional opts: IRelationsRequestOpts = ...options with optional values for the request.
Finds a DM verification request that is already in progress for the given room id
the VerificationRequest that is in progress, if any
the room to use for verification
Get account data event of given type for the current user.
The contents of the given account data event
The event type
Get account data event of given type for the current user. This variant gets account data directly from the homeserver if the local store is not ready, which can be useful very early in startup before the initial sync.
Resolves: The contents of the given account data event.
Rejects: with an error response.
The event type
Get the callback set via setCanResetTimelineCallback.
The callback or null
Gets the capabilities of the homeserver. Always returns an object of capability keys and their options, which may be empty.
Resolves to the capabilities of the homeserver
Rejects: with an error response.
True to ignore any cached values.
The app may wish to see if we have a key cached without triggering a user interaction.
Get the user's cross-signing key ID.
The cross-signing API is currently UNSTABLE and may change without notice.
the key ID
Optional type: string = CrossSigningKey.MasterThe type of key to get the ID of. One of "master", "self_signing", or "user_signing". Defaults to "master".
Whether to trust a others users signatures of their devices. If false, devices will only be considered 'verified' if we have verified that device individually (effectively disabling cross-signing).
Default: true
True if trusting cross-signed devices
Get a list of all file uploads in progress
Array of objects representing current uploads. Currently in progress is element 0. Keys:
Get the current dehydrated device, if any
A promise of an object containing the dehydrated device
Private getReturns the eventType that should be used taking encryption into account for a given eventType.
the event type taking encryption into account
the room for the events eventType relates to
Optional eventType: null | stringthe event type
Get information about the encryption of an event
The event information.
event to be checked
Optional options: MapperOptsGet e2e information on the device that sent an event
event to be checked
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. If the event does not belong to this EventTimelineSet then undefined will be returned.
Resolves: module:models/event-timeline~EventTimeline including the given event
The timelineSet to look for the event in, must be bound to a room
The ID of the event to look for
Get the fallback URL to use for unknown interactive-auth stages.
HS URL to hit to for the fallback interface
the type of stage being attempted
the auth session ID provided by the homeserver
Retrieve a filter.
Resolves: a Filter object
Rejects: with an error response.
The user ID of the filter owner
The filter ID to retrieve
True to allow cached filters to be returned. Default: True.
Get account info from the identity server. This is useful as a neutral check to verify that other APIs are likely to approve access by testing that the token is valid, terms have been agreed, etc.
Resolves: an object with account info.
Rejects: with an error response.
The access_token field of the Identity
Server /account/register response (see registerWithIdentityServer).
Gets the V2 hashing information from the identity server. Primarily useful for lookups.
The hashing information for the identity server.
The access token for the identity server.
Retrieve membership info. for a room.
Resolves: A list of currently joined users and their profile data.
Rejects: with an error response.
ID of the room to get membership for
Resolves: A list of the user's current rooms
Rejects: with an error response.
Get information about the current key backup.
Information object from API or null
Ask the server for a list of users who have changed their device lists between a pair of sync tokens
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Get an EventTimeline for the latest events in the room. This will just
call /messages to get the latest message in the room, then use
client.getEventTimeline(...) to construct a new timeline from it.
Resolves: module:models/event-timeline~EventTimeline timeline with the latest events in the room
The timelineSet to find or add the timeline to
Gets the local aliases for the room. Note: this includes all local aliases, unlike the curated list from the m.room.canonical_alias state event.
Resolves: an object with an aliases property, containing an array of local aliases
Rejects: with an error response.
The room ID to get local aliases for.
Get the config for the media repository.
Resolves with an object containing the config.
Return the global notification EventTimelineSet, if any
the globl notification EventTimelineSet
Gets a bearer token from the homeserver that the user can present to a third party in order to prove their ownership of the Matrix account they are logged into.
Resolves: Token object
Rejects: with an error response.
Resolves: The presence state for this user.
Rejects: with an error response.
The user to get presence for
Resolves: TODO
Rejects: with an error response.
Optional info: stringThe kind of info to retrieve (e.g. 'displayname', 'avatar_url').
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.
A dict of actions to perform.
The event to get push actions for.
forces to recalculate actions for an event Useful when an event just got decrypted
Get the push rules for the account from the server.
Resolves to the push rules.
Rejects: with an error response.
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.
The Room or null if it doesn't exist or there is no data store.
The room ID
Get the visibility of a room in the current HS's room directory
Resolves: TODO
Rejects: with an error response.
Fetches or paginates a room hierarchy as defined by MSC2946.
Falls back gracefully to sourcing its data from getSpaceSummary if this API is not yet supported by the server.
the response, with next_batch & rooms fields.
The ID of the space-room to use as the root of the summary.
Optional limit: numberThe maximum number of rooms to return per page.
Optional maxDepth: numberThe maximum depth in the tree from the root room to return.
Whether to only return rooms with suggested=true.
Optional fromToken: stringThe opaque token to paginate a previous request.
Get room info for the given alias.
Resolves: Object with room_id and servers.
Rejects: with an error response.
The room alias to resolve.
Fetches the summary of a room as defined by an initial version of MSC3266 and implemented in Synapse Proposed at https://github.com/matrix-org/matrix-doc/pull/3266
The ID or alias of the room to get the summary of.
Optional via: string[]The list of servers which know about the room if only an ID was provided.
Resolves: to an object keyed by tagId with objects containing a numeric order field.
Rejects: with an error response.
Determines the history of room upgrades for a given room, as far as the client can see. Returns an array of Rooms where the first entry is the oldest and the last entry is the newest (likely current) room. If the provided room is not found, this returns an empty list. This works in both directions, looking for older and newer rooms of the given room.
An array of rooms representing the upgrade history.
The room ID to search from
If true, the function will only return rooms which can be proven to be linked. For example, rooms which have a create event pointing to an old room which the client is not aware of or doesn't have a matching tombstone would not be returned.
Return the provided scheduler, if any.
The scheduler or undefined
The HS URL to hit to begin the SSO login process.
The URL to redirect to after the HS authenticates with the SSO.
The type of SSO login we are doing (sso or cas). Defaults to 'sso'.
Optional idpId: stringThe ID of the Identity Provider being targeted, optional.
Optional action: SSOActionthe SSO flow to indicate to the IdP, optional.
Get the cross signing information for a given user.
The cross-signing API is currently UNSTABLE and may change without notice.
the cross signing information for the user.
the user ID to get the cross-signing info for.
Get the stored device key for a user id and device id
device or null
the user to list keys for.
unique identifier for the device
Get the stored device keys for a user id
list of devices
the user to list keys for.
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.
Get information on how a specific place on a third party protocol may be reached.
Resolves to the result object
The protocol given in getThirdpartyProtocols()
Protocol-specific parameters, as given in the response to getThirdpartyProtocols()
Optional searchGet information on how a specific user on a third party protocol may be reached.
Resolves to the result object
The protocol given in getThirdpartyProtocols()
Protocol-specific parameters, as given in the response to getThirdpartyProtocols()
Get the TURN servers for this homeserver.
The servers or an empty list.
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.
Resolves: Object of OG metadata.
Rejects: with an error response. May return synthesized attributes if the URL lacked OG meta.
The URL to get preview data for
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.
Returns all to-device verification requests that are already in progress for the given user id
the VerificationRequests that are in progress
the ID of the user to query
Get the API versions supported by the server, along with any unstable APIs it supports
The server /versions response
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.
A list of rooms, or an empty list if there is no data store.
Performs a hashed lookup of addresses against the identity server. This is only supported on identity servers which have at least the version 2 API.
A collection of address mappings to found MXIDs. Results where no user could be found will not be listed.
An array of 2 element arrays. The first element of each pair is the address, the second is the 3PID medium. Eg: ["email@example.org", "email"]
The access token for the identity server.
Import a list of room keys previously exported by exportRoomKeys
a promise which resolves when the keys have been imported
a list of session export objects
Optional opts: IImportRoomKeysOptsInitialise 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.
Invite a user to a room based on their email address.
Resolves: {} an empty object.
Rejects: with an error response.
The room to invite the user to.
The email address to invite.
Invite a user to a room based on a third-party identifier.
Resolves: {} an empty object.
Rejects: with an error response.
The room to invite the user to.
The medium to invite the user e.g. "email".
The address for the specified medium.
Checks whether cross signing:
If this function returns false, bootstrapCrossSigning() can be used to fix things such that it returns true. That is to say, after bootstrapCrossSigning() completes successfully, this function should return true.
True if cross-signing is ready to be used on this device
Check if the sender of an event is verified
true if the sender of this event has been verified using module:client~MatrixClient#setDeviceVerified|setDeviceVerified.
event to be checked
Check whether the key backup private key is stored in secret storage.
map of key name to key info the secret is encrypted with, or null if it is not present or not encrypted with a trusted key
{ usable: [bool], // is the backup trusted, true iff there is a sig that is valid & from a trusted device sigs: [ valid: [bool], device: [DeviceInfo], ] }
key backup info dict from getKeyBackupVersion()
Checks whether secret storage:
If this function returns false, bootstrapSecretStorage() can be used to fix things such that it returns true. That is to say, after bootstrapSecretStorage() completes successfully, this function should return true.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
True if secret storage is ready to be used on this device
Check if a secret is stored on the server.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
map of key name to key info the secret is encrypted with, or null if it is not present or not encrypted with a trusted key
the name of the secret
Determines if the current user is an administrator of the Synapse homeserver. Returns false if untrue or the homeserver does not appear to be a Synapse homeserver. This function is implementation specific and may change as a result.
true if the user appears to be a Synapse administrator.
Check whether a username is available prior to registration. An error response indicates an invalid/unavailable username.
Resolves: to boolean of whether the username is available.
The username to check the availability of.
Join a room. If you have already joined the room, this will no-op.
Resolves: Room object.
Rejects: with an error response.
The room ID or room alias to join.
Options when joining the room.
Get the raw key for a key backup from the password Used when migrating key backups into SSSS
The cross-signing API is currently UNSTABLE and may change without notice.
key backup key
Passphrase
Backup metadata from checkKeyBackup
Get the raw key for a key backup from the recovery key Used when migrating key backups into SSSS
The cross-signing API is currently UNSTABLE and may change without notice.
key backup key
The recovery key
Leaves all rooms in the chain of room upgrades based on the given room. By
default, this will leave all the previous and upgraded rooms, including the
given room. To only leave the given room and any previous rooms, keeping the
upgraded (modern) rooms untouched supply false to includeFuture.
Resolves when completed with an object keyed by room ID and value of the error encountered when leaving or null.
The room ID to start leaving at
If true, the whole chain (past and future) of upgraded rooms will be left.
Resolves to the available login flows
Rejects: with an error response.
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.
Resolves: On success, the empty object {}
whether to stop the client before calling /logout to prevent invalid token errors.
Looks up the public Matrix ID mapping for a given 3rd party identifier from the identity server
Resolves: A threepid mapping object or the empty object if no mapping exists
Rejects: with an error response.
The medium of the threepid, eg. 'email'
The textual address of the threepid
The access_token field of the Identity
Server /account/register response (see registerWithIdentityServer).
Private makeOptional version: stringOptional version: stringOptional version: stringResolves: dictionary of userid to profile information
Rejects: with an error response.
Optional includeMembership: stringthe membership type to include in the response
Optional excludeMembership: stringthe membership type to exclude from the response
Optional atEventId: stringthe id of the event for which moment in the timeline the members should be returned for
Private membershipTurn an MXC URL into an HTTP one. This method is experimental and may change.
the avatar URL or null.
The MXC URL
Optional width: numberThe desired width of the thumbnail.
Optional height: numberThe desired height of the thumbnail.
Optional resizeMethod: stringThe thumbnail resize method to use, either "crop" or "scale".
Optional allowDirectLinks: booleanIf 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.
Take an EventTimeline, and back/forward-fill results.
Resolves to a boolean: false if there are no events and we reached either end of the timeline; else true.
timeline object to be updated
Optional opts: IPaginateOptsPeek into a room and receive updates about the room. This only works if the history visibility for the room is world_readable.
Resolves: Room object
Rejects: with an error response.
The room to attempt to peek into.
Set up the data required to create a new backup version. The backup version will not be created and enabled until createKeyBackupVersion is called.
Object that can be passed to createKeyBackupVersion and additionally has a 'recovery_key' member with the user-facing recovery key string.
Optional password: null | string | Uint8ArrayPassphrase string that can be entered by the user when restoring the backup as an alternative to entering the recovery key. Optional.
Optional room: RoomOptional events: MatrixEvent[]Private processPrivate
helper for searchRoomEvents and backPaginateRoomEventsSearch. Processes the response from the API call and updates the searchResults
searchResults
Experimental
Experimental
Resolves: IPublicRoomsResponse
Rejects: with an error response.
Options for this request
Sends events directly to specific devices using Matrix's to-device messaging system. The batch will be split up into appropriately sized batches for sending and stored in the store so they can be retried later if they fail to send. Retries will happen automatically.
The to-device messages to send
Resolves: TODO
Rejects: with an error response.
Optional txnId: stringtransaction id. One will be made up if not supplied.
Optional opts: IRedactOptsOptions to pass on, may contain reason.
Optional txnId: stringOptional opts: IRedactOptsRefreshes an access token using a provided refresh token. The refresh token must be valid for the current access token known to the client instance.
Note that this function will not cause a logout if the token is deemed unknown by the server - the caller is responsible for managing logout actions on error.
Resolves to the new token.
Rejects with an error response.
The refresh token.
Resolves: TODO
Rejects: with an error response.
Optional session?: stringOptional bindThreepids: null | boolean | { Set key 'email' to true to bind any email threepid uses during registration in the identity server. Set 'msisdn' to true to bind msisdn.
Optional guestAccessToken: stringOptional inhibitLogin: booleanRegister a guest account.
This method returns the auth info needed to create a new authenticated client,
Remember to call setGuest(true) on the (guest-)authenticated client, e.g:
const tmpClient = await sdk.createClient(MATRIX_INSTANCE);
const { user_id, device_id, access_token } = tmpClient.registerGuest();
const client = createClient({
baseUrl: MATRIX_INSTANCE,
accessToken: access_token,
userId: user_id,
deviceId: device_id,
})
client.setGuest(true);
Resolves: JSON object that contains: { user_id, device_id, access_token, home_server }
Rejects: with an error response.
Registration options
Optional body?: anyJSON HTTP body to provide.
Resolves: to the /register response
Rejects: with an error response.
parameters for registration request
Optional kind: stringtype of user to register. may be "guest"
Register with an identity server using the OpenID token from the user's Homeserver, which can be retrieved via module:client~MatrixClient#getOpenIdToken.
Note that the /account/register endpoint (as well as IS authentication in
general) was added as part of the v2 API version.
Resolves: with object containing an Identity Server access token.
Rejects: with an error response.
Try to rehydrate a device if available. The client must have been
initialized with a cryptoCallback.getDehydrationKey option, and this
function must be called before initCrypto and startClient are called.
Resolves to undefined if a device could not be dehydrated, or to the new device ID if the dehydration was successful.
Rejects: with an error response.
Returns relations for a given event. Handles encryption transparently, with the caveat that the amount of events returned might be 0, even though you get a nextBatch. When the returned promise resolves, all messages should have finished trying to decrypt.
an object with events as MatrixEvent[] and optionally nextBatch if more relations are available.
the room of the event
the id of the event
Optional relationType: null | stringthe rel_type of the relations requested
Optional eventType: null | stringthe event type of the relations requested
options with optional values for the request.
Optional event: EventEmitterEvents | EmittedEventsReports an event as inappropriate to the server, which may then notify the appropriate people.
Resolves to an empty object if successful
The room in which the event being reported is located.
The event to report.
The score to rate this content as where -100 is most offensive and 0 is inoffensive.
The reason the content is being reported. May be blank.
Requests an email verification token for the purposes of adding a third party identifier to an account. This API requests a token from the homeserver. The doesServerRequireIdServerParam() method can be used to determine if the server requires the id_server parameter to be provided. If an account with the given email address already exists and is associated with an account other than the one the user is authed as, 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 homeserver).
Resolves: As requestEmailToken
As requestEmailToken
As requestEmailToken
As requestEmailToken
Optional nextLink: stringAs requestEmailToken
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.
Resolves: As requestEmailToken
As requestRegisterMsisdnToken
As requestRegisterMsisdnToken
As requestEmailToken
As requestEmailToken
Optional nextLink: stringAs requestEmailToken
Requests an email verification token directly from an identity server.
This API is used as part of binding an email for discovery on an identity
server. The validation data that results should be passed to the
bindThreePid method to complete the binding process.
Resolves: TODO
Rejects: with an error response.
Error if no identity server is set
The email address to request a token for
A secret binary string generated by the client. It is recommended this be around 16 ASCII characters.
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.
Optional If specified, the client will be redirected to this link after validation.
Optional identityAccessToken: stringThe access_token field of the identity
server /account/register response (see registerWithIdentityServer).
Make a request for an m.login.token to be issued as per
MSC3882.
The server may require User-Interactive auth.
Note that this is UNSTABLE and subject to breaking changes without notice.
Resolves: On success, the token response or UIA auth data.
Optional auth: IAuthDataOptional. Auth data to supply for User-Interactive auth.
Requests a MSISDN verification token directly from an identity server.
This API is used as part of binding a MSISDN for discovery on an identity
server. The validation data that results should be passed to the
bindThreePid method to complete the binding process.
Resolves: TODO
Rejects: with an error response.
Error if no identity server is set
The ISO 3166-1 alpha-2 code for the country in which phoneNumber should be parsed relative to.
The phone number, in national or international format
A secret binary string generated by the client. It is recommended this be around 16 ASCII characters.
If an identity server sees a duplicate request with the same sendAttempt, it will not send another SMS. To request another SMS to be sent, use a larger value for the sendAttempt param as was used in the previous request.
Optional If specified, the client will be redirected to this link after validation.
Optional identityAccessToken: stringThe access_token field of the Identity
Server /account/register response (see registerWithIdentityServer).
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 homeserver).
requestEmailToken calls the equivalent API directly on the identity server, therefore bypassing the password reset specific logic.
Resolves: As requestEmailToken
As requestEmailToken
As requestEmailToken
As requestEmailToken
Optional nextLink: stringAs requestEmailToken
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.
Resolves: As requestEmailToken
As requestRegisterMsisdnToken
As requestRegisterMsisdnToken
As requestEmailToken
As requestEmailToken
As requestEmailToken
Requests an email verification token for the purposes of registration. This API requests a token from the homeserver. The doesServerRequireIdServerParam() method can be used to determine if the server requires the id_server parameter to be provided.
Parameters and return value are as for requestEmailToken
Resolves: As requestEmailToken
As requestEmailToken
As requestEmailToken
As requestEmailToken
Optional nextLink: stringAs requestEmailToken
Requests a text message verification token for the purposes of registration. This API requests a token from the homeserver. The doesServerRequireIdServerParam() method can be used to determine if the server requires the id_server parameter to be provided.
Resolves: As requestEmailToken
The ISO 3166-1 alpha-2 code for the country in which phoneNumber should be parsed relative to.
The phone number, in national or international format
As requestEmailToken
As requestEmailToken
Optional nextLink: stringAs requestEmailToken
Request a secret from another device.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
the secret request object
the name of the secret to request
the devices to request the secret from
Private requestInternal utility function for requesting validation tokens from usage-specific requestToken endpoints.
Resolves: As requestEmailToken
The endpoint to send the request to
Parameters for the POST request
Request a key verification from another user.
resolves to a VerificationRequest when the request has been sent to the other party.
the user to request verification with
Optional devices: string[]array of device IDs to send requests to. Defaults to all devices owned by the user
Request a key verification from another user, using a DM.
resolves to a VerificationRequest when the request has been sent to the other party.
the user to request verification with
the room to use for verification
Resend an event. Will also retry any to-device messages waiting to be sent.
Resolves: to an ISendEventResponse object
Rejects: with an error response.
The event to resend.
Optional. The room the event is in. Will update the timeline entry if provided.
Private restoreOptional opts: IKeyBackupRestoreOptsOptional opts: IKeyBackupRestoreOptsOptional opts: IKeyBackupRestoreOptsOptional opts: IKeyBackupRestoreOptsOptional opts: IKeyBackupRestoreOptsOptional opts: IKeyBackupRestoreOptsRestore from an existing key backup via a passphrase.
Status of restoration with total and imported
key counts.
Passphrase
Optional targetRoomId: undefinedRoom ID to target a specific room. Restores all rooms if omitted.
Optional targetSessionId: undefinedSession ID to target a specific session. Restores all sessions if omitted.
Backup metadata from checkKeyBackup
Optional params such as callbacks
Restore from an existing key backup via an encoded recovery key.
Status of restoration with total and imported
key counts.
Encoded recovery key
Optional targetRoomId: undefinedRoom ID to target a specific room. Restores all rooms if omitted.
Optional targetSessionId: undefinedSession ID to target a specific session. Restores all sessions if omitted.
Backup metadata from checkKeyBackup
Optional params such as callbacks
Restore from an existing key backup via a private key stored in secret storage.
Status of restoration with total and imported
key counts.
Backup metadata from checkKeyBackup
Optional targetRoomId: stringRoom ID to target a specific room. Restores all rooms if omitted.
Optional targetSessionId: stringSession ID to target a specific session. Restores all sessions if omitted.
Optional opts: IKeyBackupRestoreOptsOptional params such as callbacks
Retry a backed off syncing request immediately. This should only be used when the user explicitly attempts to retry their lost connection. Will also retry any outbound to-device messages currently in the queue to be sent (retries of regular outgoing events are handled separately, per-event).
True if this resulted in a request being retried.
Resolves: TODO
Rejects: with an error response.
Resolves: TODO
Rejects: with an error response.
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).
Resolves: Room. If you are at the beginning
of the timeline, Room.oldState.paginationToken will be
null.
Rejects: with an error response.
The room to get older messages in.
Optional. The maximum number of previous events to pull in. Default: 30.
Perform a server-side search.
Resolves: TODO
Rejects: with an error response.
the JSON object to pass to the request body.
Optional next_the batch token to pass in the query string
Optional abortSignal: AbortSignaloptional signal used to cancel the http request.
Perform a server-side search for room events.
The returned promise resolves to an object containing the fields:
Each entry in the results list is a {module:models/search-result.SearchResult}.
Resolves: result object
Rejects: with an error response.
Query the user directory with a term matching user IDs, display names and domains.
Resolves: an array of results.
options
Optional limit?: numberthe maximum number of results to return. The server will apply a limit if unspecified.
the term with which to search.
Private sendResolves: to an empty object {}
Rejects: with an error response.
An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
Optional txnId: stringOptional.
Resolves: to a ISendEventResponse object
Rejects: with an error response.
Optional txnId: stringOptional.
Optional txnId: stringResolves: to an empty object {}
Rejects: with an error response.
Optional txnId: stringOptional.
Optional txnId: stringPrivate sendResolves: to a ISendEventResponse object
Rejects: with an error response.
Resolves: to a ISendEventResponse object
Rejects: with an error response.
Resolves: to a ISendEventResponse object
Rejects: with an error response.
Resolves: to a ISendEventResponse object
Rejects: with an error response.
Optional info: IImageInfoOptional text: stringOptional info: IImageInfoOptional text: stringBack up session keys to the homeserver.
a promise that will resolve when the keys are uploaded
ID of the room that the keys are for Optional.
ID of the session that the keys are for Optional.
backup version Optional.
Object keys to send
Resolves: to an ISendEventResponse object
Rejects: with an error response.
Optional txnId: stringOptional.
Optional txnId: stringResolves: to a ISendEventResponse object
Rejects: with an error response.
Optional txnId: stringOptional.
Optional txnId: stringSend a read receipt.
Resolves: to an empty object {}
Rejects: with an error response.
The event that has been read.
other than ReceiptType.Read are experimental! Optional.
Send a receipt.
Resolves: to an empty object {}
Rejects: with an error response.
The event being acknowledged
The kind of receipt e.g. "m.read". Other than ReceiptType.Read are experimental!
Additional content to send alongside the receipt.
An unthreaded receipt will clear room+thread notifications
Share shared-history decryption keys with the given users.
the room for which keys should be shared.
a list of users to share with. The keys will be sent to all of the user's current devices.
Resolves: TODO
Rejects: with an error response.
Options for the request function.
Resolves: to a ISendEventResponse object
Rejects: with an error response.
Optional info: IImageInfoOptional text: stringOptional info: IImageInfoOptional text: stringResolves: to an empty object {}
Rejects: with an error response.
Optional txnId: stringOptional.
Optional txnId: stringSend an event to a specific list of devices. This is a low-level API that simply wraps the HTTP API call to send to-device messages. We recommend using queueToDevice() which is a higher level API.
Resolves: to an empty object {}
type of event to send
content to send. Map from user_id to device_id to content object.
Optional txnId: stringtransaction id. One will be made up if not supplied.
Set account data event for the current user. It will retry the request up to 5 times.
Resolves: an empty object
Rejects: with an error response.
The event type
the contents object for the event
Set a function which is called when /sync returns a 'limited' response. It is called with a room ID and returns a boolean. It should return 'true' if the SDK can SAFELY remove events from this room. It may not be safe to remove events if there are other references to the timelines for this room, e.g because the client is actively viewing events in this room. Default: returns false.
The callback which will be invoked.
Set the dehydration key. This will also periodically dehydrate devices to the server.
A promise that resolves when the dehydrated device is stored.
the dehydration key
Optional keyInfo: IDehydratedDeviceKeyInfoInformation about the key. Primarily for information about how to generate the key from a passphrase.
Optional deviceDisplayName: stringThe device display name for the dehydrated device.
Mark the given device as blocked/unblocked
module:client~event:MatrixClient"deviceVerificationChanged"
owner of the device
unique identifier for the device or user's cross-signing public key ID.
whether to mark the device as blocked. defaults to 'true'.
Update the given device
Resolves: to an empty object {}
Rejects: with an error response.
device to update
body of request
Mark the given device as known/unknown
module:client~event:MatrixClient"deviceVerificationChanged"
owner of the device
unique identifier for the device or user's cross-signing public key ID.
whether to mark the device as known. defaults to 'true'.
Private setOptional verified: null | booleanOptional blocked: null | booleanOptional known: null | booleanMark the given device as verified
module:client~event:MatrixClient"deviceVerificationChanged"
owner of the device
unique identifier for the device or user's cross-signing public key ID.
whether to mark the device as verified. defaults to 'true'.
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.
whether to blacklist all unverified devices by default
Set whether sendMessage in a room with unknown and unverified devices should throw an error and not send them message. This has 'Global' for symmetry with setGlobalBlacklistUnverifiedDevices but there is currently no room-level equivalent for this setting.
This API is currently UNSTABLE and may change or be removed without notice.
whether error on unknown devices
Set r/w flags for guest access in a room.
Resolves: TODO
Rejects: with an error response.
The room to configure guest access in.
Options
Persists local notification settings
Resolves: an empty object
Rejects: with an error response.
Set the global notification EventTimelineSet
Make a request to change your password.
Resolves: to an empty object {}
Rejects: with an error response.
The new desired password.
Optional logoutDevices: booleanShould all sessions be logged out after the password change. Defaults to true.
Set a user's power level.
Resolves: to an ISendEventResponse object
Rejects: with an error response.
Resolves: TODO
Rejects: with an error response.
If 'presence' isn't a valid presence enum value.
Options to apply
Resolves: to an empty object {}
Rejects: with an error response.
The kind of info to set (e.g. 'avatar_url')
The JSON object to set.
Set the actions for a push notification rule.
Resolves: to an empty object {}
Rejects: with an error response.
Enable or disable a push notification rule.
Resolves: to an empty object {}
Rejects: with an error response.
Adds a new pusher or updates an existing pusher
Resolves: Empty json object on success
Rejects: with an error response.
Object representing a pusher
Resolves: to an empty object {}
Rejects: with an error response.
event type to be set
event content
Set the visbility of a room in the current HS's room directory
Resolves: to an empty object {}
Rejects: with an error response.
"public" to make the room visible in the public directory, or "private" to make it invisible.
Set the visbility of a room bridged to a 3rd party network in the current HS's room directory.
Resolves: result object
Rejects: with an error response.
the network ID of the 3rd party instance under which this room is published under.
"public" to make the room visible in the public directory, or "private" to make it invisible.
Enable end-to-end encryption for a room. This does not modify room state. Any messages sent before the returned promise resolves will be sent unencrypted.
A promise that will resolve when encryption is set up.
The room ID to enable encryption in.
The encryption config for the room.
Set a room-kind muting push rule in a room. The operation also updates MatrixClient.pushRules at the end.
Resolves: result object
Rejects: with an error response.
"global" or device-specific.
the id of the room.
the mute state.
Resolves: TODO
Rejects: with an error response.
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.
Resolves: the empty object, {}.
ID of the room that has been read
ID of the event that has been read
Optional rrEvent: MatrixEventthe 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.
Optional rpEvent: MatrixEventthe m.read.private read receipt event for when we don't want other users to see the read receipts. This is experimental. Optional.
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.
Resolves: the empty object, {}.
ID of the room that has been read
ID of the event that has been read
Optional rrEventId: stringID 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.
Optional rpEventId: stringrpEvent the m.read.private read receipt event for when we don't want other users to see the read receipts. This is experimental. Optional.
Resolves: to an empty object
Rejects: with an error response.
name of room tag to be set
associated with that tag to be stored
Resolves: TODO
Rejects: with an error response.
Optional htmlTopic: stringOptional.
Perform a single MSC3575 sliding sync request.
The sliding sync response, or a standard error.
on non 2xx status codes with an object with a field "httpStatus":number.
The request to make.
Optional proxyBaseUrl: stringThe base URL for the sliding sync proxy.
Optional abortSignal: AbortSignalOptional signal to abort request mid-flight.
Private startHigh level helper method to begin syncing and poll for new events. To listen for these
events, add a listener for module:clientMatrixClient#event:"event"
via module:clientMatrixClient#on. Alternatively, listen for specific
state change events.
Optional opts: IStartClientOptsOptions to apply when syncing.
Store an encrypted secret on the server.
The Secure Secret Storage API is currently UNSTABLE and may change without notice.
The name of the secret
The secret contents.
Optional keys: string[]The IDs of the keys to use to encrypt the secret or null/undefined to use the default (will throw if no default key is set).
Submits a MSISDN token to the identity server
This is used when submitting the code sent by SMS to a phone number. The identity 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.
Resolves: Object, currently with no parameters.
Rejects: with an error response.
Error if No identity server is set
The sid given in the response to requestToken
A secret binary string generated by the client. This must be the same value submitted in the requestToken call.
The MSISDN token, as enetered by the user.
The access_token field of the Identity
Server /account/register response (see registerWithIdentityServer).
Submits a MSISDN token to an arbitrary URL.
This is used when submitting the code sent by SMS to a phone number in the
newer 3PID flow where the homeserver validates 3PID ownership (as part of
requestAdd3pidMsisdnToken). The homeserver response may include a
submit_url to specify where the token should be sent, and this helper can
be used to pass the token to this URL.
Resolves: Object, currently with no parameters.
Rejects: with an error response.
The URL to submit the token to
The sid given in the response to requestToken
A secret binary string generated by the client. This must be the same value submitted in the requestToken call.
The MSISDN token, as enetered by the user.
Private termsFind the event_id closest to the given timestamp in the given direction.
A promise of an object containing the event_id and origin_server_ts of the closest event to the timestamp in the given direction
Resolves: ITurnServerResponse object
Rejects: with an error response.
Unbind a 3PID for discovery on an identity server via the homeserver. The homeserver removes its record of the binding to keep an updated record of where all 3PIDs for the account are bound.
Resolves: on success
Rejects: with an error response.
The threepid medium (eg. 'email')
The threepid address (eg. 'bob@example.com') this must be as returned by getThreePids.
Creates a new file tree space with the given name. The client will pick defaults for how it expects to be able to support the remaining API offered by the returned class.
Note that this is UNSTABLE and may have breaking changes without notice.
Resolves to the created space.
The name of the tree space.
Gets a reference to a tree space, if the room ID given is a tree space. If the room does not appear to be a tree space then null is returned.
Note that this is UNSTABLE and may have breaking changes without notice.
The tree space, or null if not a tree space.
The room ID to get a tree space reference for.
Create an m.beacon_info event
Upsert a live beacon event using a specific m.beacon_info.* event variable type
string
Protected updateUpgrades a room to a new protocol version
Resolves: Object with key 'replacement_room'
Rejects: with an error response.
The target version to upgrade to
Upload a file to the media repository on the homeserver.
Resolves to response object, as determined by this.opts.onlyData, opts.rawResponse, and opts.onlyContentUri. Rejects with an error (usually a MatrixError).
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.
Optional opts: UploadOptsoptions object
Optional auth: IAuthDataOptional keys: CrossSigningKeysUpload keys
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
body of upload request
Optional opts: voidthis method no longer takes any opts, used to take opts.device_id but this was not removed from the spec as a redundant parameter
Wait until an initial state for the given room has been processed by the client and the client is aware of any ongoing group calls. Awaiting on the promise returned by this method before calling getGroupCallForRoom() avoids races where getGroupCallForRoom is called before the state for that room has been processed. It does not, however, fix other races, eg. two clients both creating a group call at the same time.
A promise that resolves once existing group calls in the room have been processed.
The room ID to wait for
Performs a whois lookup on a user using Synapse's administrator API. This function is implementation specific and may change as a result.
the whois response - see Synapse docs for information.
the User ID to look up.
Generated using TypeDoc
Represents 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.