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:

  1. registration_email_token/5 or registration_msisdn_token/6
  2. register_user/4

Flow 2—adding a 3PID to HS account after registration:

  1. account_email_token/5 or account_msisdn_token/6
  2. account_add_3pid/5

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:

  1. password_email_token/5
  2. change_password/4

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.

Deactivates a user's account.

Retrieves the display name for a user.

Lets a user forget 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.

Lists the public rooms on the server with basic filtering.

Lists the public rooms on the server with more advanced filtering options.

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.

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.

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.

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.

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

Link to this function

account_3pids(base_url, token)

View Source

Specs

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")
Link to this function

account_add_3pid(base_url, token, client_secret, sid, opts \\ %{})

View Source

Specs

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:

For more info see 3PID API flows section above.

Examples

MatrixSDK.Client.account_add_3pid("https://matrix.org", "token", "client_secret", "sid")
Link to this function

account_bind_3pid(base_url, token, client_secret, id_server, id_access_token, sid)

View Source

Specs

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")
Link to this function

account_delete_3pid(base_url, token, medium, address, opt \\ %{})

View Source

Specs

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")
Link to this function

account_email_token(base_url, token, client_secret, email, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

account_msisdn_token(base_url, token, client_secret, country, phone, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

account_unbind_3pid(base_url, token, medium, address, opt \\ %{})

View Source

Specs

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"})
Link to this function

avatar_url(base_url, user_id)

View Source

Specs

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")
Link to this function

change_password(base_url, new_password, auth, opts \\ %{})

View Source

Specs

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 by MatrixSDK.Client.Auth.

Optional:

  • logout_devices: true or false, 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)
Link to this function

create_room(base_url, token, opts \\ %{})

View Source

Specs

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, an m.room.name event will be sent into the room to indicate the name of the room.
  • topic: if this is included, an m.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 the m.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)
Link to this function

deactivate_account(base_url, token, opts \\ %{})

View Source

Specs

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:

Examples

MatrixSDK.Client.deactivate_account("https://matrix.org", "token")
Link to this function

display_name(base_url, user_id)

View Source

Specs

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")
Link to this function

forget_room(base_url, token, room_id)

View Source

Specs

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")
Link to this function

join_room(base_url, token, room_id_or_alias, opts \\ %{})

View Source

Specs

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 an m.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")
Link to this function

joined_rooms(base_url, token)

View Source

Specs

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")
Link to this function

leave_room(base_url, token, room_id)

View Source

Specs

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

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")
Link to this function

login(base_url, auth, opts \\ %{})

View Source

Specs

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 by MatrixSDK.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 a device_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

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")
Link to this function

logout_all(base_url, token)

View Source

Specs

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")
Link to this function

password_email_token(base_url, client_secret, email, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

password_msisdn_token(base_url, client_secret, country, phone, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

public_rooms(base_url, opts \\ %{})

View Source

Specs

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})
Link to this function

public_rooms(base_url, token, filter, server \\ nil)

View Source

Specs

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 if include_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")
Link to this function

redact_room_event(base_url, token, room_id, event_id, transaction_id, opt \\ %{})

View Source

Specs

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)
Link to this function

register_guest(base_url, opts \\ %{})

View Source

Specs

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)
Link to this function

register_user(base_url, password, auth, opts \\ %{})

View Source

Specs

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 by MatrixSDK.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 a device_id if this is not specified.
  • initial_device_display_name: a display name to assign to the newly-created device.
  • inhibit_login: if true, an access_token and device_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)
Link to this function

registration_email_token(base_url, client_secret, email, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

registration_msisdn_token(base_url, client_secret, country, phone, send_attempt, opts \\ %{})

View Source

Specs

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)
Link to this function

room_ban(base_url, token, room_id, user_id, opt \\ %{})

View Source

Specs

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"})
Link to this function

room_event(base_url, token, room_id, event_id)

View Source

Specs

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")
Link to this function

room_invite(base_url, token, room_id, user_id)

View Source

Specs

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")
Link to this function

room_joined_members(base_url, token, room_id)

View Source

Specs

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")
Link to this function

room_kick(base_url, token, room_id, user_id, opt \\ %{})

View Source

Specs

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"})
Link to this function

room_members(base_url, token, room_id, opts \\ %{})

View Source

Specs

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)
Link to this function

room_messages(base_url, token, room_id, from, dir, opts \\ %{})

View Source

Specs

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)
Link to this function

room_state(base_url, token, room_id)

View Source

Specs

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")
Link to this function

room_state_event(base_url, token, room_id, event_type, state_key)

View Source

Specs

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") 
Link to this function

room_unban(base_url, token, room_id, user_id)

View Source

Specs

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")
Link to this function

room_visibility(base_url, room_id)

View Source

Specs

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")
Link to this function

room_visibility(base_url, token, room_id, visibility)

View Source

Specs

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")
Link to this function

send_room_event(base_url, token, room_event)

View Source

Specs

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 in MatrixSDK.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)
Link to this function

send_state_event(base_url, token, state_event)

View Source

Specs

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 in MatrixSDK.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)
Link to this function

server_capabilities(base_url, token)

View Source

Specs

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")
Link to this function

server_discovery(base_url)

View Source

Specs

Gets discovery information about the domain.

Args

Required:

  • base_url: the base URL for the homeserver.

Examples

MatrixSDK.Client.server_discovery("https://matrix.org")
Link to this function

set_avatar_url(base_url, token, user_id, avatar_url)

View Source

Specs

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")
Link to this function

set_display_name(base_url, token, user_id, display_name)

View Source

Specs

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

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")
Link to this function

sync(base_url, token, opts \\ %{})

View Source

Specs

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 the next_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)
Link to this function

user_directory_search(base_url, token, search_term, opts \\ %{})

View Source

Specs

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"})
Link to this function

user_profile(base_url, user_id)

View Source

Specs

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")
Link to this function

username_availability(base_url, username)

View Source

Specs

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

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