Class MatrixClient

Thin wrapper over the Matrix Client-Server API for one homeserver and session.

Inheritance
object
MatrixClient
Inherited Members
Namespace: Uniform.Matrix.Protocol.Client
Assembly: Uniform.Matrix.Protocol.Client.dll
Syntax
public sealed class MatrixClient
Remarks

Split into partial files by spec area:

  • MatrixClient.Auth.cs: server info, login and logout.
  • MatrixClient.Sync.cs: sync, sync loop and filters.
  • MatrixClient.Rooms.cs: room membership, creation, aliases, state and members.
  • MatrixClient.Events.cs: room history, sending, redaction, typing and read markers.
  • MatrixClient.Profile.cs: profiles and presence.
  • MatrixClient.AccountData.cs: account data, tags, ignored users and direct rooms.
  • MatrixClient.PushRules.cs: push rules and pushers.
  • MatrixClient.Directory.cs: public room directory and user directory.
  • MatrixClient.Media.cs: media upload and download, file messages.
  • MatrixClient.Devices.cs: devices and user-interactive auth.
  • MatrixClient.Keys.cs: encryption keys and to-device messages.
  • MatrixClient.Admin.cs: server administration, for admins.
  • MatrixClient.Rtc.cs: MatrixRTC transports, OpenID tokens and delayed events.
Examples
MatrixClient client = new(http, new Uri("https://matrix.org"));
await client.LoginWithPasswordAsync("@alice:matrix.org", password);
await foreach (SyncResponse sync in client.SyncLoopAsync(cancellationToken: cancellationToken))
    foreach ((string roomId, JoinedRoom room) in sync.Rooms.Join)
        foreach (ClientEvent ev in room.Timeline.Events)
            if (ev.TryGetContent(out MessageContent? message)) Console.WriteLine($"{ev.Sender}: {message.Body}");

Constructors

| Edit this page View Source

MatrixClient(HttpClient, Uri)

Create a logged-out client for homeserver.

Declaration
public MatrixClient(HttpClient http, Uri homeserver)
Parameters
Type Name Description
HttpClient http

Client used for all requests; owned by the caller.
Uri homeserver

Homeserver base URL, e.g. from DiscoverAsync(HttpClient, string, CancellationToken).
| Edit this page View Source

MatrixClient(HttpClient, MatrixSession)

Create a client that resumes a stored session.

Declaration
public MatrixClient(HttpClient http, MatrixSession session)
Parameters
Type Name Description
HttpClient http

Client used for all requests; owned by the caller.
MatrixSession session

Session from an earlier LoginWithPasswordAsync(string, string, string?, CancellationToken).

Fields

| Edit this page View Source

DelayParameter

The query parameter that delays a send, MSC4140.

Declaration
public const string DelayParameter = "org.matrix.msc4140.delay"
Field Value
Type Description
string

Properties

| Edit this page View Source

AccessToken

Access token of Session.

Declaration
public string? AccessToken { get; }
Property Value
Type Description
string
| Edit this page View Source

DeviceId

Device ID of Session.

Declaration
public string? DeviceId { get; }
Property Value
Type Description
string
| Edit this page View Source

Homeserver

Base URL with a trailing slash, so relative endpoint paths append instead of replacing.

Declaration
public Uri Homeserver { get; }
Property Value
Type Description
Uri
| Edit this page View Source

IsLoggedIn

Whether Session is set.

Declaration
public bool IsLoggedIn { get; }
Property Value
Type Description
bool
| Edit this page View Source

MaxRateLimitDelay

Longest server-requested wait that is retried; longer waits throw MatrixException at once so callers are not blocked for minutes.

Declaration
public TimeSpan MaxRateLimitDelay { get; set; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

MaxRateLimitRetries

Times a rate-limited request is retried before MatrixException is thrown.

Declaration
public int MaxRateLimitRetries { get; set; }
Property Value
Type Description
int
| Edit this page View Source

Session

Current session; null when logged out.

Declaration
public MatrixSession? Session { get; }
Property Value
Type Description
MatrixSession
| Edit this page View Source

SyncRetryDelay

First wait after a failed sync in SyncLoopAsync(string?, string?, TimeSpan?, Action<Exception, TimeSpan>?, CancellationToken); doubles on each failure.

Declaration
public TimeSpan SyncRetryDelay { get; set; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

SyncRetryMaxDelay

Longest wait between failed syncs in SyncLoopAsync(string?, string?, TimeSpan?, Action<Exception, TimeSpan>?, CancellationToken).

Declaration
public TimeSpan SyncRetryMaxDelay { get; set; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

UserId

Full user ID of Session.

Declaration
public string? UserId { get; }
Property Value
Type Description
string

Methods

| Edit this page View Source

BanAsync(string, string, string?, CancellationToken)

Bans userId from a room.

Declaration
public Task BanAsync(string roomId, string userId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string userId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ChangePasswordAsync(string, string, bool, CancellationToken)

Changes the password, confirming with the current one; other devices are logged out unless logoutDevices is false.

Declaration
public Task ChangePasswordAsync(string currentPassword, string newPassword, bool logoutDevices = true, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string currentPassword
string newPassword
bool logoutDevices
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ClaimKeysAsync(IReadOnlyDictionary<string, IReadOnlyList<string>>, CancellationToken)

Claims one SignedCurve25519 key for each user and device in devices.

Declaration
public Task<KeysClaimResponse> ClaimKeysAsync(IReadOnlyDictionary<string, IReadOnlyList<string>> devices, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IReadOnlyDictionary<string, IReadOnlyList<string>> devices
CancellationToken cancellationToken
Returns
Type Description
Task<KeysClaimResponse>
| Edit this page View Source

CreateAdminAccountAsync(string, string, string?, bool, CancellationToken)

Create an account that logs in with password; for admins.

Declaration
public Task<AdminAccount> CreateAdminAccountAsync(string userId, string password, string? displayName = null, bool admin = false, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
string password
string displayName
bool admin
CancellationToken cancellationToken
Returns
Type Description
Task<AdminAccount>
| Edit this page View Source

CreateDirectRoomAsync(string, bool, CancellationToken)

Create a direct-message room with userId, invites them and record it in Direct; return the room ID.

Declaration
public Task<string> CreateDirectRoomAsync(string userId, bool encrypted = false, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId

User to chat with.
bool encrypted

Whether to turn on end-to-end encryption from the start.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

CreateEditContent(string, string, string?)

Build edit content replacing the text of eventId, optionally with a formatted html body.

Declaration
public static MessageContent CreateEditContent(string eventId, string newText, string? html = null)
Parameters
Type Name Description
string eventId
string newText
string html
Returns
Type Description
MessageContent
| Edit this page View Source

CreateFileContent(EncryptedFile, string, string, long?)

Build file message content for an encrypted upload, for encrypted rooms.

Declaration
public static MessageContent CreateFileContent(EncryptedFile file, string fileName, string contentType, long? size)
Parameters
Type Name Description
EncryptedFile file
string fileName
string contentType
long? size
Returns
Type Description
MessageContent
| Edit this page View Source

CreateFileContent(MxcUri, string, string, long?)

Build file message content for uploaded media, picking the message type from contentType.

Declaration
public static MessageContent CreateFileContent(MxcUri uri, string fileName, string contentType, long? size)
Parameters
Type Name Description
MxcUri uri
string fileName
string contentType
long? size
Returns
Type Description
MessageContent
| Edit this page View Source

CreateFilterAsync(Filter, CancellationToken)

Uploads filter and returns its ID for SyncAsync(string?, TimeSpan?, string?, bool, string?, CancellationToken).

Declaration
public Task<string> CreateFilterAsync(Filter filter, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Filter filter
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

CreateKeyBackupVersionAsync(string, JsonObject, CancellationToken)

Creates a key backup version, which becomes current; returns its version ID.

Declaration
public Task<string> CreateKeyBackupVersionAsync(string algorithm, JsonObject authData, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string algorithm
JsonObject authData
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

CreateMediaAsync(CancellationToken)

Reserve a content URI whose content is uploaded later with UploadMediaToAsync(MxcUri, Stream, string, string?, CancellationToken), e.g. to send a message before a large file is up; return it and when it expires.

Declaration
public Task<(MxcUri ContentUri, DateTimeOffset ExpiresAt)> CreateMediaAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<(MxcUri ContentUri, DateTimeOffset ExpiresAt)>
| Edit this page View Source

CreateReactionContent(string, string)

Build reaction content.

Declaration
public static ReactionContent CreateReactionContent(string eventId, string key)
Parameters
Type Name Description
string eventId
string key
Returns
Type Description
ReactionContent
| Edit this page View Source

CreateRegistrationTokenAsync(string?, int?, DateTimeOffset?, CancellationToken)

Create a registration token: token, or a random one; usable usesAllowed times, or any number, until expiry, or forever. For admins.

Declaration
public Task<AdminRegistrationToken> CreateRegistrationTokenAsync(string? token = null, int? usesAllowed = null, DateTimeOffset? expiry = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string token
int? usesAllowed
DateTimeOffset? expiry
CancellationToken cancellationToken
Returns
Type Description
Task<AdminRegistrationToken>
| Edit this page View Source

CreateReplyContent(ClientEvent, string, string?, IEnumerable<string>?, string?)

Build reply content that mentions the replied sender unless it is ownUserId.

Declaration
public static MessageContent CreateReplyContent(ClientEvent replyTo, string text, string? ownUserId, IEnumerable<string>? alsoMentioned = null, string? html = null)
Parameters
Type Name Description
ClientEvent replyTo

Event replied to.
string text

Reply text.
string ownUserId

Logged-in user, not mentioned when replying to self.
IEnumerable<string> alsoMentioned

Further users to mention, e.g. completed nicks.
string html

Formatted body in the allowed HTML subset; plain text only when null.
Returns
Type Description
MessageContent
| Edit this page View Source

CreateRoomAliasAsync(string, string, CancellationToken)

Creates an alias like #room:server for a room.

Declaration
public Task CreateRoomAliasAsync(string roomAlias, string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomAlias
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

CreateRoomAsync(CreateRoomRequest, CancellationToken)

Creates a room and returns its ID.

Declaration
public Task<string> CreateRoomAsync(CreateRoomRequest request, CancellationToken cancellationToken = default)
Parameters
Type Name Description
CreateRoomRequest request
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

DeactivateAccountAsync(string, CancellationToken)

Deactivates the account for good, confirming with password, and clears Session; the user ID cannot be registered again.

Declaration
public Task DeactivateAccountAsync(string password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string password
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeactivateUserAsync(string, CancellationToken)

Deactivate an account: it leaves its rooms and cannot log in again; for admins.

Declaration
public Task DeactivateUserAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeleteDevicesAsync(IReadOnlyList<string>, string?, CancellationToken)

Deletes devices, logging them out; the server asks for the password first.

Declaration
public Task DeleteDevicesAsync(IReadOnlyList<string> deviceIds, string? password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IReadOnlyList<string> deviceIds

Devices to delete.
string password

Password for the auth challenge; when null, UserInteractiveAuthException is thrown so the caller can ask for it.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

DeleteMediaAsync(string, string, CancellationToken)

Delete media of the server; for admins.

Declaration
public Task DeleteMediaAsync(string serverName, string mediaId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string serverName
string mediaId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeletePushRuleAsync(string, string, CancellationToken)

Delete one of the user's own push rules.

Declaration
public Task DeletePushRuleAsync(string kind, string ruleId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string kind
string ruleId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeleteRegistrationTokenAsync(string, CancellationToken)

Delete a registration token; for admins.

Declaration
public Task DeleteRegistrationTokenAsync(string token, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string token
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeleteReportAsync(long, CancellationToken)

Delete a report; for admins.

Declaration
public Task DeleteReportAsync(long reportId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
long reportId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeleteRoomAliasAsync(string, CancellationToken)

Deletes a room alias.

Declaration
public Task DeleteRoomAliasAsync(string roomAlias, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomAlias
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DeleteTagAsync(string, string, CancellationToken)

Removes tag from a room.

Declaration
public Task DeleteTagAsync(string roomId, string tag, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string tag
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DownloadMediaAsync(MxcUri, CancellationToken)

Download media via the authenticated media endpoint, streaming the body.

Declaration
public Task<MediaDownload> DownloadMediaAsync(MxcUri uri, CancellationToken cancellationToken = default)
Parameters
Type Name Description
MxcUri uri
CancellationToken cancellationToken
Returns
Type Description
Task<MediaDownload>
Examples
using MediaDownload media = await client.DownloadMediaAsync(MxcUri.Parse(message.Url!));
await using FileStream file = File.Create(media.FileName ?? "download");
await media.Content.CopyToAsync(file);
| Edit this page View Source

DownloadThumbnailAsync(MxcUri, int, int, bool, CancellationToken)

Download a server-made thumbnail of about width×height pixels; servers may return the original for small images.

Declaration
public Task<MediaDownload> DownloadThumbnailAsync(MxcUri uri, int width, int height, bool crop = false, CancellationToken cancellationToken = default)
Parameters
Type Name Description
MxcUri uri

Content URI of an image or video.
int width

Desired width in pixels.
int height

Desired height in pixels.
bool crop

Whether to crop to the exact size instead of scaling to fit.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<MediaDownload>
| Edit this page View Source

ForgetRoomAsync(string, CancellationToken)

Forgets a left room so it no longer appears in sync.

Declaration
public Task ForgetRoomAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

GetAccountDataAsync<T>(string, CancellationToken)

Return global account data of type; throw MatrixException with NotFound when unset.

Declaration
public Task<T> GetAccountDataAsync<T>(string type, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string type
CancellationToken cancellationToken
Returns
Type Description
Task<T>
Type Parameters
Name Description
T
| Edit this page View Source

GetAdminAccountAsync(string, CancellationToken)

Return a local account; for admins.

Declaration
public Task<AdminAccount> GetAdminAccountAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<AdminAccount>
| Edit this page View Source

GetAdminAccountsAsync(string?, bool, int, int, CancellationToken)

Return a page of local accounts, optionally matching name and including deactivated ones; for admins.

Declaration
public Task<AdminAccountsResponse> GetAdminAccountsAsync(string? name = null, bool includeDeactivated = false, int from = 0, int limit = 100, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string name
bool includeDeactivated
int from
int limit
CancellationToken cancellationToken
Returns
Type Description
Task<AdminAccountsResponse>
| Edit this page View Source

GetAdminRoomMembersAsync(string, CancellationToken)

Return the joined members of a room; for admins.

Declaration
public Task<IReadOnlyList<string>> GetAdminRoomMembersAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<string>>
| Edit this page View Source

GetAdminRoomsAsync(string?, int, int, CancellationToken)

Return a page of rooms, most members first, optionally matching searchTerm; for admins.

Declaration
public Task<AdminRoomsResponse> GetAdminRoomsAsync(string? searchTerm = null, int from = 0, int limit = 100, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string searchTerm
int from
int limit
CancellationToken cancellationToken
Returns
Type Description
Task<AdminRoomsResponse>
| Edit this page View Source

GetContextAsync(string, string, int?, string?, CancellationToken)

Return an event with the events around it and the state at it.

Declaration
public Task<ContextResponse> GetContextAsync(string roomId, string eventId, int? limit = null, string? filter = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string eventId

Event to center on.
int? limit

Maximum number of events before and after together; server default when null.
string filter

Inline RoomEventFilter JSON.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<ContextResponse>
| Edit this page View Source

GetDevicesAsync(CancellationToken)

List the user's devices.

Declaration
public Task<IReadOnlyList<Device>> GetDevicesAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<Device>>
| Edit this page View Source

GetDirectRoomsAsync(CancellationToken)

Return direct-message rooms keyed by the other user's ID.

Declaration
public Task<DirectContent> GetDirectRoomsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<DirectContent>
| Edit this page View Source

GetEventAsync(string, string, CancellationToken)

Return one event by ID.

Declaration
public Task<ClientEvent> GetEventAsync(string roomId, string eventId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventId
CancellationToken cancellationToken
Returns
Type Description
Task<ClientEvent>
| Edit this page View Source

GetIgnoredUsersAsync(CancellationToken)

Return ignored user IDs.

Declaration
public Task<IReadOnlyCollection<string>> GetIgnoredUsersAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyCollection<string>>
| Edit this page View Source

GetJoinedMembersAsync(string, CancellationToken)

Return joined members keyed by user ID.

Declaration
public Task<IReadOnlyDictionary<string, RoomMember>> GetJoinedMembersAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyDictionary<string, RoomMember>>
| Edit this page View Source

GetJoinedRoomsAsync(CancellationToken)

List joined room IDs.

Declaration
public Task<IReadOnlyList<string>> GetJoinedRoomsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<string>>
| Edit this page View Source

GetKeyBackupVersionAsync(CancellationToken)

Return the current key backup version, or null when there is none.

Declaration
public Task<KeyBackupVersion?> GetKeyBackupVersionAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<KeyBackupVersion>
| Edit this page View Source

GetLoginFlowsAsync(CancellationToken)

List login types the server accepts.

Declaration
public Task<LoginFlowsResponse> GetLoginFlowsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<LoginFlowsResponse>
| Edit this page View Source

GetMembersAsync(string, string?, CancellationToken)

Return member events of a room.

Declaration
public Task<IReadOnlyList<ClientEvent>> GetMembersAsync(string roomId, string? membership = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string membership

Only members with this membership, see Memberships; all when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<IReadOnlyList<ClientEvent>>
| Edit this page View Source

GetMessagesAsync(string, string?, Direction, int?, string?, string?, CancellationToken)

Return a page of room history.

Declaration
public Task<MessagesResponse> GetMessagesAsync(string roomId, string? from = null, Direction direction = Direction.Backward, int? limit = null, string? filter = null, string? to = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string from

Token to start from, e.g. PrevBatch or End; null starts from the newest event when going Backward.
Direction direction

Towards older or newer events.
int? limit

Maximum number of events; server default when null.
string filter

Inline RoomEventFilter JSON.
string to

Token to stop at.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<MessagesResponse>
| Edit this page View Source

GetPowerLevelsAsync(string, CancellationToken)

Return the room's power levels from the server; null when the room has none.

Declaration
public Task<PowerLevelsContent?> GetPowerLevelsAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<PowerLevelsContent>
| Edit this page View Source

GetPresenceAsync(string, CancellationToken)

Return the presence of userId.

Declaration
public Task<PresenceContent> GetPresenceAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<PresenceContent>
| Edit this page View Source

GetProfileAsync(string, CancellationToken)

Return the global profile of userId.

Declaration
public Task<ProfileResponse> GetProfileAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<ProfileResponse>
| Edit this page View Source

GetPublicRoomsAsync(string?, int?, string?, string?, CancellationToken)

Return a page of the public room directory, like IRC /list.

Declaration
public Task<PublicRoomsResponse> GetPublicRoomsAsync(string? server = null, int? limit = null, string? since = null, string? searchTerm = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string server

Server whose directory to list; this homeserver when null.
int? limit

Maximum number of rooms; server default when null.
string since

NextBatch of the previous page.
string searchTerm

Text to match in name, topic and alias; uses the filtered form when set.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<PublicRoomsResponse>
| Edit this page View Source

GetPushRulesAsync(CancellationToken)

Return the user's push rules as JSON by kind: override, content, room, sender and underride.

Declaration
public Task<JsonElement> GetPushRulesAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<JsonElement>
| Edit this page View Source

GetPushersAsync(CancellationToken)

Return the user's pushers as JSON: an array of pushers with their app, key and data.

Declaration
public Task<JsonElement> GetPushersAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<JsonElement>
| Edit this page View Source

GetRegistrationRequirementsAsync(CancellationToken)

Return what registering on the server needs: whether it is open at all, a registration token, and policies to accept; throw MatrixException when registration is disabled.

Declaration
public Task<RegistrationRequirements> GetRegistrationRequirementsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<RegistrationRequirements>
| Edit this page View Source

GetRegistrationTokensAsync(bool?, CancellationToken)

Return the registration tokens; with valid, only those that may or may not register now. For admins.

Declaration
public Task<IReadOnlyList<AdminRegistrationToken>> GetRegistrationTokensAsync(bool? valid = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
bool? valid
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<AdminRegistrationToken>>
| Edit this page View Source

GetReportsAsync(int, int, CancellationToken)

Return a page of reports, newest first; for admins.

Declaration
public Task<AdminReportsResponse> GetReportsAsync(int from = 0, int limit = 100, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int from
int limit
CancellationToken cancellationToken
Returns
Type Description
Task<AdminReportsResponse>
| Edit this page View Source

GetRoomAccountDataAsync<T>(string, string, CancellationToken)

Return room account data of type; throw MatrixException with NotFound when unset.

Declaration
public Task<T> GetRoomAccountDataAsync<T>(string roomId, string type, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string type
CancellationToken cancellationToken
Returns
Type Description
Task<T>
Type Parameters
Name Description
T
| Edit this page View Source

GetRoomAliasesAsync(string, CancellationToken)

Return the local aliases of a room.

Declaration
public Task<IReadOnlyList<string>> GetRoomAliasesAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<string>>
| Edit this page View Source

GetRoomKeysAsync(string, CancellationToken)

Downloads all session keys of backup version.

Declaration
public Task<KeysBackup> GetRoomKeysAsync(string version, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string version
CancellationToken cancellationToken
Returns
Type Description
Task<KeysBackup>
| Edit this page View Source

GetRtcTransportsAsync(CancellationToken)

Return the homeserver's MatrixRTC transports, preferred first; none when the server has none or does not know the endpoint.

Declaration
public Task<IReadOnlyList<RtcTransport>> GetRtcTransportsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<RtcTransport>>
| Edit this page View Source

GetStateAsync(string, CancellationToken)

Return all current state events of a room.

Declaration
public Task<IReadOnlyList<ClientEvent>> GetStateAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<IReadOnlyList<ClientEvent>>
| Edit this page View Source

GetStateEventAsync<T>(string, string, string, CancellationToken)

Return the content of one state event; throw MatrixException with NotFound when unset.

Declaration
public Task<T> GetStateEventAsync<T>(string roomId, string eventType, string stateKey = "", CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventType
string stateKey
CancellationToken cancellationToken
Returns
Type Description
Task<T>
Type Parameters
Name Description
T
Examples
TopicContent topic = await client.GetStateEventAsync<TopicContent>(roomId, EventTypes.RoomTopic);
| Edit this page View Source

GetTagsAsync(string, CancellationToken)

Return the tags of a room.

Declaration
public Task<TagContent> GetTagsAsync(string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
CancellationToken cancellationToken
Returns
Type Description
Task<TagContent>
| Edit this page View Source

GetTurnServerAsync(CancellationToken)

Return TURN credentials for calls; empty when the server has none.

Declaration
public Task<TurnServerResponse> GetTurnServerAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<TurnServerResponse>
| Edit this page View Source

GetUrlPreviewAsync(Uri, CancellationToken)

Return the server's preview of a web page as JSON: og:title, og:description, and og:image as an mxc:// URI with matrix:image:size; throws MatrixException when the server has previews off.

Declaration
public Task<JsonElement> GetUrlPreviewAsync(Uri url, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Uri url
CancellationToken cancellationToken
Returns
Type Description
Task<JsonElement>
| Edit this page View Source

GetVersionsAsync(CancellationToken)

List spec versions supported by the server.

Declaration
public Task<VersionsResponse> GetVersionsAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<VersionsResponse>
| Edit this page View Source

IgnoreUserAsync(string, CancellationToken)

Ignore userId; the server then hides their events and invite.

Declaration
public Task IgnoreUserAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

InterruptSync()

Abandon the long-poll of SyncLoopAsync(string?, string?, TimeSpan?, Action<Exception, TimeSpan>?, CancellationToken) that is under way and sync again at once, without waiting; e.g. after the network changed, as a request on the old network would only fail when it times out.

Declaration
public void InterruptSync()
| Edit this page View Source

InviteAsync(string, string, string?, CancellationToken)

Invites userId to a room.

Declaration
public Task InviteAsync(string roomId, string userId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string userId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

IsLockedAsync(string, CancellationToken)

Return whether an account is locked; for admins.

Declaration
public Task<bool> IsLockedAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<bool>
| Edit this page View Source

IsServerAdminAsync(CancellationToken)

Return whether the signed-in user is a server admin, by asking for an admin-only list; false on servers without Synapse's admin API.

Declaration
public Task<bool> IsServerAdminAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<bool>
| Edit this page View Source

IsSuspendedAsync(string, CancellationToken)

Return whether an account is suspended; for admins.

Declaration
public Task<bool> IsSuspendedAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<bool>
| Edit this page View Source

IsUsernameAvailableAsync(string, CancellationToken)

Return whether username can be registered; throw MatrixException for invalid names.

Declaration
public Task<bool> IsUsernameAvailableAsync(string username, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string username
CancellationToken cancellationToken
Returns
Type Description
Task<bool>
| Edit this page View Source

JoinRoomAsync(string, IEnumerable<string>?, string?, CancellationToken)

Joins a room by ID or alias, accepting an invite if there is one; returns the room ID.

Declaration
public Task<string> JoinRoomAsync(string roomIdOrAlias, IEnumerable<string>? via = null, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomIdOrAlias

Room ID like !abc:server or alias like #room:server.
IEnumerable<string> via

Servers to join through when this server is not in the room.
string reason

Reason shown in the membership event.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

KickAsync(string, string, string?, CancellationToken)

Kicks userId from a room.

Declaration
public Task KickAsync(string roomId, string userId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string userId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

LeaveRoomAsync(string, string?, CancellationToken)

Leaves a room or rejects an invite.

Declaration
public Task LeaveRoomAsync(string roomId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

LoginWithPasswordAsync(string, string, string?, CancellationToken)

Logs in with a password and stores the Session.

Declaration
public Task<LoginResponse> LoginWithPasswordAsync(string user, string password, string? deviceDisplayName = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string user

Localpart or full user ID.
string password

Password of the user.
string deviceDisplayName

Display name for the new device; server default when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<LoginResponse>
| Edit this page View Source

LogoutAllAsync(CancellationToken)

Logs out every device of the user, including this one, and clears Session.

Declaration
public Task LogoutAllAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

LogoutAsync(CancellationToken)

Invalidates the access token, deletes the device and clears Session.

Declaration
public Task LogoutAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

MarkDirectRoomAsync(string, string, CancellationToken)

Record roomId as a direct chat with userId in Direct, e.g. after joining an invite marked is_direct; nothing changes when it is recorded already.

Declaration
public Task MarkDirectRoomAsync(string userId, string roomId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId

The other person.
string roomId

Room of the chat.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

QueryKeysAsync(IEnumerable<string>, CancellationToken)

Queries all device keys of userIds.

Declaration
public Task<KeysQueryResponse> QueryKeysAsync(IEnumerable<string> userIds, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IEnumerable<string> userIds
CancellationToken cancellationToken
Returns
Type Description
Task<KeysQueryResponse>
| Edit this page View Source

ReactivateUserAsync(string, CancellationToken)

Reactivate a deactivated account, so it can log in again; for admins.

Declaration
public Task ReactivateUserAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

RedactAsync(string, string, string?, string?, CancellationToken)

Redacts an event and returns the redaction's event ID.

Declaration
public Task<string> RedactAsync(string roomId, string eventId, string? reason = null, string? transactionId = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventId
string reason
string transactionId
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

RegisterAsync(string, string, string?, string?, bool, bool, CancellationToken)

Registers an account and stores the Session; answers the stages of the first flow it can: the dummy stage of open registration, the token stage with registrationToken, and the terms stage when acceptTerms.

Declaration
public Task<RegisterResponse> RegisterAsync(string username, string password, string? registrationToken = null, string? deviceDisplayName = null, bool acceptTerms = false, bool inhibitLogin = false, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string username

Wanted localpart, e.g. alice.
string password

Password of the new account.
string registrationToken

Token from the server's admin, when registration needs one.
string deviceDisplayName

Display name of the new device.
bool acceptTerms

Whether the user accepted the policies of GetRegistrationRequirementsAsync(CancellationToken).
bool inhibitLogin

Whether to only create the account, without a device or Session, e.g. to log in afterwards the usual way.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<RegisterResponse>
Remarks

Throws UserInteractiveAuthException when the server wants a stage this method cannot answer, e.g. a captcha, a wrong token, or terms not accepted.

| Edit this page View Source

RenameDeviceAsync(string, string, CancellationToken)

Renames a device.

Declaration
public Task RenameDeviceAsync(string deviceId, string displayName, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string deviceId
string displayName
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ReportEventAsync(string, string, string?, CancellationToken)

Reports an event as objectionable to the admins of this user's server.

Declaration
public Task ReportEventAsync(string roomId, string eventId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ReportRoomAsync(string, string?, CancellationToken)

Reports a room as objectionable to the admins of this user's server.

Declaration
public Task ReportRoomAsync(string roomId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ReportUserAsync(string, string?, CancellationToken)

Reports a user as objectionable to the admins of this user's server.

Declaration
public Task ReportUserAsync(string userId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

RequestOpenIdTokenAsync(CancellationToken)

Return an OpenID token of the logged-in user, which another service, e.g. a LiveKit authorization service, verifies with the homeserver.

Declaration
public Task<OpenIdTokenResponse> RequestOpenIdTokenAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<OpenIdTokenResponse>
| Edit this page View Source

ResetPasswordAsync(string, string, bool, CancellationToken)

Set a new password for an account, logging out its devices unless logoutDevices is false; for admins.

Declaration
public Task ResetPasswordAsync(string userId, string newPassword, bool logoutDevices = true, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
string newPassword
bool logoutDevices
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ResolveRoomAliasAsync(string, CancellationToken)

Resolves an alias like #room:server to a room ID.

Declaration
public Task<RoomAliasResponse> ResolveRoomAliasAsync(string roomAlias, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomAlias
CancellationToken cancellationToken
Returns
Type Description
Task<RoomAliasResponse>
| Edit this page View Source

RetryTransientAsync<T>(Func<CancellationToken, Task<T>>, Action<Exception, TimeSpan>?, CancellationToken)

Run action until it succeeds, retrying transient failures (network errors, 5xx, rate limiting) with the backoff of SyncLoopAsync(string?, string?, TimeSpan?, Action<Exception, TimeSpan>?, CancellationToken); throw other errors.

Declaration
public Task<T> RetryTransientAsync<T>(Func<CancellationToken, Task<T>> action, Action<Exception, TimeSpan>? onRetry, CancellationToken cancellationToken)
Parameters
Type Name Description
Func<CancellationToken, Task<T>> action

The work, e.g. a first sync.
Action<Exception, TimeSpan> onRetry

Called with the error and wait time before each retry.
CancellationToken cancellationToken

Cancellation token; ends the retries.
Returns
Type Description
Task<T>
Type Parameters
Name Description
T
| Edit this page View Source

SearchUsersAsync(string, int?, CancellationToken)

Searches users by user ID or display name, e.g. for /whois or completion.

Declaration
public Task<UserDirectoryResponse> SearchUsersAsync(string searchTerm, int? limit = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string searchTerm

Text to match.
int? limit

Maximum number of results; server default when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<UserDirectoryResponse>
| Edit this page View Source

SendDelayedStateEventAsync(string, string, object, string, TimeSpan, CancellationToken)

Send a state event after delay, unless restarted, cancelled or sent first; return its delay ID. MatrixRTC sends an empty membership so, to leave a call when the device disappears.

Declaration
public Task<string> SendDelayedStateEventAsync(string roomId, string eventType, object content, string stateKey, TimeSpan delay, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventType
object content
string stateKey
TimeSpan delay
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendEditAsync(string, string, string, CancellationToken)

Send an edit replacing the text of eventId.

Declaration
public Task<string> SendEditAsync(string roomId, string eventId, string newText, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventId
string newText
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendEmoteAsync(string, string, CancellationToken)

Send a Emote message, like IRC /me.

Declaration
public Task<string> SendEmoteAsync(string roomId, string text, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string text
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendEventAsync(string, string, object, string?, CancellationToken)

Sends a room event and returns its event ID.

Declaration
public Task<string> SendEventAsync(string roomId, string eventType, object content, string? transactionId = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string eventType

Event type, see EventTypes.
object content

Event content; serialized with its runtime type.
string transactionId

Reuse when retrying the same send so the server deduplicates it; generated when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

SendFileAsync(string, Stream, string, string, string?, CancellationToken)

Upload content and send it to roomId as an image, video, audio or file message by contentType; return the event ID.

Declaration
public Task<string> SendFileAsync(string roomId, Stream content, string fileName, string contentType, string? transactionId = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
Stream content

File bytes.
string fileName

File name shown to others.
string contentType

MIME type, e.g. image/png.
string transactionId

Reuse when retrying the same send; generated when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

SendHtmlAsync(string, string, string, Mentions?, CancellationToken)

Send an HTML message with a plain-text fallback.

Declaration
public Task<string> SendHtmlAsync(string roomId, string text, string html, Mentions? mentions = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string text

Plain-text body for clients that do not render HTML.
string html

Body in the allowed HTML subset.
Mentions mentions

Users or room to notify; none when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

SendMessageAsync(string, MessageContent, string?, CancellationToken)

Send an RoomMessage and return its event ID.

Declaration
public Task<string> SendMessageAsync(string roomId, MessageContent content, string? transactionId = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
MessageContent content
string transactionId
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendNoticeAsync(string, string, CancellationToken)

Send a Notice message.

Declaration
public Task<string> SendNoticeAsync(string roomId, string text, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string text
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendReactionAsync(string, string, string, CancellationToken)

Send a reaction key, usually an emoji, to eventId.

Declaration
public Task<string> SendReactionAsync(string roomId, string eventId, string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventId
string key
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendReceiptAsync(string, string, string, CancellationToken)

Send a read receipt up to eventId.

Declaration
public Task SendReceiptAsync(string roomId, string eventId, string receiptType = "m.read", CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string eventId

Last read event.
string receiptType

Receipt type, see ReceiptTypes.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SendReplyAsync(string, ClientEvent, string, CancellationToken)

Send a reply to replyTo, mentioning its sender.

Declaration
public Task<string> SendReplyAsync(string roomId, ClientEvent replyTo, string text, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
ClientEvent replyTo
string text
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendServerNoticeAsync(string, string, CancellationToken)

Send a server notice to a local user; return the event ID. For admins.

Declaration
public Task<string> SendServerNoticeAsync(string userId, string text, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
string text
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendStateEventAsync(string, string, object, string, CancellationToken)

Sets a state event and returns its event ID.

Declaration
public Task<string> SendStateEventAsync(string roomId, string eventType, object content, string stateKey = "", CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventType
object content
string stateKey
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendTextAsync(string, string, CancellationToken)

Send a Text message.

Declaration
public Task<string> SendTextAsync(string roomId, string text, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string text
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SendToDeviceAsync(string, IReadOnlyDictionary<string, Dictionary<string, object>>, string?, CancellationToken)

Sends to-device messages, content by user ID then device ID.

Declaration
public Task SendToDeviceAsync(string eventType, IReadOnlyDictionary<string, Dictionary<string, object>> messages, string? transactionId = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string eventType

Event type, e.g. RoomEncrypted.
IReadOnlyDictionary<string, Dictionary<string, object>> messages

Content by user ID, then device ID or * for all devices.
string transactionId

Reuse when retrying the same send; generated when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetAccountDataAsync(string, object, CancellationToken)

Sets global account data of type.

Declaration
public Task SetAccountDataAsync(string type, object content, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string type
object content
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetAvatarUrlAsync(string, CancellationToken)

Sets the global avatar of the logged-in user to an mxc:// URI.

Declaration
public Task SetAvatarUrlAsync(string avatarUrl, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string avatarUrl
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetDisplayNameAsync(string, CancellationToken)

Sets the global display name of the logged-in user.

Declaration
public Task SetDisplayNameAsync(string displayName, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string displayName
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetLockedAsync(string, bool, CancellationToken)

Lock an account, so its sessions are refused until it is unlocked; or unlock it. For admins.

Declaration
public Task SetLockedAsync(string userId, bool locked, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
bool locked
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetPresenceAsync(string, string?, CancellationToken)

Sets the presence of the logged-in user, like IRC /away.

Declaration
public Task SetPresenceAsync(string presence, string? statusMessage = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string presence

Presence state, see PresenceStates.
string statusMessage

Status message; cleared when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetPushRuleActionsAsync(string, string, IReadOnlyList<object>, CancellationToken)

Replace the actions of a push rule, e.g. ["notify"].

Declaration
public Task SetPushRuleActionsAsync(string kind, string ruleId, IReadOnlyList<object> actions, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string kind
string ruleId
IReadOnlyList<object> actions
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetPushRuleAsync(string, string, object, string?, string?, CancellationToken)

Add or replace a push rule of the user.

Declaration
public Task SetPushRuleAsync(string kind, string ruleId, object rule, string? before = null, string? after = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string kind

Rule kind, e.g. room to change a room's notifications, with the room ID as ruleId.
string ruleId

Rule ID; a room ID for room rules, a user ID for sender rules.
object rule

The rule's actions, with conditions or pattern as its kind needs, e.g. new { actions = Array.Empty<object>() } to mute.
string before

Rule ID to place it before, or null.
string after

Rule ID to place it after, or null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetPushRuleEnabledAsync(string, string, bool, CancellationToken)

Enable or disable a push rule, including the server's default rules.

Declaration
public Task SetPushRuleEnabledAsync(string kind, string ruleId, bool enabled, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string kind
string ruleId
bool enabled
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetPusherAsync(object, CancellationToken)

Add, replace or delete a pusher: an object with pushkey, app_id and kind (null deletes), and when adding app_display_name, device_display_name, lang and data with the gateway url.

Declaration
public Task SetPusherAsync(object pusher, CancellationToken cancellationToken = default)
Parameters
Type Name Description
object pusher
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetReadMarkersAsync(string, string, string?, CancellationToken)

Set the fully read marker and optionally a read receipt.

Declaration
public Task SetReadMarkersAsync(string roomId, string fullyRead, string? read = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string fullyRead

Event up to which the user has read everything.
string read

Event for a public read receipt; none when null.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetReportResolvedAsync(long, bool, CancellationToken)

Mark a report resolved, or open it again; for admins of Uniform servers, as Synapse has no such call.

Declaration
public Task SetReportResolvedAsync(long reportId, bool resolved, CancellationToken cancellationToken = default)
Parameters
Type Name Description
long reportId
bool resolved
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetRoomAccountDataAsync(string, string, object, CancellationToken)

Sets room account data of type.

Declaration
public Task SetRoomAccountDataAsync(string roomId, string type, object content, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string type
object content
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetRoomAvatarAsync(string, MxcUri?, CancellationToken)

Set the room avatar to an uploaded image, or remove it with null, via SendStateEventAsync(string, string, object, string, CancellationToken).

Declaration
public Task<string> SetRoomAvatarAsync(string roomId, MxcUri? avatarUrl, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
MxcUri? avatarUrl

mxc:// URI of the image, e.g. from UploadMediaAsync(Stream, string, string?, CancellationToken); null removes the avatar.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

SetRoomDirectoryVisibilityAsync(string, bool, CancellationToken)

Lists or unlists a room in the public room directory.

Declaration
public Task SetRoomDirectoryVisibilityAsync(string roomId, bool listed, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
bool listed
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetRoomNameAsync(string, string, CancellationToken)

Set the room name via SendStateEventAsync(string, string, object, string, CancellationToken).

Declaration
public Task<string> SetRoomNameAsync(string roomId, string name, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string name
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SetRoomTopicAsync(string, string, CancellationToken)

Set the room topic via SendStateEventAsync(string, string, object, string, CancellationToken).

Declaration
public Task<string> SetRoomTopicAsync(string roomId, string topic, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string topic
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

SetServerAdminAsync(string, bool, CancellationToken)

Give or take server admin rights; for admins.

Declaration
public Task SetServerAdminAsync(string userId, bool admin, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
bool admin
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetSuspendedAsync(string, bool, CancellationToken)

Suspend an account, so it can read but not send, join or invite; or end the suspension. For admins.

Declaration
public Task SetSuspendedAsync(string userId, bool suspended, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
bool suspended
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

SetTagAsync(string, string, double?, CancellationToken)

Adds tag to a room, see RoomTags.

Declaration
public Task SetTagAsync(string roomId, string tag, double? order = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string tag

Tag name; custom tags use reverse-DNS names like u.work.
double? order

Position among rooms with the same tag, from 0 to 1.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetTypingAsync(string, bool, TimeSpan?, CancellationToken)

Set whether the user is typing in a room.

Declaration
public Task SetTypingAsync(string roomId, bool typing, TimeSpan? timeout = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
bool typing

Whether the user is typing.
TimeSpan? timeout

How long typing lasts unless renewed; used only when typing is true.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

SetUserPowerLevelAsync(string, string, long, CancellationToken)

Give userId level in the room, e.g. Moderator, keeping every other power level as it is.

Declaration
public Task<string> SetUserPowerLevelAsync(string roomId, string userId, long level, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId

Room ID.
string userId

User to change.
long level

New level; 0 is an ordinary member.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<string>
| Edit this page View Source

ShutdownRoomAsync(string, bool, string?, CancellationToken)

Shut a room down on the server: its local members leave, its aliases go, and with block no local user can join it again. For admins.

Declaration
public Task<AdminRoomShutdown> ShutdownRoomAsync(string roomId, bool block, string? message = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
bool block
string message
CancellationToken cancellationToken
Returns
Type Description
Task<AdminRoomShutdown>
| Edit this page View Source

SyncAsync(string?, TimeSpan?, string?, bool, string?, CancellationToken)

Syncs once; waits up to timeout for new events.

Declaration
public Task<SyncResponse> SyncAsync(string? since = null, TimeSpan? timeout = null, string? filter = null, bool fullState = false, string? setPresence = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string since

Previous NextBatch; null for an initial sync.
TimeSpan? timeout

Long-poll time; null returns immediately.
string filter

Filter ID from CreateFilterAsync(Filter, CancellationToken) or inline JSON from ToJson().
bool fullState

Whether to return all state instead of changes since since.
string setPresence

Presence to set while syncing, see PresenceStates.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<SyncResponse>
| Edit this page View Source

SyncLoopAsync(string?, string?, TimeSpan?, Action<Exception, TimeSpan>?, CancellationToken)

Sync repeatedly, yielding each response; retry transient failures and a locked account (UserLocked) with backoff, and throw on others such as UnknownToken.

Declaration
public IAsyncEnumerable<SyncResponse> SyncLoopAsync(string? since = null, string? filter = null, TimeSpan? timeout = null, Action<Exception, TimeSpan>? onRetry = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string since

Token to resume from; null for an initial sync.
string filter

Filter ID or inline JSON, see SyncAsync(string?, TimeSpan?, string?, bool, string?, CancellationToken).
TimeSpan? timeout

Long-poll time per request; 30 seconds when null.
Action<Exception, TimeSpan> onRetry

Called with the error and wait time before each retry, e.g. to show a connection warning.
CancellationToken cancellationToken

Cancellation token; ends the loop.
Returns
Type Description
IAsyncEnumerable<SyncResponse>
| Edit this page View Source

TryGetAccountDataAsync<T>(string, CancellationToken)

Return global account data of type, or null when unset.

Declaration
public Task<T?> TryGetAccountDataAsync<T>(string type, CancellationToken cancellationToken = default) where T : class
Parameters
Type Name Description
string type
CancellationToken cancellationToken
Returns
Type Description
Task<T>
Type Parameters
Name Description
T
| Edit this page View Source

TryGetStateEventAsync(string, string, string, CancellationToken)

Return raw content of one state event, or null when unset.

Declaration
public Task<JsonElement?> TryGetStateEventAsync(string roomId, string eventType, string stateKey = "", CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string eventType
string stateKey
CancellationToken cancellationToken
Returns
Type Description
Task<JsonElement?>
| Edit this page View Source

UnbanAsync(string, string, string?, CancellationToken)

Unbans userId.

Declaration
public Task UnbanAsync(string roomId, string userId, string? reason = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string userId
string reason
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

UnignoreUserAsync(string, CancellationToken)

Stop ignoring userId.

Declaration
public Task UnignoreUserAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

UpdateDelayedEventAsync(string, string, CancellationToken)

Restart, cancel or send a delayed event: action is restart, cancel or send.

Declaration
public Task UpdateDelayedEventAsync(string delayId, string action, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string delayId
string action
CancellationToken cancellationToken
Returns
Type Description
Task
Exceptions
Type Condition
MatrixException

With NotFound when the delayed event was sent or cancelled already.
| Edit this page View Source

UpdateRegistrationTokenAsync(string, int?, DateTimeOffset?, CancellationToken)

Change how many times a token may be used, null for any number, and when it expires, null for never; for admins.

Declaration
public Task<AdminRegistrationToken> UpdateRegistrationTokenAsync(string token, int? usesAllowed, DateTimeOffset? expiry, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string token
int? usesAllowed
DateTimeOffset? expiry
CancellationToken cancellationToken
Returns
Type Description
Task<AdminRegistrationToken>
| Edit this page View Source

UploadCrossSigningKeysAsync(JsonObject, JsonObject, JsonObject, string?, CancellationToken)

Uploads cross-signing public keys; the server may ask for the password, and refuses to replace keys without it.

Declaration
public Task UploadCrossSigningKeysAsync(JsonObject masterKey, JsonObject selfSigningKey, JsonObject userSigningKey, string? password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
JsonObject masterKey

Master key, signed by the device.
JsonObject selfSigningKey

Self-signing key, signed by the master key.
JsonObject userSigningKey

User-signing key, signed by the master key.
string password

Password for the auth challenge; when null, UserInteractiveAuthException is thrown so the caller can ask for it.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

UploadKeysAsync(JsonObject?, JsonObject?, JsonObject?, CancellationToken)

Uploads signed device keys, one-time keys and fallback keys; any may be null.

Declaration
public Task<KeysUploadResponse> UploadKeysAsync(JsonObject? deviceKeys, JsonObject? oneTimeKeys, JsonObject? fallbackKeys, CancellationToken cancellationToken = default)
Parameters
Type Name Description
JsonObject deviceKeys

Signed device keys, uploaded once per device.
JsonObject oneTimeKeys

Signed one-time keys by signed_curve25519:id.
JsonObject fallbackKeys

Signed fallback keys by signed_curve25519:id.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<KeysUploadResponse>
| Edit this page View Source

UploadMediaAsync(Stream, string, string?, CancellationToken)

Uploads media and returns its content URI for e.g. Url.

Declaration
public Task<MxcUri> UploadMediaAsync(Stream content, string contentType, string? fileName = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Stream content

Media bytes; buffered in memory when not seekable, as rate-limit retries resend it.
string contentType

MIME type, e.g. image/png.
string fileName

File name to store with the media.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<MxcUri>
| Edit this page View Source

UploadMediaToAsync(MxcUri, Stream, string, string?, CancellationToken)

Upload the content of a URI from CreateMediaAsync(CancellationToken); only once, by the user who created it.

Declaration
public Task UploadMediaToAsync(MxcUri contentUri, Stream content, string contentType, string? fileName = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
MxcUri contentUri

The reserved URI.
Stream content

Media bytes; buffered in memory when not seekable, as rate-limit retries resend it.
string contentType

MIME type, e.g. image/png.
string fileName

File name to store with the media.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task
| Edit this page View Source

UploadRoomKeysAsync(string, KeysBackup, CancellationToken)

Uploads session keys to backup version; the server keeps the better of old and new.

Declaration
public Task UploadRoomKeysAsync(string version, KeysBackup keys, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string version
KeysBackup keys
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

UploadSignaturesAsync(IReadOnlyDictionary<string, Dictionary<string, JsonObject>>, CancellationToken)

Uploads signatures of devices or master keys: user ID, then device ID or public key, then the signed object.

Declaration
public Task<JsonElement> UploadSignaturesAsync(IReadOnlyDictionary<string, Dictionary<string, JsonObject>> signatures, CancellationToken cancellationToken = default)
Parameters
Type Name Description
IReadOnlyDictionary<string, Dictionary<string, JsonObject>> signatures
CancellationToken cancellationToken
Returns
Type Description
Task<JsonElement>
| Edit this page View Source

WhoAmIAsync(CancellationToken)

Return the user and device that own the access token.

Declaration
public Task<WhoAmIResponse> WhoAmIAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<WhoAmIResponse>
| Edit this page View Source

WhoisAsync(string, CancellationToken)

Return a user's devices and connections with whois; servers allow it for admins, and for oneself.

Declaration
public Task<WhoisResponse> WhoisAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task<WhoisResponse>