class Chatrix::Api::Users
Contains methods to use user endpoints in the API.
Public Instance Methods
Gets information about a specific user.
@param user [String] The user to query (`@user:host.tld`). @return [Hash] The user information. @raise [UserNotFoundError] If the user could not be found.
@example Print a user's display name
puts get_user('@foo:matrix.org')['displayname']
# File lib/chatrix/api/users.rb, line 18 def get(user) make_request(:get, "/profile/#{user}").parsed_response rescue NotFoundError => e raise UserNotFoundError.new(user, e.error), 'The specified user could not be found' end
Get the URL to a user's avatar (an `mxp://` URL).
@param (see get_user) @return [String] The avatar URL. @raise [AvatarNotFoundError] If the avatar or user could not be found.
# File lib/chatrix/api/users.rb, line 30 def get_avatar(user) make_request(:get, "/profile/#{user}/avatar_url")['avatar_url'] rescue NotFoundError => e raise AvatarNotFoundError.new(user, e.error), 'Avatar or user could not be found' end
Get a user's display name (not username).
@param (see get_user) @raise (see get_user) @return [String] The user's display name.
# File lib/chatrix/api/users.rb, line 56 def get_displayname(user) make_request(:get, "/profile/#{user}/displayname")['displayname'] rescue NotFoundError => e raise UserNotFoundError.new(user, e.error), 'The specified user could not be found' end
Gets the presence list for a user.
@param user [String] The user whose list to get. @return [Array] A list of presences for this user.
@todo The official documentation on this endpoint is weird, what does
this really do?
# File lib/chatrix/api/users.rb, line 116 def get_presence_list(user) make_request(:get, "/presence/list/#{user}").parsed_response end
Gets the presence status of a user.
@param user [String] The user to query. @return [Hash] Hash with information about the user's presence,
contains information indicating if they are available and when they were last active.
# File lib/chatrix/api/users.rb, line 154 def get_presence_status(user) make_request(:get, "/presence/#{user}/status").parsed_response end
Sets a new avatar for a user.
@param user [String] The user to update. @param avatar [String] The new avatar to set, an `mxc://` URL. @return [Boolean] `true` if the new avatar was set successfully,
otherwise `false`.
# File lib/chatrix/api/users.rb, line 43 def set_avatar(user, avatar) make_request( :put, "/profile/#{user}/avatar_url", content: { avatar_url: avatar } ).code == 200 end
Sets account data for a user.
@param user [String] The user to add the data to. @param type [String] The event type of `account_data` to set. @param data [Hash] The actual data to set. @return [Boolean] `true` if the account data was successfully set,
otherwise `false`.
# File lib/chatrix/api/users.rb, line 87 def set_data(user, type, data) make_request( :put, "/user/#{user}/account_data/#{type}", content: data ).code == 200 end
Sets a new display name for a user.
@note Can only be used on the user who possesses the
{Matrix#access_token access_token} currently in use.
@param user [String] The user to modify (`@user:host.tld`). @param displayname [String] The new displayname to set. @return [Boolean] `true` if the new display name was successfully set,
otherwise `false`.
# File lib/chatrix/api/users.rb, line 72 def set_displayname(user, displayname) make_request( :put, "/profile/#{user}/displayname", content: { displayname: displayname } ).code == 200 end
Sets account data for a user specific to a certain room.
@param (see set_data
) @param room [String] The room to add the data in. @return [Boolean] `true` if the account data was successfully set
in the specified room, otherwise `false`.
# File lib/chatrix/api/users.rb, line 101 def set_room_data(user, room, type, data) make_request( :put, "/user/#{user}/rooms/#{room}/account_data/#{type}", content: data ).code == 200 end
Adds or removes users from a user's presence list.
@param user [String] The user whose list to modify. @param data [Hash{String=>Array<String>}] Contains two arrays,
`invite` and `drop`. Users listed in the `invite` array will be invited to join the presence list. Users listed in the `drop` array will be removed from the presence list. Note that both arrays are not required but at least one must be present.
@return [Boolean] `true` if the list was successfully updated,
otherwise `false`.
@example Add and remove two users
update_presence_list( '@me:home.org', { invite: ['@friend:home.org'], drop: ['@enemy:other.org'] } )
# File lib/chatrix/api/users.rb, line 140 def update_presence_list(user, data) make_request( :post, "/presence/list/#{user}", content: { presence_diff: data } ).code == 200 end
Updates the presence status of a user.
@note Only the user for whom the {Matrix#access_token access_token} is
valid for can have their presence updated.
@param user [String] The user to update. @param status [String] The new status to set. Eg. `'online'`
or `'offline'`.
@param message [String,nil] If set,
associates a message with the status.
@return [Boolean] `true` if the presence was updated successfully,
otherwise `false`.
# File lib/chatrix/api/users.rb, line 170 def update_presence_status(user, status, message = nil) content = { presenceState: { presence: status } } content[:presenceState][:status_msg] = message if message make_request(:put, "/presence/#{user}/status", content: content) .code == 200 end