DigitalWorldClient

ruleId

string

body

Pick<IPushRule, "actions" | "conditions" | "pattern">

Returns

Promise<EmptyObject>

Promise which resolves: an empty object {}

addThreePidOnly()

addThreePidOnly(data): Promise<EmptyObject>

Defined in: src/client.ts:7573

Add a 3PID to your hub account. This API does not use an identity server, as the hub is expected to handle 3PID ownership validation.

Parameters

data

IAddThreePidOnlyBody

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

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

agreeToTerms()

agreeToTerms(serviceType, baseUrl, accessToken, termsUrls): Promise<EmptyObject>

Defined in: src/client.ts:8555

Parameters

serviceType

SERVICE_TYPES

baseUrl

string

accessToken

string

termsUrls

string[]

Returns

Promise<EmptyObject>

backPaginateRoomEventsSearch()

backPaginateRoomEventsSearch<T>(searchResults): Promise<T>

Defined in: src/client.ts:5696

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

Type Parameters

T

T extends ISearchResults

Parameters

searchResults

T

the results object to be updated

Returns

Promise<T>

Promise which resolves: updated result object

ban()

ban(roomId, userId, reason?): Promise<EmptyObject>

Defined in: src/client.ts:4233

Parameters

roomId

string

userId

string

reason?

string

Optional.

Returns

Promise<EmptyObject>

Promise which resolves: TODO

bindThreePid()

bindThreePid(data): Promise<EmptyObject>

Defined in: src/client.ts:7589

Bind a 3PID for discovery onto an identity server via the hub. The identity server handles 3PID ownership validation and the hub records the new binding to track where all 3PIDs for the account are bound.

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<EmptyObject>

Promise which resolves: to an empty object {}

bulkLookupThreePids()

bulkLookupThreePids(query, identityAccessToken): Promise<{ threepids: [string, string, string][]; }>

Defined in: src/client.ts:8384

Looks up the public Digital World ID mappings for multiple 3PIDs.

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<{ threepids: [string, string, string][]; }>

Promise which resolves: Lookup results from IS.

cancelPendingEvent()

cancelPendingEvent(event): void

Defined in: src/client.ts:2519

Cancel a queued or unsent event.

Parameters

event

Event to cancel

Returns

void

Throws

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

cancelUpload()

cancelUpload(upload): boolean

Defined in: src/client.ts:7322

Cancel a file upload in progress

Parameters

upload

Promise<UploadResponse>

The object returned from uploadContent

Returns

boolean

true if canceled, otherwise false

checkTurnServers()

checkTurnServers(): Promise<boolean | undefined>

Defined in: src/client.ts:5981

Returns

Promise<boolean | undefined>

claimOneTimeKeys()

claimOneTimeKeys(devices, keyAlgorithm?, timeout?): Promise<IClaimOTKsResult>

Defined in: src/client.ts:7966

Claim one-time keys

Parameters

devices

[string, string][]

a list of [userId, deviceId] pairs

keyAlgorithm?

string = "signed_curve25519"

desired key type

timeout?

number

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

Returns

Promise<IClaimOTKsResult>

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

clearStores()

clearStores(args?): Promise<void>

Defined in: src/client.ts:1600

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

Parameters

args?

cryptoDatabasePrefix?

string

The database name to use for indexeddb, defaults to ‘digital-world-messaging-sdk’.

Returns

Promise<void>

Promise which resolves when the stores have been cleared.

createAlias()

createAlias(alias, roomId): Promise<EmptyObject>

Defined in: src/client.ts:7205

Create an alias to room ID mapping.

Parameters

alias

string

The room alias to create.

roomId

string

The room ID to link the alias to.

Returns

Promise<EmptyObject>

Promise which resolves: an empty object {}

createCall()

createCall(roomId): DigitalWorldCall | null

Defined in: src/client.ts:1765

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

Parameters

roomId

string

The room the call is to be placed in.

Returns

DigitalWorldCall | null

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

createFilter()

createFilter(content): Promise<Filter>

Defined in: src/client.ts:5800

Create a new filter.

Parameters

content

IFilterDefinition

The HTTP body for the request

Returns

Promise<Filter>

Promise which resolves to a Filter object.

createGroupCall()

createGroupCall(roomId, type, isPtt, intent, dataChannelsEnabled?, dataChannelOptions?): Promise<GroupCall>

Defined in: src/client.ts:1775

Creates a new group call and sends the associated state event to alert other members that the room now has a group call.

Parameters

roomId

string

The room the call is to be placed in.

type

GroupCallType

isPtt

boolean

intent

GroupCallIntent

dataChannelsEnabled?

boolean

dataChannelOptions?

IGroupCallDataChannelOptions

Returns

Promise<GroupCall>

createMessagesRequest()

createMessagesRequest(roomId, fromToken, limit?, dir, timelineFilter?): Promise<IMessagesResponse>

Defined in: src/client.ts:4905

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

string | null

limit?

number = 30

the maximum amount of events the retrieve

dir

Direction

‘f’ or ‘b’

timelineFilter?

Filter

the timeline filter to pass

Returns

Promise<IMessagesResponse>

createRoom()

createRoom(options): Promise<{ room_id: string; }>

Defined in: src/client.ts:6850

Create a new room.

Parameters

options

ICreateRoomOpts

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

Returns

Promise<{ room_id: string; }>

Promise which resolves: {room_id: {string}}

createThreadListMessagesRequest()

createThreadListMessagesRequest(roomId, fromToken, limit?, dir?, threadListType?, timelineFilter?): Promise<IMessagesResponse>

Defined in: src/client.ts:4951

Parameters

roomId

string

fromToken

string | null

limit?

number = 30

the maximum amount of events the retrieve

dir?

Direction = Direction.Backward

‘f’ or ‘b’

threadListType?

ThreadFilterType | null

timelineFilter?

Filter

the timeline filter to pass

Returns

Promise<IMessagesResponse>

deactivateAccount()

deactivateAccount(auth?, erase?): Promise<{ id_server_unbind_result: IdServerUnbindResult; }>

Defined in: src/client.ts:6790

Deactivates the logged-in account. Obviously, further calls that require authorisation should fail after this method is called. The state of the DigitalWorldClient object is not affected: it is up to the caller to either reset or destroy the DigitalWorldClient after this method succeeds.

Parameters

auth?

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

erase?

boolean

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

Returns

Promise<{ id_server_unbind_result: IdServerUnbindResult; }>

Promise which resolves: On success, the empty object

deactivateSynapseUser()

deactivateSynapseUser(userId): Promise<ISynapseAdminDeactivateResponse>

Defined in: src/client.ts:6082

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

Parameters

userId

string

the User ID to deactivate.

Returns

Promise<ISynapseAdminDeactivateResponse>

the deactivate response - see Synapse docs for information.

decryptEventIfNeeded()

decryptEventIfNeeded(event, options?): Promise<void>

Defined in: src/client.ts:6419

Attempts to decrypt an event

Parameters

event

The event to decrypt

options?

IDecryptOptions

Returns

Promise<void>

A decryption promise

deleteAccountData()

deleteAccountData(eventType): Promise<void>

Defined in: src/client.ts:2351

Parameters

eventType

keyof AccountDataEvents

Returns

Promise<void>

deleteAlias()

deleteAlias(alias): Promise<EmptyObject>

Defined in: src/client.ts:7222

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

Parameters

alias

string

The room alias to delete.

Returns

Promise<EmptyObject>

Promise which resolves: an empty object {}.

deleteDevice()

deleteDevice(deviceId, auth?): Promise<EmptyObject>

Defined in: src/client.ts:7701

Delete the given device

Parameters

deviceId

string

device to delete

auth?

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

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

Returns

Promise<EmptyObject>

Promise which resolves: result object

deleteExtendedProfileProperty()

deleteExtendedProfileProperty(key): Promise<void>

Defined in: src/client.ts:7486

Delete a property on your extended profile.

Parameters

key

string

The key of the property to delete.

Returns

Promise<void>

See

Throws

An error if the server does not support MSC4133 OR the server disallows editing the user profile.

deleteKeysFromBackup()

Call Signature

deleteKeysFromBackup(roomId, sessionId, version?): Promise<void>

Defined in: src/client.ts:2140

Parameters

roomId

undefined

sessionId

undefined

version?

string

Returns

Promise<void>

Call Signature

deleteKeysFromBackup(roomId, sessionId, version?): Promise<void>

Defined in: src/client.ts:2141

Parameters

roomId

string

sessionId

undefined

version?

string

Returns

Promise<void>

Call Signature

deleteKeysFromBackup(roomId, sessionId, version?): Promise<void>

Defined in: src/client.ts:2142

Parameters

roomId

string

sessionId

string

version?

string

Returns

Promise<void>

deleteMultipleDevices()

deleteMultipleDevices(devices, auth?): Promise<EmptyObject>

Defined in: src/client.ts:7723

Delete multiple device

Parameters

devices

string[]

IDs of the devices to delete

auth?

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

Returns

Promise<EmptyObject>

Promise which resolves: result object

deletePushRule()

deletePushRule(scope, kind, ruleId): Promise<EmptyObject>

Defined in: src/client.ts:7844

Parameters

scope

string

kind

TypedEventEmitter.emit

ruleId

string

Returns

Promise<EmptyObject>

Promise which resolves: an empty object {}

deleteRoomTag()

deleteRoomTag(roomId, tagName): Promise<EmptyObject>

Defined in: src/client.ts:2595

Parameters

roomId

string

tagName

string

name of room tag to be removed

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object

deleteThreePid()

deleteThreePid(medium, address): Promise<{ id_server_unbind_result: IdServerUnbindResult; }>

Defined in: src/client.ts:7627

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; }>

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

doesServerForceEncryptionForPreset()

doesServerForceEncryptionForPreset(presetName): Promise<boolean>

Defined in: src/client.ts:6273

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

Parameters

presetName

Preset

The name of the preset to check.

Returns

Promise<boolean>

true if the server is forcing encryption for the preset.

doesServerSupportExtendedProfiles()

doesServerSupportExtendedProfiles(): Promise<boolean>

Defined in: src/client.ts:7360

Determine if the server supports extended profiles, as described by MSC4133.

Returns

Promise<boolean>

true if supported, otherwise false

doesServerSupportThread()

doesServerSupportThread(): Promise<{ fwdPagination: FeatureSupport; list: FeatureSupport; threads: FeatureSupport; }>

Defined in: src/client.ts:6286

Returns

Promise<{ fwdPagination: FeatureSupport; list: FeatureSupport; threads: FeatureSupport; }>

doesServerSupportUnstableFeature()

doesServerSupportUnstableFeature(feature): Promise<boolean>

Defined in: src/client.ts:6259

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

Parameters

feature

string

the feature name

Returns

Promise<boolean>

true if the feature is supported

downloadKeysForUsers()

downloadKeysForUsers(userIds, token?): Promise<IDownloadKeyResult>

Defined in: src/client.ts:7939

Download device keys

Parameters

userIds

string[]

list of users to get keys for

token?

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

token?

string

Returns

Promise<IDownloadKeyResult>

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

emit()

Call Signature

emit<T>(event, …args): boolean

Defined in: src/models/typed-event-emitter.ts:86

Synchronously calls each of the listeners registered for the event named event, in the order they were registered, passing the supplied arguments to each.

Type Parameters

T

T extends EmittedEvents

Parameters

event

T

The name of the event to emit

args

…Parameters<ClientEventHandlerMap[T]>

Arguments to pass to the listener

Returns

boolean

true if the event had listeners, false otherwise.

Inherited from

Call Signature

emit<T>(event, …args): boolean

Defined in: src/models/typed-event-emitter.ts:87

Synchronously calls each of the listeners registered for the event named event, in the order they were registered, passing the supplied arguments to each.

Type Parameters

T

T extends EmittedEvents

Parameters

event

T

The name of the event to emit

args

…Parameters<ClientEventHandlerMap[T]>

Arguments to pass to the listener

Returns

boolean

true if the event had listeners, false otherwise.

Inherited from

TypedEventEmitter.emit

emitPromised()

Call Signature

emitPromised<T>(event, …args): Promise<boolean>

Defined in: src/models/typed-event-emitter.ts:98

Similar to emit but calls all listeners within a Promise.all and returns the promise chain

Type Parameters

T

T extends EmittedEvents

Parameters

event

T

The name of the event to emit

args

…Parameters<ClientEventHandlerMap[T]>

Arguments to pass to the listener

Returns

Promise<boolean>

true if the event had listeners, false otherwise.

Inherited from

TypedEventEmitter.emitPromised

Call Signature

emitPromised<T>(event, …args): Promise<boolean>

Defined in: src/models/typed-event-emitter.ts:102

Similar to emit but calls all listeners within a Promise.all and returns the promise chain

Type Parameters

T

T extends EmittedEvents

Parameters

event

T

The name of the event to emit

args

…Parameters<ClientEventHandlerMap[T]>

Arguments to pass to the listener

Returns

Promise<boolean>

true if the event had listeners, false otherwise.

Inherited from

TypedEventEmitter.emitPromised

encryptAndSendToDevice()

encryptAndSendToDevice(eventType, devices, payload): Promise<void>

Defined in: src/client.ts:8472

This will encrypt the payload for all devices in the list and will queue it. The type of the sent to-device message will be m.room.encrypted.

Parameters

eventType

string

The type of event to send

devices

object[]

The list of devices to send the event to.

payload

ToDevicePayload

The payload to send. This will be encrypted.

Returns

Promise<void>

Promise which resolves once queued there is no error feedback when sending fails.

eventNames()

eventNames(): (string | symbol)[]

Defined in: node_modules/.pnpm/@types+node@22.20.0/node_modules/@types/node/events.d.ts:967

Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

Returns

(string | symbol)[]

Since

v6.0.0

Inherited from

TypedEventEmitter.eventNames

fetchCapabilities()

fetchCapabilities(): Promise<Capabilities>

Defined in: src/client.ts:1964

Fetches the latest capabilities from the hub, ignoring any cached versions. The newly returned version is cached.

Returns

Promise<Capabilities>

A promise which resolves to the capabilities of the hub

fetchRelations()

fetchRelations(roomId, eventId, relationType, eventType?, opts?): Promise<IRelationsResponse>

Defined in: src/client.ts:6877

Fetches relations for a given event

Parameters

roomId

string

the room of the event

eventId

string

the id of the event

relationType

string | null

the rel_type of the relations requested

eventType?

string | null

the event type of the relations requested

opts?

IRelationsRequestOpts = ...

options with optional values for the request.

Returns

Promise<IRelationsResponse>

the response, with chunk, prev_batch and, next_batch.

fetchRoomEvent()

fetchRoomEvent(roomId, eventId): Promise<Partial<IEvent>>

Defined in: src/client.ts:6931

Get an event in a room by its event id.

Parameters

roomId

string

eventId

string

Returns

Promise<Partial<IEvent>>

Promise which resolves to an object containing the event.

forget()

forget(roomId, deleteRoom?): Promise<EmptyObject>

Defined in: src/client.ts:4243

Parameters

roomId

string

deleteRoom?

boolean = true

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

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

generateClientSecret()

generateClientSecret(): string

Defined in: src/client.ts:6410

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

Returns

string

A new client secret

getAccessToken()

getAccessToken(): string | null

Defined in: src/client.ts:6479

Get the access token associated with this account.

Returns

string | null

The access_token or null

getAccountData()

getAccountData<K>(eventType): DigitalWorldEvent | undefined

Defined in: src/client.ts:2313

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

Type Parameters

K

K extends keyof AccountDataEvents

Parameters

eventType

K

The event type

Returns

DigitalWorldEvent | undefined

The contents of the given account data event

getAccountDataFromServer()

getAccountDataFromServer<K>(eventType): Promise<AccountDataEvents[K] | null>

Defined in: src/client.ts:2325

Get account data event of given type for the current user. This variant gets account data directly from the hub if the local store is not ready, which can be useful very early in startup before the initial sync.

Type Parameters

K

K extends keyof AccountDataEvents

Parameters

eventType

K

The event type

Returns

Promise<AccountDataEvents[K] | null>

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

getAuthMetadata()

getAuthMetadata(): Promise<ValidatedAuthMetadata>

Defined in: src/client.ts:8896

Discover and validate the auth metadata for the OAuth 2.0 API.

When successful, validated metadata is returned.

Returns

Promise<ValidatedAuthMetadata>

validated authentication metadata

Throws

when delegated auth config is invalid or unreachable

getCachedCapabilities()

getCachedCapabilities(): Capabilities | undefined

Defined in: src/client.ts:1954

Gets the cached capabilities of the hub. If none have been fetched yet, return undefined.

Returns

Capabilities | undefined

The capabilities of the hub

getCanResetTimelineCallback()

getCanResetTimelineCallback(): ResetTimelineCallback | undefined

Defined in: src/client.ts:6349

Get the callback set via setCanResetTimelineCallback.

Returns

ResetTimelineCallback | undefined

The callback or null

getCapabilities()

getCapabilities(): Promise<Capabilities>

Defined in: src/client.ts:1942

Gets the cached capabilities of the hub, returning cached ones if available. If there are no cached capabilities and none can be fetched, throw an exception.

Returns

Promise<Capabilities>

Promise resolving with The capabilities of the hub

getCasLoginUrl()

getCasLoginUrl(redirectUrl): string

Defined in: src/client.ts:6703

Parameters

redirectUrl

string

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

Returns

string

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

getClientWellKnown()

getClientWellKnown(): IClientWellKnown | undefined

Defined in: src/client.ts:6095

Returns

IClientWellKnown | undefined

getCrypto()

getCrypto(): CryptoApi | undefined

Defined in: src/client.ts:2087

Access the crypto API for this client.

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

Returns

CryptoApi | undefined

getCurrentUploads()

getCurrentUploads(): Upload[]

Defined in: src/client.ts:7334

Get a list of all file uploads in progress

Returns

Upload[]

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

getDevice()

getDevice(deviceId): Promise<IMyDevice>

Defined in: src/client.ts:7669

Gets specific device details for the logged-in user

Parameters

deviceId

string

device to query

Returns

Promise<IMyDevice>

Promise which resolves: result object

getDeviceId()

getDeviceId(): string | null

Defined in: src/client.ts:1704

Get the device ID of this client

Returns

string | null

device ID

getDevices()

getDevices(): Promise<{ devices: IMyDevice[]; }>

Defined in: src/client.ts:7659

Gets all devices recorded for the logged-in user

Returns

Promise<{ devices: IMyDevice[]; }>

Promise which resolves: result object

getDomain()

getDomain(): string | null

Defined in: src/client.ts:1685

Get the domain for this client’s Digital World ID

Returns

string | null

Domain of this Digital World ID

getEventMapper()

getEventMapper(options?): EventMapper

Defined in: src/client.ts:4564

Parameters

options?

MapperOpts

Returns

EventMapper

getEventTimeline()

getEventTimeline(timelineSet, eventId): Promise<EventTimeline | null>

Defined in: src/client.ts:4622

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.

Parameters

timelineSet

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

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<EventTimeline | null>

Promise which resolves: EventTimeline including the given event

getExtendedProfile()

getExtendedProfile(userId): Promise<Record<string, unknown>>

Defined in: src/client.ts:7395

Fetch a user’s extended profile, which may include additional keys. Always returns all available profile fields, irrespective of what profile fields are set in the sync filter.

Parameters

userId

string

The user ID to fetch the profile of.

Returns

Promise<Record<string, unknown>>

A set of keys to property values.

See

Throws

An error if the server does not support MSC4133.

Throws

A M_NOT_FOUND error if the profile could not be found.

getExtendedProfileProperty()

getExtendedProfileProperty(userId, key): Promise<unknown>

Defined in: src/client.ts:7426

Fetch a specific key from the user’s extended profile by checking local cache (which is updated from the sync) and querying the server if no data is cached locally.

Parameters

userId

string

The user ID to fetch the profile of.

key

string

The key of the property to fetch.

Returns

Promise<unknown>

The property value.

See

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

Throws

An error if the server does not support MSC4133.

Throws

A M_NOT_FOUND error if the key was not set OR the profile could not be found.

getFallbackAuthUrl()

getFallbackAuthUrl(loginType, authSessionId): string

Defined in: src/client.ts:6834

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

Parameters

loginType

string

the type of stage being attempted

authSessionId

string

the auth session ID provided by the hub

Returns

string

HS URL to hit to for the fallback interface

getFilter()

getFilter(userId, filterId, allowCached): Promise<Filter>

Defined in: src/client.ts:5821

Retrieve a filter.

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>

Promise which resolves: a Filter object

getGroupCallForRoom()

getGroupCallForRoom(roomId): GroupCall | null

Defined in: src/client.ts:1839

Get an existing group call for the provided room.

Parameters

roomId

string

Returns

GroupCall | null

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

getHubUrl()

getHubUrl(): string

Defined in: src/client.ts:6450

Get the Hub URL of this client

Returns

string

Hub URL of this client

getIdentityAccount()

getIdentityAccount(identityAccessToken): Promise<{ user_id: string; }>

Defined in: src/client.ts:8427

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.

Parameters

identityAccessToken

string

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

Returns

Promise<{ user_id: string; }>

Promise which resolves: an object with account info.

getIdentityHashDetails()

getIdentityHashDetails(identityAccessToken): Promise<{ algorithms: string[]; lookup_pepper: string; }>

Defined in: src/client.ts:8220

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

Parameters

identityAccessToken

string

The access token for the identity server.

Returns

Promise<{ algorithms: string[]; lookup_pepper: string; }>

The hashing information for the identity server.

getIdentityServerUrl()

getIdentityServerUrl(stripProto?): string | undefined

Defined in: src/client.ts:6459

Get the identity server URL of this client

Parameters

stripProto?

boolean = false

whether or not to strip the protocol from the URL

Returns

string | undefined

Identity server URL of this client

getIgnoredUsers()

getIgnoredUsers(): string[]

Defined in: src/client.ts:2373

Gets the users that are ignored by this client

Returns

string[]

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

getJoinedRoomMembers()

getJoinedRoomMembers(roomId): Promise<IJoinedMembersResponse>

Defined in: src/client.ts:7163

Retrieve membership info. for a room.

Parameters

roomId

string

ID of the room to get membership for

Returns

Promise<IJoinedMembersResponse>

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

getJoinedRooms()

getJoinedRooms(): Promise<IJoinedRoomsResponse>

Defined in: src/client.ts:7151

Returns

Promise<IJoinedRoomsResponse>

Promise which resolves: A list of the user’s current rooms

getKeyChanges()

getKeyChanges(oldToken, newToken): Promise<{ changed: string[]; left: string[]; }>

Defined in: src/client.ts:7998

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

Parameters

oldToken

string

newToken

string

Returns

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

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

getLatestTimeline()

getLatestTimeline(timelineSet): Promise<EventTimeline | null>

Defined in: src/client.ts:4839

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.

Parameters

timelineSet

TypedEventEmitter.getMaxListeners

The timelineSet to find or add the timeline to

Returns

Promise<EventTimeline | null>

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

getLivekitServiceURL()

getLivekitServiceURL(): string | undefined

Defined in: src/client.ts:1810

Returns

string | undefined

getLocalAliases()

getLocalAliases(roomId): Promise<{ aliases: string[]; }>

Defined in: src/client.ts:7236

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.

Parameters

roomId

string

The room ID to get local aliases for.

Returns

Promise<{ aliases: string[]; }>

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

getMaxListeners()

getMaxListeners(): number

Defined in: node_modules/.pnpm/@types+node@22.20.0/node_modules/@types/node/events.d.ts:819

Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to EventEmitter.defaultMaxListeners.

Returns

number

Since

v1.0.0

Inherited from

getMediaConfig()

getMediaConfig(useAuthenticatedMedia?): Promise<IMediaConfig>

Defined in: src/client.ts:2158

Get the config for the media repository.

Parameters

useAuthenticatedMedia?

boolean = false

Returns

Promise<IMediaConfig>

Promise which resolves with an object containing the config.

getMediaHandler()

getMediaHandler(): MediaHandler

Defined in: src/client.ts:1727

Returns

MediaHandler

getNotifTimelineSet()

getNotifTimelineSet(): EventTimelineSet | null

Defined in: src/client.ts:1924

Return the global notification EventTimelineSet, if any

Returns

EventTimelineSet | null

the globl notification EventTimelineSet

getOpenIdToken()

getOpenIdToken(): Promise<IOpenIDToken>

Defined in: src/client.ts:5899

Gets a bearer token from the hub that the user can present to a third party in order to prove their ownership of the account they are logged into.

Returns

Promise<IOpenIDToken>

Promise which resolves: Token object

getOrCreateFilter()

getOrCreateFilter(filterName, filter): Promise<string>

Defined in: src/client.ts:5845

Parameters

filterName

string

filter

Filter

Returns

Promise<string>

Filter ID

getPresence()

getPresence(userId): Promise<IStatusResponse>

Defined in: src/client.ts:4468

Parameters

userId

string

The user to get presence for

Returns

Promise<IStatusResponse>

Promise which resolves: The presence state for this user.

getProfileInfo()

getProfileInfo(userId, info?): Promise<{ avatar_url?: string; displayname?: string; }>

Defined in: src/client.ts:7344

Parameters

userId

string

info?

string

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

Returns

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

Promise which resolves: TODO

getPushActionsForEvent()

getPushActionsForEvent(event, forceRecalculate?): IActionsObject | null

Defined in: src/client.ts:4316

Obtain a dict of actions which should be performed for this event according to the push rules for this user. Caches the dict on the event.

Parameters

event

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

IActionsObject | null

A dict of actions to perform.

getPushDetailsForEvent()

getPushDetailsForEvent(event, forceRecalculate?): PushDetails | null

Defined in: src/client.ts:4332

Obtain a dict of actions which should be performed for this event according to the push rules for this user. Caches the dict on the event.

Parameters

event

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

PushDetails | null

A dict of actions to perform.

getPushers()

getPushers(): Promise<{ pushers: IPusher[]; }>

Defined in: src/client.ts:7740

Gets all pushers registered for the logged-in user

Returns

Promise<{ pushers: IPusher[]; }>

Promise which resolves: Array of objects representing pushers

getPushRules()

getPushRules(): Promise<IPushRules>

Defined in: src/client.ts:7804

Get the push rules for the account from the server.

Returns

Promise<IPushRules>

Promise which resolves to the push rules.

getRefreshToken()

getRefreshToken(): string | null

Defined in: src/client.ts:6487

Get the refresh token associated with this account.

Returns

string | null

The refresh_token or null

getRoom()

getRoom(roomId): Room | null

Defined in: src/client.ts:2173

Get the room for the given room ID. This function will return a valid room for any room for which a Room event has been emitted. Note in particular that other events, eg. RoomState.members will be emitted for a room before this function will return the given room.

Parameters

roomId

string | undefined

The room ID

Returns

Room | null

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

getRoomDirectoryVisibility()

getRoomDirectoryVisibility(roomId): Promise<{ visibility: Visibility; }>

Defined in: src/client.ts:7261

Get the visibility of a room in the current HS’s room directory

Parameters

roomId

string

Returns

Promise<{ visibility: Visibility; }>

Promise which resolves: TODO

getRoomHierarchy()

getRoomHierarchy(roomId, limit?, maxDepth?, suggestedOnly?, fromToken?): Promise<IRoomHierarchy>

Defined in: src/client.ts:8619

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.

Parameters

roomId

string

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

limit?

number

The maximum number of rooms to return per page.

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.

fromToken?

string

The opaque token to paginate a previous request.

Returns

Promise<IRoomHierarchy>

the response, with next_batch & rooms fields.

getRoomIdForAlias()

getRoomIdForAlias(alias): Promise<{ room_id: string; servers: string[]; }>

Defined in: src/client.ts:7248

Get room info for the given alias.

Parameters

alias

string

The room alias to resolve.

Returns

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

Promise which resolves: Object with room_id and servers.

getRoomPushRule()

getRoomPushRule(scope, roomId): IPushRule | undefined

Defined in: src/client.ts:5536

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

Parameters

scope

"global" | "device"

“global” or device-specific.

roomId

string

the id of the room.

Returns

IPushRule | undefined

the rule or undefined.

getRooms()

getRooms(): Room[]

Defined in: src/client.ts:2184

Retrieve all known rooms.

Returns

Room[]

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

getRoomSummary()

getRoomSummary(roomIdOrAlias, via?): Promise<RoomSummary>

Defined in: src/client.ts:8776

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.

via?

string[]

The list of servers which know about the room if only an ID was provided.

Returns

Promise<RoomSummary>

getRoomTags()

getRoomTags(roomId): Promise<ITagsResponse>

Defined in: src/client.ts:2567

Parameters

roomId

string

Returns

Promise<ITagsResponse>

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

getRoomUpgradeHistory()

getRoomUpgradeHistory(roomId, verifyLinks?, msc3946ProcessDynamicPredecessor?): Room[]

Defined in: src/client.ts:4015

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.

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

An array of rooms representing the upgrade history.

getSafeUserId()

getSafeUserId(): string

Defined in: src/client.ts:1673

Get the user-id of the logged-in user

Returns

string

Digital World ID for the logged-in user

Throws

Error if not logged in

getScheduler()

getScheduler(): DigitalWorldScheduler<ISendEventResponse> | undefined

Defined in: src/client.ts:1902

Return the provided scheduler, if any.

Returns

DigitalWorldScheduler<ISendEventResponse> | undefined

The scheduler or undefined

getSessionId()

getSessionId(): string

Defined in: src/client.ts:1712

Get the session ID of this client

Returns

string

session ID

getSsoLoginUrl()

getSsoLoginUrl(redirectUrl, loginType?, idpId?, action?): string

Defined in: src/client.ts:6716

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

idpId?

string

The ID of the Identity Provider being targeted, optional.

action?

SSOAction

the SSO flow to indicate to the IdP, optional.

Returns

string

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

getStateEvent()

getStateEvent(roomId, eventType, stateKey): Promise<Record<string, any>>

Defined in: src/client.ts:6996

Retrieve a state event.

Parameters

roomId

string

eventType

string

stateKey

string

Returns

Promise<Record<string, any>>

Promise which resolves: TODO

getSyncState()

getSyncState(): SyncState | null

Defined in: src/client.ts:1848

Get the current sync state.

Returns

SyncState | null

the sync state, which may be null.

See

DigitalWorldClient#event:“sync”

getSyncStateData()

getSyncStateData(): SyncStateData | null

Defined in: src/client.ts:1859

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

SyncStateData | null

getTerms()

getTerms(serviceType, baseUrl): Promise<Terms>

Defined in: src/client.ts:8550

Parameters

serviceType

SERVICE_TYPES

baseUrl

string

Returns

Promise<Terms>

getThirdpartyLocation()

getThirdpartyLocation(protocol, params): Promise<IThirdPartyLocation[]>

Defined in: src/client.ts:8523

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

Parameters

protocol

string

The protocol given in getThirdpartyProtocols()

params

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

searchFields?

string[]

Returns

Promise<IThirdPartyLocation[]>

Promise which resolves to the result object

getThirdpartyProtocols()

getThirdpartyProtocols(): Promise<{[protocol: string]: IProtocol; }>

Defined in: src/client.ts:8503

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

Returns

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

Promise which resolves to the result object

getThirdpartyUser()

getThirdpartyUser(protocol, params?): Promise<IThirdPartyUser[]>

Defined in: src/client.ts:8542

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

Parameters

protocol

string

The protocol given in getThirdpartyProtocols()

params?

QueryDict

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

Returns

Promise<IThirdPartyUser[]>

Promise which resolves to the result object

getThreadTimeline()

getThreadTimeline(timelineSet, eventId): Promise<EventTimeline | undefined>

Defined in: src/client.ts:4692

Parameters

timelineSet

eventId

string

Returns

Promise<EventTimeline | undefined>

getThreePids()

getThreePids(): Promise<{ threepids: IThreepid[]; }>

Defined in: src/client.ts:7560

Returns

Promise<{ threepids: IThreepid[]; }>

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

getTurnServers()

getTurnServers(): ITurnServer[]

Defined in: src/client.ts:5963

Get the TURN servers for this hub.

Returns

ITurnServer[]

The servers or an empty list.

getTurnServersExpiry()

getTurnServersExpiry(): number

Defined in: src/client.ts:5972

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

Returns

number

The expiry timestamp in milliseconds

getUrlPreview()

getUrlPreview(url, ts): Promise<IPreviewUrlResponse>

Defined in: src/client.ts:3940

Get a preview of the given URL as of (roughly) the given point in time, described as an object with OpenGraph keys and associated values. Attributes may be synthesized where actual OG metadata is lacking. Caches results to prevent hammering the server.

Parameters

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>

Promise which resolves: Object of OG metadata.

getUseE2eForGroupCall()

getUseE2eForGroupCall(): boolean

Defined in: src/client.ts:1754

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

Returns

boolean

boolean Whether group call signalling will be encrypted

getUser()

getUser(userId): User | null

Defined in: src/client.ts:2218

Retrieve a user.

Parameters

userId

string

The user ID to retrieve.

Returns

User | null

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

getUserId()

getUserId(): string | null

Defined in: src/client.ts:1663

Get the user-id of the logged-in user

Returns

string | null

Digital World ID for the logged-in user, or null if not logged in

getUserIdLocalpart()

getUserIdLocalpart(): string | null

Defined in: src/client.ts:1696

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

Returns

string | null

The user ID localpart or null.

getUsers()

getUsers(): User[]

Defined in: src/client.ts:2226

Retrieve all known users.

Returns

User[]

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

getVersions()

getVersions(): Promise<IServerVersions>

Defined in: src/client.ts:6220

Get the API versions supported by the server, along with any unstable APIs it supports

Returns

Promise<IServerVersions>

The server /versions response

getVisibleRooms()

getVisibleRooms(msc3946ProcessDynamicPredecessor?): Room[]

Defined in: src/client.ts:2199

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.

Parameters

msc3946ProcessDynamicPredecessor?

boolean = false

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

Returns

Room[]

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

hasLazyLoadMembersEnabled()

hasLazyLoadMembersEnabled(): boolean

Defined in: src/client.ts:6328

Get if lazy loading members is being used.

Returns

boolean

Whether or not members are lazy loaded by this client

identityHashedLookup()

identityHashedLookup(addressPairs, identityAccessToken): Promise<object[]>

Defined in: src/client.ts:8250

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.

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<object[]>

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

initRustCrypto()

initRustCrypto(args?): Promise<void>

Defined in: src/client.ts:1988

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

WARNING: the cryptography stack is not thread-safe. Having multiple DigitalWorldClient instances connected to the same Indexed DB will cause data corruption and decryption failures. The application layer is responsible for ensuring that only one DigitalWorldClient issue is instantiated at a time.

Parameters

args?

cryptoDatabasePrefix?

string

The database name to use for indexeddb, defaults to ‘digital-world-messaging-sdk’. Unused if useIndexedDB is ‘false’.

storageKey?

Uint8Array<ArrayBufferLike>

A key with which to encrypt the indexeddb store. If provided, it must be exactly 32 bytes of data, and must be the same each time the client is initialised for a given device. If both this and storagePassword are unspecified, the store will be unencrypted.

storagePassword?

string

An alternative to storageKey. A password which will be used to derive a key to encrypt the store with. Deriving a key from a password is (deliberately) a slow operation, so prefer to pass a storageKey directly where possible.

useIndexedDB?

boolean

True to use an indexeddb store, false to use an in-memory store. Defaults to ‘true’.

Returns

Promise<void>

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

invite()

invite(roomId, userId, opts?): Promise<EmptyObject>

Defined in: src/client.ts:4104

Send an invite to the given user to join the given room.

Parameters

roomId

string

The ID of the room to which the user should be invited.

userId

string

The ID of the user that should be invited.

opts?

string | InviteOpts

Optional reason object. For backwards compatibility, a string is also accepted, and will be interpreted as a reason.

Returns

Promise<EmptyObject>

An empty object.

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

inviteByEmail()

inviteByEmail(roomId, email): Promise<EmptyObject>

Defined in: src/client.ts:4129

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

Parameters

roomId

string

The room to invite the user to.

email

string

The email address to invite.

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

inviteByThreePid()

inviteByThreePid(roomId, medium, address): Promise<EmptyObject>

Defined in: src/client.ts:4143

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

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<EmptyObject>

Promise which resolves: {} an empty object.

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

isFallbackICEServerAllowed()

isFallbackICEServerAllowed(): boolean

Defined in: src/client.ts:6046

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

Returns

boolean

isGuest()

isGuest(): boolean

Defined in: src/client.ts:1882

Return whether the client is configured for a guest account.

Returns

boolean

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

isInitialSyncComplete()

isInitialSyncComplete(): boolean

Defined in: src/client.ts:1870

Whether the initial sync has completed.

Returns

boolean

True if at least one sync has happened.

isKeyBackupKeyStored()

isKeyBackupKeyStored(): Promise<Record<string, SecretStorageKeyDescriptionAesV1> | null>

Defined in: src/client.ts:2118

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

Returns

Promise<Record<string, SecretStorageKeyDescriptionAesV1> | null>

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

isLoggedIn()

isLoggedIn(): boolean

Defined in: src/client.ts:6504

Returns

boolean

true if there is a valid access_token for this client.

isRoomEncrypted()

isRoomEncrypted(roomId): boolean

Defined in: src/client.ts:2099

Whether encryption is enabled for a room.

Parameters

roomId

string

the room id to query.

Returns

boolean

whether encryption is enabled.

isSynapseAdministrator()

isSynapseAdministrator(): Promise<boolean>

Defined in: src/client.ts:6057

Determines if the current user is an administrator of the Synapse hub. Returns false if untrue or the hub does not appear to be a Synapse hub. This function is implementation specific and may change as a result.

Returns

Promise<boolean>

true if the user appears to be a Synapse administrator.

isUserIgnored()

isUserIgnored(userId): boolean

Defined in: src/client.ts:2398

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

Parameters

userId

string

the user ID to check

Returns

boolean

true if the user is ignored, false otherwise

isUsernameAvailable()

isUsernameAvailable(username): Promise<boolean>

Defined in: src/client.ts:6523

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

Parameters

username

string

The username to check the availability of.

Returns

Promise<boolean>

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

isVersionSupported()

isVersionSupported(version): Promise<boolean>

Defined in: src/client.ts:6248

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

Parameters

version

string

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

Returns

Promise<boolean>

Whether it is supported

joinRoom()

joinRoom(roomIdOrAlias, opts?): Promise<Room>

Defined in: src/client.ts:2409

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

Parameters

roomIdOrAlias

string

The room ID or room alias to join.

opts?

IJoinRoomOpts = {}

Options when joining the room.

Returns

Promise<Room>

Promise which resolves: Room object.

kick()

kick(roomId, userId, reason?): Promise<EmptyObject>

Defined in: src/client.ts:4280

Parameters

roomId

string

userId

string

reason?

string

Optional.

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

knockRoom()

knockRoom(roomIdOrAlias, opts?): Promise<{ room_id: string; }>

Defined in: src/client.ts:2472

Knock a room. If you have already knocked the room, this will no-op.

Parameters

roomIdOrAlias

string

The room ID or room alias to knock.

opts?

KnockRoomOpts = {}

Options when knocking the room.

Returns

Promise<{ room_id: string; }>

Promise which resolves: {room_id: {string}}

leave()

leave(roomId): Promise<EmptyObject>

Defined in: src/client.ts:4175

Parameters

roomId

string

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

leaveRoomChain()

leaveRoomChain(roomId, includeFuture?): Promise<{[roomId: string]: Error | DigitalWorldError | null; }>

Defined in: src/client.ts:4190

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.

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 | DigitalWorldError | null; }>

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

listenerCount()

listenerCount(event): number

Defined in: src/models/typed-event-emitter.ts:115

Returns the number of listeners listening to the event named event.

Parameters

event

TypedEventEmitter.listenerCount

The name of the event being listened for

Returns

number

Inherited from

listeners()

listeners(event): Function[]

Defined in: src/models/typed-event-emitter.ts:122

Returns a copy of the array of listeners for the event named event.

Parameters

event

TypedEventEmitter.listeners

Returns

Function[]

Inherited from

login(loginType, data): Promise<LoginResponse>

Defined in: src/client.ts:6668

Parameters

loginType

string

data

Omit<LoginRequest, "type">

Returns

Promise<LoginResponse>

Promise which resolves to a LoginResponse object

loginFlows()

loginFlows(): Promise<ILoginFlowsResponse>

Defined in: src/client.ts:6656

Returns

Promise<ILoginFlowsResponse>

Promise which resolves to the available login flows

loginRequest()

loginRequest(data): Promise<LoginResponse>

Defined in: src/client.ts:6756

Sends a POST /login request to the server.

If successful, this will create a new device and access token for the user.

Parameters

data

LoginRequest

Credentials and other details for the login request.

Returns

Promise<LoginResponse>

See

DigitalWorldClient.loginFlows which makes a GET /login request.
https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3login

loginWithPassword()

loginWithPassword(user, password): Promise<LoginResponse>

Defined in: src/client.ts:6691

Parameters

user

string

password

string

Returns

Promise<LoginResponse>

Promise which resolves to a LoginResponse object

loginWithToken()

loginWithToken(token): Promise<LoginResponse>

Defined in: src/client.ts:6740

Parameters

token

string

Returns

Promise<LoginResponse>

Promise which resolves to a LoginResponse object

logout()

logout(stopClient?): Promise<EmptyObject>

Defined in: src/client.ts:6769

Logs out the current session. Obviously, further calls that require authorisation should fail after this method is called. The state of the DigitalWorldClient object is not affected: it is up to the caller to either reset or destroy the DigitalWorldClient after this method succeeds.

Parameters

stopClient?

boolean = false

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

Returns

Promise<EmptyObject>

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

lookupThreePid()

lookupThreePid(medium, address, identityAccessToken): Promise<EmptyObject | { address: string; medium: string; mxid: string; }>

Defined in: src/client.ts:8337

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

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<EmptyObject | { address: string; medium: string; mxid: string; }>

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

makeTxnId()

makeTxnId(): string

Defined in: src/client.ts:6513

Make up a new transaction id

Returns

string

a new, unique, transaction id

members()

members(roomId, includeMembership?, excludeMembership?, atEventId?): Promise<{[userId: string]: IStateEventWithRoomId[]; }>

Defined in: src/client.ts:6946

Parameters

roomId

string

includeMembership?

string

the membership type to include in the response

excludeMembership?

string

the membership type to exclude from the response

atEventId?

string

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

Returns

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

Promise which resolves: dictionary of userid to profile information

mxcUrlToHttp()

mxcUrlToHttp(mxcUrl, width?, height?, resizeMethod?, allowDirectLinks?, allowRedirects?, useAuthentication?): string | null

Defined in: src/client.ts:4414

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

Parameters

mxcUrl

string

The MXC URL

width?

number

The desired width of the thumbnail.

height?

number

The desired height of the thumbnail.

resizeMethod?

string

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

allowDirectLinks?

boolean

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

allowRedirects?

boolean

If true, the caller supports the URL being 307 or 308 redirected to another resource upon request. If false, redirects are not expected. Implied true when useAuthentication is true.

useAuthentication?

boolean

If true, the caller supports authenticated media and wants an authentication-required URL. Note that server support for authenticated media will not be checked - it is the caller’s responsibility to do so before calling this function. Note also that useAuthentication implies allowRedirects. Defaults to false (unauthenticated endpoints).

Returns

string | null

the avatar URL or null.

off()

off<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:129

Alias for removeListener

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

Returns

this

Inherited from

TypedEventEmitter.off

on()

on<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:150

Adds the listener function to the end of the listeners array for the event named event.

No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added, and called, multiple times.

By default, event listeners are invoked in the order they are added. The prependListener method can be used as an alternative to add the event listener to the beginning of the listeners array.

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

The name of the event.

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

The callback function

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

TypedEventEmitter.on

once()

once<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:169

Adds a one-time listener function for the event named event. The next time event is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The prependOnceListener method can be used as an alternative to add the event listener to the beginning of the listeners array.

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

The name of the event.

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

The callback function

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

TypedEventEmitter.once

paginateEventTimeline()

paginateEventTimeline(eventTimeline, opts): Promise<boolean>

Defined in: src/client.ts:5016

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

Parameters

eventTimeline

EventTimeline

timeline object to be updated

opts

IPaginateOpts

Returns

Promise<boolean>

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

patchExtendedProfile()

patchExtendedProfile(profile): Promise<Record<string, unknown>>

Defined in: src/client.ts:7513

Update multiple properties on your extended profile. This will merge with any existing keys.

Parameters

profile

Record<string, unknown>

The profile object to merge with the existing profile.

Returns

Promise<Record<string, unknown>>

The newly merged profile.

See

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

Throws

An error if the server does not support MSC4133 OR the server disallows editing the user profile.

peekInRoom()

peekInRoom(roomId, limit?): Promise<Room>

Defined in: src/client.ts:5285

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

Parameters

roomId

string

The room to attempt to peek into.

limit?

number = 20

The number of timeline events to initially retrieve.

Returns

Promise<Room>

Promise which resolves: Room object

prependListener()

prependListener<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:186

Adds the listener function to the beginning of the listeners array for the event named event.

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

The name of the event.

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

The callback function

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

TypedEventEmitter.prependListener

prependOnceListener()

prependOnceListener<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:202

Adds a one-timelistener function for the event named event to the beginning of the listeners array. The next time event is triggered, this listener is removed, and then invoked.

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

The name of the event.

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

The callback function

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

TypedEventEmitter.prependOnceListener

processAggregatedTimelineEvents()

processAggregatedTimelineEvents(room?, events?): void

Defined in: src/client.ts:8825

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

Parameters

room?

room the events belong to

events?

timeline events to be processed

Returns

void

processBeaconEvents()

processBeaconEvents(room?, events?): void

Defined in: src/client.ts:8814

Parameters

room?

events?

Returns

void

processThreadEvents()

processThreadEvents(room, threadedEvents, toStartOfTimeline): void

Defined in: src/client.ts:8799

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

Parameters

room

the room the adds the threaded events

threadedEvents

an array of the threaded events

toStartOfTimeline

boolean

the direction in which we want to add the events

Returns

void

processThreadRoots()

processThreadRoots(room, threadedEvents, toStartOfTimeline): void

Defined in: src/client.ts:8809

Processes a list of thread roots and creates a thread model

Parameters

room

the room to create the threads in

threadedEvents

an array of thread roots

toStartOfTimeline

boolean

the direction

Returns

void

publicRooms()

publicRooms(params?): Promise<IPublicRoomsResponse>

Defined in: src/client.ts:7178

Get the public rooms list from the server. Supports pagination

Parameters

params?

IRoomDirectoryOptions = {}

Options for this request

Returns

Promise<IPublicRoomsResponse>

Promise which resolves: IPublicRoomsResponse

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

queueToDevice()

queueToDevice(batch): Promise<void>

Defined in: src/client.ts:8494

Sends events directly to specific devices using the protocol’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

batch

ToDeviceBatch

The to-device messages to send

Returns

Promise<void>

rawListeners()

rawListeners(event): Function[]

Defined in: src/models/typed-event-emitter.ts:243

Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).

Parameters

event

TypedEventEmitter.rawListeners

Returns

Function[]

Inherited from

redactEvent()

Call Signature

redactEvent(roomId, eventId, txnId?, opts?): Promise<ISendEventResponse>

Defined in: src/client.ts:3148

Parameters

roomId

string

eventId

string

txnId?

string

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

opts?

IRedactOpts

Redact options

Returns

Promise<ISendEventResponse>

Promise which resolves: TODO

Throws

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

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

redactEvent(roomId, threadId, eventId, txnId?, opts?): Promise<ISendEventResponse>

Defined in: src/client.ts:3154

Parameters

roomId

string

threadId

string | null

eventId

string

txnId?

string

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

opts?

IRedactOpts

Redact options

Returns

Promise<ISendEventResponse>

Promise which resolves: TODO

Throws

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

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

refreshToken()

refreshToken(refreshToken): Promise<IRefreshTokenResponse>

Defined in: src/client.ts:6628

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.

Parameters

refreshToken

string

The refresh token.

Returns

Promise<IRefreshTokenResponse>

Promise which resolves to the new token.

register()

register(username, password, sessionId, auth, bindThreepids?, guestAccessToken?, inhibitLogin?): Promise<RegisterResponse>

Defined in: src/client.ts:6544

Parameters

username

string

password

string

sessionId

string | null

auth

session?

string

type

string

bindThreepids?

Set key ‘email’ to true to bind any email threepid uses during registration in the identity server. Set ‘msisdn’ to true to bind msisdn.

email?

boolean

msisdn?

boolean

guestAccessToken?

string

inhibitLogin?

boolean

Returns

Promise<RegisterResponse>

Promise which resolves to a RegisterResponse object

registerGuest()

registerGuest(body?): Promise<RegisterResponse>

Defined in: src/client.ts:6598

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(HUB_INSTANCE);
const { user_id, device_id, access_token } = tmpClient.registerGuest();
const client = createClient({
  baseUrl: HUB_INSTANCE,
  accessToken: access_token,
  userId: user_id,
  deviceId: device_id,
})
client.setGuest(true);

Parameters

body?

JSON HTTP body to provide.

body?

RegisterRequest

Returns

Promise<RegisterResponse>

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

registerRequest()

registerRequest(data, kind?): Promise<RegisterResponse>

Defined in: src/client.ts:6608

Parameters

data

RegisterRequest

parameters for registration request

kind?

string

type of user to register. may be “guest”

Returns

Promise<RegisterResponse>

Promise which resolves: to the /register response

registerWithIdentityServer()

registerWithIdentityServer(hsOpenIdToken): Promise<{ access_token: string; token: string; }>

Defined in: src/client.ts:8028

Register with an identity server using the OpenID token from the user’s Hub, which can be retrieved via DigitalWorldClient#getOpenIdToken.

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

Parameters

hsOpenIdToken

IOpenIDToken

Returns

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

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

relations()

relations(roomId, eventId, relationType, eventType?, opts?): Promise<{ events: DigitalWorldEvent[]; nextBatch?: string | null; originalEvent?: DigitalWorldEvent | null; prevBatch?: string | null; }>

Defined in: src/client.ts:6364

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.

Parameters

roomId

string

the room of the event

eventId

string

the id of the event

relationType

string | null

the rel_type of the relations requested

eventType?

string | null

the event type of the relations requested

opts?

IRelationsRequestOpts = ...

options with optional values for the request.

Returns

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

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

removeAllListeners()

removeAllListeners(event?): this

Defined in: src/models/typed-event-emitter.ts:219

Removes all listeners, or those of the specified event.

It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

Parameters

event?

TypedEventEmitter.removeAllListeners

The name of the event. If undefined, all listeners everywhere are removed.

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

removeListener()

removeListener<T>(event, listener): this

Defined in: src/models/typed-event-emitter.ts:232

Removes the specified listener from the listener array for the event named event.

Type Parameters

T

T extends EventEmitterEvents | EmittedEvents

Parameters

event

T

listener

Listener<EmittedEvents, ClientEventHandlerMap, T>

Returns

this

a reference to the EventEmitter, so that calls can be chained.

Inherited from

TypedEventEmitter.removeListener

removePusher()

removePusher(pushKey, appId): Promise<EmptyObject>

Defined in: src/client.ts:7776

Removes an existing pusher

Parameters

pushKey

string

pushkey of pusher to remove

appId

string

app_id of pusher to remove

Returns

Promise<EmptyObject>

Promise which resolves: Empty json object on success

reportEvent()

reportEvent(roomId, eventId, score, reason): Promise<EmptyObject>

Defined in: src/client.ts:8583

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

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<EmptyObject>

Promise which resolves to an empty object if successful

reportRoom()

reportRoom(roomId, reason): Promise<EmptyObject>

Defined in: src/client.ts:8601

Reports a room as inappropriate to the server, which may then notify the appropriate people.

This API was introduced in protocol v1.13.

Parameters

roomId

string

The room being reported.

reason

string

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

Returns

Promise<EmptyObject>

Promise which resolves to an empty object if successful

requestAdd3pidEmailToken()

requestAdd3pidEmailToken(email, clientSecret, sendAttempt, nextLink?): Promise<IRequestTokenResponse>

Defined in: src/client.ts:5408

Requests an email verification token for the purposes of adding a third party identifier to an account. This API requests a token from the hub. 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 hub).

Parameters

email

string

As requestEmailToken

clientSecret

string

As requestEmailToken

sendAttempt

number

As requestEmailToken

nextLink?

string

As requestEmailToken

Returns

Promise<IRequestTokenResponse>

Promise which resolves: As requestEmailToken

requestAdd3pidMsisdnToken()

requestAdd3pidMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink?): Promise<IRequestMsisdnTokenResponse>

Defined in: src/client.ts:5436

Requests a text message verification token for the purposes of adding a third party identifier to an account. This API proxies the identity server /validate/email/requestToken API, adding specific behaviour for the addition of phone numbers to an account, as requestAdd3pidEmailToken.

Parameters

phoneCountry

string

As requestRegisterMsisdnToken

phoneNumber

string

As requestRegisterMsisdnToken

clientSecret

string

As requestEmailToken

sendAttempt

number

As requestEmailToken

nextLink?

string

As requestEmailToken

Returns

Promise which resolves: As requestEmailToken

requestEmailToken()

requestEmailToken(email, clientSecret, sendAttempt, nextLink?, identityAccessToken?): Promise<IRequestTokenResponse>

Defined in: src/client.ts:8063

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.

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.

nextLink?

string

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

identityAccessToken?

string

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

Returns

Promise<IRequestTokenResponse>

Promise which resolves: TODO

Throws

Error if no identity server is set

requestLoginToken()

requestLoginToken(auth?): Promise<LoginTokenPostResponse>

Defined in: src/client.ts:6815

Make a request for an m.login.token to be issued as per https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv1loginget_token

The server may require User-Interactive auth.

Parameters

auth?

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

Returns

Promise<LoginTokenPostResponse>

Promise which resolves: On success, the token response or UIA auth data.

requestMsisdnToken()

requestMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink?, identityAccessToken?): Promise<IRequestMsisdnTokenResponse>

Defined in: src/client.ts:8114

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.

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.

nextLink?

string

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

identityAccessToken?

string

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

Returns

Promise which resolves to an object with a sid string

Throws

Error if no identity server is set

requestPasswordEmailToken()

requestPasswordEmailToken(email, clientSecret, sendAttempt, nextLink?): Promise<IRequestTokenResponse>

Defined in: src/client.ts:5470

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

requestEmailToken calls the equivalent API directly on the identity server, therefore bypassing the password reset specific logic.

Parameters

email

string

As requestEmailToken

clientSecret

string

As requestEmailToken

sendAttempt

number

As requestEmailToken

nextLink?

string

As requestEmailToken

Returns

Promise<IRequestTokenResponse>

Promise which resolves: As requestEmailToken

requestPasswordMsisdnToken()

requestPasswordMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink): Promise<IRequestMsisdnTokenResponse>

Defined in: src/client.ts:5497

Requests a text message verification token for the purposes of resetting the password on an account. This API proxies the identity server /validate/email/requestToken API, adding specific behaviour for the password resetting, as requestPasswordEmailToken.

Parameters

phoneCountry

string

As requestRegisterMsisdnToken

phoneNumber

string

As requestRegisterMsisdnToken

clientSecret

string

As requestEmailToken

sendAttempt

number

As requestEmailToken

nextLink

string

As requestEmailToken

Returns

Promise which resolves: As requestEmailToken

requestRegisterEmailToken()

requestRegisterEmailToken(email, clientSecret, sendAttempt, nextLink?): Promise<IRequestTokenResponse>

Defined in: src/client.ts:5347

Requests an email verification token for the purposes of registration. This API requests a token from the hub. 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

Parameters

email

string

As requestEmailToken

clientSecret

string

As requestEmailToken

sendAttempt

number

As requestEmailToken

nextLink?

string

As requestEmailToken

Returns

Promise<IRequestTokenResponse>

Promise which resolves: As requestEmailToken

requestRegisterMsisdnToken()

requestRegisterMsisdnToken(phoneCountry, phoneNumber, clientSecret, sendAttempt, nextLink?): Promise<IRequestMsisdnTokenResponse>

Defined in: src/client.ts:5375

Requests a text message verification token for the purposes of registration. This API requests a token from the hub. The doesServerRequireIdServerParam() method can be used to determine if the server requires the id_server parameter to be provided.

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

nextLink?

string

As requestEmailToken

Returns

Promise which resolves: As requestEmailToken

resendEvent()

resendEvent(event, room): Promise<ISendEventResponse>

Defined in: src/client.ts:2505

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

Parameters

event

The event to resend.

room

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

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

resetNotifTimelineSet()

resetNotifTimelineSet(): void

Defined in: src/client.ts:5248

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

Returns

void

retryImmediately()

retryImmediately(): boolean

Defined in: src/client.ts:1913

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

boolean

True if this resulted in a request being retried.

roomInitialSync()

roomInitialSync(roomId, limit): Promise<IRoomInitialSyncResponse>

Defined in: src/client.ts:7102

Parameters

roomId

string

limit

number

Returns

Promise<IRoomInitialSyncResponse>

Promise which resolves: TODO

roomState()

roomState(roomId): Promise<IStateEventWithRoomId[]>

Defined in: src/client.ts:6920

Parameters

roomId

string

Returns

Promise<IStateEventWithRoomId[]>

Promise which resolves: TODO

scrollback()

scrollback(room, limit?): Promise<Room>

Defined in: src/client.ts:4492

Retrieve older messages from the given room and put them in the timeline.

If this is called multiple times whilst a request is ongoing, the same Promise will be returned. If there was a problem requesting scrollback, there will be a small delay before another request can be made (to prevent tight-looping when there is no connection).

Parameters

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>

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

search()

search(params, abortSignal?): Promise<ISearchResponse>

Defined in: src/client.ts:7898

Perform a server-side search.

Parameters

params

body

ISearchRequestBody

the JSON object to pass to the request body.

next_batch?

string

the batch token to pass in the query string

abortSignal?

AbortSignal

optional signal used to cancel the http request.

Returns

Promise<ISearchResponse>

Promise which resolves to the search response object.

searchMessageText()

searchMessageText(opts): Promise<ISearchResponse>

Defined in: src/client.ts:5629

Parameters

opts

ISearchOpts

Returns

Promise<ISearchResponse>

searchRoomEvents()

searchRoomEvents(opts): Promise<ISearchResults>

Defined in: src/client.ts:5662

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.

Parameters

opts

IEventSearchOpts

Returns

Promise<ISearchResults>

Promise which resolves: result object

searchUserDirectory()

searchUserDirectory(options): Promise<IUserDirectoryResponse>

Defined in: src/client.ts:7290

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

Parameters

options

limit?

number

the maximum number of results to return. The server will apply a limit if unspecified.

term

string

the term with which to search.

Returns

Promise<IUserDirectoryResponse>

Promise which resolves: an array of results.

sendEmoteMessage()

Call Signature

sendEmoteMessage(roomId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3296

Parameters

roomId

string

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendEmoteMessage(roomId, threadId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3297

Parameters

roomId

string

threadId

string | null

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendEvent()

Call Signature

sendEvent<K>(roomId, eventType, content, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:2716

Send a timeline event.

Type Parameters

K

K extends keyof TimelineEvents

Parameters

roomId

string

The room to send to.

eventType

K

The event type.

content

TimelineEvents[K]

The event content.

txnId?

string

An optional ID to deduplicate requests in case of repeated attempts.

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendEvent<K>(roomId, threadId, eventType, content, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:2722

Send a timeline event.

Type Parameters

K

K extends keyof TimelineEvents

Parameters

roomId

string

The room to send to.

threadId

string | null

eventType

K

The event type.

content

TimelineEvents[K]

The event content.

txnId?

string

An optional ID to deduplicate requests in case of repeated attempts.

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendHtmlEmote()

Call Signature

sendHtmlEmote(roomId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3457

Parameters

roomId

string

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendHtmlEmote(roomId, threadId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3458

Parameters

roomId

string

threadId

string | null

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendHtmlMessage()

Call Signature

sendHtmlMessage(roomId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3401

Parameters

roomId

string

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendHtmlMessage(roomId, threadId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3402

Parameters

roomId

string

threadId

string | null

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendHtmlNotice()

Call Signature

sendHtmlNotice(roomId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3429

Parameters

roomId

string

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendHtmlNotice(roomId, threadId, body, htmlBody): Promise<ISendEventResponse>

Defined in: src/client.ts:3430

Parameters

roomId

string

threadId

string | null

body

string

htmlBody

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendImageMessage()

Call Signature

sendImageMessage(roomId, url, info?, text?): Promise<ISendEventResponse>

Defined in: src/client.ts:3324

Parameters

roomId

string

url

string

info?

text?

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendImageMessage(roomId, threadId, url, info?, text?): Promise<ISendEventResponse>

Defined in: src/client.ts:3325

Parameters

roomId

string

threadId

string | null

url

string

info?

RoomMessageEventContent

text?

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendMessage()

Call Signature

sendMessage(roomId, content, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3210

Parameters

roomId

string

content

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to an ISendEventResponse object

Call Signature

sendMessage(roomId, threadId, content, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3211

Parameters

roomId

string

threadId

string | null

content

RoomMessageEventContent

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to an ISendEventResponse object

sendNotice()

Call Signature

sendNotice(roomId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3267

Parameters

roomId

string

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Call Signature

sendNotice(roomId, threadId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3268

Parameters

roomId

string

threadId

string | null

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

sendReadReceipt()

sendReadReceipt(event, receiptType?, unthreaded?): Promise<EmptyObject | undefined>

Defined in: src/client.ts:3849

Send a read receipt.

Parameters

event

DigitalWorldEvent | null

The event that has been read.

receiptType?

ReceiptType = ReceiptType.Read

other than ReceiptType.Read are experimental! Optional.

unthreaded?

boolean = false

Returns

Promise<EmptyObject | undefined>

Promise which resolves: to an empty object {}

sendReceipt()

sendReceipt(event, receiptType, body?, unthreaded?): Promise<EmptyObject>

Defined in: src/client.ts:3812

Send a receipt.

Parameters

event

The event being acknowledged

receiptType

ReceiptType

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

body?

Record<string, any>

Additional content to send alongside the receipt.

unthreaded?

boolean = false

An unthreaded receipt will clear room+thread notifications

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

sendRtcDecline()

sendRtcDecline(roomId, notificationEventId): Promise<ISendEventResponse>

Defined in: src/client.ts:3920

Parameters

roomId

string

notificationEventId

string

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendStateEvent()

sendStateEvent<K>(roomId, eventType, content, stateKey?, opts?): Promise<ISendEventResponse>

Defined in: src/client.ts:7019

Send a state event into a room

Type Parameters

K

K extends keyof StateEvents

Parameters

roomId

string

ID of the room to send the event into

eventType

K

type of the state event to send

content

StateEvents[K]

content of the event to send

stateKey?

string = ""

the stateKey to send into the room

opts?

IRequestOpts = {}

Options for the request function.

Returns

Promise<ISendEventResponse>

Promise which resolves: TODO

sendStickerMessage()

Call Signature

sendStickerMessage(roomId, url, info?, text?): Promise<ISendEventResponse>

Defined in: src/client.ts:3360

Parameters

roomId

string

url

string

info?

text?

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

sendStickerMessage(roomId, threadId, url, info?, text?): Promise<ISendEventResponse>

Defined in: src/client.ts:3366

Parameters

roomId

string

threadId

string | null

url

string

info?

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

text?

string

Returns

Promise<ISendEventResponse>

Promise which resolves: to a ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

sendTextMessage()

Call Signature

sendTextMessage(roomId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3240

Parameters

roomId

string

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

Call Signature

sendTextMessage(roomId, threadId, body, txnId?): Promise<ISendEventResponse>

Defined in: src/client.ts:3241

Parameters

roomId

string

threadId

string | null

body

string

txnId?

string

Optional.

Returns

Promise<ISendEventResponse>

sendToDevice()

sendToDevice(eventType, contentMap, txnId?): Promise<EmptyObject>

Defined in: src/client.ts:8443

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.

Parameters

eventType

string

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

contentMap

SendToDeviceContentMap

txnId?

string

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

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

sendTyping()

sendTyping(roomId, isTyping, timeoutMs): Promise<EmptyObject>

Defined in: src/client.ts:3980

Parameters

roomId

string

isTyping

boolean

timeoutMs

number

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setAccessToken()

setAccessToken(token): void

Defined in: src/client.ts:6495

Set the access token associated with this account.

Parameters

token

string

The new access token.

Returns

void

setAccountData()

setAccountData<K>(eventType, content): Promise<EmptyObject>

Defined in: src/client.ts:2244

Set account data event for the current user, and wait for the result to be echoed over /sync.

Waiting for the remote echo ensures that a subsequent call to getAccountData will return the updated value.

If called before the client is started with startClient, logs a warning and falls back to setAccountDataRaw.

Retries the request up to 5 times in the case of an ConnectionError.

Type Parameters

K

K extends keyof AccountDataEvents

Parameters

eventType

K

The event type

content

Record<string, never> | AccountDataEvents[K]

the contents object for the event

Returns

Promise<EmptyObject>

setAccountDataRaw()

setAccountDataRaw<K>(eventType, content): Promise<EmptyObject>

Defined in: src/client.ts:2296

Set account data event for the current user, without waiting for the remote echo.

Type Parameters

K

K extends keyof AccountDataEvents

Parameters

eventType

K

The event type

content

Record<string, never> | AccountDataEvents[K]

the contents object for the event

Returns

Promise<EmptyObject>

setAvatarUrl()

setAvatarUrl(url): Promise<EmptyObject>

Defined in: src/client.ts:4382

Parameters

url

string

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setCanResetTimelineCallback()

setCanResetTimelineCallback(cb): void

Defined in: src/client.ts:6341

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

cb

ResetTimelineCallback

The callback which will be invoked.

Returns

void

setDeviceDetails()

setDeviceDetails(deviceId, body): Promise<EmptyObject>

Defined in: src/client.ts:7685

Update the given device

Parameters

deviceId

string

device to update

body

body of request

display_name

string

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setDisplayName()

setDisplayName(name): Promise<EmptyObject>

Defined in: src/client.ts:4365

Parameters

name

string

Returns

Promise<EmptyObject>

Promise which resolves: {} an empty object.

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setExtendedProfile()

setExtendedProfile(profile): Promise<void>

Defined in: src/client.ts:7539

Set multiple properties on your extended profile. This will completely replace the existing profile, removing any unspecified keys.

Parameters

profile

Record<string, unknown>

The profile object to set.

Returns

Promise<void>

See

Throws

An error if the server does not support MSC4133 OR the server disallows editing the user profile.

setExtendedProfileProperty()

setExtendedProfileProperty(key, value): Promise<void>

Defined in: src/client.ts:7461

Set a property on your extended profile.

Parameters

key

string

The key of the property to set.

value

unknown

The value to set on the property.

Returns

Promise<void>

See

https://github.com/tcpipuk/matrix-spec-proposals/blob/main/proposals/4133-extended-profiles.md

Throws

An error if the server does not support MSC4133 OR the server disallows editing the user profile.

setFallbackICEServerAllowed()

setFallbackICEServerAllowed(allow): void

Defined in: src/client.ts:6035

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

Parameters

allow

boolean

Returns

void

setForceTURN()

setForceTURN(force): void

Defined in: src/client.ts:1737

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

setGuest()

setGuest(guest): void

Defined in: src/client.ts:1894

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. if the token is a macaroon, it should be encoded in it that it is a ‘guest’ access token, which means that the SDK can determine this entirely without the dev manually flipping this flag.

Returns

void

setGuestAccess()

setGuestAccess(roomId, opts): Promise<void>

Defined in: src/client.ts:5308

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

Parameters

roomId

string

The room to configure guest access in.

opts

IGuestAccessOpts

Options

Returns

Promise<void>

Promise which resolves

setIdentityServerUrl()

setIdentityServerUrl(url?): void

Defined in: src/client.ts:6470

Set the identity server URL of this client

Parameters

url?

string

New identity server URL

Returns

void

setIgnoredUsers()

setIgnoredUsers(userIds): Promise<EmptyObject>

Defined in: src/client.ts:2385

Sets the users that the current user should ignore.

Parameters

userIds

string[]

the user IDs to ignore

Returns

Promise<EmptyObject>

Promise which resolves: an empty object

setLivekitServiceURL()

setLivekitServiceURL(newURL): void

Defined in: src/client.ts:1816

Parameters

newURL

string

Returns

void

setLocalNotificationSettings()

setLocalNotificationSettings(deviceId, notificationSettings): Promise<EmptyObject>

Defined in: src/client.ts:7791

Persists local notification settings

Parameters

deviceId

string

notificationSettings

LocalNotificationSettings

Returns

Promise<EmptyObject>

Promise which resolves: an empty object

setMaxListeners()

setMaxListeners(n): this

Defined in: node_modules/.pnpm/@types+node@22.20.0/node_modules/@types/node/events.d.ts:813

By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

n

number

Returns

this

Since

v0.3.5

Inherited from

TypedEventEmitter.setMaxListeners

setNotifTimelineSet()

setNotifTimelineSet(set): void

Defined in: src/client.ts:1932

Set the global notification EventTimelineSet

Parameters

set

Returns

void

setPassword()

setPassword(authDict, newPassword, logoutDevices?): Promise<EmptyObject>

Defined in: src/client.ts:7643

Make a request to change your password.

Parameters

authDict

newPassword

string

The new desired password.

logoutDevices?

boolean

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

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setPowerLevel()

setPowerLevel(roomId, userId, powerLevel): Promise<ISendEventResponse>

Defined in: src/client.ts:2636

Set a power level to one or multiple users. Will apply changes atop of current power level event from local state if running & synced, falling back to fetching latest from the /state/ API.

Parameters

roomId

string

the room to update power levels in

userId

string | string[]

the ID of the user or users to update power levels of

powerLevel

number | undefined

the numeric power level to update given users to

Returns

Promise<ISendEventResponse>

Promise which resolves: to an ISendEventResponse object

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setPresence()

setPresence(opts): Promise<void>

Defined in: src/client.ts:4451

Parameters

opts

IPresenceOpts

Options to apply

Returns

Promise<void>

Promise which resolves

Throws

If ‘presence’ isn’t a valid presence enum value.

setProfileInfo()

Call Signature

setProfileInfo(info, data): Promise<EmptyObject>

Defined in: src/client.ts:4349

Parameters

info

"avatar_url"

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

data

The JSON object to set.

avatar_url

string

Returns

Promise<EmptyObject>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

Call Signature

setProfileInfo(info, data): Promise<EmptyObject>

Defined in: src/client.ts:4350

Parameters

info

"displayname"

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

data

The JSON object to set.

displayname

string

Returns

Promise<EmptyObject>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setPusher()

setPusher(pusher): Promise<EmptyObject>

Defined in: src/client.ts:7764

Adds a new pusher or updates an existing pusher

Parameters

pusher

IPusherRequest

Object representing a pusher

Returns

Promise<EmptyObject>

Promise which resolves: Empty json object on success

setPushRuleActions()

setPushRuleActions(scope, kind, ruleId, actions): Promise<EmptyObject>

Defined in: src/client.ts:7876

Set the actions for a push notification rule.

Parameters

scope

string

kind

ruleId

string

actions

PushRuleAction[]

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setPushRuleEnabled()

setPushRuleEnabled(scope, kind, ruleId, enabled): Promise<EmptyObject>

Defined in: src/client.ts:7858

Enable or disable a push notification rule.

Parameters

scope

string

kind

ruleId

string

enabled

boolean

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setPushRules()

setPushRules(rules): void

Defined in: src/client.ts:7815

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

Parameters

rules

IPushRules

Returns

void

setRoomAccountData()

setRoomAccountData<K>(roomId, eventType, content): Promise<EmptyObject>

Defined in: src/client.ts:2611

Type Parameters

K

K extends keyof RoomAccountDataEvents

Parameters

roomId

string

the ID of the room this event should be stored within

eventType

K

event type to be set

content

Record<string, never> | RoomAccountDataEvents[K]

event content

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setRoomDirectoryVisibility()

setRoomDirectoryVisibility(roomId, visibility): Promise<EmptyObject>

Defined in: src/client.ts:7276

Set the visibility of a room in the current HS’s room directory

Parameters

roomId

string

visibility

Visibility

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

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object {}

setRoomMutePushRule()

setRoomMutePushRule(scope, roomId, mute): Promise<void> | undefined

Defined in: src/client.ts:5555

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

Parameters

scope

"global" | "device"

“global” or device-specific.

roomId

string

the id of the room.

mute

boolean

the mute state.

Returns

Promise<void> | undefined

Promise which resolves: result object

setRoomName()

setRoomName(roomId, name): Promise<ISendEventResponse>

Defined in: src/client.ts:2545

Parameters

roomId

string

name

string

Returns

Promise<ISendEventResponse>

Promise which resolves: TODO

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setRoomReadMarkers()

setRoomReadMarkers(roomId, rmEventId, rrEvent?, rpEvent?): Promise<EmptyObject>

Defined in: src/client.ts:3878

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

Parameters

roomId

string

ID of the room that has been read

rmEventId

string

ID of the event that has been read

rrEvent?

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.

rpEvent?

MBeaconInfoEventContent

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<EmptyObject>

Promise which resolves: the empty object, {}.

setRoomReadMarkersHttpRequest()

setRoomReadMarkersHttpRequest(roomId, rmEventId, rrEventId?, rpEventId?): Promise<EmptyObject>

Defined in: src/client.ts:7122

Parameters

roomId

string

ID of the room that has been read

rmEventId

string

ID of the event that has been read

rrEventId?

string

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

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<EmptyObject>

Promise which resolves: the empty object, {}.

setRoomTag()

setRoomTag(roomId, tagName, metadata?): Promise<EmptyObject>

Defined in: src/client.ts:2581

Parameters

roomId

string

tagName

string

name of room tag to be set

metadata?

ITagMetadata = {}

associated with that tag to be stored

Returns

Promise<EmptyObject>

Promise which resolves: to an empty object

setRoomTopic()

setRoomTopic(roomId, topic?, htmlTopic?): Promise<ISendEventResponse>

Defined in: src/client.ts:2558

Parameters

roomId

string

The room to update the topic in.

topic?

string

The plaintext topic. May be empty to remove the topic.

htmlTopic?

string

Optional.

Returns

Promise<ISendEventResponse>

Promise which resolves: TODO

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

setSupportsCallTransfer()

setSupportsCallTransfer(support): void

Defined in: src/client.ts:1745

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

Parameters

support

boolean

True to advertise the ‘m.call.transferee’ capability

Returns

void

setSyncPresence()

setSyncPresence(presence?): Promise<void>

Defined in: src/client.ts:4441

Specify the set_presence value to be used for subsequent calls to the Sync API. This has an advantage over calls to the PUT /presence API in that it doesn’t clobber status_msg set by other devices.

Parameters

presence?

SetPresence

the presence to specify to set_presence of sync calls

Returns

Promise<void>

slidingSync()

slidingSync(req, proxyBaseUrl?, abortSignal?): Promise<MSC3575SlidingSyncResponse>

Defined in: src/client.ts:8729

Perform a single MSC3575 sliding sync request.

Parameters

req

MSC3575SlidingSyncRequest

The request to make.

proxyBaseUrl?

string

The base URL for the sliding sync proxy.

abortSignal?

AbortSignal

Optional signal to abort request mid-flight.

Returns

Promise<MSC3575SlidingSyncResponse>

The sliding sync response, or a standard error.

Throws

on non 2xx status codes with an object with a field “httpStatus”:number.

startClient()

startClient(opts?): Promise<void>

Defined in: src/client.ts:1465

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

Parameters

opts?

IStartClientOpts

Options to apply when syncing.

Returns

Promise<void>

stopClient()

stopClient(): void

Defined in: src/client.ts:1559

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

Returns

void

stopPeeking()

stopPeeking(): void

Defined in: src/client.ts:5294

Stop any ongoing room peeking.

Returns

void

storeClientOptions()

storeClientOptions(): Promise<void>

Defined in: src/client.ts:6112

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

Promise<void>

for store operation

submitMsisdnToken()

submitMsisdnToken(sid, clientSecret, msisdnToken, identityAccessToken): Promise<{ success: boolean; }>

Defined in: src/client.ts:8161

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.

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 entered by the user.

identityAccessToken

string | null

The access_token field of the Identity Server /account/register response (see registerWithIdentityServer). Some legacy identity servers had no authentication here.

Returns

Promise<{ success: boolean; }>

Promise which resolves: Object, containing success boolean.

Throws

Error if No identity server is set

submitMsisdnTokenOtherUrl()

submitMsisdnTokenOtherUrl(url, sid, clientSecret, msisdnToken): Promise<{ success: boolean; }>

Defined in: src/client.ts:8200

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 hub validates 3PID ownership (as part of requestAdd3pidMsisdnToken). The hub 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.

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 entered by the user.

Returns

Promise<{ success: boolean; }>

Promise which resolves: Object, containing success boolean.

supportsIntentionalMentions()

supportsIntentionalMentions(): boolean

Defined in: src/client.ts:8766

A helper to determine intentional mentions support

Returns

boolean

a boolean to determine if intentional mentions are enabled on the server

supportsThreads()

supportsThreads(): boolean

Defined in: src/client.ts:8757

A helper to determine thread support

Returns

boolean

a boolean to determine if threads are enabled

supportsVoip()

supportsVoip(): boolean

Defined in: src/client.ts:1720

Check if the runtime environment supports VoIP calling.

Returns

boolean

True if VoIP is supported.

syncLeftRooms()

syncLeftRooms(): Promise<Room[]>

Defined in: src/client.ts:5770

Populate the store with rooms the user has left.

Returns

Promise<Room[]>

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

timestampToEvent()

timestampToEvent(roomId, timestamp, dir): Promise<TimestampToEventResponse>

Defined in: src/client.ts:8846

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

Parameters

roomId

string

timestamp

number

dir

Direction

Returns

Promise<TimestampToEventResponse>

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

turnServer()

turnServer(): Promise<ITurnServerResponse>

Defined in: src/client.ts:5955

Returns

Promise<ITurnServerResponse>

Promise which resolves: ITurnServerResponse object

unban()

unban(roomId, userId): Promise<EmptyObject>

Defined in: src/client.ts:4260

Parameters

roomId

string

userId

string

Returns

Promise<EmptyObject>

Promise which resolves: Object (currently empty)

unbindThreePid()

unbindThreePid(medium, address): Promise<{ id_server_unbind_result: IdServerUnbindResult; }>

Defined in: src/client.ts:7605

Unbind a 3PID for discovery on an identity server via the hub. The hub removes its record of the binding to keep an updated record of where all 3PIDs for the account are bound.

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; }>

Promise which resolves: on success

unstable_createLiveBeacon()

unstable_createLiveBeacon(roomId, beaconInfoContent): Promise<ISendEventResponse>

Defined in: src/client.ts:2684

Create an m.beacon_info event

Parameters

roomId

string

beaconInfoContent

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

unstable_setLiveBeacon()

unstable_setLiveBeacon(roomId, beaconInfoContent): Promise<ISendEventResponse>

Defined in: src/client.ts:2700

Upsert a live beacon event using a specific m.beacon_info.* event variable type

Parameters

roomId

string

string

beaconInfoContent

MBeaconInfoEventContent

Returns

Promise<ISendEventResponse>

Throws

May throw a DigitalWorldSafetyError if content is deemed unsafe.

See

DigitalWorldSafetyError

unstableCreateFileTree()

unstableCreateFileTree(name): Promise<MSC3089TreeSpace>

Defined in: src/client.ts:8662

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.

Parameters

name

string

The name of the tree space.

Returns

Promise<MSC3089TreeSpace>

Promise which resolves to the created space.

unstableGetFileTreeSpace()

unstableGetFileTreeSpace(roomId): MSC3089TreeSpace | null

Defined in: src/client.ts:8703

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.

Parameters

roomId

string

The room ID to get a tree space reference for.

Returns

MSC3089TreeSpace | null

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

upgradeRoom()

upgradeRoom(roomId, newVersion, additionalCreators?): Promise<{ replacement_room: string; }>

Defined in: src/client.ts:6978

Upgrades a room to a new protocol version

Parameters

roomId

string

newVersion

string

The target version to upgrade to

additionalCreators?

string[]

an optional list of user IDs of users who should have the same permissions as the user performing the upgrade

Returns

Promise<{ replacement_room: string; }>

Promise which resolves: Object with key ‘replacement_room’

uploadContent()

uploadContent(file, opts?): Promise<UploadResponse>

Defined in: src/client.ts:7313

Upload a file to the media repository on the hub.

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.

opts?

UploadOpts

options object

Returns

Promise<UploadResponse>

Promise which resolves to response object, or rejects with an error (usually a DigitalWorldError).

uploadDeviceSigningKeys()

uploadDeviceSigningKeys(auth?, keys?): Promise<EmptyObject>

Defined in: src/client.ts:8007

Parameters

auth?