Class: MatrixBaseApis

base-apis~MatrixBaseApis

new MatrixBaseApis(opts)

Low-level wrappers for the Matrix APIs
Parameters:
Name Type Description
opts Object Configuration options
Properties
Name Type Description
baseUrl string Required. The base URL to the client-server HTTP API.
idBaseUrl string Optional. The base identity server URL for identity server requests.
request function Required. The function to invoke for HTTP requests. The value of this property is typically require("request") as it returns a function which meets the required interface. See requestFunction for more information.
accessToken string The access_token for this user.
queryParams Object Optional. Extra query parameters to append to all requests with this client. Useful for application services which require ?user_id=.
Source:

Methods

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

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

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

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

cancelUpload(promise) → {boolean}

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

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

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

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

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

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

Create a new room.
Parameters:
Name Type Description
options Object a list of options to pass to the /createRoom API.
Properties
Name Type Description
room_alias_name string The alias localpart to assign to this room.
visibility string Either 'public' or 'private'.
invite Array.<string> A list of user IDs to invite to this room.
name string The name to give this room.
topic string The topic to give this room.
callback module:client.callback Optional.
Source:
Returns:

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

Deactivates the logged-in account. Obviously, further calls that require authorisation should fail after this method is called. The state of the MatrixClient object is not affected: it is up to the caller to either reset or destroy the MatrixClient after this method succeeds.
Parameters:
Name Type Description
auth object Optional. Auth data to supply for User-Interactive auth.
callback module:client.callback Optional.
Source:
Returns:
Resolves: On success, the empty object
Type
module:client.Promise

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

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

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

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

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

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

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

Download device keys
Parameters:
Name Type Attributes Description
userIds Array.<string> list of users to get keys for
callback module:client.callback <optional>
Source:
Returns:
Resolves: result object. Rejects: with an error response (module:http-api.MatrixError).
Type
module:client.Promise

getAccessToken() → (nullable) {String}

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

getCasLoginUrl(redirectUrl) → {string}

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

getCurrentUploads() → {array}

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

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

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

getFallbackAuthUrl(loginType, authSessionId) → {string}

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

getHomeserverUrl() → {string}

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

getIdentityServerUrl() → {string}

Get the Identity Server URL of this client
Source:
Returns:
Identity Server URL of this client
Type
string

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

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

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

Gets all pushers registered for the logged-in user
Parameters:
Name Type Description
callback module:client.callback Optional.
Source:
Returns:

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

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

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

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

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

Get room info for the given alias.
Parameters:
Name Type Description
alias string The room alias to resolve.
callback module:client.callback Optional.
Source:
Returns:

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

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

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

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

getThirdpartyProtocols() → {module:client.Promise}

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

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

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

isLoggedIn() → {boolean}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Looks up the public Matrix ID mapping for a given 3rd party identifier from the Identity Server
Parameters:
Name Type Description
medium string The medium of the threepid, eg. 'email'
address string The textual address of the threepid
callback module:client.callback Optional.
Source:
Returns:

makeTxnId() → {string}

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

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

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

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

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

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

Parameters:
Name Type Description
username string
password string
sessionId string
auth Object
bindEmail boolean
guestAccessToken string
callback module:client.callback Optional.
Source:
Returns:

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

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

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

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

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

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

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

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

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

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

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

Parameters:
Name Type Description
roomId string
callback module:client.callback Optional.
Source:
Returns:
Perform a server-side search.
Parameters:
Name Type Description
opts Object
Properties
Name Type Description
next_batch string the batch token to pass in the query string
body Object the JSON object to pass to the request body.
callback module:client.callback Optional.
Source:
Returns:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Upload a file to the media repository on the home server.
Parameters:
Name Type Description
file object The object to upload. On a browser, something that can be sent to XMLHttpRequest.send (typically a File). Under node.js, a a Buffer, String or ReadStream.
opts object options object
Properties
Name Type Attributes Description
name string <optional>
Name to give the file on the server. Defaults to file.name.
type string <optional>
Content-type for the upload. Defaults to file.type, or applicaton/octet-stream.
rawResponse boolean <optional>
Return the raw body, rather than parsing the JSON. Defaults to false (except on node.js, where it defaults to true for backwards compatibility).
onlyContentUri boolean <optional>
Just return the content URI, rather than the whole body. Defaults to false (except on browsers, where it defaults to true for backwards compatibility). Ignored if opts.rawResponse is true.
callback function <optional>
Deprecated. Optional. The callback to invoke on success/failure. See the promise return values for more information.
Source:
Returns:
Resolves to response object, as determined by this.opts.onlyData, opts.rawResponse, and opts.onlyContentUri. Rejects with an error (usually a MatrixError).
Type
module:client.Promise

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

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