matrix_sdk v0.1.0 MatrixSDK.Client View Source
Provides functions to make HTTP requests to a Matrix homeserver using the
MatrixSDK.Client.Request
and MatrixSDK.HTTPClient
modules.
3PID API flows
See this gist for more details.
Flow 1—adding a 3PID to HS account during registration:
Flow 2—adding a 3PID to HS account after registration:
Flow 3—changing the bind status of a 3PID: this is currently unsupported but will be available once the identity server endpoints are wrapped.
Flow 4—reset password via email:
Link to this section Summary
Functions
Gets a list of the third party identifiers the homeserver has associated with the user's account.
Adds contact information to the user's account.
Binds contact information to the user's account through the specified identity server.
Deletes contact information from the user's account.
Requests a validation token when adding an email to a user's account.
Requests a validation token when adding a phone number to a user's account.
Unbinds contact information from the user's account without deleting it from the homeserver.
Retrieves the avatar url for a user.
Changes the password for an account on the homeserver. This request will need to be authenticated with m.login.email.identity
or m.login.msisdn.identity
. For more info see 3PID API flows section above.
Creates a new room.
Deactivates a user's account.
Retrieves the display name for a user.
Lets a user forget a room.
Lets a user join a room.
Gets a list of the user's current rooms.
Lets a user leave a room.
Gets the homeserver's supported login types to authenticate users.
Authenticates the user, and issues an access token they can use to authorize themself in subsequent requests.
Invalidates an existing access token, so that it can no longer be used for authorization.
Invalidates all existing access tokens, so that they can no longer be used for authorization.
Request validation tokens when authenticating for change_password/4
.
Request validation tokens when authenticating for change_password/4
.
Lists the public rooms on the server with basic filtering.
Lists the public rooms on the server with more advanced filtering options.
Redacts a room event with a reason.
Registers a guest account on the homeserver and returns an access token which can be used to authenticate subsequent requests.
Registers a user account on the homeserver.
Checks the given email address is not already associated with an account on the homeserver. This should be used to get a token to register an email as part of the initial user registration.
Checks the given phone number is not already associated with an account on the homeserver. This should be used to get a token to register a phone number as part of the initial user registration.
Bans a user from a room.
Gets a single event based on room_id
and event_id
.
Invites a user to participate in a particular room.
Gets a map of MXIDs to member info objects for members of the room.
Kicks a user from a room.
Gets the list of members for this room.
Gets message and state events for a room. It uses pagination parameters to paginate history in the room.
Gets the state events for the current state of a room.
Looks up the contents of a state event in a room.
Unbans a user from a room.
Gets the visibility of a given room on the server's public room directory.
Sets the visibility of a given room in the server's public room directory.
Sends a room event to a room.
Sends a state event to a room.
Gets information about the server's supported feature set and other relevant capabilities.
Gets discovery information about the domain.
Sets the avatar url for a user.
Sets the display name for a user.
Gets the versions of the Matrix specification supported by the server.
Synchronises the client's state with the latest state on the server.
Searches for users based on search term.
Retrieves the user profile for a user.
Checks if a username is available and valid for the server.
Gets information about the owner of a given access token.
Link to this section Functions
Specs
account_3pids(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Gets a list of the third party identifiers the homeserver has associated with the user's account.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Examples
MatrixSDK.Client.account_3pids("https://matrix.org", "token")
account_add_3pid(base_url, token, client_secret, sid, opts \\ %{})
View SourceSpecs
account_add_3pid( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Adds contact information to the user's account.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.client_secret
: the client secret used in the session with the homeserver.sid
: the session ID give by the homeserver.
Optional:
auth
: a map containing autentication data as defined byMatrixSDK.Client.Auth
.
For more info see 3PID API flows section above.
Examples
MatrixSDK.Client.account_add_3pid("https://matrix.org", "token", "client_secret", "sid")
account_bind_3pid(base_url, token, client_secret, id_server, id_access_token, sid)
View SourceSpecs
account_bind_3pid( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), binary(), binary() ) :: MatrixSDK.HTTPClient.result()
Binds contact information to the user's account through the specified identity server.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.client_secret
: the client secret used in the session with the identity server.id_server
: the identity server to use.id_access_token
: an access token previously registered with the identity server.sid
: the session ID given by the identity server.
For more info see 3PID API flows section above.
Examples
MatrixSDK.Client.account_bind_3pid("https://matrix.org", "token", "client_secret", "example.org", "abc123", "sid")
Specs
account_delete_3pid( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Deletes contact information from the user's account.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.medium
: the medium of the third party identifier being removed. One of:"email"
or"msisdn"
.address
: the third party address being removed.
Optional:
id_server
: the identity server to unbind from.
Examples
MatrixSDK.Client.account_delete_3pid("https://matrix.org", "token", "email", "example@example.org")
With id_server
option:
MatrixSDK.Client.account_delete_3pid("https://matrix.org", "token", "email", "example@example.org", %{id_server: "id.example.org")
account_email_token(base_url, token, client_secret, email, send_attempt, opts \\ %{})
View SourceSpecs
account_email_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Requests a validation token when adding an email to a user's account.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.email
: the email address.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.account_email_token("https://matrix.org", "token", "client_secret", "example@example.org", 1)
With optional parameter:
opt = %{next_link: "test-site.url"}
MatrixSDK.Client.account_email_token("https://matrix.org", "token", "client_secret", "example@example.org", 1, opts)
account_msisdn_token(base_url, token, client_secret, country, phone, send_attempt, opts \\ %{})
View SourceSpecs
account_msisdn_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Requests a validation token when adding a phone number to a user's account.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.country
: the two-letter uppercase ISO-3166-1 alpha-2 country code.phone
: the phone number.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.account_msisdn_token("https://matrix.org", "token", "client_secret", "GB", "07700900001", 1)
With optional paramter:
opt = %{next_link: "test-site.url"}
MatrixSDK.Client.account_msisdn_token("https://matrix.org", "token", "client_secret", "GB", "07700900001", 1, opt)
Specs
account_unbind_3pid( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Unbinds contact information from the user's account without deleting it from the homeserver.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.medium
: the medium of the third party identifier being removed. One of:"email"
or"msisdn"
.address
: the third party address being removed.
Optional:
id_server
: the identity server to unbind from.
Examples
MatrixSDK.Client.account_unbind_3pid("https://matrix.org", "token", "email", "example@example.org")
With id_server
option:
MatrixSDK.Client.account_unbind_3pid("https://matrix.org", "token", "email", "example@example.org", %{id_server: "id.example.org"})
Specs
avatar_url(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Retrieves the avatar url for a user.
Args
Required:
base_url
: the base URL for the homeserver.user_id
: the user ID.
Examples
MatrixSDK.Client.avatar_url("https://matrix.org", "@user:matrix.org")
Specs
change_password( MatrixSDK.Client.Request.base_url(), binary(), MatrixSDK.Client.Auth.t(), map() ) :: MatrixSDK.HTTPClient.result()
Changes the password for an account on the homeserver. This request will need to be authenticated with m.login.email.identity
or m.login.msisdn.identity
. For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.new_password
: the desired password for the account.auth
: a map containing autentication data as defined byMatrixSDK.Client.Auth
.
Optional:
logout_devices
:true
orfalse
, whether the user's other access tokens, and their associated devices, should be revoked if the request succeeds.
Examples
auth = MatrixSDK.Client.Auth.login_email_identity("sid", "client_secret")
MatrixSDK.Client.Request.change_password("https://matrix.org", "new_password", auth)
Specs
create_room(MatrixSDK.Client.Request.base_url(), binary(), map()) :: MatrixSDK.HTTPClient.result()
Creates a new room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Optional:
visibility
: controls the presence of the room on the room list. One of:"public"
or"private"
.room_alias_name
: the desired room alias local part.name
: if this is included, anm.room.name
event will be sent into the room to indicate the name of the room.topic
: if this is included, anm.room.topic
event will be sent into the room to indicate the topic for the room.invite
: a list of user IDs to invite to the room.invite_3pid
: a list of objects representing third party IDs to invite into the room.room_version
: the room version to set for the room.creation_content
: extra keys, such as m.federate, to be added to the content of them.room.create
event.initial_state
: a list of state events to set in the new room.preset
: convenience parameter for setting various default state events based on a preset.is_direct
: boolean flag.power_level_content_override
: the power level content to override in the default power level event.
Examples
MatrixSDK.Client.create_room("https://matrix.org", "token")
With options:
opts = %{
visibility: "public",
room_alias_name: "chocolate",
topic: "Some cool stuff about chocolate."
}
MatrixSDK.Client.create_room("https://matrix.org", "token", opts)
Specs
deactivate_account(MatrixSDK.Client.Request.base_url(), binary(), map()) :: MatrixSDK.HTTPClient.result()
Deactivates a user's account.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Optional:
auth
: a map containing autentication data as defined byMatrixSDK.Client.Auth
.
Examples
MatrixSDK.Client.deactivate_account("https://matrix.org", "token")
Specs
display_name(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Retrieves the display name for a user.
Args
Required:
base_url
: the base URL for the homeserver.user_id
: the user ID.
Examples
MatrixSDK.Client.display_name("https://matrix.org", "@user:matrix.org")
Specs
forget_room(MatrixSDK.Client.Request.base_url(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Lets a user forget a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.
Example
MatrixSDK.Client.forget_room("https://matrix.org", "token", "!someroom:matrix.org")
Specs
join_room(MatrixSDK.Client.Request.base_url(), binary(), binary(), map()) :: MatrixSDK.HTTPClient.result()
Lets a user join a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id_or_alias
: the room ID or room alias.
Optional:
third_party_signed
: a signature of anm.third_party_invite
token to prove that this user owns a third party identity which has been invited to the room.
Example
MatrixSDK.Client.join_room("https://matrix.org", "token", "!someroom:matrix.org")
Specs
joined_rooms(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Gets a list of the user's current rooms.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Example
MatrixSDK.Client.joined_rooms("https://matrix.org", "token")
Specs
leave_room(MatrixSDK.Client.Request.base_url(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Lets a user leave a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.
Example
MatrixSDK.Client.leave_room("https://matrix.org", "token", "!someroom:matrix.org")
Specs
login(MatrixSDK.Client.Request.base_url()) :: MatrixSDK.HTTPClient.result()
Gets the homeserver's supported login types to authenticate users.
Args
Required:
base_url
: the base URL for the homeserver.
Examples
MatrixSDK.Client.login("https://matrix.org")
Specs
login( MatrixSDK.Client.Request.base_url(), MatrixSDK.Client.Auth.t(), opts :: map() ) :: MatrixSDK.HTTPClient.result()
Authenticates the user, and issues an access token they can use to authorize themself in subsequent requests.
Args
Required:
base_url
: the base URL for the homeserver.auth
: a map containing autentication data as defined byMatrixSDK.Client.Auth
.
Optional:
device_id
: ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate adevice_id
if this is not specified.initial_device_display_name
: a display name to assign to the newly-created device.
Examples
Token authentication:
auth = MatrixSDK.Client.Auth.login_token("token")
MatrixSDK.Client.login("https://matrix.org", auth)
User and password authentication with optional parameters:
auth = MatrixSDK.Client.Auth.login_user("maurice_moss", "password")
opts = %{device_id: "id", initial_device_display_name: "THE INTERNET"}
MatrixSDK.Client.login("https://matrix.org", auth, opts)
Specs
logout(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Invalidates an existing access token, so that it can no longer be used for authorization.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Examples
MatrixSDK.Client.logout("https://matrix.org", "token")
Specs
logout_all(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Invalidates all existing access tokens, so that they can no longer be used for authorization.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Examples
MatrixSDK.Client.logout_all("https://matrix.org", "token")
password_email_token(base_url, client_secret, email, send_attempt, opts \\ %{})
View SourceSpecs
password_email_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Request validation tokens when authenticating for change_password/4
.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.email
: the email address.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.password_email_token("https://matrix.org", "secret", "maurice@moss.yay", 1)
password_msisdn_token(base_url, client_secret, country, phone, send_attempt, opts \\ %{})
View SourceSpecs
password_msisdn_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Request validation tokens when authenticating for change_password/4
.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.country
: the two-letter uppercase ISO-3166-1 alpha-2 country code.phone
: the phone number.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.password_msisdn_token("https://matrix.org", "secret", "GB", "07700900001", 1)
Specs
public_rooms(MatrixSDK.Client.Request.base_url(), map()) :: MatrixSDK.HTTPClient.result()
Lists the public rooms on the server with basic filtering.
Args
Required:
base_url
: the base URL for the homeserver.
Optional:
limit
: limit the number of results returned.since
: a pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms.server
: the server to fetch the public room lists from.
Examples
MatrixSDK.Client.public_rooms("https://matrix.org")
With optional parameters:
MatrixSDK.Client.public_rooms("https://matrix.org", %{limit: 10})
Specs
public_rooms(MatrixSDK.Client.Request.base_url(), binary(), map(), binary()) :: MatrixSDK.HTTPClient.result()
Lists the public rooms on the server with more advanced filtering options.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.- filters:
limit
: limit the number of results returned.since
: a pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms.filter
: a string to search for in the room metadata, e.g. name, topic, canonical alias, etc...include_all_networks
: boolean, whether or not to include all known networks/protocols from application services on the homeserver.third_party_instance_id
: the specific third party network/protocol to request from the homeserver. Can only be used ifinclude_all_networks
is false.
Optional:
server
: the server to fetch the public room lists from.
Examples
MatrixSDK.Client.public_rooms("https://matrix.org", "token", %{limit: 10})
With optional parameter:
MatrixSDK.Client.public_rooms("https://matrix.org", "token", %{limit: 10}, "server")
redact_room_event(base_url, token, room_id, event_id, transaction_id, opt \\ %{})
View SourceSpecs
redact_room_event( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Redacts a room event with a reason.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.event_id
: the event ID.transaction_id
: the transaction ID for this event. Clients should generate a unique ID; it will be used by the server to ensure idempotency of requests.
Optional:
reason
: the reason for the event being redacted.
Examples
MatrixSDK.Client.redact_room_event("https://matrix.org", "token", "!someroom@matrix.org", "event_id", "transaction_id")
With reason option:
opt = %{reason: "Indecent material"}
MatrixSDK.Client.redact_room_event("https://matrix.org", "token", "!someroom@matrix.org", "event_id", "transaction_id", opt)
Specs
register_guest(MatrixSDK.Client.Request.base_url(), map()) :: MatrixSDK.HTTPClient.result()
Registers a guest account on the homeserver and returns an access token which can be used to authenticate subsequent requests.
Args
Required:
base_url
: the base URL for the homeserver.
Optional:
initial_device_display_name
: a display name to assign to the newly-created device.
Examples
MatrixSDK.Client.register_guest("https://matrix.org")
Specifiying a display name for the device:
opts = %{initial_device_display_name: "THE INTERNET"}
MatrixSDK.Client.register_guest("https://matrix.org", opts)
Specs
register_user( MatrixSDK.Client.Request.base_url(), binary(), MatrixSDK.Client.Auth.t(), map() ) :: MatrixSDK.HTTPClient.result()
Registers a user account on the homeserver.
Args
Required:
base_url
: the base URL for the homeserver.password
: the desired password for the account.auth
: a map containing autentication data as defined byMatrixSDK.Client.Auth
. This is used to authenticate the registration request, not to define how a user will be authenticated.
Optional:
username
: the basis for the localpart of the desired Matrix ID. If omitted, the homeserver will generate a Matrix ID local part.device_id
: ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate adevice_id
if this is not specified.initial_device_display_name
: a display name to assign to the newly-created device.inhibit_login
: if true, anaccess_token
anddevice_id
will not be returned from this call, therefore preventing an automatic login.
Examples
MatrixSDK.Client.Request.register_user("https://matrix.org", "password", auth)
With optional parameters:
auth = MatrixSDK.Client.Auth.login_dummy()
opts = %{
username: "maurice_moss",
device_id: "id",
initial_device_display_name: "THE INTERNET",
inhibit_login: true
}
MatrixSDK.Client.Request.register_user("https://matrix.org", "password", auth, opts)
registration_email_token(base_url, client_secret, email, send_attempt, opts \\ %{})
View SourceSpecs
registration_email_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Checks the given email address is not already associated with an account on the homeserver. This should be used to get a token to register an email as part of the initial user registration.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.email
: the email address.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.registration_email_token("https://matrix.org", "secret", "maurice@moss.yay", 1)
registration_msisdn_token(base_url, client_secret, country, phone, send_attempt, opts \\ %{})
View SourceSpecs
registration_msisdn_token( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), pos_integer(), map() ) :: MatrixSDK.HTTPClient.result()
Checks the given phone number is not already associated with an account on the homeserver. This should be used to get a token to register a phone number as part of the initial user registration.
For more info see 3PID API flows section above.
Args
Required:
base_url
: the base URL for the homeserver.client_secret
: a unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters[0-9a-zA-Z.=_-]
. Its length must not exceed 255 characters and it must not be empty.country
: the two-letter uppercase ISO-3166-1 alpha-2 country code.phone
: the phone number.send_attempt
: stops the server from sending duplicate emails unless incremented by the client.
Optional:
next_link
: when the validation is completed, the identity server will redirect the user to this URL.
Examples
MatrixSDK.Client.registration_msisdn_token("https://matrix.org", "secret", "GB", "07700900001", 1)
Specs
room_ban( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Bans a user from a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.user_id
: the user ID to ban from the room.
Optional:
reason
: the reason the user has been banned.
Examples
MatrixSDK.Client.room_ban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
With option:
MatrixSDK.Client.room_ban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org", %{reason: "Ate all the chocolate"})
Specs
room_event(MatrixSDK.Client.Request.base_url(), binary(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Gets a single event based on room_id
and event_id
.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the ID of the room the event is in.event_id
: the event ID.
Example
MatrixSDK.Client.room_event("https://matrix.org", "token", "!someroom:matrix.org", "$someevent")
Specs
room_invite(MatrixSDK.Client.Request.base_url(), binary(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Invites a user to participate in a particular room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.user_id
: the user ID to invite to the room.
Example
MatrixSDK.Client.room_invite("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
Specs
room_joined_members(MatrixSDK.Client.Request.base_url(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Gets a map of MXIDs to member info objects for members of the room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.
Example
MatrixSDK.Client.room_joined_members("https://matrix.org", "token", "!someroom:matrix.org")
Specs
room_kick( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Kicks a user from a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.user_id
: the user ID to kick from the room.
Optional:
reason
: the reason the user has been kicked.
Examples
MatrixSDK.Client.room_kick("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
With option:
MatrixSDK.Client.room_kick("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org", %{reason: "Ate all the chocolate"})
Specs
room_members(MatrixSDK.Client.Request.base_url(), binary(), binary(), map()) :: MatrixSDK.HTTPClient.result()
Gets the list of members for this room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.
Optional:
at
: the point in time (pagination token) to return members for in the room.membership
: the kind of membership to filter for. Defaults to no filtering if unspecified.not_membership
: the kind of membership to exclude from the results. Defaults to no filtering if unspecified. One of:"join"
,"invite"
,"leave"
,"ban"
.
Examples
MatrixSDK.Client.room_members("https://matrix.org", "token", "!someroom:matrix.org")
With optional parameters:
opts = %{
at: "t123456789",
membership: "join",
not_membership: "invite"
}
MatrixSDK.Client.room_members("https://matrix.org", "token", "!someroom:matrix.org", opts)
Specs
room_messages( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Gets message and state events for a room. It uses pagination parameters to paginate history in the room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.from
: the pagination token to start returning events from.dir
: the direction to return events from. One of:"b"
or"f"
.
Optional:
to
: the pagination token to stop returning events at.limit
: the maximum number of events to return.filter
: a filter to apply to the returned events.
Examples
MatrixSDK.Client.room_messages("https://matrix.org", "token", "!someroom:matrix.org", "t123456789", "f")
With optional parameters:
opts = %{
to: "t123456789",
limit: 10,
filter: "filter"
}
MatrixSDK.Client.room_messages("https://matrix.org", "token", "!someroom:matrix.org", "t123456789", "f", opts)
Specs
room_state(MatrixSDK.Client.Request.base_url(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Gets the state events for the current state of a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room the events are in.
Example
MatrixSDK.Client.room_state("https://matrix.org", "token", "!someroom:matrix.org")
Specs
room_state_event( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary(), binary() ) :: MatrixSDK.HTTPClient.result()
Looks up the contents of a state event in a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room the state event is in.event_type
: the type of the state event.state_key
: the key of the state to look up. Often an empty string.
Example
MatrixSDK.Client.room_state_event("https://matrix.org", "token", "!someroom:matrix.org", "m.room.member", "@user:matrix.org")
Specs
room_unban(MatrixSDK.Client.Request.base_url(), binary(), binary(), binary()) :: MatrixSDK.HTTPClient.result()
Unbans a user from a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.user_id
: the user ID to unban from the room.
Examples
MatrixSDK.Client.room_unban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
Specs
room_visibility(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Gets the visibility of a given room on the server's public room directory.
Args
Required:
base_url
: the base URL for the homeserver.room_id
: the room ID.
Example
MatrixSDK.Client.room_visibility("https://matrix.org", "!someroom:matrix.org")
Specs
room_visibility( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary() ) :: MatrixSDK.HTTPClient.result()
Sets the visibility of a given room in the server's public room directory.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_id
: the room ID.visibility
: the new visibility setting for the room. One of:"private"
or"public"
.
Example
MatrixSDK.Client.room_visibility("https://matrix.org", "token", "!someroom:matrix.org", "private")
Specs
send_room_event( MatrixSDK.Client.Request.base_url(), binary(), MatrixSDK.Client.RoomEvent.t() ) :: MatrixSDK.HTTPClient.result()
Sends a room event to a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.room_event
: a state event as defined inMatrixSDK.Client.RoomEvent
.
Example
room_event = MatrixSDK.Client.RoomEvent.message("!someroom:matrix.org", :text, "Fire! Fire! Fire!", "transaction_id")
MatrixSDK.Client.Request.send_room_event("https://matrix.org", "token", room_event)
Specs
send_state_event( MatrixSDK.Client.Request.base_url(), binary(), MatrixSDK.Client.StateEvent.t() ) :: MatrixSDK.HTTPClient.result()
Sends a state event to a room.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.state_event
: a state event as defined inMatrixSDK.Client.StateEvent
.
Example
state_event = MatrixSDK.Client.StateEvent.join_rules("!someroom:matrix.org", "private")
MatrixSDK.Client.Request.send_state_event("https://matrix.org", "token", state_event)
Specs
server_capabilities(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Gets information about the server's supported feature set and other relevant capabilities.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Examples
MatrixSDK.Client.server_capabilities("https://matrix.org", "token")
Specs
server_discovery(MatrixSDK.Client.Request.base_url()) :: MatrixSDK.HTTPClient.result()
Gets discovery information about the domain.
Args
Required:
base_url
: the base URL for the homeserver.
Examples
MatrixSDK.Client.server_discovery("https://matrix.org")
Specs
set_avatar_url( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary() ) :: MatrixSDK.HTTPClient.result()
Sets the avatar url for a user.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.user_id
: the user ID.avatar_url
: the new avatar URL for this user.
Examples
MatrixSDK.Client.set_avatar_url("https://matrix.org", "token", "@user:matrix.org", "mxc://matrix.org/wefh34uihSDRGhw34")
Specs
set_display_name( MatrixSDK.Client.Request.base_url(), binary(), binary(), binary() ) :: MatrixSDK.HTTPClient.result()
Sets the display name for a user.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.user_id
: the user ID.display_name
: new display name.
Examples
MatrixSDK.Client.set_display_name("https://matrix.org", "token", "@user:matrix.org", "mickey")
Specs
spec_versions(MatrixSDK.Client.Request.base_url()) :: MatrixSDK.HTTPClient.result()
Gets the versions of the Matrix specification supported by the server.
Args
Required:
base_url
: the base URL for the homeserver.
Examples
MatrixSDK.Client.spec_versions("https://matrix.org")
Specs
sync(MatrixSDK.Client.Request.base_url(), binary(), map()) :: MatrixSDK.HTTPClient.result()
Synchronises the client's state with the latest state on the server.
Args
Required:
base_url
: the base URL for the homeserver.token
: the authentication token returned from user login.
Optional:
filter
: the ID of a filter created using the filter API or a filter JSON object encoded as a string.since
: a point in time to continue a sync from (usuall thenext_batch
value from last sync).full_state
: controls whether to include the full state for all rooms the user is a member of.set_presence
: controls whether the client is automatically marked as online by polling this API.timeout
: the maximum time to wait, in milliseconds, before returning this request.
Examples
MatrixSDK.Client.sync("https://matrix.org", "token")
With optional parameters:
opts = %{
since: "s123456789",
filter: "filter",
full_state: true,
set_presence: "online",
timeout: 1000
}
MatrixSDK.Client.sync("https://matrix.org", "token", opts)
Specs
user_directory_search( MatrixSDK.Client.Request.base_url(), binary(), binary(), map() ) :: MatrixSDK.HTTPClient.result()
Searches for users based on search term.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.search_term
: the term to search for.
Optional:
limit
: limit the number of returned results.language
: sets the language header for the request.
Examples
MatrixSDK.Client.user_directory_search("https://matrix.org", "token", "mickey")
With options:
MatrixSDK.Client.user_directory_search("https://matrix.org", "token", %{limit: 10, language: "en-US"})
Specs
user_profile(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Retrieves the user profile for a user.
Args
Required:
base_url
: the base URL for the homeserver.user_id
: the user ID.
Examples
MatrixSDK.Client.user_profile("https://matrix.org", "@user:matrix.org")
Specs
username_availability(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Checks if a username is available and valid for the server.
Args
Required:
base_url
: the base URL for the homeserver.username
: the basis for the localpart of the desired Matrix ID.
Examples
MatrixSDK.Client.username_availability("https://matrix.org", "maurice_moss")
Specs
whoami(MatrixSDK.Client.Request.base_url(), binary()) :: MatrixSDK.HTTPClient.result()
Gets information about the owner of a given access token.
Args
Required:
base_url
: the base URL for the homeserver.token
: access token, typically obtained via the login or registration processes.
Examples
MatrixSDK.Client.whoami("https://matrix.org", "token")