Module: MatrixSdk::Protocols::CS

Defined in:
lib/matrix_sdk/protocols/cs.rb

Overview

rubocop:disable Metrics/ModuleLength

Instance Method Summary collapse

Instance Method Details

#add_user_tag(user_id, room_id, tag, **params) ⇒ Object 



1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1316

def add_user_tag(user_id, room_id, tag, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  if params[:body]
    content = params[:body]
  else
    content = {}
    content[:order] = params[:order] if params.key? :order
  end

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s
  tag = ERB::Util.url_encode tag.to_s

  request(:put, client_api_latest, "/user/#{user_id}/rooms/#{room_id}/tags/#{tag}", body: content, query: query)
end

#allowed_login_methods ⇒ Response

Gets the list of available methods for logging in

Returns:



56
57
58
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 56

def 
  request(:get, client_api_latest, '/login')
end

#ban_user(room_id, user_id, reason: '', **params) ⇒ Object 



1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1235

def ban_user(room_id, user_id, reason: '', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id,
    reason: reason
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/ban", body: content, query: query)
end

#bind_3pid(secret:, id_server:, id_server_token:, session:) ⇒ Response

Finishes binding a 3PID to the current user

Parameters:

  • secret (String) —

    The shared secret with the identity server

  • id_server (String) —

    The identity server being acted against

  • id_server_token (String) —

    A previous identity server token

  • session (String) —

    The session ID to finish the bind for

Returns:

See Also:



345
346
347
348
349
350
351
352
353
354
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 345

def bind_3pid(secret:, id_server:, id_server_token:, session:)
  body = {
    client_secret: secret,
    id_server: id_server,
    id_server_token: id_server_token,
    sid: session
  }

  request(:post, client_api_latest, '/account/3pid/bind', body: body)
end

#change_password(new_password, auth:, **params) ⇒ Response

Changes the users password

Parameters:

  • new_password (String) —

    The new password

  • auth (Hash) —

    An auth object returned from an interactive auth query

Returns:

  • (Response) —

    An empty response if the password change was successful

See Also:



239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 239

def change_password(new_password, auth:, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  # raise Error unless auth.is_a?(Hash) && auth.key? :type

  body = {
    new_password: new_password,
    auth: auth
  }

  request(:post, client_api_latest, '/account/password', body: body, query: query)
end

#claim_one_time_keys(one_time_keys, timeout: 10) ⇒ Response

Claim one-time keys for pre-key messaging

Parameters:

  • one_time_keys (Hash) —

    Hash mapping user IDs to hashes of device IDs and key types

  • timeout (Numeric) (defaults to: 10) —

    (10) The timeout - in seconds - for the request

Returns:

  • (Response) —

    A response hash containing one-time keys for the requested users and devices

See Also:



1785
1786
1787
1788
1789
1790
1791
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1785

def claim_one_time_keys(one_time_keys, timeout: 10)
  body = {
    one_time_keys: one_time_keys,
    timeout: timeout * 1000
  }
  request(:post, client_api_latest, '/keys/claim', body: body)
end

#client_api_latest ⇒ Symbol

Gets the latest version of the client API

Returns:

  • (Symbol) —

    :client_r0 / :client_v3 / etc



46
47
48
49
50
51
52
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 46

def client_api_latest
  @client_api_latest ||= :client_v3 if client_api_versions.any? { |v| v.start_with? 'v1.1' }
  @client_api_latest ||= :client_r0
rescue StandardError => e
  logger.warn "Failed to look up supported client API, defaulting to r0. The error was #{e.class}: #{e}"
  @client_api_latest ||= :client_r0
end

#client_api_unstable_features ⇒ Hash

Gets the list of available unstable client API features

Examples:

Checking for unstable features

api.client_api_unstable_features
# => { :"m.lazy_load_members" => true }
api.client_api_unstable_features.has? 'm.lazy_load_members'
# => true

Returns:

  • (Hash) 


33
34
35
36
37
38
39
40
41
42
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 33

def client_api_unstable_features
  (@client_api_versions ||= request(:get, :client, '/versions')).unstable_features.tap do |vers|
    vers.instance_eval <<-'CODE', __FILE__, __LINE__ + 1
      def has?(feature)
        feature = feature.to_s.to_sym unless feature.is_a? Symbol
        fetch(feature, nil)
      end
    CODE
  end
end

#client_api_versions ⇒ Array

Gets the available client API versions

Examples:

Getting API versions

api.client_api_versions
# => [ 'r0.1.0', 'r0.2.0', ...
api.client_api_versions.latest
# => 'latest'

Returns:

  • (Array) 


13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 13

def client_api_versions
  (@client_api_versions ||= request(:get, :client, '/versions')).versions.tap do |vers|
    vers.instance_eval <<-'CODE', __FILE__, __LINE__ + 1
      if !respond_to? :latest
        def latest
          last
        end
      end
    CODE
  end
end

#complete_3pid_add(secret:, session:, auth_data: nil) ⇒ Response

Finishes a 3PID addition to the current user

Parameters:

  • secret (String) —

    The shared secret with the HS

  • session (String) —

    The session ID to finish the request for

  • auth_data (Hash) (defaults to: nil) —

    Interactive authentication data to verify the request

Returns:

See Also:



326
327
328
329
330
331
332
333
334
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 326

def complete_3pid_add(secret:, session:, auth_data: nil)
  body = {
    sid: session,
    client_secret: secret,
    auth: auth_data
  }.compact

  request(:post, client_api_latest, '/account/3pid/add', body: body)
end

#create_filter(user_id, filter_params, **params) ⇒ Object

Creates a filter for future use

Parameters:

  • user_id (String, MXID) —

    The user to create the filter for

  • filter_params (Hash) —

    The filter to create



1402
1403
1404
1405
1406
1407
1408
1409
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1402

def create_filter(user_id, filter_params, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:post, client_api_latest, "/user/#{user_id}/filter", body: filter_params, query: query)
end

#create_room(visibility: :public, **params) ⇒ Response

Creates a new room

Parameters:

  • params (Hash) —

    The room creation details

Options Hash (**params):

  • :visibility (Symbol) — default: :public —

    The room visibility

  • :room_alias (String) —

    A room alias to apply on creation

  • :invite (Boolean) —

    Should the room be created invite-only

Returns:

  • (Response) —

    A response hash with …

See Also:



444
445
446
447
448
449
450
451
452
453
454
455
456
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 444

def create_room(visibility: :public, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    visibility: visibility
  }
  content[:room_alias_name] = params.delete(:room_alias) if params[:room_alias]
  content[:invite] = [params.delete(:invite)].flatten if params[:invite]
  content.merge! params

  request(:post, client_api_latest, '/createRoom', body: content, query: query)
end

#deactivate_account(auth_data, id_server: nil) ⇒ Response

Deactivates the current account, logging out all connected devices and preventing future logins

Parameters:

  • auth_data (Hash) —

    Interactive authentication data to verify the request

  • id_server (String) (defaults to: nil) —

    Override the ID server to unbind all 3PIDs from

Returns:

See Also:



302
303
304
305
306
307
308
309
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 302

def (auth_data, id_server: nil)
  body = {
    auth: auth_data,
    id_server: id_server
  }.compact

  request(:post, client_api_latest, '/account/deactivate', body: body)
end

#delete_3pid(medium, address, id_server:) ⇒ Response

Deletes a 3PID from the current user, this method might not unbind it from the identity server

Parameters:

  • medium (:email, :msisdn) —

    The medium of 3PID being removed

  • address (String) —

    The address that is to be removed

  • id_server (String) —

    The identity server being acted against

Returns:

See Also:



364
365
366
367
368
369
370
371
372
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 364

def delete_3pid(medium, address, id_server:)
  body = {
    address: address,
    id_server: id_server,
    medium: medium
  }

  request(:post, client_api_latest, '/account/3pid/delete', body: body)
end

#delete_device(device_id, auth:) ⇒ Object

Removes a device from the current user

Parameters:

  • device_id (String) —

    The device to remove

  • auth (Hash) —

    Authentication data for the removal request

Raises:

  • (MatrixNotAuthorizeedError) —

    The request did not contain enough authentication information, the data in this error will include the necessary information to perform interactive auth

See Also:



1747
1748
1749
1750
1751
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1747

def delete_device(device_id, auth:)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:delete, client_api_latest, "/devices/#{device_id}", body: { auth: auth })
end

#forget_room(room_id, **params) ⇒ Object 



1159
1160
1161
1162
1163
1164
1165
1166
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1159

def forget_room(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/forget", query: query)
end

#get_3pids(**params) ⇒ Object 



311
312
313
314
315
316
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 311

def get_3pids(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, client_api_latest, '/account/3pid', query: query)
end

#get_account_data(user_id, type_key, **params) ⇒ Object 



1334
1335
1336
1337
1338
1339
1340
1341
1342
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1334

def (user_id, type_key, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:get, client_api_latest, "/user/#{user_id}/account_data/#{type_key}", query: query)
end

#get_avatar_url(user_id, **params) ⇒ Object 



1440
1441
1442
1443
1444
1445
1446
1447
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1440

def get_avatar_url(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/profile/#{user_id}/avatar_url", query: query)
end

#get_device(device_id) ⇒ Response

Gets the information about a certain client device

Parameters:

  • device_id (String) —

    The ID of the device to look up

Returns:

  • (Response) —

    An object containing all available device information

See Also:



1723
1724
1725
1726
1727
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1723

def get_device(device_id)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:get, client_api_latest, "/devices/#{device_id}")
end

#get_devices ⇒ Response

Gets a list of the current users registered devices

Returns:

  • (Response) —

    An object including all information about the users devices.

See Also:



1714
1715
1716
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1714

def get_devices
  request(:get, client_api_latest, '/devices')
end

#get_display_name(user_id, **params) ⇒ Object 



1418
1419
1420
1421
1422
1423
1424
1425
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1418

def get_display_name(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/profile/#{user_id}/displayname", query: query)
end

#get_download_url(mxcurl, source: nil, **_params) ⇒ URI

Converts a Matrix content URL (mxc://) to a media download URL

Examples:

Converting a MXC URL

url = 'mxc://example.com/media_hash'

api.get_download_url(url)
# => #<URI::HTTPS https://example.com/_matrix/media/r0/download/example.com/media_hash>
api.get_download_url(url, source: 'matrix.org')
# => #<URI::HTTPS https://matrix.org/_matrix/media/r0/download/example.com/media_hash>

Parameters:

  • mxcurl (String, URI) —

    The Matrix content URL to convert

  • source (String, URI) (defaults to: nil) —

    A source HS to use for the convertion, defaults to the connected HS

Returns:

  • (URI) —

    The full download URL for the requested piece of media



1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1574

def get_download_url(mxcurl, source: nil, **_params)
  mxcurl = URI.parse(mxcurl.to_s) unless mxcurl.is_a? URI
  raise 'Not a mxc:// URL' unless mxcurl.is_a? URI::MXC

  if source
    source = "https://#{source}" unless source.include? '://'
    source = URI(source.to_s) unless source.is_a?(URI)
  end

  source ||= homeserver.dup
  source.tap do |u|
    full_path = mxcurl.full_path.to_s
    u.path = "/_matrix/media/r0/download/#{full_path}"
  end
end

#get_filter(user_id, filter_id, **params) ⇒ Object 



1388
1389
1390
1391
1392
1393
1394
1395
1396
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1388

def get_filter(user_id, filter_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  filter_id = ERB::Util.url_encode filter_id.to_s

  request(:get, client_api_latest, "/user/#{user_id}/filter/#{filter_id}", query: query)
end

#get_joined_rooms(**params) ⇒ Response

Gets the list of rooms joined by the current user

Returns:

  • (Response) —

    An array of room IDs under the key :joined_rooms

See Also:



396
397
398
399
400
401
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 396

def get_joined_rooms(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, client_api_latest, '/joined_rooms', query: query)
end

#get_key_changes(from:, to:) ⇒ Response

Retrieve device key changes between two sync requests

Parameters:

  • from (String) —

    The sync token denoting the start of the range

  • to (String) —

    The sync token denoting the end of the range

Returns:

  • (Response) —

    The users with device key changes during the specified range

See Also:



1800
1801
1802
1803
1804
1805
1806
1807
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1800

def get_key_changes(from:, to:)
  query = {
    from: from,
    to: to
  }

  request(:get, client_api_latest, '/keys/changes', query: query)
end

#get_media_config ⇒ Response

Gets the media configuration of the current server

Returns:

  • (Response) —

    A response hash containing media configuration informtion

See Also:



1613
1614
1615
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1613

def get_media_config
  request(:get, :media_r0, '/config')
end

#get_membership(room_id, user_id, **params) ⇒ Object 



1214
1215
1216
1217
1218
1219
1220
1221
1222
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1214

def get_membership(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/state/m.room.member/#{user_id}", query: query)
end

#get_notifications(from: nil, limit: nil, only: nil) ⇒ Response

Enumerates the list of notifies that the current user has/should have received.

Parameters:

  • from (String) (defaults to: nil) —

    The pagination token to continue reading events from

  • limit (Integer) (defaults to: nil) —

    The maximum number of event to return

  • only (String) (defaults to: nil) —

    A filter string that is to be applied to the notification events

Returns:

  • (Response) —

    A response hash containing notifications for the current user

Raises:

  • (ArgumentError)

See Also:



1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1860

def get_notifications(from: nil, limit: nil, only: nil)
  raise ArgumentError, 'Limit must be an integer' unless limit.nil? || limit.is_a?(Integer)

  query = {
    from: from,
    limit: limit,
    only: only
  }.compact

  request(:get, client_api_latest, '/notifications', query: query)
end

#get_presence_status(user_id) ⇒ Response

Gets the presence status of a user

Parameters:

  • user_id (String, MXID) —

    The User ID to read the status for

Returns:

  • (Response) —

    A response hash containing the current user presence status

See Also:



1536
1537
1538
1539
1540
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1536

def get_presence_status(user_id)
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/presence/#{user_id}/status")
end

#get_profile(user_id, **params) ⇒ Response

Gets the combined profile object of a user.

This includes their display name and avatar

Parameters:

  • user_id (String, MXID) —

    The User ID to read the profile for

Returns:

  • (Response) —

    The user profile object

See Also:



1491
1492
1493
1494
1495
1496
1497
1498
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1491

def get_profile(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/profile/#{user_id}", query: query)
end

#get_public_rooms(server: nil, **params) ⇒ Response

Gets the list of public rooms on a Matrix server

Parameters:

  • limit (Integer) —

    Limits the number of results returned

  • since (String) —

    A pagination token received from an earlier call

  • server (String) (defaults to: nil) —

    The Matrix server to request public rooms from

Returns:

  • (Response) —

    An array of public rooms in the :chunk key, along with :next_batch, :prev_batch, and :total_room_count_estimate for pagination

See Also:



413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 413

def get_public_rooms(server: nil, **params)
  query = {
    server: server
  }.compact
  body = nil
  method = :get

  if !params[:filter].nil? || !params[:include_all_networks].nil? || !params[:third_party_instance_id].nil?
    body = {
      limit: params[:limit],
      since: params[:since],
      filter: params[:filter],
      include_all_networks: params[:include_all_networks],
      third_party_instance_id: params[:third_party_instance_id]
    }.merge(params).compact
    method = :post
  else
    query = query.merge(params).compact
  end

  request(method, client_api_latest, '/publicRooms', query: query, body: body)
end

#get_pushers ⇒ Response

Gets the list of registered pushers for the current user

Returns:

  • (Response) —

    A response hash containing all the currently registered pushers for the current user

See Also:



1814
1815
1816
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1814

def get_pushers
  request(:get, client_api_latest, '/pushers')
end

#get_pushrule(kind:, id:, scope: 'global') ⇒ Response

Retrieves a single registered push rule for the current user

Parameters:

  • scope (String) (defaults to: 'global') —

    (‘global’) The scope to look up push rules from

  • kind (:override, :underride, :sender, :room, :content) —

    The kind of push rule to look up

  • id (String) —

    The ID of the rule that’s being retrieved

Returns:

  • (Response) —

    A response hash containing the full data of the requested push rule

See Also:



1889
1890
1891
1892
1893
1894
1895
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1889

def get_pushrule(kind:, id:, scope: 'global')
  scope = ERB::Util.url_encode scope.to_s
  kind = ERB::Util.url_encode kind.to_s
  id = ERB::Util.url_encode id.to_s

  request(:get, client_api_latest, "/pushrules/#{scope}/#{kind}/#{id}")
end

#get_pushrule_actions(kind:, id:, scope: 'global') ⇒ Response

Gets the current list of actions for a specific push rule for the current user

Parameters:

  • scope (String) (defaults to: 'global') —

    (‘global’) The scope to look up push rules from

  • kind (:override, :underride, :sender, :room, :content) —

    The kind of push rule to look up

  • id (String) —

    The ID of the rule that’s being retrieved

Returns:

  • (Response) —

    A response hash containing an :enabled key for if the rule is enabled or not

See Also:



1942
1943
1944
1945
1946
1947
1948
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1942

def get_pushrule_actions(kind:, id:, scope: 'global')
  scope = ERB::Util.url_encode scope.to_s
  kind = ERB::Util.url_encode kind.to_s
  id = ERB::Util.url_encode id.to_s

  request(:get, client_api_latest, "/pushrules/#{scope}/#{kind}/#{id}/actions")
end

#get_pushrule_enabled(kind:, id:, scope: 'global') ⇒ Response

Checks if a push rule for the current user is enabled

Parameters:

  • scope (String) (defaults to: 'global') —

    (‘global’) The scope to look up push rules from

  • kind (:override, :underride, :sender, :room, :content) —

    The kind of push rule to look up

  • id (String) —

    The ID of the rule that’s being retrieved

Returns:

  • (Response) —

    A response hash containing an :enabled key for if the rule is enabled or not

See Also:



1905
1906
1907
1908
1909
1910
1911
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1905

def get_pushrule_enabled(kind:, id:, scope: 'global')
  scope = ERB::Util.url_encode scope.to_s
  kind = ERB::Util.url_encode kind.to_s
  id = ERB::Util.url_encode id.to_s

  request(:get, client_api_latest, "/pushrules/#{scope}/#{kind}/#{id}/enabled")
end

#get_pushrules ⇒ Response

Retrieves the full list of registered push rules for the current user

Returns:

  • (Response) —

    A response hash containing the current list of push rules for the current user

See Also:



1877
1878
1879
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1877

def get_pushrules
  request(:get, client_api_latest, '/pushrules/')
end

#get_room_account_data(user_id, room_id, type_key, **params) ⇒ Object 



1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1354

def (user_id, room_id, type_key, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  room_id = ERB::Util.url_encode room_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:get, client_api_latest, "/user/#{user_id}/rooms/#{room_id}/account_data/#{type_key}", query: query)
end

#get_room_aliases(room_id, **params) ⇒ Response

Gets a list of currently known aliases of a room

Examples:

Looking up aliases for a room

api.get_room_aliases('!QtykxKocfZaZOUrTwp:matrix.org')
# => {:aliases=>["#matrix:matrix.org"]}

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

Returns:

  • (Response) —

    A response hash with the array :aliases

Raises:

See Also:



927
928
929
930
931
932
933
934
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 927

def get_room_aliases(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/aliases", query: query)
end

#get_room_avatar(room_id, **params) ⇒ Response

Gets the current avatar URL of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the parameters :url and (optionally) :info

Raises:

See Also:



898
899
900
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 898

def get_room_avatar(room_id, **params)
  get_room_state(room_id, 'm.room.avatar', **params)
end

#get_room_creation_info(room_id, **params) ⇒ Response

Gets the creation configuration object for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the configuration the room was created for

See Also:



1055
1056
1057
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1055

def get_room_creation_info(room_id, **params)
  get_room_state(room_id, 'm.room.create', **params)
end

#get_room_directory_visibility(room_id, **params) ⇒ Response

Gets the room directory visibility status for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

Returns:

  • (Response) —

    A response hash with a :visibility key

See Also:



1266
1267
1268
1269
1270
1271
1272
1273
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1266

def get_room_directory_visibility(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/directory/list/room/#{room_id}", query: query)
end

#get_room_encryption_settings(room_id, **params) ⇒ Response

Gets the encryption configuration for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the configuration the room was created for

See Also:



1067
1068
1069
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1067

def get_room_encryption_settings(room_id, **params)
  get_room_state(room_id, 'm.room.encryption', **params)
end

#get_room_event(room_id, event_id, **params) ⇒ Response

Gets a specific event from a room

Parameters:

  • room_id (MXID, String) —

    The room ID to read from

  • event_id (MXID, String) —

    The event ID to retrieve

Returns:

  • (Response) —

    A response hash with the contents of the event

See Also:



763
764
765
766
767
768
769
770
771
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 763

def get_room_event(room_id, event_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  event_id = ERB::Util.url_encode event_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/event/#{event_id}", query: query)
end

#get_room_event_context(room_id, event_id, **params) ⇒ Response

Retrieves number of events that happened just before and after the specified event

Examples:

Find event context with filter and limit specified

api.get_room_event_context('#room:example.com', '$event_id:example.com', filter: { types: ['m.room.message'] }.to_json, limit: 20)

Parameters:

  • room_id (MXID, String) —

    The room to get events from.

  • event_id (MXID, String) —

    The event to get context around.

  • params (Hash) —

    a customizable set of options

Options Hash (**params):

  • :limit (Integer) — default: 10 —

    The limit of messages to retrieve

  • :filter (String) —

    A filter to limit the retrieval to

Returns:

  • (Response) —

    A response hash with contextual event information

See Also:



817
818
819
820
821
822
823
824
825
826
827
828
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 817

def get_room_event_context(room_id, event_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  query[:limit] = params.fetch(:limit) if params.key? :limit
  query[:filter] = params.fetch(:filter) if params.key? :filter

  room_id = ERB::Util.url_encode room_id.to_s
  event_id = ERB::Util.url_encode event_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/context/#{event_id}", query: query)
end

#get_room_guest_access(room_id, **params) ⇒ Response

Gets the guest access settings for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the key :guest_acces, either :can_join or :forbidden

See Also:



1027
1028
1029
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1027

def get_room_guest_access(room_id, **params)
  get_room_state(room_id, 'm.room.guest_access', **params)
end

#get_room_history_visibility(room_id, **params) ⇒ Response

Gets the history availabiilty for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the key :history_visibility

See Also:



1098
1099
1100
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1098

def get_room_history_visibility(room_id, **params)
  get_room_state(room_id, 'm.room.history_visibility', **params)
end

#get_room_id(room_alias, **params) ⇒ Response

Gets the room ID for an alias

Parameters:

  • room_alias (String, MXID) —

    The room alias to look up

Returns:

  • (Response) —

    An object containing the :room_id key and a key of :servers that know of the room

Raises:



1643
1644
1645
1646
1647
1648
1649
1650
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1643

def get_room_id(room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:get, client_api_latest, "/directory/room/#{room_alias}", query: query)
end

#get_room_join_rules(room_id, **params) ⇒ Response

Gets the join rules for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the key :join_rule

See Also:



999
1000
1001
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 999

def get_room_join_rules(room_id, **params)
  get_room_state(room_id, 'm.room.join_rules', **params)
end

#get_room_joined_members(room_id, **params) ⇒ Response

Gets a list of the joined members in a room

Parameters:

  • room_id (String, MXID) —

    The ID of the room

Returns:

See Also:



1701
1702
1703
1704
1705
1706
1707
1708
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1701

def get_room_joined_members(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/joined_members", query: query)
end

#get_room_members(room_id, **params) ⇒ Response

Gets a list of all the members in a room

Parameters:

  • room_id (String, MXID) —

    The ID of the room

Returns:

See Also:



1686
1687
1688
1689
1690
1691
1692
1693
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1686

def get_room_members(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/members", query: query.merge(params))
end

#get_room_messages(room_id, token, direction:, limit: 10, **params) ⇒ Response

Retrieve additional messages in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to retrieve messages for

  • token (String) —

    The token to start retrieving from, can be from a sync or from an earlier get_room_messages call

  • direction (:b, :f) —

    The direction to retrieve messages

  • limit (Integer) (defaults to: 10) —

    (10) The limit of messages to retrieve

  • params (Hash) —

    Additional options for the request

Options Hash (**params):

  • :to (String) —

    A token to limit retrieval to

  • :filter (String) —

    A filter to limit the retrieval to

Returns:

  • (Response) —

    A response hash with the message information containing :start, :end, and :chunk fields

See Also:



741
742
743
744
745
746
747
748
749
750
751
752
753
754
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 741

def get_room_messages(room_id, token, direction:, limit: 10, **params)
  query = {
    from: token,
    dir: direction,
    limit: limit
  }
  query[:to] = params[:to] if params.key? :to
  query[:filter] = params.fetch(:filter) if params.key? :filter
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/messages", query: query)
end

#get_room_name(room_id, **params) ⇒ Response

Gets the current display name of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the parameter :name

Raises:

See Also:



842
843
844
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 842

def get_room_name(room_id, **params)
  get_room_state(room_id, 'm.room.name', **params)
end

#get_room_pinned_events(room_id, **params) ⇒ Response

Gets a list of pinned events in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the array :pinned

Raises:

See Also:



945
946
947
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 945

def get_room_pinned_events(room_id, **params)
  get_room_state(room_id, 'm.room.pinned_events', **params)
end

#get_room_power_levels(room_id, **params) ⇒ Response Also known as: get_power_levels

Gets the configured power levels for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with power level information

See Also:



972
973
974
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 972

def get_room_power_levels(room_id, **params)
  get_room_state(room_id, 'm.room.power_levels', **params)
end

#get_room_server_acl(room_id, **params) ⇒ Response

Gets the server ACLs for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with server ACL information

See Also:



1126
1127
1128
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1126

def get_room_server_acl(room_id, **params)
  get_room_state(room_id, 'm.room.server_acl', **params)
end

#get_room_state(room_id, state_type, key: nil, **params) ⇒ Response

Reads the latest instance of a room state event

Parameters:

  • room_id (MXID, String) —

    The room ID to read from

  • state_type (String) —

    The state type to read

Returns:

  • (Response) —

    A response hash with the contents of the state event

See Also:



780
781
782
783
784
785
786
787
788
789
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 780

def get_room_state(room_id, state_type, key: nil, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  state_type = ERB::Util.url_encode state_type.to_s
  key = ERB::Util.url_encode key.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/state/#{state_type}#{key.empty? ? nil : "/#{key}"}", query: query)
end

#get_room_state_all(room_id, **params) ⇒ Response

Retrieves all current state objects from a room

Parameters:

  • room_id (MXID, String) —

    The room ID to read from

Returns:

  • (Response) —

    A response hash with the contents of all state events

See Also:



797
798
799
800
801
802
803
804
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 797

def get_room_state_all(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, client_api_latest, "/rooms/#{room_id}/state", query: query)
end

#get_room_topic(room_id, **params) ⇒ Response

Gets the current topic of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

  • params (Hash) —

    Extra options to provide to the request, see #get_room_state

Returns:

  • (Response) —

    A response hash with the parameter :topic

Raises:

See Also:



870
871
872
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 870

def get_room_topic(room_id, **params)
  get_room_state(room_id, 'm.room.topic', **params)
end

#get_turn_server ⇒ Response

Gets TURN server connection information and credentials

Returns:

  • (Response) —

    A response hash according to the spec

See Also:



1505
1506
1507
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1505

def get_turn_server
  request(:get, client_api_latest, '/voip/turnServer')
end

#get_url_preview(url, timestamp: nil) ⇒ Response

Gets a preview of the given URL

Parameters:

  • url (String, URI) —

    The URL to retrieve a preview for

Returns:

  • (Response) —

    A response hash containing OpenGraph data for the URL

See Also:



1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1596

def get_url_preview(url, timestamp: nil)
  ts = (timestamp.to_i * 1000) if timestamp.is_a? Time
  ts = timestamp if timestamp.is_a? Integer

  query = {
    url: url,
    ts: ts
  }.compact

  request(:get, :media_r0, '/preview_url', query: query)
end

#get_user_tags(user_id, room_id, **params) ⇒ Object 



1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1295

def get_user_tags(user_id, room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/user/#{user_id}/rooms/#{room_id}/tags", query: query)
end

#invite_user(room_id, user_id, **params) ⇒ Object 



1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1188

def invite_user(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id
  }

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/invite", body: content, query: query)
end

#join_room(id_or_alias, reason: nil, **params) ⇒ Response

TODO:

Add support for 3rd-party signed objects

Joins a room

Parameters:

  • id_or_alias (MXID, String) —

    The room ID or Alias to join

  • params (Hash) —

    Extra room join options

Options Hash (**params):

  • :server_name (String[]) —

    A list of servers to perform the join through

Returns:

  • (Response) —

    A response hash with the parameter :room_id

See Also:



488
489
490
491
492
493
494
495
496
497
498
499
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 488

def join_room(id_or_alias, reason: nil, **params)
  query = {}
  query[:server_name] = params[:server_name] if params[:server_name]
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {}
  content[:reason] = reason if reason

  id_or_alias = ERB::Util.url_encode id_or_alias.to_s

  request(:post, client_api_latest, "/join/#{id_or_alias}", body: content, query: query)
end

#join_room_id(room_id, third_party_signed: nil, **params) ⇒ Response

Directly joins a room by ID

Parameters:

  • room_id (MXID, String) —

    The room ID to join

  • third_party_signed (Hash) (defaults to: nil) —

    The 3PID signature allowing the user to join

Returns:

  • (Response) —

    A response hash with the parameter :room_id

See Also:



1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1175

def join_room_id(room_id, third_party_signed: nil, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  body = {
    third_party_signed: third_party_signed
  }.compact

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/join", body: body, query: query)
end

#keys_query(device_keys:, timeout: nil, token: nil, **params) ⇒ Object

Run a query for device keys

Examples:

Looking up all the device keys for a user

api.keys_query(device_keys: { '@alice:example.com': [] })
# => { :device_keys => { :'@alice:example.com' => { :JLAFKJWSCS => { ...

Looking up a specific device for a user

api.keys_query(device_keys: { '@alice:example.com': ['ABCDEFGHIJ'] })
# => { :device_keys => { :'@alice:example.com' => { :ABCDEFGHIJ => { ...

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    The timeout - in seconds - for the query

  • device_keys (Array) —

    The list of devices to query

  • token (String) (defaults to: nil) —

    The sync token that led to this query - if any

  • params (Hash) —

    Additional parameters

Options Hash (**params):

  • timeout_ms (Integer) —

    The timeout in milliseconds for the query, overrides timeout

See Also:



1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1767

def keys_query(device_keys:, timeout: nil, token: nil, **params)
  body = {
    timeout: (timeout || 10) * 1000,
    device_keys: device_keys
  }
  body[:timeout] = params[:timeout_ms] if params.key? :timeout_ms
  body[:token] = token if token

  request(:post, client_api_latest, '/keys/query', body: body)
end

#kick_user(room_id, user_id, reason: '', **params) ⇒ Object 



1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1201

def kick_user(room_id, user_id, reason: '', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id,
    reason: reason
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/kick", body: content, query: query)
end

#knock_room(id_or_alias, reason: nil, server_name: nil, **params) ⇒ Response

Knock on a room

Parameters:

  • id_or_alias (MXID, String) —

    The room ID or Alias to knock

  • reason (String) (defaults to: nil) —

    A reason for the knock, will be attached to the membership data

  • server_name (String[]) (defaults to: nil) —

    A list of servers to perform the join through

  • params (Hash) —

    Extra room knock options

Returns:

  • (Response) —

    A response hash with at least the parameter :room_id

See Also:



467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 467

def knock_room(id_or_alias, reason: nil, server_name: nil, **params)
  query = {}
  query[:server_name] = server_name if server_name
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {}
  content[:reason] = reason if reason

  id_or_alias = ERB::Util.url_encode id_or_alias.to_s

  request(:post, client_api_latest, "/knock/#{id_or_alias}", body: content, query: query)
end

#leave_room(room_id, **params) ⇒ Object 



1150
1151
1152
1153
1154
1155
1156
1157
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1150

def leave_room(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/leave", query: query)
end

#login(login_type: 'm.login.password', **params) ⇒ Response

Logs in using the client API /login endpoint, and optionally stores the resulting access for API usage

Examples:

Logging in with username and password

api.(user: 'example', password: 'NotARealPass')
# => { user_id: '@example:matrix.org', access_token: '...', home_server: 'matrix.org', device_id: 'ABCD123' }
api.whoami?
# => { user_id: '@example:matrix.org' }

Advanced login, without storing details

api.whoami?
# => { user_id: '@example:matrix.org' }
api.(medium: 'email', address: 'someone@somewhere.net', password: '...', store_token: false)
# => { user_id: '@someone:matrix.org', access_token: ...
api.whoami?.user_id
# => '@example:matrix.org'

Parameters:

  • login_type (String) (defaults to: 'm.login.password') —

    (‘m.login.password’) The type of login to attempt

  • params (Hash) —

    The login information to use, along with options for said log in

Options Hash (**params):

  • :store_token (Boolean) — default: true —

    Should the resulting access token be stored for the API

  • :store_device_id (Boolean) — default: store_token value —

    Should the resulting device ID be stored for the API

  • :initial_device_display_name (String) — default: USER_AGENT —

    The device display name to specify for this login attempt

  • :device_id (String) —

    The device ID to set on the login

Returns:

  • (Response) —

    A response hash with the parameters :user_id, :access_token, :home_server, and :device_id.

See Also:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 191

def (login_type: 'm.login.password', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  options = {}
  options[:store_token] = params.delete(:store_token) { true }
  options[:store_device_id] = params.delete(:store_device_id) { options[:store_token] }

  data = {
    type: ,
    initial_device_display_name: params.delete(:initial_device_display_name) { MatrixSdk::Api::USER_AGENT }
  }.merge params
  data[:device_id] = device_id if device_id

  request(:post, client_api_latest, '/login', body: data, query: query).tap do |resp|
    @access_token = resp.access_token if resp.key?(:access_token) && options[:store_token]
    @device_id = resp.device_id if resp.key?(:device_id) && options[:store_device_id]
  end
end

#logout(**params) ⇒ Response

Logs out the currently logged in device for the current user

Returns:

  • (Response) —

    An empty response if the logout was successful

See Also:



215
216
217
218
219
220
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 215

def logout(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:post, client_api_latest, '/logout', query: query)
end

#logout_all(**params) ⇒ Response

Logs out the currently logged in user

Returns:

  • (Response) —

    An empty response if the logout was successful

See Also:



226
227
228
229
230
231
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 226

def logout_all(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:post, client_api_latest, '/logout/all', query: query)
end

#media_upload(content, content_type, **params) ⇒ Object 



1411
1412
1413
1414
1415
1416
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1411

def media_upload(content, content_type, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:post, :media_r0, '/upload', body: content, headers: { 'content-type' => content_type }, query: query)
end

#redact_event(room_id, event_id, **params) ⇒ Response

Redact an event in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message event to

  • event_id (String) —

    The event ID of the event to redact

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :reason (String) —

    The reason for the redaction

  • :txn_id (Integer) —

    The ID of the transaction, or automatically generated

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 556

def redact_event(room_id, event_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {}
  content[:reason] = params[:reason] if params[:reason]

  txn_id = transaction_id
  txn_id = params.fetch(:txn_id, "#{txn_id}#{Time.now.to_i}")

  room_id = ERB::Util.url_encode room_id.to_s
  event_id = ERB::Util.url_encode event_id.to_s
  txn_id = ERB::Util.url_encode txn_id.to_s

  request(:put, client_api_latest, "/rooms/#{room_id}/redact/#{event_id}/#{txn_id}", body: content, query: query)
end

#register(kind: 'user', **params) ⇒ Response

Registers a user using the client API /register endpoint

Examples:

Regular user registration and login

api.register(username: 'example', password: 'NotARealPass')
# => { user_id: '@example:matrix.org', access_token: '...', home_server: 'matrix.org', device_id: 'ABCD123' }
api.whoami?
# => { user_id: '@example:matrix.org' }

Parameters:

  • kind (String, Symbol) (defaults to: 'user') —

    (‘user’) The kind of registration to use

  • params (Hash) —

    The registration information, all not handled by Ruby will be passed as JSON in the body

Options Hash (**params):

  • :store_token (Boolean) — default: true —

    Should the resulting access token be stored for the API

  • :store_device_id (Boolean) — default: store_token value —

    Should the resulting device ID be stored for the API

Returns:

See Also:



97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 97

def register(kind: 'user', **params)
  query = {}
  query[:kind] = kind
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  store_token = params.delete(:store_token) { !protocol?(:AS) }
  store_device_id = params.delete(:store_device_id) { store_token }

  request(:post, client_api_latest, '/register', body: params, query: query).tap do |resp|
    @access_token = resp.token if resp.key?(:token) && store_token
    @device_id = resp.device_id if resp.key?(:device_id) && store_device_id
  end
end

#register_email_request(secret, email, attempt: 1, next_link: nil) ⇒ Response

Requests to register an email address to the current account

Parameters:

  • secret (String) —

    A random string containing only the characters ‘[0-9a-zA-Z.=_-]`

  • email (String) —

    The email address to register

  • attempt (Integer) (defaults to: 1) —

    The current attempt count to register the email+secret combo, increase to send another verification email

  • next_link (String, URI) (defaults to: nil) —

    An URL to redirect to after verification is finished

Returns:

  • (Response) —

    A hash containing the :sid id for the current request

See Also:



120
121
122
123
124
125
126
127
128
129
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 120

def register_email_request(secret, email, attempt: 1, next_link: nil)
  body = {
    client_secret: secret,
    email: email,
    send_attempt: attempt,
    next_link: next_link
  }.compact

  request(:post, client_api_latest, '/register/email/requestToken', body: body)
end

#register_msisdn_request(secret, country, number, attempt: 1, next_link: nil) ⇒ Response

Requests to register a phone number to the current account

Parameters:

  • secret (String) —

    A random string containing only the characters ‘[0-9a-zA-Z.=_-]`

  • country (String) —

    The two-letter ISO-3166-1 country identifier of the destination country of the number

  • number (String) —

    The phone number itself

  • attempt (Integer) (defaults to: 1) —

    The current attempt count to register the email+secret combo, increase to send another verification email

  • next_link (String, URI) (defaults to: nil) —

    An URL to redirect to after verification is finished

Returns:

  • (Response) —

    A hash containing the :sid id for the current request

See Also:



141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 141

def register_msisdn_request(secret, country, number, attempt: 1, next_link: nil)
  body = {
    client_secret: secret,
    country: country,
    phone_number: number,
    send_attempt: attempt,
    next_link: next_link
  }.compact

  request(:post, client_api_latest, '/register/msisdn/requestToken', body: body)
end

#remove_room_alias(room_alias, **params) ⇒ Response

Remove an alias from its room

Parameters:

  • room_alias (String, MXID) —

    The alias to remove

Returns:

  • (Response) —

    An empty object denoting success



1672
1673
1674
1675
1676
1677
1678
1679
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1672

def remove_room_alias(room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:delete, client_api_latest, "/directory/room/#{room_alias}", query: query)
end

#remove_user_tag(user_id, room_id, tag, **params) ⇒ Object 



1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1305

def remove_user_tag(user_id, room_id, tag, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s
  tag = ERB::Util.url_encode tag.to_s

  request(:delete, client_api_latest, "/user/#{user_id}/rooms/#{room_id}/tags/#{tag}", query: query)
end

#report_event(room_id, event_id, score:, reason:, **params) ⇒ Object

Report an event in a room

Parameters:

  • room_id (MXID, String) —

    The room ID in which the event occurred

  • room_id (MXID, String) —

    The event ID to report

  • score (Integer) —

    The severity of the report, range between -100 - 0

  • reason (String) —

    The reason for the report

See Also:



714
715
716
717
718
719
720
721
722
723
724
725
726
727
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 714

def report_event(room_id, event_id, score:, reason:, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  body = {
    score: score,
    reason: reason
  }

  room_id = ERB::Util.url_encode room_id.to_s
  event_id = ERB::Util.url_encode event_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/report/#{event_id}", body: body, query: query)
end

#request_email_login_token(secret, email, attempt: 1, next_link: nil) ⇒ Response

Requests an authentication token based on an email address

Parameters:

  • secret (String) —

    A random string containing only the characters ‘[0-9a-zA-Z.=_-]`

  • email (String) —

    The email address to register

  • attempt (Integer) (defaults to: 1) —

    The current attempt count to register the email+secret combo, increase to send another verification email

  • next_link (String, URI) (defaults to: nil) —

    An URL to redirect to after verification is finished

Returns:

  • (Response) —

    A hash containing the :sid id for the current request

See Also:



262
263
264
265
266
267
268
269
270
271
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 262

def (secret, email, attempt: 1, next_link: nil)
  body = {
    client_secret: secret,
    email: email,
    send_attempt: attempt,
    next_link: next_link
  }.compact

  request(:post, client_api_latest, '/account/password/email/requestToken', body: body)
end

#request_msisdn_login_token(secret, country, number, attempt: 1, next_link: nil) ⇒ Response

Requests an authentication token based on a phone number

Parameters:

  • secret (String) —

    A random string containing only the characters ‘[0-9a-zA-Z.=_-]`

  • country (String) —

    The two-letter ISO-3166-1 country identifier of the destination country of the number

  • number (String) —

    The phone number itself

  • attempt (Integer) (defaults to: 1) —

    The current attempt count to register the email+secret combo, increase to send another verification email

  • next_link (String, URI) (defaults to: nil) —

    An URL to redirect to after verification is finished

Returns:

  • (Response) —

    A hash containing the :sid id for the current request

See Also:



283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 283

def (secret, country, number, attempt: 1, next_link: nil)
  body = {
    client_secret: secret,
    country: country,
    phone_number: number,
    send_attempt: attempt,
    next_link: next_link
  }.compact

  request(:post, client_api_latest, '/account/password/msisdn/requestToken', body: body)
end

#send_content(room_id, url, name, msg_type, **params) ⇒ Response

Send a content message to a room

Examples:

Sending an image to a room

send_content('!abcd123:localhost',
             'mxc://localhost/1234567',
             'An image of a cat',
             'm.image',
             extra_information: {
               h: 128,
               w: 128,
               mimetype: 'image/png',
               size: 1024
             })

Sending a file to a room

send_content('!example:localhost',
             'mxc://localhost/fileurl',
             'Contract.pdf',
             'm.file',
             extra_content: {
               filename: 'contract.pdf'
             },
             extra_information: {
               mimetype: 'application/pdf',
               size: 96674
             })

Parameters:

  • room_id (MXID, String) —

    The room ID to send the content to

  • url (URI, String) —

    The URL to the content

  • name (String) —

    The name of the content

  • msg_type (String) —

    The message type of the content

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :extra_information (Hash) — default: {} —

    Extra information for the content

  • :extra_content (Hash) —

    Extra data to insert into the content hash

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



614
615
616
617
618
619
620
621
622
623
624
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 614

def send_content(room_id, url, name, msg_type, **params)
  content = {
    url: url,
    msgtype: msg_type,
    body: name,
    info: params.delete(:extra_information) { {} }
  }
  content.merge!(params.fetch(:extra_content)) if params.key? :extra_content

  send_message_event(room_id, 'm.room.message', content, **params)
end

#send_emote(room_id, emote, **params) ⇒ Response

Send a plaintext emote to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • emote (String) —

    The emote to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.emote' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



680
681
682
683
684
685
686
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 680

def send_emote(room_id, emote, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.emote' },
    body: emote
  }
  send_message_event(room_id, 'm.room.message', content, **params)
end

#send_location(room_id, geo_uri, name, **params) ⇒ Response

Send a geographic location to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the location to

  • geo_uri (URI, String) —

    The geographical URI to send

  • name (String) —

    The name of the location

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :extra_information (Hash) — default: {} —

    Extra information for the location

  • :thumbnail_url (URI, String) —

    The URL to a thumbnail of the location

  • :thumbnail_info (Hash) —

    Image information about the location thumbnail

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



639
640
641
642
643
644
645
646
647
648
649
650
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 639

def send_location(room_id, geo_uri, name, **params)
  content = {
    geo_uri: geo_uri,
    msgtype: 'm.location',
    body: name,
    info: params.delete(:extra_information) { {} }
  }
  content[:info][:thumbnail_url] = params.delete(:thumbnail_url) if params.key? :thumbnail_url
  content[:info][:thumbnail_info] = params.delete(:thumbnail_info) if params.key? :thumbnail_info

  send_message_event(room_id, 'm.room.message', content, **params)
end

#send_message(room_id, message, **params) ⇒ Response

Send a plaintext message to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • message (String) —

    The message to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.text' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



662
663
664
665
666
667
668
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 662

def send_message(room_id, message, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.text' },
    body: message
  }
  send_message_event(room_id, 'm.room.message', content, **params)
end

#send_message_event(room_id, event_type, content, **params) ⇒ Response

Sends a message event to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message event to

  • event_type (String) —

    The event type of the message

  • content (Hash) —

    The contents of the message

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :txn_id (Integer) —

    The ID of the transaction, or automatically generated

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 533

def send_message_event(room_id, event_type, content, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  txn_id = transaction_id
  txn_id = params.fetch(:txn_id, "#{txn_id}#{Time.now.to_i}")

  room_id = ERB::Util.url_encode room_id.to_s
  event_type = ERB::Util.url_encode event_type.to_s
  txn_id = ERB::Util.url_encode txn_id.to_s

  request(:put, client_api_latest, "/rooms/#{room_id}/send/#{event_type}/#{txn_id}", body: content, query: query)
end

#send_notice(room_id, notice, **params) ⇒ Response

Send a plaintext notice to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • notice (String) —

    The notice to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.notice' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



698
699
700
701
702
703
704
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 698

def send_notice(room_id, notice, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.notice' },
    body: notice
  }
  send_message_event(room_id, 'm.room.message', content, **params)
end

#send_state_event(room_id, event_type, content, **params) ⇒ Response Also known as: set_room_state

Sends a state event to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the state event to

  • event_type (String) —

    The event type to send

  • content (Hash) —

    The contents of the state event

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :state_key (String) —

    The state key of the event, if there is one

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



511
512
513
514
515
516
517
518
519
520
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 511

def send_state_event(room_id, event_type, content, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  event_type = ERB::Util.url_encode event_type.to_s
  state_key = ERB::Util.url_encode params[:state_key].to_s if params.key? :state_key

  request(:put, client_api_latest, "/rooms/#{room_id}/state/#{event_type}#{"/#{state_key}" unless state_key.nil?}", body: content, query: query)
end

#send_to_device(event_type, messages:, **params) ⇒ Object

Sends events directly to the specified devices

Parameters:

  • event_type (String) —

    The type of event to send

  • messages (Hash) —

    The hash of events to send and devices to send them to

  • params (Hash) —

    Additional parameters

Options Hash (**params):

  • :txn_id (Integer) —

    The ID of the transaction, automatically generated if not specified

See Also:



1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1625

def send_to_device(event_type, messages:, **params)
  txn_id = transaction_id
  txn_id = params.fetch(:txn_id, "#{txn_id}#{Time.now.to_i}")

  event_type = ERB::Util.url_encode event_type.to_s
  txn_id = ERB::Util.url_encode txn_id.to_s

  body = {
    messages: messages
  }.compact

  request(:put, client_api_latest, "/sendToDevice/#{event_type}/#{txn_id}", body: body)
end

#set_account_data(user_id, type_key, account_data, **params) ⇒ Object 



1344
1345
1346
1347
1348
1349
1350
1351
1352
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1344

def (user_id, type_key, , **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:put, client_api_latest, "/user/#{user_id}/account_data/#{type_key}", body: , query: query)
end

#set_avatar_url(user_id, url, **params) ⇒ Response

Sets the avatar URL for a user

Examples:

Reuploading a gravatar as an avatar

require 'digest/md5'

# Get a 256x256 gravatar of user@example.com, returning 404 if one doesn't exist
email = 'user@example.com'
url = "https://www.gravatar.com/avatar/#{Digest::MD5.hexdigest email.striprim.downcase}?d=404&s=256"

data = Net::HTTP.get_response(URI(url))
data.value

# Reupload the gravatar to your connected HS before setting the resulting MXC URL as the new avatar
mxc = api.media_upload(data.body, data.content_type)[:content_uri]
api.set_avatar_url(api.whoami?[:user_id], mxc)

Parameters:

  • user_id (String, MXID) —

    The ID of the user to set the avatar for

  • url (String, URI::MXC) —

    The new avatar URL, should be a mxc:// URL

Returns:

  • (Response) —

    An empty response hash if the change was successful

See Also:



1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1470

def set_avatar_url(user_id, url, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    avatar_url: url
  }

  user_id = ERB::Util.url_encode user_id.to_s

  request(:put, client_api_latest, "/profile/#{user_id}/avatar_url", body: content, query: query)
end

#set_device(device_id, display_name:) ⇒ Object

Sets the metadata for a device

Parameters:

  • device_id (String) —

    The ID of the device to modify

  • display_name (String) —

    The new display name to set for the device

See Also:



1734
1735
1736
1737
1738
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1734

def set_device(device_id, display_name:)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:put, client_api_latest, "/devices/#{device_id}", body: { display_name: display_name })
end

#set_display_name(user_id, display_name, **params) ⇒ Object 



1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1427

def set_display_name(user_id, display_name, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    displayname: display_name
  }

  user_id = ERB::Util.url_encode user_id.to_s

  request(:put, client_api_latest, "/profile/#{user_id}/displayname", body: content, query: query)
end

#set_membership(room_id, user_id, membership, reason: '', **params) ⇒ Object 



1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1224

def set_membership(room_id, user_id, membership, reason: '', **params)
  content = {
    membership: membership,
    reason: reason
  }
  content[:displayname] = params.delete(:displayname) if params.key? :displayname
  content[:avatar_url] = params.delete(:avatar_url) if params.key? :avatar_url

  send_state_event(room_id, 'm.room.member', content, params.merge(state_key: user_id))
end

#set_presence_status(user_id, status, message: nil) ⇒ Response

Note:

The specified user_id should be of the local user unless used for AS purposes

Sets the presence status of a user

Parameters:

  • user_id (String, MXID) —

    The User ID to set the status for

  • status (:online, :offline, :unavailable) —

    The status to set

  • messge (String) —

    The status message to store for the new status

Returns:

  • (Response) —

    An empty response hash if the status update succeeded

See Also:



1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1551

def set_presence_status(user_id, status, message: nil)
  user_id = ERB::Util.url_encode user_id.to_s

  body = {
    presence: status,
    status_msg: message
  }.compact

  request(:put, client_api_latest, "/presence/#{user_id}/status", body: body)
end

#set_pusher(key, kind:, app_id:, app_name:, device_name:, lang:, data:, **params) ⇒ Response

Sets a pusher on the current user

Parameters:

  • key (String) —

    The pushkey for the pusher, used for routing purposes and for unique identification in coordination with app_id

  • kind (String) —

    The kind of pusher, should be either ‘http’ or ‘email’

  • app_id (String) —

    The ID of the application to push to

  • app_name (String) —

    The user-visible name of the application to push to

  • device_name (String) —

    The user-visible name of the device to push to

  • lang (String) —

    The language that pushes should be sent in

  • data (Hash) —

    Pusher configuration data, depends on the kind parameter

  • params (Hash) —

    Additional optional parameters

Options Hash (**params):

  • profile_tag (String) —

    Specifies which device rules to use

  • append (Boolean) —

    Specifies if the pusher should replace or be appended to the pusher list based on uniqueness

Returns:

  • (Response) —

    An empty response hash if the pusher was added/replaced correctly

See Also:



1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1835

def set_pusher(key, kind:, app_id:, app_name:, device_name:, lang:, data:, **params)
  body = {
    pushkey: key,
    kind: kind,
    app_id: app_id,
    app_display_name: app_name,
    device_display_name: device_name,
    profile_tag: params[:profile_tag],
    lang: lang,
    data: data,
    append: params[:append]
  }.compact

  request(:post, client_api_latest, '/pushers/set', body: body)
end

#set_pushrule_actions(actions, kind:, id:, scope: 'global') ⇒ Response

Replaces the list of actions for a push rule for the current user

Parameters:

  • actions (String, Array[String]) —

    The list of actions to apply on the push rule

  • scope (String) (defaults to: 'global') —

    (‘global’) The scope to look up push rules from

  • kind (:override, :underride, :sender, :room, :content) —

    The kind of push rule to look up

  • id (String) —

    The ID of the rule that’s being retrieved

Returns:

  • (Response) —

    An empty response hash if the push rule actions were modified successfully

See Also:



1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1959

def set_pushrule_actions(actions, kind:, id:, scope: 'global')
  scope = ERB::Util.url_encode scope.to_s
  kind = ERB::Util.url_encode kind.to_s
  id = ERB::Util.url_encode id.to_s

  actions = [actions] unless actions.is_a? Array

  body = {
    actions: actions
  }

  request(:put, client_api_latest, "/pushrules/#{scope}/#{kind}/#{id}/actions", body: body)
end

#set_pushrule_enabled(enabled, kind:, id:, scope: 'global') ⇒ Response

Enabled/Disables a specific push rule for the current user

Parameters:

  • enabled (Boolean) —

    Should the push rule be enabled or not

  • scope (String) (defaults to: 'global') —

    (‘global’) The scope to look up push rules from

  • kind (:override, :underride, :sender, :room, :content) —

    The kind of push rule to look up

  • id (String) —

    The ID of the rule that’s being retrieved

Returns:

  • (Response) —

    An empty response hash if the push rule was enabled/disabled successfully

See Also:



1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1922

def set_pushrule_enabled(enabled, kind:, id:, scope: 'global')
  scope = ERB::Util.url_encode scope.to_s
  kind = ERB::Util.url_encode kind.to_s
  id = ERB::Util.url_encode id.to_s

  body = {
    enabled: enabled
  }

  request(:put, client_api_latest, "/pushrules/#{scope}/#{kind}/#{id}/enabled", body: body)
end

#set_room_account_data(user_id, room_id, type_key, account_data, **params) ⇒ Object 



1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1365

def (user_id, room_id, type_key, , **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  room_id = ERB::Util.url_encode room_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:put, client_api_latest, "/user/#{user_id}/rooms/#{room_id}/account_data/#{type_key}", body: , query: query)
end

#set_room_alias(room_id, room_alias, **params) ⇒ Response

Sets the room ID for an alias

Parameters:

  • room_id (String, MXID) —

    The room to set an alias for

  • room_alias (String, MXID) —

    The alias to configure for the room

Returns:

  • (Response) —

    An empty object denoting success

Raises:



1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1657

def set_room_alias(room_id, room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    room_id: room_id
  }
  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:put, client_api_latest, "/directory/room/#{room_alias}", body: content, query: query)
end

#set_room_avatar(room_id, url, **params) ⇒ Response

Sets the avatar URL for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • url (String, URI) —

    The new avatar URL for the room

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



910
911
912
913
914
915
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 910

def set_room_avatar(room_id, url, **params)
  content = {
    url: url
  }
  send_state_event(room_id, 'm.room.avatar', content, **params)
end

#set_room_directory_visibility(room_id, visibility, **params) ⇒ Response

Sets the room directory visibility status for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to change visibility for

  • visibility (:public, :private) —

    The new visibility status

Returns:

  • (Response) —

    An empty response hash if the visibilty change succeeded

See Also:



1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1282

def set_room_directory_visibility(room_id, visibility, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  body = {
    visibility: visibility
  }

  room_id = ERB::Util.url_encode room_id.to_s

  request(:put, client_api_latest, "/directory/list/room/#{room_id}", body: body, query: query)
end

#set_room_encryption_settings(room_id, algorithm: 'm.megolm.v1.aes-sha2', rotation_period_ms: 1 * 7 * 24 * 60 * 60 * 1000, rotation_period_msgs: 100, **params) ⇒ Response

Sets the encryption configuration for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • algorithm ('m.megolm.v1.aes-sha2') (defaults to: 'm.megolm.v1.aes-sha2') —

    The encryption algorithm to use

  • rotation_period_ms (Integer) (defaults to: 1 * 7 * 24 * 60 * 60 * 1000) —

    The interval between key rotation in milliseconds

  • rotation_period_msgs (Integer) (defaults to: 100) —

    The interval between key rotation in messages

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



1081
1082
1083
1084
1085
1086
1087
1088
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1081

def set_room_encryption_settings(room_id, algorithm: 'm.megolm.v1.aes-sha2', rotation_period_ms: 1 * 7 * 24 * 60 * 60 * 1000, rotation_period_msgs: 100, **params)
  content = {
    algorithm: algorithm,
    rotation_period_ms: rotation_period_ms,
    rotation_period_msgs: rotation_period_msgs
  }
  send_state_event(room_id, 'm.room.encryption', content, **params)
end

#set_room_guest_access(room_id, guest_access, **params) ⇒ Response

Sets the guest access settings for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • guest_access (:can_join, :forbidden) —

    The new guest access setting for the room

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



1039
1040
1041
1042
1043
1044
1045
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1039

def set_room_guest_access(room_id, guest_access, **params)
  content = {
    guest_access: guest_access
  }

  send_state_event(room_id, 'm.room.guest_access', content, **params)
end

#set_room_history_visibility(room_id, visibility, **params) ⇒ Response

Sets the history availability for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • visibility (:invited, :joined, :shared, :world_readable) —

    The new history visibility level

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



1110
1111
1112
1113
1114
1115
1116
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1110

def set_room_history_visibility(room_id, visibility, **params)
  content = {
    history_visibility: visibility
  }

  send_state_event(room_id, 'm.room.history_visibility', content, **params)
end

#set_room_join_rules(room_id, join_rule, **params) ⇒ Response

Sets the join rules for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • join_rule (String, Symbol) —

    The new join rule setting (Currently only public and invite are implemented)

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



1011
1012
1013
1014
1015
1016
1017
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1011

def set_room_join_rules(room_id, join_rule, **params)
  content = {
    join_rule: join_rule
  }

  send_state_event(room_id, 'm.room.join_rules', content, **params)
end

#set_room_name(room_id, name, **params) ⇒ Response

Sets the display name of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • name (String) —

    The new name of the room

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



854
855
856
857
858
859
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 854

def set_room_name(room_id, name, **params)
  content = {
    name: name
  }
  send_state_event(room_id, 'm.room.name', content, **params)
end

#set_room_pinned_events(room_id, events, **params) ⇒ Response

Sets the list of pinned events in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • events (Array[String]) —

    The new list of events to set as pinned

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



957
958
959
960
961
962
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 957

def set_room_pinned_events(room_id, events, **params)
  content = {
    pinned: events
  }
  send_state_event(room_id, 'm.room.pinned_events', content, **params)
end

#set_room_power_levels(room_id, content, **params) ⇒ Response Also known as: set_power_levels

Sets the configuration for power levels in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • content (Hash) —

    The new power level configuration

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



985
986
987
988
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 985

def set_room_power_levels(room_id, content, **params)
  content[:events] = {} unless content.key? :events
  send_state_event(room_id, 'm.room.power_levels', content, **params)
end

#set_room_server_acl(room_id, allow:, deny:, allow_ip_literals: false, **params) ⇒ Response

Sets the server ACL configuration for a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • allow_ip_literals (Boolean) (defaults to: false) —

    If HSes with literal IP domains should be allowed

  • allow (Array[String]) —

    A list of HS wildcards that are allowed to communicate with the room

  • deny (Array[String]) —

    A list of HS wildcards that are denied from communicating with the room

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



1140
1141
1142
1143
1144
1145
1146
1147
1148
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1140

def set_room_server_acl(room_id, allow:, deny:, allow_ip_literals: false, **params)
  content = {
    allow_ip_literals: allow_ip_literals,
    allow: allow,
    deny: deny
  }

  send_state_event(room_id, 'm.room.server_acl', content, **params)
end

#set_room_topic(room_id, topic, **params) ⇒ Response

Sets the topic of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to work on

  • topic (String) —

    The new topic of the room

  • params (Hash) —

    Extra options to set on the request, see #send_state_event

Returns:

  • (Response) —

    The resulting state event

See Also:



882
883
884
885
886
887
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 882

def set_room_topic(room_id, topic, **params)
  content = {
    topic: topic
  }
  send_state_event(room_id, 'm.room.topic', content, **params)
end

#set_typing(room_id, user_id, typing: true, timeout: nil) ⇒ Response

Sets the typing status for a user

Parameters:

  • room_id (String, MXID) —

    The ID of the room to set the typing status in

  • user_id (String, MXID) —

    The ID of the user to set the typing status for

  • typing (Boolean) (defaults to: true) —

    Is the user typing or not

  • timeout (Numeric) (defaults to: nil) —

    The timeout in seconds for how long the typing status should be valid

Returns:

  • (Response) —

    An empty response hash if the typing change was successful

See Also:



1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1518

def set_typing(room_id, user_id, typing: true, timeout: nil)
  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s

  body = {
    typing: typing,
    timeout: timeout ? timeout * 1000 : nil
  }.compact

  request(:put, client_api_latest, "/rooms/#{room_id}/typing/#{user_id}", body: body)
end

#sync(timeout: 30.0, **params) ⇒ Response

Runs the client API /sync method

Parameters:

  • timeout (Numeric) (defaults to: 30.0) —

    (30.0) The timeout in seconds for the sync

  • params (Hash) —

    The sync options to use

Options Hash (**params):

  • :since (String) —

    The value of the batch token to base the sync from

  • :filter (String, Hash) —

    The filter to use on the sync

  • :full_state (Boolean) —

    Should the sync include the full state

  • :set_presence (Boolean) —

    Should the sync set the user status to online

Returns:

See Also:



70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 70

def sync(timeout: 30.0, **params)
  query = params.select do |k, _v|
    %i[since filter full_state set_presence].include? k
  end

  query[:timeout] = (timeout * 1000).to_i if timeout
  query[:timeout] = params.delete(:timeout_ms).to_i if params.key? :timeout_ms
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, client_api_latest, '/sync', query: query)
end

#unban_user(room_id, user_id, **params) ⇒ Object 



1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1248

def unban_user(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, client_api_latest, "/rooms/#{room_id}/unban", body: content, query: query)
end

#unbind_3pid(medium, address, id_server:) ⇒ Response

Unbinds a 3PID from the current user

Parameters:

  • medium (:email, :msisdn) —

    The medium of 3PID being removed

  • address (String) —

    The address that is to be removed

  • id_server (String) —

    The identity server being acted against

Returns:

See Also:



382
383
384
385
386
387
388
389
390
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 382

def unbind_3pid(medium, address, id_server:)
  body = {
    address: address,
    id_server: id_server,
    medium: medium
  }

  request(:post, client_api_latest, '/account/3pid/unbind', body: body)
end

#username_available?(username) ⇒ Response

Checks if a given username is available and valid for registering

Examples:

Verifying a username

api.username_available?('example')
# => { available: true }

Parameters:

  • username (String) —

    The username to check

Returns:

See Also:



162
163
164
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 162

def username_available?(username)
  request(:get, client_api_latest, '/register/available', query: { username: username })
end

#whoami?(**params) ⇒ Response

Gets the MXID of the currently logged-in user

Returns:

  • (Response) —

    An object containing the key :user_id



1975
1976
1977
1978
1979
1980
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1975

def whoami?(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, client_api_latest, '/account/whoami', query: query)
end

#whois(user_id) ⇒ Response

Retrieve user information

Parameters:

  • user_id (String) —

    The MXID to look up

Returns:

  • (Response) —

    A response hash containing the requested user’s information

See Also:



1382
1383
1384
1385
1386
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 1382

def whois(user_id)
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, client_api_latest, "/admin/whois/#{user_id}")
end