Class MatrixClient

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.

Hierarchy

Constructors

Properties

Accessors

Methods

_unstable_getSharedRooms addListener addPushRule addSecretStorageKey addThreePid addThreePidOnly agreeToTerms backPaginateRoomEventsSearch ban beginKeyVerification bindThreePid bootstrapCrossSigning bootstrapSecretStorage buildSyncApiOptions bulkLookupThreePids cancelAndResendEventRoomKeyRequest cancelPendingEvent cancelUpload checkCrossSigningPrivateKey checkDeviceTrust checkIfOwnDeviceCrossSigned checkKeyBackup checkOwnCrossSigningTrust checkSecretStorageKey checkSecretStoragePrivateKey checkTurnServers checkUserTrust claimOneTimeKeys clearStores countSessionsNeedingBackup createAlias createCall createDehydratedDevice createFilter createGroupCall createKeyBackupVersion createMessagesRequest createRecoveryKeyFromPassphrase createRoom createThreadListMessagesRequest deactivateAccount deactivateSynapseUser decryptEventIfNeeded deleteAccountData deleteAlias deleteDevice deleteKeyBackupVersion deleteKeysFromBackup deleteMultipleDevices deletePushRule deleteRoomTag deleteThreePid disableKeyBackup doesServerAcceptIdentityAccessToken doesServerForceEncryptionForPreset doesServerRequireIdServerParam doesServerSupportLazyLoading doesServerSupportLogoutDevices doesServerSupportSeparateAddAndBind doesServerSupportThread doesServerSupportUnstableFeature downloadKeys downloadKeysForUsers emit enableKeyBackup encryptAndSendEvent encryptAndSendToDevices encryptEventIfNeeded eventNames exportDevice exportRoomKeys fetchClientWellKnown fetchRelations fetchRoomEvent findPredecessorRooms findSuccessorRooms findVerificationRequestDMInProgress fixupRoomNotifications flagAllGroupSessionsForBackup forceDiscardSession forget generateClientSecret getAccessToken getAccountData getAccountDataFromServer getCanResetTimelineCallback getCapabilities getCasLoginUrl getClientWellKnown getCrossSigningCacheCallbacks getCrossSigningId getCrypto getCryptoTrustCrossSignedDevices getCurrentUploads getDefaultSecretStorageKeyId getDehydratedDevice getDevice getDeviceCurve25519Key getDeviceEd25519Key getDeviceId getDevices getDomain getEncryptedIfNeededEventType getEventEncryptionInfo getEventMapper getEventSenderDeviceInfo getEventTimeline getFallbackAuthUrl getFilter getGlobalBlacklistUnverifiedDevices getGlobalErrorOnUnknownDevices getGroupCallForRoom getHomeserverUrl getIdentityAccount getIdentityHashDetails getIdentityServerUrl getIgnoredUsers getJoinedRoomMembers getJoinedRooms getKeyBackupEnabled getKeyBackupVersion getKeyChanges getLatestTimeline getLocalAliases getMediaConfig getMediaHandler getNotifTimelineSet getOpenIdToken getOrCreateFilter getOutgoingRoomKeyRequest getPresence getProfileInfo getPushActionsForEvent getPushRules getPushers getRoom getRoomDirectoryVisibility getRoomHierarchy getRoomIdForAlias getRoomPushRule getRoomSummary getRoomTags getRoomUpgradeHistory getRooms getSafeUserId getScheduler getSecret getSessionId getSsoLoginUrl getStateEvent getStoredCrossSigningForUser getStoredDevice getStoredDevicesForUser getSyncState getSyncStateData getTerms getThirdpartyLocation getThirdpartyProtocols getThirdpartyUser getThreadTimeline getThreePids getTurnServers getTurnServersExpiry getUrlPreview getUseE2eForGroupCall getUser getUserId getUserIdLocalpart getUsers getVerificationRequestsToDeviceInProgress getVersions getVisibleRooms hasLazyLoadMembersEnabled hasSecretStorageKey identityHashedLookup importRoomKeys initCrypto initRustCrypto invite inviteByEmail inviteByThreePid isCrossSigningReady isCryptoEnabled isEventSenderVerified isFallbackICEServerAllowed isGuest isInitialSyncComplete isKeyBackupKeyStored isKeyBackupTrusted isLoggedIn isRoomEncrypted isSecretStorageReady isSecretStored isSynapseAdministrator isUserIgnored isUsernameAvailable isValidRecoveryKey isVersionSupported joinRoom keyBackupKeyFromPassword keyBackupKeyFromRecoveryKey kick leave leaveRoomChain legacyDeviceVerification listenerCount listeners login loginFlows loginWithPassword loginWithSAML2 loginWithToken logout lookupThreePid makeKeyBackupPath makeTxnId members membershipChange mxcUrlToHttp off on once paginateEventTimeline peekInRoom prepareKeyBackupVersion prepareToEncrypt prependListener prependOnceListener processAggregatedTimelineEvents processBeaconEvents processRoomEventsSearch processThreadEvents processThreadRoots publicRooms queueToDevice rawListeners redactEvent refreshToken register registerGuest registerRequest registerWithIdentityServer rehydrateDevice relations removeAllListeners removeListener reportEvent requestAdd3pidEmailToken requestAdd3pidMsisdnToken requestEmailToken requestLoginToken requestMsisdnToken requestPasswordEmailToken requestPasswordMsisdnToken requestRegisterEmailToken requestRegisterMsisdnToken requestSecret requestTokenFromEndpoint requestVerification requestVerificationDM resendEvent resetNotifTimelineSet resolveRoomAlias restoreKeyBackup restoreKeyBackupWithCache restoreKeyBackupWithPassword restoreKeyBackupWithRecoveryKey restoreKeyBackupWithSecretStorage retryImmediately roomInitialSync roomState scheduleAllGroupSessionsForBackup scrollback search searchMessageText searchRoomEvents searchUserDirectory sendCompleteEvent sendEmoteMessage sendEvent sendEventHttpRequest sendHtmlEmote sendHtmlMessage sendHtmlNotice sendImageMessage sendKeyBackup sendMessage sendNotice sendReadReceipt sendReceipt sendSharedHistoryKeys sendStateEvent sendStickerMessage sendTextMessage sendToDevice sendTyping setAccessToken setAccountData setAvatarUrl setCanResetTimelineCallback setCryptoTrustCrossSignedDevices setDefaultSecretStorageKeyId setDehydrationKey setDeviceBlocked setDeviceDetails setDeviceKnown setDeviceVerification setDeviceVerified setDisplayName setFallbackICEServerAllowed setForceTURN setGlobalBlacklistUnverifiedDevices setGlobalErrorOnUnknownDevices setGuest setGuestAccess setIdentityServerUrl setIgnoredUsers setLocalNotificationSettings setNotifTimelineSet setPassword setPowerLevel setPresence setProfileInfo setPushRuleActions setPushRuleEnabled setPushRules setPusher setRoomAccountData setRoomDirectoryVisibility setRoomDirectoryVisibilityAppService setRoomEncryption setRoomMutePushRule setRoomName setRoomReadMarkers setRoomReadMarkersHttpRequest setRoomTag setRoomTopic setSupportsCallTransfer slidingSync startCallEventHandler startClient stopClient stopPeeking storeClientOptions storeSecret submitMsisdnToken submitMsisdnTokenOtherUrl supportsExperimentalThreads supportsThreads supportsVoip syncLeftRooms termsUrlForService timestampToEvent turnServer unban unbindThreePid unstableCreateFileTree unstableGetFileTreeSpace unstable_createLiveBeacon unstable_setLiveBeacon updatePendingEventStatus upgradeRoom uploadContent uploadDeviceSigningKeys uploadKeySignatures uploadKeys uploadKeysRequest userHasCrossSigningKeys waitForClientWellKnown waitUntilRoomReadyForGroupCalls whoami whoisSynapseUser

Constructors

Properties

baseUrl: string
cachedCapabilities?: {
    capabilities: ICapabilities;
    expiration: number;
}

Type declaration

callEventHandler?: CallEventHandler
canResetTimelineCallback?: ResetTimelineCallback
canSupport: Map<Feature, ServerSupport> = ...
canSupportVoip: boolean = false
checkTurnServersIntervalID?: Timer
clientOpts?: IStoredClientOpts
clientRunning: boolean = false
clientWellKnown?: IClientWellKnown
clientWellKnownIntervalID?: Timer
clientWellKnownPromise?: Promise<IClientWellKnown>
credentials: {
    userId: null | string;
}

Type declaration

  • userId: null | string
crypto?: Crypto

The libolm crypto implementation, if it is in use.

Deprecated

This should not be used. Instead, use the methods exposed directly on this class or (where they are available) via getCrypto.

cryptoBackend?: CryptoBackend
cryptoCallbacks: ICryptoCallbacks
cryptoStore?: CryptoStore
deviceId: null | string
exportedOlmDeviceToImport?: IExportedDevice
fallbackICEServerAllowed: boolean = false
forceTURN: boolean = false
groupCallEventHandler?: GroupCallEventHandler
http: MatrixHttpApi<IHttpOpts & {
    onlyData: true;
}>
iceCandidatePoolSize: number = 0
idBaseUrl?: string
identityServer?: IIdentityServerProvider
ignoredInvites: IgnoredInvites
isGuestAccount: boolean = false
isVoipWithNoMediaAllowed: boolean
mediaHandler: MediaHandler = ...
notifTimelineSet: null | EventTimelineSet = null
olmVersion: null | [number, number, number] = null
ongoingScrollbacks: {
    [roomId: string]: {
        errorTs?: number;
        promise?: Promise<Room>;
    };
} = {}

Type declaration

  • [roomId: string]: {
        errorTs?: number;
        promise?: Promise<Room>;
    }
    • Optional errorTs?: number
    • Optional promise?: Promise<Room>
peekSync: null | SyncApi = null
pendingEventEncryption: Map<string, Promise<void>> = ...
pickleKey?: string
pushProcessor: PushProcessor = ...
pushRules?: IPushRules
roomList: RoomList
roomNameGenerator?: ((roomId: string, state: RoomNameState) => null | string)

Type declaration

    • (roomId: string, state: RoomNameState): null | string
    • Method to generate room names for empty rooms and rooms names based on membership. Defaults to a built-in English handler with basic pluralisation.

      Parameters

      Returns null | string

serverVersionsPromise?: Promise<IServerVersions>
sessionId: string
store: IStore
supportsCallTransfer: boolean = false
syncLeftRoomsPromise?: Promise<Room[]>
syncedLeftRooms: boolean = false
timelineSupport: boolean = false
toDeviceMessageQueue: ToDeviceMessageQueue
turnServers: ITurnServer[] = []
turnServersExpiry: number = 0
txnCtr: number = 0
urlPreviewCache: {
    [key: string]: Promise<IPreviewUrlResponse>;
} = {}

Type declaration

useE2eForGroupCall: boolean = true
usingExternalCrypto: boolean = false
verificationMethods?: string[]
RESTORE_BACKUP_ERROR_BAD_KEY: "RESTORE_BACKUP_ERROR_BAD_KEY" = "RESTORE_BACKUP_ERROR_BAD_KEY"

Accessors

Methods

  • Gets a set of room IDs in common with another user

    Returns

    Promise which resolves to a set of rooms

    Returns

    Rejects: with an error response.

    Parameters

    • userId: string

      The userId to check.

    Returns Promise<string[]>

  • Returns

    Promise which resolves: an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • scope: string
    • kind: PushRuleKind
    • ruleId: string
    • body: Pick<IPushRule, "pattern" | "actions" | "conditions">

    Returns Promise<{}>

  • Add a key for encrypting secrets.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    An object with: keyId: the ID of the key keyInfo: details about the key (iv, mac, passphrase)

    Parameters

    • algorithm: string

      the algorithm used by the key

    • opts: IAddSecretStorageKeyOpts

      the options for the algorithm. The properties used depend on the algorithm given.

    • Optional keyName: string

      the name of the key. If not given, a random name will be generated.

    Returns Promise<{
        keyId: string;
        keyInfo: ISecretStorageKeyInfo;
    }>

  • 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.

    Returns

    Promise which resolves: on success

    Returns

    Rejects: with an error response.

    Parameters

    • creds: any
    • bind: boolean

    Returns Promise<any>

  • 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.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • data: IAddThreePidOnlyBody

      A object with 3PID validation data from having called account/3pid/<medium>/requestToken on the homeserver.

    Returns Promise<{}>

  • Parameters

    • serviceType: SERVICE_TYPES
    • baseUrl: string
    • accessToken: string
    • termsUrls: string[]

    Returns Promise<{}>

  • Take a result from an earlier searchRoomEvents call, and backfill results.

    Returns

    Promise which resolves: updated result object

    Returns

    Rejects: with an error response.

    Type Parameters

    Parameters

    • searchResults: T

      the results object to be updated

    Returns Promise<T>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • userId: string
    • Optional reason: string

      Optional.

    Returns Promise<{}>

  • Begin a key verification.

    Returns

    a verification object

    Deprecated

    Use requestVerification instead.

    Parameters

    • method: string

      the verification method to use

    • userId: string

      the user to verify keys with

    • deviceId: string

      the device to verify

    Returns VerificationBase<any, any>

  • 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.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • data: IBindThreePidBody

      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.

    Returns Promise<{}>

  • 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:

    • creates new cross-signing keys if they are not found locally cached nor in secret storage (if it has been setup)

    The cross-signing API is currently UNSTABLE and may change without notice.

    Parameters

    Returns Promise<void>

  • 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

    • creates a new Secure Secret Storage key if no default key exists
      • if a key backup exists, it is migrated to store the key in the Secret Storage
    • creates a backup if none exists, and one is requested
    • migrates Secure Secret Storage to use the latest algorithm, if an outdated algorithm is found

    Parameters

    Returns Promise<void>

  • Looks up the public Matrix ID mappings for multiple 3PIDs.

    Returns

    Promise which resolves: Lookup results from IS.

    Returns

    Rejects: with an error response.

    Parameters

    • query: [string, string][]

      Array of arrays containing [medium, address]

    • identityAccessToken: string

      The access_token field of the Identity Server /account/register response (see registerWithIdentityServer).

    Returns Promise<any>

  • Cancel a room key request for this event if one is ongoing and resend the request.

    Returns

    A promise that will resolve when the key request is queued

    Parameters

    • event: MatrixEvent

      event of which to cancel and resend the room key request.

    Returns Promise<void>

  • Cancel a queued or unsent event.

    Throws

    Error if the event is not in QUEUED, NOT_SENT or ENCRYPTING state

    Parameters

    Returns void

  • Cancel a file upload in progress

    Returns

    true if canceled, otherwise false

    Parameters

    • upload: Promise<UploadResponse>

      The object returned from uploadContent

    Returns boolean

  • 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.

    Returns

    true if the key matches, otherwise false

    Parameters

    • privateKey: Uint8Array

      The private key

    • expectedPublicKey: string

      The public key

    Returns boolean

  • Check whether a given device is trusted.

    The cross-signing API is currently UNSTABLE and may change without notice.

    Parameters

    • userId: string

      The ID of the user whose devices is to be checked.

    • deviceId: string

      The ID of the device to check

    Returns DeviceTrustLevel

  • Check whether one of our own devices is cross-signed by our user's stored keys, regardless of whether we trust those keys yet.

    Returns

    true if the device is cross-signed

    Parameters

    • deviceId: string

      The ID of the device to check

    Returns boolean

  • Force a re-check of the local key backup status against what's on the server.

    Returns

    Object with backup info (as returned by getKeyBackupVersion) in backupInfo and trust information (as returned by isKeyBackupTrusted) in trustInfo.

    Returns Promise<null | IKeyBackupCheck>

  • 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.

    Returns

    true if the key matches, otherwise false

    Parameters

    • privateKey: Uint8Array

      The private key

    • expectedPublicKey: string

      The public key

    Returns boolean

  • Returns Promise<undefined | boolean>

  • Check whether a given user is trusted.

    The cross-signing API is currently UNSTABLE and may change without notice.

    Parameters

    • userId: string

      The ID of the user to check.

    Returns UserTrustLevel

  • Claim one-time keys

    Returns

    Promise which resolves: result object. Rejects: with an error response (MatrixError).

    Parameters

    • devices: [string, string][]

      a list of [userId, deviceId] pairs

    • keyAlgorithm: string = "signed_curve25519"

      desired key type

    • Optional timeout: number

      the time (in milliseconds) to wait for keys from remote servers

    Returns Promise<IClaimOTKsResult>

  • Clear any data out of the persistent stores used by the client.

    Returns

    Promise which resolves when the stores have been cleared.

    Returns Promise<void>

  • Counts the number of end to end session keys that are waiting to be backed up

    Returns

    Promise which resolves to the number of sessions requiring backup

    Returns Promise<number>

  • Create an alias to room ID mapping.

    Returns

    Promise which resolves: an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • alias: string

      The room alias to create.

    • roomId: string

      The room ID to link the alias to.

    Returns Promise<{}>

  • Creates a new call. The place*Call methods on the returned call can be used to actually place a call

    Returns

    the call or null if the browser doesn't support calling.

    Parameters

    • roomId: string

      The room the call is to be placed in.

    Returns null | MatrixCall

  • Creates a new dehydrated device (without queuing periodic dehydration)

    Returns

    the device id of the newly created dehydrated device

    Parameters

    • key: Uint8Array

      the dehydration key

    • keyInfo: IDehydratedDeviceKeyInfo

      Information about the key. Primarily for information about how to generate the key from a passphrase.

    • Optional deviceDisplayName: string

      The device display name for the dehydrated device.

    Returns Promise<undefined | string>

  • Create a new key backup version and enable it, using the information return from prepareKeyBackupVersion.

    Returns

    Object with 'version' param indicating the version created

    Parameters

    Returns Promise<IKeyBackupInfo>

  • Makes a request to /messages with the appropriate lazy loading filter set. XXX: if we do get rid of scrollback (as it's not used at the moment), we could inline this method again in paginateEventTimeline as that would then be the only call-site

    Parameters

    • roomId: string
    • fromToken: null | string
    • limit: number = 30

      the maximum amount of events the retrieve

    • dir: Direction

      'f' or 'b'

    • Optional timelineFilter: Filter

      the timeline filter to pass

    Returns Promise<IMessagesResponse>

  • Create a recovery key from a user-supplied passphrase.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    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.

    Parameters

    • Optional password: string

      Passphrase string that can be entered by the user when restoring the backup as an alternative to entering the recovery key. Optional.

    Returns Promise<IRecoveryKey>

  • Create a new room.

    Returns

    Promise which resolves: {room_id: {string}}

    Returns

    Rejects: with an error response.

    Parameters

    • options: ICreateRoomOpts

      a list of options to pass to the /createRoom API.

    Returns Promise<{
        room_id: string;
    }>

  • Makes a request to /messages with the appropriate lazy loading filter set. XXX: if we do get rid of scrollback (as it's not used at the moment), we could inline this method again in paginateEventTimeline as that would then be the only call-site

    Parameters

    • roomId: string
    • fromToken: null | string
    • limit: number = 30

      the maximum amount of events the retrieve

    • dir: Direction = Direction.Backward

      'f' or 'b'

    • threadListType: null | ThreadFilterType = ThreadFilterType.All
    • Optional timelineFilter: Filter

      the timeline filter to pass

    Returns Promise<IMessagesResponse>

  • 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.

    Returns

    Promise which resolves: On success, the empty object

    Parameters

    • Optional auth: any

      Optional. Auth data to supply for User-Interactive auth.

    • Optional erase: boolean

      Optional. If set, send as erase attribute in the JSON request body, indicating whether the account should be erased. Defaults to false.

    Returns Promise<{}>

  • Deactivates a user using Synapse's administrator API. This function is implementation specific and may change as a result.

    Returns

    the deactivate response - see Synapse docs for information.

    Parameters

    • userId: string

      the User ID to deactivate.

    Returns Promise<ISynapseAdminDeactivateResponse>

  • Parameters

    • eventType: string

    Returns Promise<void>

  • Delete an alias to room ID mapping. This alias must be on your local server, and you must have sufficient access to do this operation.

    Returns

    Promise which resolves: an empty object {}.

    Returns

    Rejects: with an error response.

    Parameters

    • alias: string

      The room alias to delete.

    Returns Promise<{}>

  • Delete the given device

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    • deviceId: string

      device to delete

    • Optional auth: IAuthDict

      Optional. Auth data to supply for User-Interactive auth.

    Returns Promise<{} | IAuthData>

  • Parameters

    • version: string

    Returns Promise<void>

  • Parameters

    • roomId: undefined
    • sessionId: undefined
    • Optional version: string

    Returns Promise<void>

  • Parameters

    • roomId: string
    • sessionId: undefined
    • Optional version: string

    Returns Promise<void>

  • Parameters

    • roomId: string
    • sessionId: string
    • Optional version: string

    Returns Promise<void>

  • Delete multiple device

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    • devices: string[]

      IDs of the devices to delete

    • Optional auth: IAuthDict

      Optional. Auth data to supply for User-Interactive auth.

    Returns Promise<{} | IAuthData>

  • Returns

    Promise which resolves: an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<{}>

  • Returns

    Promise which resolves: to an empty object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • tagName: string

      name of room tag to be removed

    Returns Promise<{}>

  • Returns

    Promise which resolves: The server response on success (generally the empty JSON object)

    Returns

    Rejects: with an error response.

    Parameters

    • medium: string

      The threepid medium (eg. 'email')

    • address: string

      The threepid address (eg. 'bob@example.com') this must be as returned by getThreePids.

    Returns Promise<{
        id_server_unbind_result: IdServerUnbindResult;
    }>

  • Disable backing up of keys.

    Returns void

  • 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.

    Returns

    true if id_access_token can be sent

    Returns Promise<boolean>

  • Query the server to see if it is forcing encryption to be enabled for a given room preset, based on the /versions response.

    Returns

    true if the server is forcing encryption for the preset.

    Parameters

    • presetName: Preset

      The name of the preset to check.

    Returns Promise<boolean>

  • Query the server to see if the id_server parameter is required when registering with an 3pid, adding a 3pid or resetting password.

    Returns

    true if id_server parameter is required

    Returns Promise<boolean>

  • Query the server to see if it supports members lazy loading

    Returns

    true if server supports lazy loading

    Returns Promise<boolean>

  • Query the server to see if it supports the MSC2457 logout_devices parameter when setting password

    Returns

    true if server supports the logout_devices parameter

    Returns Promise<boolean>

  • 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.

    Returns

    true if separate functions are supported

    Returns Promise<boolean>

  • Query the server to see if it lists support for an unstable feature in the /versions response

    Returns

    true if the feature is supported

    Parameters

    • feature: string

      the feature name

    Returns Promise<boolean>

  • Download the keys for a list of users and stores the keys in the session store.

    Returns

    A promise which resolves to a map userId->deviceId->DeviceInfo

    Parameters

    • userIds: string[]

      The users to fetch.

    • Optional forceDownload: boolean

      Always download the keys even if cached.

    Returns Promise<Record<string, Record<string, IDevice>>>

  • Download device keys

    Returns

    Promise which resolves: result object. Rejects: with an error response (MatrixError).

    Parameters

    • userIds: string[]

      list of users to get keys for

    • token: {
          token?: string;
      } = {}

      sync token to pass in the query request, to help the HS give the most recent results

      • Optional token?: string

    Returns Promise<IDownloadKeyResult>

  • Enable backing up of keys, using data previously returned from getKeyBackupVersion.

    Returns

    Promise which resolves when complete.

    Parameters

    • info: IKeyBackupInfo

      Backup information object as returned by getKeyBackupVersion

    Returns Promise<void>

  • Encrypts and sends a given object via Olm to-device messages to a given set of devices.

    Returns

    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.

    Parameters

    • userDeviceInfoArr: IOlmDevice<DeviceInfo>[]
    • payload: object

      fields to include in the encrypted payload

    Returns Promise<void>

  • Returns Promise<void>

  • Fetches relations for a given event

    Returns

    the response, with chunk, prev_batch and, next_batch.

    Parameters

    • roomId: string

      the room of the event

    • eventId: string

      the id of the event

    • Optional relationType: null | string

      the rel_type of the relations requested

    • Optional eventType: null | string

      the event type of the relations requested

    • opts: IRelationsRequestOpts = ...

      options with optional values for the request.

    Returns Promise<IRelationsResponse>

  • Get an event in a room by its event id.

    Returns

    Promise which resolves to an object containing the event.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • eventId: string

    Returns Promise<Partial<IEvent>>

  • Parameters

    • room: Room
    • verifyLinks: boolean
    • msc3946ProcessDynamicPredecessor: boolean

    Returns Room[]

  • Parameters

    • room: Room
    • verifyLinks: boolean
    • msc3946ProcessDynamicPredecessor: boolean

    Returns Room[]

  • Once the client has been initialised, we want to clear notifications we know for a fact should be here. This issue should also be addressed on synapse's side and is tracked as part of https://github.com/matrix-org/synapse/issues/14837

    We consider a room or a thread as fully read if the current user has sent the last event in the live timeline of that context and if the read receipt we have on record matches.

    Returns void

  • Marks all group sessions as needing to be backed up without scheduling them to upload in the background.

    Returns

    Promise which resolves to the number of sessions requiring a backup.

    Returns Promise<number>

  • Forces the current outbound group session to be discarded such that another one will be created next time an event is sent.

    Parameters

    • roomId: string

      The ID of the room to discard the session for

      This should not normally be necessary.

    Returns void

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • deleteRoom: boolean = true

      True to delete the room from the store on success. Default: true.

    Returns Promise<{}>

  • Generates a random string suitable for use as a client secret. This method is experimental and may change.

    Returns

    A new client secret

    Returns string

  • Get the access token associated with this account.

    Returns

    The access_token or null

    Returns null | string

  • Get account data event of given type for the current user.

    Returns

    The contents of the given account data event

    Parameters

    • eventType: string

      The event type

    Returns undefined | MatrixEvent

  • 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.

    Returns

    Promise which resolves: The contents of the given account data event.

    Returns

    Rejects: with an error response.

    Type Parameters

    • T extends {
          [k: string]: any;
      }

    Parameters

    • eventType: string

      The event type

    Returns Promise<null | T>

  • Gets the capabilities of the homeserver. Always returns an object of capability keys and their options, which may be empty.

    Returns

    Promise which resolves to the capabilities of the homeserver

    Returns

    Rejects: with an error response.

    Parameters

    • fresh: boolean = false

      True to ignore any cached values.

    Returns Promise<ICapabilities>

  • Returns

    The HS URL to hit to begin the CAS login process.

    Parameters

    • redirectUrl: string

      The URL to redirect to after the HS authenticates with CAS.

    Returns string

  • Get the user's cross-signing key ID.

    The cross-signing API is currently UNSTABLE and may change without notice.

    Returns

    the key ID

    Parameters

    • type: string = CrossSigningKey.Master

      The type of key to get the ID of. One of "master", "self_signing", or "user_signing". Defaults to "master".

    Returns null | string

  • Access the crypto API for this client.

    If end-to-end encryption has been enabled for this client (via initCrypto or initRustCrypto), returns an object giving access to the crypto API. Otherwise, returns undefined.

    Returns undefined | CryptoApi

  • 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

    Returns

    True if trusting cross-signed devices

    Returns boolean

  • Get a list of all file uploads in progress

    Returns

    Array of objects representing current uploads. Currently in progress is element 0. Keys:

    • promise: The promise associated with the upload
    • loaded: Number of bytes uploaded
    • total: Total number of bytes to upload

    Returns Upload[]

  • Get the current default key ID for encrypting secrets.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    The default key ID or null if no default key ID is set

    Returns Promise<null | string>

  • Gets specific device details for the logged-in user

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    • deviceId: string

      device to query

    Returns Promise<IMyDevice>

  • Get the Curve25519 key for this device

    Returns

    base64-encoded curve25519 key. Null if crypto is disabled.

    Returns null | string

  • Get the Ed25519 key for this device

    Returns

    base64-encoded ed25519 key. Null if crypto is disabled.

    Returns null | string

  • Get the device ID of this client

    Returns

    device ID

    Returns null | string

  • Gets all devices recorded for the logged-in user

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Returns Promise<{
        devices: IMyDevice[];
    }>

  • Get the domain for this client's MXID

    Returns

    Domain of this MXID

    Returns null | string

  • Returns the eventType that should be used taking encryption into account for a given eventType.

    Returns

    the event type taking encryption into account

    Parameters

    • roomId: string

      the room for the events eventType relates to

    • Optional eventType: null | string

      the event type

    Returns undefined | null | string

  • 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.

    Returns

    Promise which resolves: EventTimeline including the given event

    Parameters

    • timelineSet: EventTimelineSet

      The timelineSet to look for the event in, must be bound to a room

    • eventId: string

      The ID of the event to look for

    Returns Promise<Optional<EventTimeline>>

  • Get the fallback URL to use for unknown interactive-auth stages.

    Returns

    HS URL to hit to for the fallback interface

    Parameters

    • loginType: string

      the type of stage being attempted

    • authSessionId: string

      the auth session ID provided by the homeserver

    Returns string

  • Retrieve a filter.

    Returns

    Promise which resolves: a Filter object

    Returns

    Rejects: with an error response.

    Parameters

    • userId: string

      The user ID of the filter owner

    • filterId: string

      The filter ID to retrieve

    • allowCached: boolean

      True to allow cached filters to be returned. Default: True.

    Returns Promise<Filter>

  • Returns

    whether to blacklist all unverified devices by default

    Deprecated

    Prefer direct access to globalBlacklistUnverifiedDevices:

    value = client.getCrypto().globalBlacklistUnverifiedDevices;
    

    Returns boolean

  • Returns

    whether to error on unknown devices

    This API is currently UNSTABLE and may change or be removed without notice.

    Returns boolean

  • Get an existing group call for the provided room.

    Returns

    The group call or null if it doesn't already exist.

    Parameters

    • roomId: string

    Returns null | GroupCall

  • Get the Homeserver URL of this client

    Returns

    Homeserver URL of this client

    Returns string

  • 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.

    Returns

    Promise which resolves: an object with account info.

    Returns

    Rejects: with an error response.

    Parameters

    • identityAccessToken: string

      The access_token field of the Identity Server /account/register response (see registerWithIdentityServer).

    Returns Promise<any>

  • Gets the V2 hashing information from the identity server. Primarily useful for lookups.

    Returns

    The hashing information for the identity server.

    Parameters

    • identityAccessToken: string

      The access token for the identity server.

    Returns Promise<any>

  • Get the identity server URL of this client

    Returns

    Identity server URL of this client

    Parameters

    • stripProto: boolean = false

      whether or not to strip the protocol from the URL

    Returns undefined | string

  • Gets the users that are ignored by this client

    Returns

    The array of users that are ignored (empty if none)

    Returns string[]

  • Retrieve membership info. for a room.

    Returns

    Promise which resolves: A list of currently joined users and their profile data.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      ID of the room to get membership for

    Returns Promise<IJoinedMembersResponse>

  • Returns

    true if the client is configured to back up keys to the server, otherwise false. If we haven't completed a successful check of key backup status yet, returns null.

    Returns null | boolean

  • Ask the server for a list of users who have changed their device lists between a pair of sync tokens

    Returns

    Promise which resolves: result object. Rejects: with an error response (MatrixError).

    Parameters

    • oldToken: string
    • newToken: string

    Returns Promise<{
        changed: string[];
        left: string[];
    }>

  • 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.

    Returns

    Promise which resolves: EventTimeline timeline with the latest events in the room

    Parameters

    Returns Promise<Optional<EventTimeline>>

  • 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.

    Returns

    Promise which resolves: an object with an aliases property, containing an array of local aliases

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      The room ID to get local aliases for.

    Returns Promise<{
        aliases: string[];
    }>

  • 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.

    Returns

    Promise which resolves: Token object

    Returns

    Rejects: with an error response.

    Returns Promise<IOpenIDToken>

  • Returns

    Filter ID

    Parameters

    • filterName: string
    • filter: Filter

    Returns Promise<string>

  • Returns

    Promise which resolves: The presence state for this user.

    Returns

    Rejects: with an error response.

    Parameters

    • userId: string

      The user to get presence for

    Returns Promise<IStatusResponse>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • userId: string
    • Optional info: string

      The kind of info to retrieve (e.g. 'displayname', 'avatar_url').

    Returns Promise<{
        avatar_url?: string;
        displayname?: string;
    }>

  • 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.

    Returns

    A dict of actions to perform.

    Parameters

    • event: MatrixEvent

      The event to get push actions for.

    • forceRecalculate: boolean = false

      forces to recalculate actions for an event Useful when an event just got decrypted

    Returns null | IActionsObject

  • Get the push rules for the account from the server.

    Returns

    Promise which resolves to the push rules.

    Returns

    Rejects: with an error response.

    Returns Promise<IPushRules>

  • Gets all pushers registered for the logged-in user

    Returns

    Promise which resolves: Array of objects representing pushers

    Returns

    Rejects: with an error response.

    Returns Promise<{
        pushers: IPusher[];
    }>

  • 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.

    Returns

    The Room or null if it doesn't exist or there is no data store.

    Parameters

    • roomId: undefined | string

      The room ID

    Returns null | Room

  • Get the visibility of a room in the current HS's room directory

    Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

    Returns Promise<{
        visibility: Visibility;
    }>

  • 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.

    Returns

    the response, with next_batch & rooms fields.

    Parameters

    • roomId: string

      The ID of the space-room to use as the root of the summary.

    • Optional limit: number

      The maximum number of rooms to return per page.

    • Optional maxDepth: number

      The maximum depth in the tree from the root room to return.

    • suggestedOnly: boolean = false

      Whether to only return rooms with suggested=true.

    • Optional fromToken: string

      The opaque token to paginate a previous request.

    Returns Promise<IRoomHierarchy>

  • Get room info for the given alias.

    Returns

    Promise which resolves: Object with room_id and servers.

    Returns

    Rejects: with an error response.

    Parameters

    • alias: string

      The room alias to resolve.

    Returns Promise<{
        room_id: string;
        servers: string[];
    }>

  • Get the room-kind push rule associated with a room.

    Returns

    the rule or undefined.

    Parameters

    • scope: "global" | "device"

      "global" or device-specific.

    • roomId: string

      the id of the room.

    Returns undefined | IPushRule

  • 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

    Parameters

    • roomIdOrAlias: string

      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.

    Returns Promise<IRoomSummary>

  • Returns

    Promise which resolves: to an object keyed by tagId with objects containing a numeric order field.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

    Returns Promise<ITagsResponse>

  • 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.

    Returns

    An array of rooms representing the upgrade history.

    Parameters

    • roomId: string

      The room ID to search from

    • verifyLinks: boolean = false

      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.

    • msc3946ProcessDynamicPredecessor: boolean = false

      if true, look for m.room.predecessor state events as well as create events, and prefer predecessor events where they exist (MSC3946).

    Returns Room[]

  • Retrieve all known rooms.

    Returns

    A list of rooms, or an empty list if there is no data store.

    Returns Room[]

  • Get the user-id of the logged-in user

    Returns

    MXID for the logged-in user

    Throws

    Error if not logged in

    Returns string

  • Get a secret from storage.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    the contents of the secret

    Parameters

    • name: string

      the name of the secret

    Returns Promise<undefined | string>

  • Get the session ID of this client

    Returns

    session ID

    Returns string

  • Returns

    The HS URL to hit to begin the SSO login process.

    Parameters

    • redirectUrl: string

      The URL to redirect to after the HS authenticates with the SSO.

    • loginType: string = "sso"

      The type of SSO login we are doing (sso or cas). Defaults to 'sso'.

    • Optional idpId: string

      The ID of the Identity Provider being targeted, optional.

    • Optional action: SSOAction

      the SSO flow to indicate to the IdP, optional.

    Returns string

  • Retrieve a state event.

    Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • eventType: string
    • stateKey: string

    Returns Promise<Record<string, any>>

  • Get the cross signing information for a given user.

    The cross-signing API is currently UNSTABLE and may change without notice.

    Returns

    the cross signing information for the user.

    Parameters

    • userId: string

      the user ID to get the cross-signing info for.

    Returns null | CrossSigningInfo

  • Get the stored device key for a user id and device id

    Returns

    device or null

    Parameters

    • userId: string

      the user to list keys for.

    • deviceId: string

      unique identifier for the device

    Returns null | DeviceInfo

  • Get the stored device keys for a user id

    Returns

    list of devices

    Parameters

    • userId: string

      the user to list keys for.

    Returns DeviceInfo[]

  • Get the current sync state.

    Returns

    the sync state, which may be null.

    See

    MatrixClient#event:"sync"

    Returns null | SyncState

  • 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.

    Returns null | ISyncStateData

  • Get information on how a specific place on a third party protocol may be reached.

    Returns

    Promise which resolves to the result object

    Parameters

    • protocol: string

      The protocol given in getThirdpartyProtocols()

    • params: {
          searchFields?: string[];
      }

      Protocol-specific parameters, as given in the response to getThirdpartyProtocols()

      • Optional searchFields?: string[]

    Returns Promise<IThirdPartyLocation[]>

  • Get the third party protocols that can be reached using this HS

    Returns

    Promise which resolves to the result object

    Returns Promise<{
        [protocol: string]: IProtocol;
    }>

  • Get information on how a specific user on a third party protocol may be reached.

    Returns

    Promise which resolves to the result object

    Parameters

    • protocol: string

      The protocol given in getThirdpartyProtocols()

    • params: any

      Protocol-specific parameters, as given in the response to getThirdpartyProtocols()

    Returns Promise<IThirdPartyUser[]>

  • Returns

    Promise which resolves to a list of the user's threepids.

    Returns

    Rejects: with an error response.

    Returns Promise<{
        threepids: IThreepid[];
    }>

  • Get the unix timestamp (in milliseconds) at which the current TURN credentials (from getTurnServers) expire

    Returns

    The expiry timestamp in milliseconds

    Returns number

  • 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.

    Returns

    Promise which resolves: Object of OG metadata.

    Returns

    Rejects: with an error response. May return synthesized attributes if the URL lacked OG meta.

    Parameters

    • url: string

      The URL to get preview data for

    • ts: number

      The preferred point in time that the preview should describe (ms since epoch). The preview returned will either be the most recent one preceding this timestamp if available, or failing that the next most recent available preview.

    Returns Promise<IPreviewUrlResponse>

  • Returns true if to-device signalling for group calls will be encrypted with Olm. If false, it will be sent unencrypted.

    Returns

    boolean Whether group call signalling will be encrypted

    Returns boolean

  • Retrieve a user.

    Returns

    A user or null if there is no data store or the user does not exist.

    Parameters

    • userId: string

      The user ID to retrieve.

    Returns null | User

  • Get the user-id of the logged-in user

    Returns

    MXID for the logged-in user, or null if not logged in

    Returns null | string

  • Get the local part of the current user ID e.g. "foo" in "@foo:bar".

    Returns

    The user ID localpart or null.

    Returns null | string

  • Retrieve all known users.

    Returns

    A list of users, or an empty list if there is no data store.

    Returns User[]

  • 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.

    Returns

    A list of rooms, or an empty list if there is no data store.

    Parameters

    • msc3946ProcessDynamicPredecessor: boolean = false

      if true, look for an m.room.predecessor state event and use it if found (MSC3946).

    Returns Room[]

  • Get if lazy loading members is being used.

    Returns

    Whether or not members are lazy loaded by this client

    Returns boolean

  • Check whether we have a key with a given ID.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    Whether we have the key.

    Parameters

    • Optional keyId: string

      The ID of the key to check for. Defaults to the default key ID if not provided.

    Returns Promise<boolean>

  • 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.

    Returns

    A collection of address mappings to found MXIDs. Results where no user could be found will not be listed.

    Parameters

    • addressPairs: [string, string][]

      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"]

    • identityAccessToken: string

      The access token for the identity server.

    Returns Promise<{
        address: string;
        mxid: string;
    }[]>

  • Initialise support for end-to-end encryption in this client, using libolm.

    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.

    Returns Promise<void>

  • Experimental

    Initialise support for end-to-end encryption in this client, using the rust matrix-sdk-crypto.

    An alternative to initCrypto.

    WARNING: this API is very experimental, should not be used in production, and may change without notice! Eventually it will be deprecated and initCrypto will do the same thing.

    Returns

    a Promise which will resolve when the crypto layer has been successfully initialised.

    Returns Promise<void>

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • userId: string
    • Optional reason: string

      Optional.

    Returns Promise<{}>

  • Invite a user to a room based on their email address.

    Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      The room to invite the user to.

    • email: string

      The email address to invite.

    Returns Promise<{}>

  • Invite a user to a room based on a third-party identifier.

    Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      The room to invite the user to.

    • medium: string

      The medium to invite the user e.g. "email".

    • address: string

      The address for the specified medium.

    Returns Promise<{}>

  • Checks whether cross signing:

    • is enabled on this account and trusted by this device
    • has private keys either cached locally or stored in secret storage

    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.

    Returns

    True if cross-signing is ready to be used on this device

    Returns Promise<boolean>

  • Is end-to-end crypto enabled for this client.

    Returns

    True if end-to-end is enabled.

    Deprecated

    prefer getCrypto

    Returns boolean

  • Check if the sender of an event is verified

    Returns

    true if the sender of this event has been verified using setDeviceVerified.

    Parameters

    Returns Promise<boolean>

  • Get whether to allow a fallback ICE server should be used for negotiating a WebRTC connection if the homeserver doesn't provide any servers. Defaults to false.

    Returns

    Returns boolean

  • Return whether the client is configured for a guest account.

    Returns

    True if this is a guest access_token (or no token is supplied).

    Returns boolean

  • Whether the initial sync has completed.

    Returns

    True if at least one sync has happened.

    Returns boolean

  • Check whether the key backup private key is stored in secret storage.

    Returns

    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

    Returns Promise<null | Record<string, ISecretStorageKeyInfo>>

  • Returns

    true if there is a valid access_token for this client.

    Returns boolean

  • Whether encryption is enabled for a room.

    Returns

    whether encryption is enabled.

    Parameters

    • roomId: string

      the room id to query.

    Returns boolean

  • Checks whether secret storage:

    • is enabled on this account
    • is storing cross-signing private keys
    • is storing session backup key (if enabled)

    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.

    Returns

    True if secret storage is ready to be used on this device

    Returns Promise<boolean>

  • Check if a secret is stored on the server.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    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

    Parameters

    • name: string

      the name of the secret

    Returns Promise<null | Record<string, ISecretStorageKeyInfo>>

  • 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.

    Returns

    true if the user appears to be a Synapse administrator.

    Returns Promise<boolean>

  • Gets whether or not a specific user is being ignored by this client.

    Returns

    true if the user is ignored, false otherwise

    Parameters

    • userId: string

      the user ID to check

    Returns boolean

  • Check whether a username is available prior to registration. An error response indicates an invalid/unavailable username.

    Returns

    Promise which resolves: to boolean of whether the username is available.

    Parameters

    • username: string

      The username to check the availability of.

    Returns Promise<boolean>

  • Parameters

    • recoveryKey: string

    Returns boolean

  • Check if a particular spec version is supported by the server.

    Returns

    Whether it is supported

    Parameters

    • version: string

      The spec version (such as "r0.5.0") to check for.

    Returns Promise<boolean>

  • Join a room. If you have already joined the room, this will no-op.

    Returns

    Promise which resolves: Room object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomIdOrAlias: string

      The room ID or room alias to join.

    • opts: IJoinRoomOpts = {}

      Options when joining the room.

    Returns Promise<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.

    Returns

    key backup key

    Parameters

    • password: string

      Passphrase

    • backupInfo: IKeyBackupInfo

      Backup metadata from checkKeyBackup

    Returns Promise<Uint8Array>

  • 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.

    Returns

    key backup key

    Parameters

    • recoveryKey: string

      The recovery key

    Returns Uint8Array

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • userId: string
    • Optional reason: string

      Optional.

    Returns Promise<{}>

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

    Returns Promise<{}>

  • 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.

    Returns

    Promise which resolves when completed with an object keyed by room ID and value of the error encountered when leaving or null.

    Parameters

    • roomId: string

      The room ID to start leaving at

    • includeFuture: boolean = true

      If true, the whole chain (past and future) of upgraded rooms will be left.

    Returns Promise<{
        [roomId: string]: Error | MatrixError | null;
    }>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • loginType: string
    • data: any

    Returns Promise<any>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • user: string
    • password: string

    Returns Promise<any>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • relayState: string

      URL Callback after SAML2 Authentication

    Returns Promise<any>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • token: string

      Login token previously received from homeserver

    Returns Promise<any>

  • 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.

    Returns

    Promise which resolves: On success, the empty object {}

    Parameters

    • stopClient: boolean = false

      whether to stop the client before calling /logout to prevent invalid token errors.

    Returns Promise<{}>

  • Looks up the public Matrix ID mapping for a given 3rd party identifier from the identity server

    Returns

    Promise which resolves: A threepid mapping object or the empty object if no mapping exists

    Returns

    Rejects: with an error response.

    Parameters

    • medium: string

      The medium of the threepid, eg. 'email'

    • address: string

      The textual address of the threepid

    • identityAccessToken: string

      The access_token field of the Identity Server /account/register response (see registerWithIdentityServer).

    Returns Promise<any>

  • Make up a new transaction id

    Returns

    a new, unique, transaction id

    Returns string

  • Returns

    Promise which resolves: dictionary of userid to profile information

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • Optional includeMembership: string

      the membership type to include in the response

    • Optional excludeMembership: string

      the membership type to exclude from the response

    • Optional atEventId: string

      the id of the event for which moment in the timeline the members should be returned for

    Returns Promise<{
        [userId: string]: IStateEventWithRoomId[];
    }>

  • Parameters

    • roomId: string
    • userId: undefined | string
    • membership: string
    • Optional reason: string

    Returns Promise<{}>

  • Turn an MXC URL into an HTTP one. This method is experimental and may change.

    Returns

    the avatar URL or null.

    Parameters

    • mxcUrl: string

      The MXC URL

    • Optional width: number

      The desired width of the thumbnail.

    • Optional height: number

      The desired height of the thumbnail.

    • Optional resizeMethod: string

      The thumbnail resize method to use, either "crop" or "scale".

    • Optional allowDirectLinks: boolean

      If true, return any non-mxc URLs directly. Fetching such URLs will leak information about the user to anyone they share a room with. If false, will return null for such URLs.

    Returns null | string

  • Take an EventTimeline, and back/forward-fill results.

    Returns

    Promise which resolves to a boolean: false if there are no events and we reached either end of the timeline; else true.

    Parameters

    Returns Promise<boolean>

  • Peek into a room and receive updates about the room. This only works if the history visibility for the room is world_readable.

    Returns

    Promise which resolves: Room object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      The room to attempt to peek into.

    Returns Promise<Room>

  • Set up the data required to create a new backup version. The backup version will not be created and enabled until createKeyBackupVersion is called.

    Returns

    Object that can be passed to createKeyBackupVersion and additionally has a 'recovery_key' member with the user-facing recovery key string.

    Parameters

    • Optional password: null | string | Uint8Array

      Passphrase string that can be entered by the user when restoring the backup as an alternative to entering the recovery key. Optional.

    • opts: IKeyBackupPrepareOpts = ...

    Returns Promise<Pick<IPreparedKeyBackupVersion, "algorithm" | "auth_data" | "recovery_key">>

  • Perform any background tasks that can be done before a message is ready to send, in order to speed up sending of the message.

    Deprecated

    Prefer CryptoApi.prepareToEncrypt:

    client.getCrypto().prepareToEncrypt(room);
    

    Parameters

    • room: Room

      the room the event is in

    Returns void

  • Calls aggregation functions for event types that are aggregated Polls and location beacons

    Returns

    Parameters

    • Optional room: Room

      room the events belong to

    • Optional events: MatrixEvent[]

      timeline events to be processed

    Returns void

  • Internal

    helper for searchRoomEvents and backPaginateRoomEventsSearch. Processes the response from the API call and updates the searchResults

    Returns

    searchResults

    Type Parameters

    Parameters

    Returns T

  • Processes a list of threaded events and adds them to their respective timelines

    Parameters

    • room: Room

      the room the adds the threaded events

    • threadedEvents: MatrixEvent[]

      an array of the threaded events

    • toStartOfTimeline: boolean

      the direction in which we want to add the events

    Returns void

  • Processes a list of thread roots and creates a thread model

    Parameters

    • room: Room

      the room to create the threads in

    • threadedEvents: MatrixEvent[]

      an array of thread roots

    • toStartOfTimeline: boolean

      the direction

    Returns void

  • 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.

    Parameters

    Returns Promise<void>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Throws

    Error if called with with_relations (MSC3912) but the server does not support it. Callers should check whether the server supports MSC3912 via MatrixClient.canSupport.

    Parameters

    • roomId: string
    • eventId: string
    • Optional txnId: string

      transaction id. One will be made up if not supplied.

    • Optional opts: IRedactOpts

      Options to pass on, may contain reason and with_relations (MSC3912)

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • eventId: string
    • Optional txnId: string
    • Optional opts: IRedactOpts

    Returns Promise<ISendEventResponse>

  • Refreshes 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.

    Returns

    Promise which resolves to the new token.

    Returns

    Rejects with an error response.

    Parameters

    • refreshToken: string

      The refresh token.

    Returns Promise<IRefreshTokenResponse>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • username: string
    • password: string
    • sessionId: null | string
    • auth: {
          session?: string;
          type: string;
      }
      • Optional session?: string
      • type: string
    • Optional bindThreepids: null | boolean | {
          email?: boolean;
          msisdn?: 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: string
    • Optional inhibitLogin: boolean

    Returns Promise<IAuthData>

  • Register 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);

    Returns

    Promise which resolves: JSON object that contains: { user_id, device_id, access_token, home_server }

    Returns

    Rejects: with an error response.

    Parameters

    • body: {
          body?: any;
      } = {}

      JSON HTTP body to provide.

      • Optional body?: any

    Returns Promise<any>

  • Register with an identity server using the OpenID token from the user's Homeserver, which can be retrieved via getOpenIdToken.

    Note that the /account/register endpoint (as well as IS authentication in general) was added as part of the v2 API version.

    Returns

    Promise which resolves: with object containing an Identity Server access token.

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<{
        access_token: string;
        token: string;
    }>

  • 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.

    Returns

    Promise which resolves to undefined if a device could not be dehydrated, or to the new device ID if the dehydration was successful.

    Returns

    Rejects: with an error response.

    Returns Promise<undefined | string>

  • 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.

    Returns

    an object with events as MatrixEvent[] and optionally nextBatch if more relations are available.

    Parameters

    • roomId: string

      the room of the event

    • eventId: string

      the id of the event

    • Optional relationType: null | string

      the rel_type of the relations requested

    • Optional eventType: null | string

      the event type of the relations requested

    • opts: IRelationsRequestOpts = ...

      options with optional values for the request.

    Returns Promise<{
        events: MatrixEvent[];
        nextBatch?: null | string;
        originalEvent?: null | MatrixEvent;
        prevBatch?: null | string;
    }>

  • Reports an event as inappropriate to the server, which may then notify the appropriate people.

    Returns

    Promise which resolves to an empty object if successful

    Parameters

    • roomId: string

      The room in which the event being reported is located.

    • eventId: string

      The event to report.

    • score: number

      The score to rate this content as where -100 is most offensive and 0 is inoffensive.

    • reason: string

      The reason the content is being reported. May be blank.

    Returns Promise<{}>

  • 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).

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • email: string

      As requestEmailToken

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • Optional nextLink: string

      As requestEmailToken

    Returns Promise<IRequestTokenResponse>

  • 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.

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • phoneCountry: string

      As requestRegisterMsisdnToken

    • phoneNumber: string

      As requestRegisterMsisdnToken

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • Optional nextLink: string

      As requestEmailToken

    Returns Promise<IRequestMsisdnTokenResponse>

  • 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.

    Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Throws

    Error if no identity server is set

    Parameters

    • email: string

      The email address to request a token for

    • clientSecret: string

      A secret binary string generated by the client. It is recommended this be around 16 ASCII characters.

    • sendAttempt: number

      If an identity server sees a duplicate request with the same sendAttempt, it will not send another email. To request another email to be sent, use a larger value for the sendAttempt param as was used in the previous request.

    • Optional nextLink: string

      Optional If specified, the client will be redirected to this link after validation.

    • Optional identityAccessToken: string

      The access_token field of the identity server /account/register response (see registerWithIdentityServer).

    Returns Promise<IRequestTokenResponse>

  • 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.

    Returns

    Promise which resolves to an object with a sid string

    Returns

    Rejects: with an error response.

    Throws

    Error if no identity server is set

    Parameters

    • phoneCountry: string

      The ISO 3166-1 alpha-2 code for the country in which phoneNumber should be parsed relative to.

    • phoneNumber: string

      The phone number, in national or international format

    • clientSecret: string

      A secret binary string generated by the client. It is recommended this be around 16 ASCII characters.

    • sendAttempt: number

      If an identity server sees a duplicate request with the same sendAttempt, it will not send another SMS. To request another SMS to be sent, use a larger value for the sendAttempt param as was used in the previous request.

    • Optional nextLink: string

      Optional If specified, the client will be redirected to this link after validation.

    • Optional identityAccessToken: string

      The access_token field of the Identity Server /account/register response (see registerWithIdentityServer).

    Returns Promise<IRequestMsisdnTokenResponse>

  • 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.

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • email: string

      As requestEmailToken

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • Optional nextLink: string

      As requestEmailToken

    Returns Promise<IRequestTokenResponse>

  • 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.

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • phoneCountry: string

      As requestRegisterMsisdnToken

    • phoneNumber: string

      As requestRegisterMsisdnToken

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • nextLink: string

      As requestEmailToken

    Returns Promise<IRequestMsisdnTokenResponse>

  • 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

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • email: string

      As requestEmailToken

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • Optional nextLink: string

      As requestEmailToken

    Returns Promise<IRequestTokenResponse>

  • 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.

    Returns

    Promise which resolves: As requestEmailToken

    Parameters

    • phoneCountry: string

      The ISO 3166-1 alpha-2 code for the country in which phoneNumber should be parsed relative to.

    • phoneNumber: string

      The phone number, in national or international format

    • clientSecret: string

      As requestEmailToken

    • sendAttempt: number

      As requestEmailToken

    • Optional nextLink: string

      As requestEmailToken

    Returns Promise<IRequestMsisdnTokenResponse>

  • Request a secret from another device.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Returns

    the secret request object

    Parameters

    • name: string

      the name of the secret to request

    • devices: string[]

      the devices to request the secret from

    Returns ISecretRequest

  • Internal utility function for requesting validation tokens from usage-specific requestToken endpoints.

    Returns

    Promise which resolves: As requestEmailToken

    Type Parameters

    Parameters

    • endpoint: string

      The endpoint to send the request to

    • params: Record<string, any>

      Parameters for the POST request

    Returns Promise<T>

  • Request a key verification from another user.

    Returns

    resolves to a VerificationRequest when the request has been sent to the other party.

    Parameters

    • userId: string

      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

    Returns Promise<VerificationRequest<IVerificationChannel>>

  • Resend an event. Will also retry any to-device messages waiting to be sent.

    Returns

    Promise which resolves: to an ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • event: MatrixEvent

      The event to resend.

    • room: Room

      Optional. The room the event is in. Will update the timeline entry if provided.

    Returns Promise<ISendEventResponse>

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

    Returns void

  • Returns

    Promise which resolves: Object with room_id and servers.

    Returns

    Rejects: with an error response.

    Parameters

    • roomAlias: string

    Returns Promise<{
        room_id: string;
        servers: string[];
    }>

  • Restore from an existing key backup via a private key stored in secret storage.

    Returns

    Status of restoration with total and imported key counts.

    Parameters

    • backupInfo: IKeyBackupInfo

      Backup metadata from checkKeyBackup

    • Optional targetRoomId: string

      Room ID to target a specific room. Restores all rooms if omitted.

    • Optional targetSessionId: string

      Session ID to target a specific session. Restores all sessions if omitted.

    • Optional opts: IKeyBackupRestoreOpts

      Optional params such as callbacks

    Returns Promise<IKeyBackupRestoreResult>

  • 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).

    Returns

    True if this resulted in a request being retried.

    Returns boolean

  • Marks all group sessions as needing to be backed up and schedules them to upload in the background as soon as possible.

    Returns Promise<void>

  • 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).

    Returns

    Promise which resolves: Room. If you are at the beginning of the timeline, Room.oldState.paginationToken will be null.

    Returns

    Rejects: with an error response.

    Parameters

    • room: Room

      The room to get older messages in.

    • limit: number = 30

      Optional. The maximum number of previous events to pull in. Default: 30.

    Returns Promise<Room>

  • Perform a server-side search.

    Returns

    Promise which resolves to the search response object.

    Returns

    Rejects: with an error response.

    Parameters

    • __namedParameters: {
          body: ISearchRequestBody;
          next_batch?: string;
      }
    • Optional abortSignal: AbortSignal

      optional signal used to cancel the http request.

    Returns Promise<ISearchResponse>

  • Perform a server-side search for room events.

    The returned promise resolves to an object containing the fields:

    • count: estimate of the number of results
    • next_batch: token for back-pagination; if undefined, there are no more results
    • highlights: a list of words to highlight from the stemming algorithm
    • results: a list of results

    Each entry in the results list is a SearchResult.

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<ISearchResults>

  • Query the user directory with a term matching user IDs, display names and domains.

    Returns

    Promise which resolves: an array of results.

    Parameters

    • __namedParameters: {
          limit?: number;
          term: string;
      }
      • Optional limit?: number
      • term: string

    Returns Promise<IUserDirectoryResponse>

  • Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • threadId: null | string
    • eventObject: any

      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: string

      Optional.

    Returns Promise<ISendEventResponse>

  • Returns

    Promise which resolves: to a ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • Optional txnId: string

      Optional.

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • Optional txnId: string

    Returns Promise<ISendEventResponse>

  • Returns

    Promise which resolves: to a ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Returns

    Promise which resolves: to a ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Returns

    Promise which resolves: to a ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • htmlBody: string

    Returns Promise<ISendEventResponse>

  • Back up session keys to the homeserver.

    Returns

    a promise that will resolve when the keys are uploaded

    Parameters

    • roomId: undefined

      ID of the room that the keys are for Optional.

    • sessionId: undefined

      ID of the session that the keys are for Optional.

    • version: undefined | string

      backup version Optional.

    • data: IKeyBackup

      Object keys to send

    Returns Promise<void>

  • Parameters

    • roomId: string
    • sessionId: undefined
    • version: undefined | string
    • data: IKeyBackup

    Returns Promise<void>

  • Parameters

    • roomId: string
    • sessionId: string
    • version: undefined | string
    • data: IKeyBackup

    Returns Promise<void>

  • Returns

    Promise which resolves: to a ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • Optional txnId: string

      Optional.

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • Optional txnId: string

    Returns Promise<ISendEventResponse>

  • Send a read receipt.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • event: null | MatrixEvent

      The event that has been read.

    • receiptType: ReceiptType = ReceiptType.Read

      other than ReceiptType.Read are experimental! Optional.

    • unthreaded: boolean = false

    Returns Promise<undefined | {}>

  • Send a receipt.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • event: MatrixEvent

      The event being acknowledged

    • receiptType: ReceiptType

      The kind of receipt e.g. "m.read". Other than ReceiptType.Read are experimental!

    • body: any

      Additional content to send alongside the receipt.

    • unthreaded: boolean = false

      An unthreaded receipt will clear room+thread notifications

    Returns Promise<{}>

  • Share shared-history decryption keys with the given users.

    Parameters

    • roomId: string

      the room for which keys should be shared.

    • userIds: string[]

      a list of users to share with. The keys will be sent to all of the user's current devices.

    Returns Promise<void>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • eventType: string
    • content: any
    • stateKey: string = ""
    • opts: IRequestOpts = {}

      Options for the request function.

    Returns Promise<ISendEventResponse>

  • Returns

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • body: string
    • Optional txnId: string

      Optional.

    Returns Promise<ISendEventResponse>

  • Parameters

    • roomId: string
    • threadId: null | string
    • body: string
    • Optional txnId: string

    Returns Promise<ISendEventResponse>

  • Send 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.

    Returns

    Promise which resolves: to an empty object {}

    Parameters

    • eventType: string

      type of event to send content to send. Map from user_id to device_id to content object.

    • contentMap: {
          [userId: string]: {
              [deviceId: string]: Record<string, any>;
          };
      }
      • [userId: string]: {
            [deviceId: string]: Record<string, any>;
        }
        • [deviceId: string]: Record<string, any>
    • Optional txnId: string

      transaction id. One will be made up if not supplied.

    Returns Promise<{}>

  • Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • isTyping: boolean
    • timeoutMs: number

    Returns Promise<{}>

  • Set the access token associated with this account.

    Parameters

    • token: string

      The new access token.

    Returns void

  • Set account data event for the current user. It will retry the request up to 5 times.

    Returns

    Promise which resolves: an empty object

    Returns

    Rejects: with an error response.

    Parameters

    • eventType: string

      The event type

    • content: IContent

      the contents object for the event

    Returns Promise<{}>

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • url: string

    Returns Promise<{}>

  • 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.

    Parameters

    Returns void

  • See getCryptoTrustCrossSignedDevices

    Parameters

    • val: boolean

      True to trust cross-signed devices

    Returns void

  • Set the current default key ID for encrypting secrets.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Parameters

    • keyId: string

      The new default key ID

    Returns Promise<void>

  • Set the dehydration key. This will also periodically dehydrate devices to the server.

    Returns

    A promise that resolves when the dehydrated device is stored.

    Parameters

    • key: Uint8Array

      the dehydration key

    • keyInfo: IDehydratedDeviceKeyInfo

      Information about the key. Primarily for information about how to generate the key from a passphrase.

    • Optional deviceDisplayName: string

      The device display name for the dehydrated device.

    Returns Promise<void>

  • Mark the given device as blocked/unblocked

    Returns

    Remarks

    Fires CryptoEvent.DeviceVerificationChanged

    Parameters

    • userId: string

      owner of the device

    • deviceId: string

      unique identifier for the device or user's cross-signing public key ID.

    • blocked: boolean = true

      whether to mark the device as blocked. defaults to 'true'.

    Returns Promise<void>

  • Update the given device

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • deviceId: string

      device to update

    • body: {
          display_name: string;
      }

      body of request

      • display_name: string

    Returns Promise<{}>

  • Mark the given device as known/unknown

    Returns

    Remarks

    Fires CryptoEvent#DeviceVerificationChanged

    Parameters

    • userId: string

      owner of the device

    • deviceId: string

      unique identifier for the device or user's cross-signing public key ID.

    • known: boolean = true

      whether to mark the device as known. defaults to 'true'.

    Returns Promise<void>

  • Parameters

    • userId: string
    • deviceId: string
    • Optional verified: null | boolean
    • Optional blocked: null | boolean
    • Optional known: null | boolean

    Returns Promise<void>

  • Mark the given device as verified

    Returns

    Remarks

    Fires CryptoEvent#DeviceVerificationChanged

    Parameters

    • userId: string

      owner of the device

    • deviceId: string

      unique identifier for the device or user's cross-signing public key ID.

    • verified: boolean = true

      whether to mark the device as verified. defaults to 'true'.

    Returns Promise<void>

  • Returns

    Promise which resolves: {} an empty object.

    Returns

    Rejects: with an error response.

    Parameters

    • name: string

    Returns Promise<{}>

  • Set whether to allow a fallback ICE server should be used for negotiating a WebRTC connection if the homeserver doesn't provide any servers. Defaults to false.

    Parameters

    • allow: boolean

    Returns void

  • Set whether VoIP calls are forced to use only TURN candidates. This is the same as the forceTURN option when creating the client.

    Parameters

    • force: boolean

      True to force use of TURN servers

    Returns void

  • 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.

    Deprecated

    Prefer direct access to globalBlacklistUnverifiedDevices:

    client.getCrypto().globalBlacklistUnverifiedDevices = value;
    

    Parameters

    • value: boolean

      whether to blacklist all unverified devices by default

    Returns boolean

  • 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.

    Deprecated

    Prefer direct access to globalBlacklistUnverifiedDevices:

    client.getCrypto().globalBlacklistUnverifiedDevices = value;
    

    Parameters

    • value: boolean

      whether error on unknown devices

    Returns void

  • Set whether this client is a guest account. This method is experimental and may change without warning.

    Parameters

    • guest: boolean

      True if this is a guest account.

    Returns void

  • Set r/w flags for guest access in a room.

    Returns

    Promise which resolves

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string

      The room to configure guest access in.

    • opts: IGuestAccessOpts

      Options

    Returns Promise<void>

  • Set the identity server URL of this client

    Parameters

    • url: string

      New identity server URL

    Returns void

  • Sets the users that the current user should ignore.

    Returns

    Promise which resolves: an empty object

    Returns

    Rejects: with an error response.

    Parameters

    • userIds: string[]

      the user IDs to ignore

    Returns Promise<{}>

  • Persists local notification settings

    Returns

    Promise which resolves: an empty object

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<{}>

  • Make a request to change your password.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • authDict: IAuthDict
    • newPassword: string

      The new desired password.

    • Optional logoutDevices: boolean

      Should all sessions be logged out after the password change. Defaults to true.

    Returns Promise<{}>

  • Set a power level to one or multiple users.

    Returns

    Promise which resolves: to an ISendEventResponse object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • userId: string | string[]
    • powerLevel: undefined | number
    • event: null | MatrixEvent

    Returns Promise<ISendEventResponse>

  • Returns

    Promise which resolves

    Returns

    Rejects: with an error response.

    Throws

    If 'presence' isn't a valid presence enum value.

    Parameters

    Returns Promise<void>

  • Returns

    Returns

    Rejects: with an error response.

    Parameters

    • info: "avatar_url"

      The kind of info to set (e.g. 'avatar_url')

    • data: {
          avatar_url: string;
      }

      The JSON object to set.

      • avatar_url: string

    Returns Promise<{}>

  • Parameters

    • info: "displayname"
    • data: {
          displayname: string;
      }
      • displayname: string

    Returns Promise<{}>

  • Set the actions for a push notification rule.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<{}>

  • Enable or disable a push notification rule.

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • scope: string
    • kind: PushRuleKind
    • ruleId: string
    • enabled: boolean

    Returns Promise<{}>

  • Update the push rules for the account. This should be called whenever updated push rules are available.

    Parameters

    Returns void

  • Adds a new pusher or updates an existing pusher

    Returns

    Promise which resolves: Empty json object on success

    Returns

    Rejects: with an error response.

    Parameters

    Returns Promise<{}>

  • Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • eventType: string

      event type to be set

    • content: Record<string, any>

      event content

    Returns Promise<{}>

  • Set the visbility of a room in the current HS's room directory

    Returns

    Promise which resolves: to an empty object {}

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • visibility: Visibility

      "public" to make the room visible in the public directory, or "private" to make it invisible.

    Returns Promise<{}>

  • Set the visbility of a room bridged to a 3rd party network in the current HS's room directory.

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    • networkId: string

      the network ID of the 3rd party instance under which this room is published under.

    • roomId: string
    • visibility: "private" | "public"

      "public" to make the room visible in the public directory, or "private" to make it invisible.

    Returns Promise<any>

  • 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.

    Returns

    A promise that will resolve when encryption is set up.

    Parameters

    • roomId: string

      The room ID to enable encryption in.

    • config: IRoomEncryption

      The encryption config for the room.

    Returns Promise<void>

  • Set a room-kind muting push rule in a room. The operation also updates MatrixClient.pushRules at the end.

    Returns

    Promise which resolves: result object

    Returns

    Rejects: with an error response.

    Parameters

    • scope: "global" | "device"

      "global" or device-specific.

    • roomId: string

      the id of the room.

    • mute: boolean

      the mute state.

    Returns undefined | Promise<void>

  • 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.

    Returns

    Promise which resolves: the empty object, {}.

    Parameters

    • roomId: string

      ID of the room that has been read

    • rmEventId: string

      ID of the event that has been read

    • Optional rrEvent: MatrixEvent

      the event tracked by the read receipt. This is here for convenience because the RR and the RM are commonly updated at the same time as each other. The local echo of this receipt will be done if set. Optional.

    • Optional rpEvent: MatrixEvent

      the m.read.private read receipt event for when we don't want other users to see the read receipts. This is experimental. Optional.

    Returns Promise<{}>

  • Set a marker to indicate the point in a room before which the user has read every event. This can be retrieved from room account data (the event type is m.fully_read) and displayed as a horizontal line in the timeline that is visually distinct to the position of the user's own read receipt.

    Returns

    Promise which resolves: the empty object, {}.

    Parameters

    • roomId: string

      ID of the room that has been read

    • rmEventId: string

      ID of the event that has been read

    • Optional rrEventId: string

      ID of the event tracked by the read receipt. This is here for convenience because the RR and the RM are commonly updated at the same time as each other. Optional.

    • Optional rpEventId: string

      rpEvent the m.read.private read receipt event for when we don't want other users to see the read receipts. This is experimental. Optional.

    Returns Promise<{}>

  • Returns

    Promise which resolves: to an empty object

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • tagName: string

      name of room tag to be set

    • metadata: ITagMetadata

      associated with that tag to be stored

    Returns Promise<{}>

  • Returns

    Promise which resolves: TODO

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • topic: string
    • Optional htmlTopic: string

      Optional.

    Returns Promise<ISendEventResponse>

  • Set whether to advertise transfer support to other parties on Matrix calls.

    Parameters

    • support: boolean

      True to advertise the 'm.call.transferee' capability

    Returns void

  • High level helper method to begin syncing and poll for new events. To listen for these events, add a listener for Event via on. Alternatively, listen for specific state change events.

    Parameters

    Returns Promise<void>

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

    Returns void

  • Stop any ongoing room peeking.

    Returns void

  • store client options with boolean/string/numeric values to know in the next session what flags the sync data was created with (e.g. lazy loading)

    Returns

    for store operation

    Returns Promise<void>

  • Store an encrypted secret on the server.

    The Secure Secret Storage API is currently UNSTABLE and may change without notice.

    Parameters

    • name: string

      The name of the secret

    • secret: string

      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).

    Returns Promise<void>

  • 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.

    Returns

    Promise which resolves: Object, currently with no parameters.

    Returns

    Rejects: with an error response.

    Throws

    Error if No identity server is set

    Parameters

    • sid: string

      The sid given in the response to requestToken

    • clientSecret: string

      A secret binary string generated by the client. This must be the same value submitted in the requestToken call.

    • msisdnToken: string

      The MSISDN token, as enetered by the user.

    • identityAccessToken: string

      The access_token field of the Identity Server /account/register response (see registerWithIdentityServer).

    Returns Promise<any>

  • 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.

    Returns

    Promise which resolves: Object, currently with no parameters.

    Returns

    Rejects: with an error response.

    Parameters

    • url: string

      The URL to submit the token to

    • sid: string

      The sid given in the response to requestToken

    • clientSecret: string

      A secret binary string generated by the client. This must be the same value submitted in the requestToken call.

    • msisdnToken: string

      The MSISDN token, as enetered by the user.

    Returns Promise<any>

  • Deprecated

    use supportsThreads() instead

    Returns boolean

  • A helper to determine thread support

    Returns

    a boolean to determine if threads are enabled

    Returns boolean

  • Check if the runtime environment supports VoIP calling.

    Returns

    True if VoIP is supported.

    Returns boolean

  • Populate the store with rooms the user has left.

    Returns

    Promise which resolves: TODO - Resolved when the rooms have been added to the data store.

    Returns

    Rejects: with an error response.

    Returns Promise<Room[]>

  • Find the event_id closest to the given timestamp in the given direction.

    Returns

    Resolves: A promise of an object containing the event_id and origin_server_ts of the closest event to the timestamp in the given direction

    Returns

    Rejects: when the request fails (module:http-api.MatrixError)

    Parameters

    • roomId: string
    • timestamp: number
    • dir: Direction

    Returns Promise<ITimestampToEventResponse>

  • Returns

    Promise which resolves: Object (currently empty)

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • userId: string

    Returns Promise<{}>

  • 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.

    Returns

    Promise which resolves: on success

    Returns

    Rejects: with an error response.

    Parameters

    • medium: string

      The threepid medium (eg. 'email')

    • address: string

      The threepid address (eg. 'bob@example.com') this must be as returned by getThreePids.

    Returns Promise<{
        id_server_unbind_result: IdServerUnbindResult;
    }>

  • 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.

    Returns

    Promise which resolves to the created space.

    Parameters

    • name: string

      The name of the tree space.

    Returns Promise<MSC3089TreeSpace>

  • 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.

    Returns

    The tree space, or null if not a tree space.

    Parameters

    • roomId: string

      The room ID to get a tree space reference for.

    Returns null | MSC3089TreeSpace

  • Upgrades a room to a new protocol version

    Returns

    Promise which resolves: Object with key 'replacement_room'

    Returns

    Rejects: with an error response.

    Parameters

    • roomId: string
    • newVersion: string

      The target version to upgrade to

    Returns Promise<{
        replacement_room: string;
    }>

  • Upload a file to the media repository on the homeserver.

    Returns

    Promise which resolves to response object, as determined by this.opts.onlyData, opts.rawResponse, and opts.onlyContentUri. Rejects with an error (usually a MatrixError).

    Parameters

    • file: XMLHttpRequestBodyInit

      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: UploadOpts

      options object

    Returns Promise<UploadResponse>

  • Deprecated

    Does nothing.

    Returns Promise<void>

  • Checks if the user has previously published cross-signing keys

    This means downloading the devicelist for the user and checking if the list includes the cross-signing pseudo-device.

    Deprecated

    Prefer CryptoApi.userHasCrossSigningKeys:

    result = client.getCrypto().userHasCrossSigningKeys();
    

    Returns Promise<boolean>

  • 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.

    Returns

    A promise that resolves once existing group calls in the room have been processed.

    Parameters

    • roomId: string

      The room ID to wait for

    Returns Promise<void>

  • Performs a whois lookup on a user using Synapse's administrator API. This function is implementation specific and may change as a result.

    Returns

    the whois response - see Synapse docs for information.

    Parameters

    • userId: string

      the User ID to look up.

    Returns Promise<ISynapseAdminWhoisResponse>

Generated using TypeDoc