class Chatrix::Api::Rooms
Contains methods for using room endpoints in the API.
Attributes
@return [RoomActions] an instance of RoomActions
to perform
room actions such as joining a room or sending messages.
Public Class Methods
Initializes a new Rooms
instance. @param matrix [Matrix] The matrix API instance.
Chatrix::Api::ApiComponent::new
# File lib/chatrix/api/rooms.rb, line 17 def initialize(matrix) super @actions = Api::RoomActions.new @matrix end
Public Instance Methods
Adds a user tag to a room.
@param user [String] The user adding the tag. @param room [String] The room to add the tag to. @param tag [String] The tag to add. @param data [Hash] Any additional data to add to the tag, e.g. ordering. @return [Boolean] `true` if the tag was successfully added,
otherwise `false`.
# File lib/chatrix/api/rooms.rb, line 75 def add_user_tag(user, room, tag, data = {}) make_request( :put, "/user/#{user}/rooms/#{room}/tags/#{tag}", content: data ).code == 200 end
Creates a new alias for a room.
@param room [String] The room to create an alias for. @param room_alias [String] The alias to create for the room. @return [Boolean] `true` if the alias was created successfully,
otherwise `false`.
# File lib/chatrix/api/rooms.rb, line 114 def create_alias(room, room_alias) make_request( :put, "/directory/room/#{room_alias}", content: { room_id: room } ).code == 200 end
Deletes a room alias. @param room_alias [String] The alias to delete. @return [Boolean] `true` if the alias was successfully removed,
otherwise `false`.
# File lib/chatrix/api/rooms.rb, line 104 def delete_alias(room_alias) make_request(:delete, "/directory/room/#{room_alias}").code == 200 end
Deletes a user tag from a room.
@param user [String] The user to remove the tag for. @param room [String] The room to remove the tag from. @param tag [String] The tag to remove. @return [Boolean] `true` if the tag was removed successfully,
otherwise `false`.
# File lib/chatrix/api/rooms.rb, line 60 def delete_user_tag(user, room, tag) make_request( :delete, "/user/#{user}/rooms/#{room}/tags/#{tag}" ).code == 200 end
Get information about a room alias.
This can be used to get the room ID that an alias points to.
@param room_alias [String] The room alias to query, this must be an
alias and not an ID.
@return [Hash] Returns information about the alias in a Hash.
@see get_id
get_id
is an example of how this method could be
used to get a room's ID.
# File lib/chatrix/api/rooms.rb, line 93 def get_alias_info(room_alias) make_request(:get, "/directory/room/#{room_alias}").parsed_response rescue NotFoundError raise RoomNotFoundError.new(room_alias), 'The specified room alias could not be found' end
Gets context for an event in a room.
The method will return events that happened before and after the specified event.
@param room [String] The room to query. @param event [String] The event to get context for. @param limit [Fixnum] Maximum number of events to retrieve. @return [Hash] The returned hash contains information about the events
happening before and after the specified event, as well as start and end timestamps and state information for the event.
# File lib/chatrix/api/rooms.rb, line 141 def get_event_context(room, event, limit = 10) make_request( :get, "/rooms/#{room}/context/#{event}", params: { limit: limit } ).parsed_response end
Get a room's ID from its alias.
@param room_alias [String] The room alias to query. @return [String] The actual room ID for the room.
# File lib/chatrix/api/rooms.rb, line 126 def get_id(room_alias) get_room_alias_info(room_alias)['room_id'] end
Get the members of a room.
@param room [String] The room to query. @return [Array] An array of users that are in this room.
# File lib/chatrix/api/rooms.rb, line 153 def get_members(room) make_request(:get, "/rooms/#{room}/members")['chunk'] end
Get a list of messages from a room.
@param room [String] The room to get messages from. @param from [String] Token to return events from. @param direction ['b', 'f'] Direction to return events from. @param limit [Fixnum] Maximum number of events to return. @return [Hash] A hash containing the messages, as well as `start` and
`end` tokens for pagination.
# File lib/chatrix/api/rooms.rb, line 165 def get_messages(room, from: 'START', to: 'END', direction: 'b', limit: 10) make_request( :get, "/rooms/#{room}/messages", params: { from: from, to: to, dir: direction, limit: limit } ).parsed_response end
Get the list of public rooms on the server.
The `start` and `end` values returned in the result can be passed to `from` and `to`, for pagination purposes.
@param from [String] The stream token to start looking from. @param to [String] The stream token to stop looking at. @param limit [Fixnum] Maximum number of results to
return in one request.
@param direction ['f', 'b'] Direction to look in. @return [Hash] Hash containing the list of rooms (in the `chunk` value),
and pagination parameters `start` and `end`.
# File lib/chatrix/api/rooms.rb, line 34 def get_rooms(from: 'START', to: 'END', limit: 10, direction: 'b') make_request( :get, '/publicRooms', params: { from: from, to: to, limit: limit, dir: direction } ).parsed_response end
@overload get_room_state(room)
Get state events for the current state of a room. @param room [String] The room to get events for. @return [Array] An array with state events for the room.
@overload get_room_state(room, type)
Get the contents of a specific kind of state in the room. @param room [String] The room to get the data from. @param type [String] The type of state to get. @return [Hash] Information about the state type.
@overload get_room_state(room, type, key)
Get the contents of a specific kind of state including only the specified key in the result. @param room [String] The room to get the data from. @param type [String] The type of state to get. @param key [String] The key of the state to look up. @return [Hash] Information about the requested state.
# File lib/chatrix/api/rooms.rb, line 190 def get_state(room, type = nil, key = nil) if type && key make_request(:get, "/rooms/#{room}/state/#{type}/#{key}") .parsed_response elsif type make_request(:get, "/rooms/#{room}/state/#{type}").parsed_response else make_request(:get, "/rooms/#{room}/state").parsed_response end end
Sends a state event to a room, with an optional state key. @param room [String] The room to send the event to. @param type [String] The event type to send. @param content [Hash] The content to set for the event. @param key [String,nil] Optional `state_key` to use. @return [String] The event ID for the sent event.
# File lib/chatrix/api/rooms.rb, line 207 def send_state(room, type, content, key = nil) path = "/rooms/#{room}/state/#{type}" path += "/#{key}" if key make_request(:put, path, content: content)['event_id'] end