MatrixSDK.Client.Request (matrix_sdk v0.2.0) View Source

Provides functions which return a struct containing the data necessary for each HTTP request.

Link to this section Summary

Types

base_url()

body()

headers()

method()

path()

t()

Functions

account_3pids(base_url, token)

Returns a %Request{} struct used to get a list of the third party identifiers the homeserver has associated with the user's account.

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

Returns a %Request{} struct used to add contact information to the user's account.

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

Returns a %Request{} struct used to bind contact information to the user's account through the specified identity server.

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

Returns a %Request{} struct used to delete contact information from the user's account.

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

Returns a %Request{} struct used to request a validation token when adding an email to a user's account.

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

Returns a %Request{} struct used to request a validation token when adding a phone number to a user's account.

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

Returns a %Request{} struct used to unbind contact information from the user's account without deleting it from the homeserver.

avatar_url(base_url, user_id)

Returns a %Request{} struct used to get the avatar url for a user.

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

Returns a %Request{} struct used to change the password for an account on the homeserver. This request needs to be authenticated with m.login.email.identity or m.login.msisdn.identity. For more info see 3PID API flows section on the MatrixSDK.Client module.

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

Returns a %Request{} struct used to create a new room.

create_room_alias(base_url, token, room_id, room_alias)

Returns a %Request{} struct used to create a new mapping from room alias to room ID.

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

Returns a %Request{} struct used to deactivate a user's account.

delete_room_alias(base_url, token, room_alias)

Returns a %Request{} struct used to remove a mapping of room alias to room ID.

display_name(base_url, user_id)

Returns a %Request{} struct used to get the display name for a user.

download(base_url, server_name, media_id, opts \\ %{})

Returns a %Request{} struct used to download content from the content repository.

forget_room(base_url, token, room_id)

Returns a %Request{} struct used to forget a room.

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

Returns a %Request{} struct used by a user to join a room.

joined_rooms(base_url, token)

Returns a %Request{} struct used to get a list of the user's current rooms.

leave_room(base_url, token, room_id)

Returns a %Request{} struct used to leave a room.

Returns a %Request{} struct used to get the homeserver's supported login types to authenticate users.

Returns a %Request{} struct used to authenticate the user and issues an access token they can use to authorize themself in subsequent requests.

logout(base_url, token)

Returns a %Request{} struct used to invalidate an existing access token, so that it can no longer be used for authorization.

logout_all(base_url, token)

Returns a %Request{} struct used to invalidate all existing access tokens, so that they can no longer be used for authorization.

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

Returns a %Request{} struct used to request validation tokens when authenticating for change_password/4.

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

Returns a %Request{} struct used to request validation tokens when authenticating for change_password/4.

public_rooms(base_url, opts \\ %{})

Returns a %Request{} struct used to list the public rooms on the server with basic filtering.

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

Returns a %Request{} struct used to list the public rooms on the server with more advanced filtering options.

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

Returns a %Request{} struct used to redact a room event.

register_guest(base_url, opts \\ %{})

Returns a %Request{} struct used to register a guest account on the homeserver and returns an access token which can be used to authenticate subsequent requests.

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

Returns a %Request{} struct used to register a user account on the homeserver.

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

Returns a %Request{} struct used to check 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.

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

Returns a %Request{} struct used to check 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.

resolve_room_alias(base_url, room_alias)

Returns a %Request{} struct used to resolve a room alias to a room ID.

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

Returns a %Request{} struct used to ban a user from a room.

room_event(base_url, token, room_id, event_id)

Returns a %Request{} struct used to get a single event based on room_id and event_id.

room_invite(base_url, token, room_id, user_id)

Returns a %Request{} struct used to invite a user to participate in a room.

room_joined_members(base_url, token, room_id)

Returns a %Request{} struct used to get a map of MXIDs to member info objects for members of the room.

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

Returns a %Request{} struct used to kick a user from a room.

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

Returns a %Request{} struct used to get the list of members for this room.

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

Returns a %Request{} struct used to get message and state events for a room. It uses pagination parameters to paginate history in the room.

room_state(base_url, token, room_id)

Returns a %Request{} struct used to get the state events for the current state of a room.

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

Returns a %Request{} struct used to look up the contents of a state event in a room.

room_unban(base_url, token, room_id, user_id)

Returns a %Request{} struct used to unban a user from a room.

room_visibility(base_url, room_id)

Returns a %Request{} struct used to get the visibility of a given room on the server's public room directory.

room_visibility(base_url, token, room_id, visibility)

Returns a %Request{} struct used to set the visibility of a given room in the server's public room directory.

send_room_event(base_url, token, room_event)

Returns a %Request{} struct used to send a room event to a room.

send_state_event(base_url, token, state_event)

Returns a %Request{} struct used to send a state event to a room.

server_capabilities(base_url, token)

Returns a %Request{} struct used to get information about the server's supported feature set and other relevant capabilities.

server_discovery(base_url)

Returns a %Request{} struct used to get discovery information about the domain.

set_avatar_url(base_url, token, user_id, avatar_url)

Returns a %Request{} struct used to set the avatar url for a user.

set_display_name(base_url, token, user_id, display_name)

Returns a %Request{} struct used to set the display name for a user.

set_room_read_markers(base_url, token, room_id, fully_read_event_id, receipt_read_event_id \\ nil)

Returns a %Request{} struct used to set the position of the read marker for a given room, and optionally to read receipt's location.

spec_versions(base_url)

Returns a %Request{} struct used to get the versions of the Matrix specification supported by the server.

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

Returns a %Request{} struct used to synchronises the client's state with the latest state on the server.

thumbnail(base_url, server_name, media_id, width, height, opts \\ %{})

Returns a %Request{} struct used to download thumbnail of content from the content repository.

upload(base_url, token, bytes, opts \\ %{})

Returns a %Request{} struct used to upload some content to the content repository.

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

Returns a %Request{} struct used to search for users.

user_profile(base_url, user_id)

Returns a %Request{} struct used to get the user profile for a given user id.

username_availability(base_url, username)

Returns a %Request{} struct used to check if a username is available and valid for the server.

whoami(base_url, token)

Returns a %Request{} struct used to get information about the owner of a given access token.

Link to this section Types

base_url()

Specs

base_url() :: binary()

body()

Specs

body() :: any()

headers()

Specs

headers() :: [{binary(), binary()}]

method()

Specs

method() :: :head | :get | :delete | :trace | :options | :post | :put | :patch

path()

Specs

path() :: binary()

t()

Specs

t() :: %MatrixSDK.Client.Request{
  base_url: base_url(),
  body: body(),
  headers: headers(),
  method: method(),
  path: path(),
  query_params: term()
}

Link to this section Functions

account_3pids(base_url, token)

Specs

account_3pids(base_url(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.account_3pids("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/account/3pid",
  query_params: []
}

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

Specs

account_add_3pid(base_url(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to add 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 by MatrixSDK.Client.Auth.

For more info see 3PID API flows section on the MatrixSDK.Client module.

Examples

iex> MatrixSDK.Client.Request.account_add_3pid("https://matrix.org", "token", "client_secret", "sid")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    sid: "sid"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/add",
  query_params: []
}

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

Specs

account_bind_3pid(base_url(), binary(), binary(), binary(), binary(), binary()) ::
  t()

Returns a %Request{} struct used to bind 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 on the MatrixSDK.Client module.

Examples

iex> MatrixSDK.Client.Request.account_bind_3pid("https://matrix.org", "token", "client_secret", "example.org", "abc123", "sid")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    sid: "sid",
    id_server: "example.org",
    id_access_token: "abc123"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/bind",
  query_params: []
}

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

Specs

account_delete_3pid(base_url(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to delete 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

iex> MatrixSDK.Client.Request.account_delete_3pid("https://matrix.org", "token", "email", "example@example.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    medium: "email",
    address: "example@example.org"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/delete",
  query_params: []
}

With optional id_server parameter:

iex> MatrixSDK.Client.Request.account_delete_3pid("https://matrix.org", "token", "email", "example@example.org", %{id_server: "example.org"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    medium: "email",
    address: "example@example.org",
    id_server: "example.org"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/delete",
  query_params: []
}

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

Specs

account_email_token(
  base_url(),
  binary(),
  binary(),
  binary(),
  pos_integer(),
  map()
) :: t()

Returns a %Request{} struct used to request a validation token when adding an email to a user's account.

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.account_email_token("https://matrix.org", "token", "client_secret", "example@example.org", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    email: "example@example.org",
    send_attempt: 1
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/email/requestToken",
  query_params: []
}

With optional parameter:

iex> opt = %{next_link: "test-site.url"}
iex> MatrixSDK.Client.Request.account_email_token("https://matrix.org", "token", "client_secret", "example@example.org", 1, opt)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    email: "example@example.org",
    next_link: "test-site.url",
    send_attempt: 1
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/email/requestToken",
  query_params: []
}

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

Specs

account_msisdn_token(
  base_url(),
  binary(),
  binary(),
  binary(),
  binary(),
  pos_integer(),
  map()
) :: t()

Returns a %Request{} struct used to request a validation token when adding a phone number to a user's account.

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.account_msisdn_token("https://matrix.org", "token", "client_secret", "GB", "07700900001", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    country: "GB",
    phone_number: "07700900001",
    send_attempt: 1
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/msisdn/requestToken",
  query_params: []
}

With optional parameter:

iex> opt = %{next_link: "test-site.url"}
iex> MatrixSDK.Client.Request.account_msisdn_token("https://matrix.org", "token", "client_secret", "GB", "07700900001", 1, opt)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "client_secret",
    country: "GB",
    phone_number: "07700900001",
    next_link: "test-site.url",
    send_attempt: 1
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/msisdn/requestToken",
  query_params: []
}

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

Specs

account_unbind_3pid(base_url(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to unbind 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

iex> MatrixSDK.Client.Request.account_unbind_3pid("https://matrix.org", "token", "email", "example@example.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    medium: "email",
    address: "example@example.org"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/unbind",
  query_params: []
}

With optional id_server parameter:

iex> MatrixSDK.Client.Request.account_unbind_3pid("https://matrix.org", "token", "email", "example@example.org", %{id_server: "example.org"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    medium: "email",
    address: "example@example.org",
    id_server: "example.org"
  },
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/3pid/unbind",
  query_params: []
}

avatar_url(base_url, user_id)

Specs

avatar_url(base_url(), binary()) :: t()

Returns a %Request{} struct used to get the avatar url for a user.

Args

Required:

base_url: the base URL for the homeserver.
user_id: the user ID.

Examples

iex> MatrixSDK.Client.Request.avatar_url("https://matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/profile/%40user%3Amatrix.org/avatar_url",
  query_params: []
}

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

Specs

change_password(base_url(), binary(), MatrixSDK.Client.Auth.t(), map()) :: t()

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

iex> auth = MatrixSDK.Client.Auth.login_email_identity("sid", "client_secret")
iex> MatrixSDK.Client.Request.change_password("https://matrix.org", "new_password", auth)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    auth: %{
      type: "m.login.email.identity",
      threepidCreds: [%{client_secret: "client_secret", sid: "sid"}]
    },
    new_password: "new_password"
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/account/password",
  query_params: []
}

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

Specs

create_room(base_url(), binary(), map()) :: t()

Returns a %Request{} struct used to create 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

iex> MatrixSDK.Client.Request.create_room("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/createRoom",
  query_params: []
}

With options:

iex> opts = %{
...>          visibility: "public",
...>          room_alias_name: "chocolate",
...>          topic: "Some cool stuff about chocolate."
...>        }
iex> MatrixSDK.Client.Request.create_room("https://matrix.org", "token", opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{room_alias_name: "chocolate", topic: "Some cool stuff about chocolate.", visibility: "public"},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/createRoom",
  query_params: []
}

create_room_alias(base_url, token, room_id, room_alias)

Specs

create_room_alias(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to create a new mapping from room alias to room 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 room ID.
room_alias: the room alias to set.

Examples

iex> MatrixSDK.Client.Request.create_room_alias("https://matrix.org", "token", "!someroom:matrix.org", "#monkeys:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{room_id: "!someroom:matrix.org"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org",
  query_params: []
}

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

Specs

deactivate_account(base_url(), binary(), map()) :: t()

Returns a %Request{} struct used to deactivate 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 by MatrixSDK.Client.Auth.

Examples

iex> MatrixSDK.Client.Request.deactivate_account("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/account/deactivate",
  query_params: []
}

delete_room_alias(base_url, token, room_alias)

Specs

delete_room_alias(base_url(), binary(), binary()) :: t()

Returns a %Request{} struct used to remove a mapping of room alias to room ID.

Args

Required:

base_url: the base URL for the homeserver.
token: access token, typically obtained via the login or registration processes.
room_alias: the room alias to set.

Examples

iex> MatrixSDK.Client.Request.delete_room_alias("https://matrix.org", "token", "#monkeys:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :delete,
  path: "/_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org",
  query_params: []
}

display_name(base_url, user_id)

Specs

display_name(base_url(), binary()) :: t()

Returns a %Request{} struct used to get the display name for a user.

Args

Required:

base_url: the base URL for the homeserver.
user_id: the user ID.

Examples

iex> MatrixSDK.Client.Request.display_name("https://matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/profile/%40user%3Amatrix.org/displayname",
  query_params: []
}

download(base_url, server_name, media_id, opts \\ %{})

Specs

download(base_url(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to download content from the content repository.

Args

Required:

base_url: the base URL for the homeserver.
server_name: the server name from the mxc:// URI of media (the authoritory component).
media_id: the media ID from the mxc:// URI of media (the path component).

Optional:

allow_remote(boolean): indicates to the server that it should not attempt to fetch the media if it is deemed remote.
filename(binary): a filename to give in the Content- Disposition header.

Examples

iex> MatrixSDK.Client.Request.download("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/download/some_server_name/AQwafuaFswefuhsfAFAgsw",
  query_params: []
}

With allow_remote option:

iex> MatrixSDK.Client.Request.download("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw", %{allow_remote: false})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/download/some_server_name/AQwafuaFswefuhsfAFAgsw",
  query_params: [allow_remote: false]
}

With filename option:

iex> MatrixSDK.Client.Request.download("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw", %{filename: "some_filename"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/download/some_server_name/AQwafuaFswefuhsfAFAgsw/some_filename",
  query_params: []
}

forget_room(base_url, token, room_id)

Specs

forget_room(base_url(), binary(), binary()) :: t()

Returns a %Request{} struct used to 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.

Examples

iex> MatrixSDK.Client.Request.forget_room("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/forget",
  query_params: []
}

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

Specs

join_room(base_url(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used by a user to 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

iex> MatrixSDK.Client.Request.join_room("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/join/%21someroom%3Amatrix.org",
  query_params: []
}

joined_rooms(base_url, token)

Specs

joined_rooms(base_url(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.joined_rooms("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/joined_rooms",
  query_params: []
}

leave_room(base_url, token, room_id)

Specs

leave_room(base_url(), binary(), binary()) :: t()

Returns a %Request{} struct used to 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.

Examples

iex> MatrixSDK.Client.Request.leave_room("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/leave",
  query_params: []
}

login(base_url)

Specs

login(base_url()) :: t()

Returns a %Request{} struct used to get the homeserver's supported login types to authenticate users.

Required:

base_url: the base URL for the homeserver.

iex> MatrixSDK.Client.Request.login("https://matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/login",
  query_params: []
}

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

Specs

login(base_url(), MatrixSDK.Client.Auth.t(), opts :: map()) :: t()

Returns a %Request{} struct used to authenticate the user and issues an access token they can use to authorize themself in subsequent requests.

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.

Token authentication:

iex> auth = MatrixSDK.Client.Auth.login_token("token")
iex> MatrixSDK.Client.Request.login("https://matrix.org", auth)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{token: "token", type: "m.login.token"},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/login",
  query_params: []
}

User and password authentication with optional parameters:

iex> auth = MatrixSDK.Client.Auth.login_user("maurice_moss", "password")
iex> opts = %{device_id: "id", initial_device_display_name: "THE INTERNET"}
iex> MatrixSDK.Client.Request.login("https://matrix.org", auth, opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    identifier: %{type: "m.id.user", user: "maurice_moss"},
    password: "password",
    type: "m.login.password",
    device_id: "id",
    initial_device_display_name: "THE INTERNET"
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/login",
  query_params: []
}

logout(base_url, token)

Specs

logout(base_url(), binary()) :: t()

Returns a %Request{} struct used to invalidate 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

iex> MatrixSDK.Client.Request.logout("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/logout",
  query_params: []
}

logout_all(base_url, token)

Specs

logout_all(base_url(), binary()) :: t()

Returns a %Request{} struct used to invalidate 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

iex> MatrixSDK.Client.Request.logout_all("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/logout/all",
  query_params: []
}

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

Specs

password_email_token(base_url(), binary(), binary(), pos_integer(), map()) ::
  t()

Returns a %Request{} struct used to request validation tokens when authenticating for change_password/4.

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.password_email_token("https://matrix.org", "secret", "maurice@moss.yay", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{client_secret: "secret", email: "maurice@moss.yay", send_attempt: 1},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/account/password/email/requestToken",
  query_params: []
}

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

Specs

password_msisdn_token(
  base_url(),
  binary(),
  binary(),
  binary(),
  pos_integer(),
  map()
) :: t()

Returns a %Request{} struct used to request validation tokens when authenticating for change_password/4.

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.password_msisdn_token("https://matrix.org", "secret", "GB", "07700900001", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{client_secret: "secret", country: "GB", phone_number: "07700900001", send_attempt: 1},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/account/password/msisdn/requestToken",
  query_params: []
}

public_rooms(base_url, opts \\ %{})

Specs

public_rooms(base_url(), map()) :: t()

Returns a %Request{} struct used to list 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

iex> MatrixSDK.Client.Request.public_rooms("https://matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/publicRooms",
  query_params: []
}

With optional parameters:

iex> MatrixSDK.Client.Request.public_rooms("https://matrix.org", %{limit: 10})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/publicRooms",
  query_params: [limit: 10]
}

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

Specs

public_rooms(base_url(), binary(), map(), binary() | nil) :: t()

Returns a %Request{} struct used to list 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

iex> MatrixSDK.Client.Request.public_rooms("https://matrix.org", "token", %{limit: 10})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{limit: 10},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/publicRooms",
  query_params: []
}

With optional parameter:

iex> MatrixSDK.Client.Request.public_rooms("https://matrix.org", "token", %{limit: 10}, "server")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{limit: 10},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/publicRooms",
  query_params: [server: "server"]
}

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

Specs

redact_room_event(base_url(), binary(), binary(), binary(), binary(), map()) ::
  t()

Returns a %Request{} struct used to redact a room event.

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.

Example

iex> MatrixSDK.Client.Request.redact_room_event("https://matrix.org", "token", "!someroom:matrix.org", "event_id", "transaction_id")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/redact/event_id/transaction_id",
  query_params: []
}

With options:

iex> opt = %{reason: "Indecent material"}
iex> MatrixSDK.Client.Request.redact_room_event("https://matrix.org", "token", "!someroom:matrix.org", "event_id", "transaction_id", opt)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{reason: "Indecent material"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/redact/event_id/transaction_id",
  query_params: []
}

register_guest(base_url, opts \\ %{})

Specs

register_guest(base_url(), map()) :: t()

Returns a %Request{} struct used to register 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

iex> MatrixSDK.Client.Request.register_guest("https://matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register?kind=guest",
  query_params: []
}

Specifiying a display name for the device:

iex> opts = %{initial_device_display_name: "THE INTERNET"}
iex> MatrixSDK.Client.Request.register_guest("https://matrix.org", opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{initial_device_display_name: "THE INTERNET"},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register?kind=guest",
  query_params: []
}

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

Specs

register_user(base_url(), binary(), MatrixSDK.Client.Auth.t(), map()) :: t()

Returns a %Request{} struct used to register 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

iex> auth = MatrixSDK.Client.Auth.login_dummy()
iex> MatrixSDK.Client.Request.register_user("https://matrix.org", "password", auth)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{auth: %{type: "m.login.dummy"}, password: "password"},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register",
  query_params: []
}

With optional parameters:

iex> auth = MatrixSDK.Client.Auth.login_dummy()
iex> opts = %{
...>          username: "maurice_moss",
...>          device_id: "id",
...>          initial_device_display_name: "THE INTERNET",
...>          inhibit_login: true
...>        }
iex> MatrixSDK.Client.Request.register_user("https://matrix.org", "password", auth, opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    auth: %{type: "m.login.dummy"},
    device_id: "id",
    inhibit_login: true,
    initial_device_display_name: "THE INTERNET",
    password: "password",
    username: "maurice_moss"
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register",
  query_params: []
}

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

Specs

registration_email_token(base_url(), binary(), binary(), pos_integer(), map()) ::
  t()

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.registration_email_token("https://matrix.org", "secret", "maurice@moss.yay", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{client_secret: "secret", email: "maurice@moss.yay", send_attempt: 1},
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register/email/requestToken",
  query_params: []
}

With optional parameters:

iex> opts = %{next_link: "nextlink.url"}
iex> MatrixSDK.Client.Request.registration_email_token("https://matrix.org", "secret", "maurice@moss.yay", 1, opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "secret",
    email: "maurice@moss.yay",
    send_attempt: 1,
    next_link: "nextlink.url"
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register/email/requestToken",
  query_params: []
}

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

Specs

registration_msisdn_token(
  base_url(),
  binary(),
  binary(),
  binary(),
  pos_integer(),
  map()
) :: t()

For more info see 3PID API flows section on the MatrixSDK.Client module.

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

iex> MatrixSDK.Client.Request.registration_msisdn_token("https://matrix.org", "secret", "GB", "07700900001", 1)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "secret",
    country: "GB",
    phone_number: "07700900001",
    send_attempt: 1
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register/msisdn/requestToken",
  query_params: []
}

With optional parameters:

iex> opts = %{next_link: "nextlink.url"}
iex> MatrixSDK.Client.Request.registration_msisdn_token("https://matrix.org", "secret", "GB", "07700900001", 1, opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{
    client_secret: "secret",
    country: "GB",
    phone_number: "07700900001",
    send_attempt: 1,
    next_link: "nextlink.url"
  },
  headers: [],
  method: :post,
  path: "/_matrix/client/r0/register/msisdn/requestToken",
  query_params: []
}

resolve_room_alias(base_url, room_alias)

Specs

resolve_room_alias(base_url(), binary()) :: t()

Returns a %Request{} struct used to resolve a room alias to a room ID.

Args

Required:

base_url: the base URL for the homeserver.
room_alias: the room alias to set.

Examples

iex> MatrixSDK.Client.Request.resolve_room_alias("https://matrix.org", "#monkeys:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org",
  query_params: []
}

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

Specs

room_ban(base_url(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to ban 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

iex> MatrixSDK.Client.Request.room_ban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/ban",
  body: %{user_id: "@user:matrix.org"},
  query_params: []
}

With optional parameter:

iex> MatrixSDK.Client.Request.room_ban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org", %{reason: "Ate all the chocolate"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/ban",
  body: %{user_id: "@user:matrix.org", reason: "Ate all the chocolate"},
  query_params: []
}

room_event(base_url, token, room_id, event_id)

Specs

room_event(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_event("https://matrix.org", "token", "!someroom:matrix.org", "$someevent")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/event/%24someevent",
  query_params: []
}

room_invite(base_url, token, room_id, user_id)

Specs

room_invite(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to invite a user to participate 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 ID.
user_id: the user ID to invite to the room.

Examples

iex> MatrixSDK.Client.Request.room_invite("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{user_id: "@user:matrix.org"},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/invite",
  query_params: []
}

room_joined_members(base_url, token, room_id)

Specs

room_joined_members(base_url(), binary(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_joined_members("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/joined_members",
  query_params: []
}

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

Specs

room_kick(base_url(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to kick 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

iex> MatrixSDK.Client.Request.room_kick("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/kick",
  body: %{user_id: "@user:matrix.org"},
  query_params: []
}

With optional parameter:

iex> MatrixSDK.Client.Request.room_kick("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org", %{reason: "Ate all the chocolate"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/kick",
  body: %{user_id: "@user:matrix.org", reason: "Ate all the chocolate"},
  query_params: []
}

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

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_members("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/members",
  query_params: []
}

With optional parameters:

iex> opts = %{
...>          at: "t123456789",
...>          membership: "join",
...>          not_membership: "invite"
...>        }
iex> MatrixSDK.Client.Request.room_members("https://matrix.org", "token", "!someroom:matrix.org", opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/members",
  query_params: [at: "t123456789", membership: "join", not_membership: "invite"]
}

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

Specs

room_messages(base_url(), binary(), binary(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_messages("https://matrix.org", "token", "!someroom:matrix.org", "t123456789", "f")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/messages",
  query_params: [dir: "f", from: "t123456789"]
}

With optional parameters:

iex> opts = %{
...>          to: "t123456789",
...>          limit: 10,
...>          filter: "filter"
...>        }
iex> MatrixSDK.Client.Request.room_messages("https://matrix.org", "token", "!someroom:matrix.org", "t123456789", "f", opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/messages",
  query_params: [dir: "f", filter: "filter", from: "t123456789", limit: 10, to: "t123456789"]
}

room_state(base_url, token, room_id)

Specs

room_state(base_url(), binary(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_state("https://matrix.org", "token", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/state",
  query_params: []
}

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

Specs

room_state_event(base_url(), binary(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to look 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

iex> MatrixSDK.Client.Request.room_state_event("https://matrix.org", "token", "!someroom:matrix.org", "m.room.member", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/state/m.room.member/%40user%3Amatrix.org",
  query_params: []
}

room_unban(base_url, token, room_id, user_id)

Specs

room_unban(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to unban 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

iex> MatrixSDK.Client.Request.room_unban("https://matrix.org", "token", "!someroom:matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/unban",
  body: %{user_id: "@user:matrix.org"},
  query_params: []
}

room_visibility(base_url, room_id)

Specs

room_visibility(base_url(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.room_visibility("https://matrix.org", "!someroom:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  method: :get,
  path: "/_matrix/client/r0/directory/list/room/%21someroom%3Amatrix.org",
  query_params: []
}

room_visibility(base_url, token, room_id, visibility)

Specs

room_visibility(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to set 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

iex> MatrixSDK.Client.Request.room_visibility("https://matrix.org", "token", "!someroom:matrix.org", "private")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{visibility: "private"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/directory/list/room/%21someroom%3Amatrix.org",
  query_params: []
}

send_room_event(base_url, token, room_event)

Specs

send_room_event(base_url(), binary(), MatrixSDK.Client.RoomEvent.t()) :: t()

Returns a %Request{} struct used to send 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

iex> room_event = MatrixSDK.Client.RoomEvent.message("!someroom:matrix.org", :text, "Fire! Fire! Fire!", "transaction_id")
iex> MatrixSDK.Client.Request.send_room_event("https://matrix.org", "token", room_event)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{body: "Fire! Fire! Fire!", msgtype: "m.text"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/send/m.room.message/transaction_id",
  query_params: []
}

send_state_event(base_url, token, state_event)

Specs

send_state_event(base_url(), binary(), MatrixSDK.Client.StateEvent.t()) :: t()

Returns a %Request{} struct used to send 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

iex> state_event = MatrixSDK.Client.StateEvent.join_rules("!someroom:matrix.org", "private")
iex> MatrixSDK.Client.Request.send_state_event("https://matrix.org", "token", state_event)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{join_rule: "private"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/state/m.room.join_rules/",
  query_params: []
}

server_capabilities(base_url, token)

Specs

server_capabilities(base_url(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.server_capabilities("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/capabilities",
  query_params: []
}

server_discovery(base_url)

Specs

server_discovery(base_url()) :: t()

Returns a %Request{} struct used to get discovery information about the domain.

Args

Required:

base_url: the base URL for the homeserver.

Examples

iex> MatrixSDK.Client.Request.server_discovery("https://matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/.well-known/matrix/client",
  query_params: []
}

set_avatar_url(base_url, token, user_id, avatar_url)

Specs

set_avatar_url(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to set 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

iex> MatrixSDK.Client.Request.set_avatar_url("https://matrix.org", "token", "@user:matrix.org", "mxc://matrix.org/wefh34uihSDRGhw34")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  method: :put,
  path: "/_matrix/client/r0/profile/%40user%3Amatrix.org/avatar_url",
  body: %{avatar_url: "mxc://matrix.org/wefh34uihSDRGhw34"},
  headers: [{"Authorization", "Bearer token"}],
  query_params: []
}

set_display_name(base_url, token, user_id, display_name)

Specs

set_display_name(base_url(), binary(), binary(), binary()) :: t()

Returns a %Request{} struct used to set 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

iex> MatrixSDK.Client.Request.set_display_name("https://matrix.org", "token", "@user:matrix.org", "mickey")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{displayname: "mickey"},
  headers: [{"Authorization", "Bearer token"}],
  method: :put,
  path: "/_matrix/client/r0/profile/%40user%3Amatrix.org/displayname",
  query_params: []
}

set_room_read_markers(base_url, token, room_id, fully_read_event_id, receipt_read_event_id \\ nil)

Specs

set_room_read_markers(base_url(), binary(), binary(), binary(), binary() | nil) ::
  t()

Returns a %Request{} struct used to set the position of the read marker for a given room, and optionally to read receipt's location.

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.
fully_read_event_id: the event ID the read marker should be located at.

Optional:

receipt_read_event_id: the event ID to set the read receipt location at.

Examples

iex> MatrixSDK.Client.Request.set_room_read_markers("https://matrix.org", "token", "!someroom:matrix.org", "$somewhere:example.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{"m.fully_read" => "$somewhere:example.org"},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/read_markers",
  query_params: []
}

With receipt_read_event_id option:

iex> MatrixSDK.Client.Request.set_room_read_markers("https://matrix.org", "token", "!someroom:matrix.org", "$somewhere:example.org", "$elsewhere:example.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{"m.fully_read" => "$somewhere:example.org", "m.read" => "$elsewhere:example.org"},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/rooms/%21someroom%3Amatrix.org/read_markers",
  query_params: []
}

spec_versions(base_url)

Specs

spec_versions(base_url()) :: t()

Returns a %Request{} struct used to get the versions of the Matrix specification supported by the server.

Args

Required:

base_url: the base URL for the homeserver.

Examples

iex> MatrixSDK.Client.Request.spec_versions("https://matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/versions",
  query_params: []
}

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

Specs

sync(base_url(), binary(), map()) :: t()

Returns a %Request{} struct used to 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

iex> MatrixSDK.Client.Request.sync("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/sync",
  query_params: []
}

With optional parameters:

iex> opts = %{
...>          since: "s123456789",
...>          filter: "filter",
...>          full_state: true,
...>          set_presence: "online",
...>          timeout: 1000
...>         }
iex> MatrixSDK.Client.Request.sync("https://matrix.org", "token", opts)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/sync",
  query_params: [
    {:filter, "filter"},
    {:full_state, true},
    {:set_presence, "online"},
    {:since, "s123456789"},
    {:timeout, 1000}
  ]
}

thumbnail(base_url, server_name, media_id, width, height, opts \\ %{})

Specs

thumbnail(base_url(), binary(), binary(), pos_integer(), pos_integer(), map()) ::
  t()

Returns a %Request{} struct used to download thumbnail of content from the content repository.

Args

Required:

base_url: the base URL for the homeserver.
server_name: the server name from the mxc:// URI of media (the authoritory component).
media_id: the media ID from the mxc:// URI of media (the path component).
width: the desired width of the thumbnail. The actual thumbnail may be larger than the size specified.
height: the desired height of the thumbnail. The actual thumbnail may be larger than the size specified.

Optional:

allow_remote(boolean): indicates to the server that it should not attempt to fetch the media if it is deemed remote.
method(binary): the desired resizing method. One of: ["crop", "scale"].

Examples

iex> MatrixSDK.Client.Request.thumbnail("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw", 100, 101)
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/thumbnail/some_server_name/AQwafuaFswefuhsfAFAgsw",
  query_params: [width: 100, height: 101]
}

With allow_remote option:

iex> MatrixSDK.Client.Request.thumbnail("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw", 100, 101, %{allow_remote: false})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/thumbnail/some_server_name/AQwafuaFswefuhsfAFAgsw",
  query_params: [width: 100, height: 101, allow_remote: false]
}

With method option:

iex> MatrixSDK.Client.Request.thumbnail("https://matrix.org", "some_server_name", "AQwafuaFswefuhsfAFAgsw", 100, 101, %{method: "crop"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/media/r0/thumbnail/some_server_name/AQwafuaFswefuhsfAFAgsw",
  query_params: [width: 100, height: 101, method: "crop"]
}

upload(base_url, token, bytes, opts \\ %{})

Specs

upload(base_url(), binary(), iodata(), map()) :: t()

Returns a %Request{} struct used to upload some content to the content repository.

Args

Required:

base_url: the base URL for the homeserver.
token: access token, typically obtained via the login or registration processes.
bytes: some content to be uploaded.

Optional:

filename(binary): the name of the file being uploaded.
content_type(binary): the content type of the file being uploaded.

Examples

iex> MatrixSDK.Client.Request.upload("https://matrix.org", "token", "some_content")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: "some_content",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/media/r0/upload",
  query_params: []
}

With filename option:

iex> MatrixSDK.Client.Request.upload("https://matrix.org", "token", "some_content", %{filename: "some_file.txt"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: "some_content",
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/media/r0/upload",
  query_params: [filename: "some_file.txt"]
}

With content_type option:

iex> MatrixSDK.Client.Request.upload("https://matrix.org", "token", "some_content", %{content_type: "text/plain"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: "some_content",
  headers: [{"Authorization", "Bearer token"}, {"Content-Type", "text/plain"}],
  method: :post,
  path: "/_matrix/media/r0/upload",
  query_params: []
}

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

Specs

user_directory_search(base_url(), binary(), binary(), map()) :: t()

Returns a %Request{} struct used to search for users.

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

iex> MatrixSDK.Client.Request.user_directory_search("https://matrix.org", "token", "mickey")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{search_term: "mickey"},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/user_directory/search",
  query_params: []
}

With limit option:

iex> MatrixSDK.Client.Request.user_directory_search("https://matrix.org", "token", "mickey", %{limit: 42})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{search_term: "mickey", limit: 42},
  headers: [{"Authorization", "Bearer token"}],
  method: :post,
  path: "/_matrix/client/r0/user_directory/search",
  query_params: []
}

With language option:

iex> MatrixSDK.Client.Request.user_directory_search("https://matrix.org", "token", "mickey", %{language: "en-US"})
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{search_term: "mickey"},
  headers: [{"Authorization", "Bearer token"}, {"Accept-Language", "en-US"}],
  method: :post,
  path: "/_matrix/client/r0/user_directory/search",
  query_params: []
}

user_profile(base_url, user_id)

Specs

user_profile(base_url(), binary()) :: t()

Returns a %Request{} struct used to get the user profile for a given user id.

Args

Required:

base_url: the base URL for the homeserver.
user_id: the user ID.

Examples

iex> MatrixSDK.Client.Request.user_profile("https://matrix.org", "@user:matrix.org")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/profile/%40user%3Amatrix.org",
  query_params: []
}

username_availability(base_url, username)

Specs

username_availability(base_url(), binary()) :: t()

Returns a %Request{} struct used to check 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

iex> MatrixSDK.Client.Request.username_availability("https://matrix.org", "maurice_moss")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [],
  method: :get,
  path: "/_matrix/client/r0/register/available?username=maurice_moss",
  query_params: []
}

whoami(base_url, token)

Specs

whoami(base_url(), binary()) :: t()

Returns a %Request{} struct used to get 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

iex> MatrixSDK.Client.Request.whoami("https://matrix.org", "token")
%MatrixSDK.Client.Request{
  base_url: "https://matrix.org",
  body: %{},
  headers: [{"Authorization", "Bearer token"}],
  method: :get,
  path: "/_matrix/client/r0/account/whoami",
  query_params: []
}