class Chatrix::Api::RoomActions

Contains methods for performing actions on rooms.

Public Class Methods

new(matrix) click to toggle source

Initializes a new RoomActions instance. @param matrix [Matrix] The matrix API instance.

Calls superclass method Chatrix::Api::ApiComponent::new
# File lib/chatrix/api/room_actions.rb, line 10
def initialize(matrix)
  super
  @transaction_id = 0
end

Public Instance Methods

ban(room, user, reason) click to toggle source

Kicks and bans a user from a room.

@param room [String] The room to ban the user from. @param user [String] The user to ban. @param reason [String] Reason why the ban was made. @return [Boolean] `true` if the ban was carried out successfully,

otherwise `false`.

@example Banning a spammer

ban('#haven:matrix.org', '@spammer:spam.com', 'Spamming the room')
# File lib/chatrix/api/room_actions.rb, line 146
def ban(room, user, reason)
  make_request(
    :post,
    "/rooms/#{room}/ban",
    content: { reason: reason, user_id: user }
  ).code == 200
end
create(data = {}) click to toggle source

Creates a new room on the server.

@param data [Hash] Additional data to send when creating the room.

None of these are required when creating a new room.

@option data [Array<String>] :invite A list of user IDs to invite

when the room has been created.

@option data [String] :name A custom name to give the room. @option data ['public', 'private'] :visibility The visibility to

create the room with.

@option data [Array<Hash>] :invite_3pid A list of third-party

ID objects to invite to the room.

@option data [String] :topic A topic to set for the room. @option data ['public_chat', 'trusted_private_chat', 'private_chat']

:preset Sets various state events based on a preset.

 * **`private_chat`**: `join_rules` is `invite`,
   `history_visibility` is `shared`.
 * **`trusted_private_chat`**: `join_rules` is `invite`,
   `history_visibility` is `shared`, all invited users get the
   same power level as the room creator.
 * **`public_chat`**: `join_rules` is `public`,
   `history_visibility` is `shared`.

@option data [Hash{String => Object}] :creation_content Additional data

to add to the `'m.room.create'` content.

@option data [Array<Hash>] :initial_state A list of state events to

set in the room.

@option data [String] :room_alias_name The localpart of the alias

to sets for this room. The localpart is the part of the alias
between the "`#`" sign and the "`:host.tld`" ending part. In the
alias `#hello:world.org`, the "`hello`" part is the localpart.

@return [String] the ID of the created room.

@example Create a room with an alias, name, and invited user

id = create(
  room_alias_name: 'foobar',
  name: 'Foo Bar Baz!',
  invite: ['@silly:example.org']
)

puts "Room #{id} created!"
# File lib/chatrix/api/room_actions.rb, line 57
def create(data = {})
  make_request(:post, '/createRoom', content: data)['room_id']
end
forget(room) click to toggle source

Forgets about a room.

@param room [String] The room to forget about. @return [Boolean] `true` if the room was forgotten successfully,

otherwise `false`.
# File lib/chatrix/api/room_actions.rb, line 111
def forget(room)
  make_request(:post, "/rooms/#{room}/forget").code == 200
end
invite(room, data) click to toggle source

@overload invite(room, user)

Invites a user to a room by ID.
@param room [String] The room to invite the user to.
@param user [String] The user ID to send the invite to.
@return [Boolean] `true` if the user was successfully invited,
  otherwise `false`.

@overload invite(room, data)

Invites a user to a room by their 3PID information.
@param room [String] The room to invite the user to.
@param data [Hash] 3PID info for the user.
@return [Boolean] `true` if the user was successfully invited,
  otherwise `false`.
# File lib/chatrix/api/room_actions.rb, line 92
def invite(room, data)
  data = { user_id: data } if data.is_a? String
  make_request(:post, "/rooms/#{room}/invite", content: data).code == 200
end
join(room, third_party_signed = nil) click to toggle source

Joins a room on the homeserver.

@param room [String] The room to join. @param third_party_signed [Hash,nil] If provided, the homeserver must

verify that it matches a pending `m.room.third_party_invite` event in
the room, and perform key validity checking if required by the event.

@return [String] The ID of the room that was joined is returned.

# File lib/chatrix/api/room_actions.rb, line 68
def join(room, third_party_signed = nil)
  if third_party_signed
    make_request(
      :post,
      "/join/#{room}",
      content: { third_party_signed: third_party_signed }
    )['room_id']
  else
    make_request(:post, "/join/#{room}")['room_id']
  end
end
kick(room, user, reason) click to toggle source

Kicks a user from a room.

This does not ban the user, they can rejoin unless the room is invite-only, in which case they need a new invite to join back.

@param room [String] The room to kick the user from. @param user [String] The user to kick. @param reason [String] The reason for the kick. @return [Boolean] `true` if the user was successfully kicked,

otherwise `false`.

@example Kicking an annoying user

kick('#fun:matrix.org', '@anon:4chan.org', 'Bad cropping')
# File lib/chatrix/api/room_actions.rb, line 128
def kick(room, user, reason)
  make_request(
    :post,
    "/rooms/#{room}/kick",
    content: { reason: reason, user_id: user }
  ).code == 200
end
leave(room) click to toggle source

Leaves a room (but does not forget about it).

@param room [String] The room to leave. @return [Boolean] `true` if the room was left successfully,

otherwise `false`.
# File lib/chatrix/api/room_actions.rb, line 102
def leave(room)
  make_request(:post, "/rooms/#{room}/leave").code == 200
end
redact(room, event, reason) click to toggle source

Redacts a room event from the server.

@param room [String] The room to redact the event from. @param event [String] The event to redact. @param reason [String] The reason for redacting the event. @return [String] The ID for the redaction event.

# File lib/chatrix/api/room_actions.rb, line 265
def redact(room, event, reason)
  make_request(
    :put,
    "/rooms/#{room}/redact/#{event}/#{@transaction_id += 1}",
    content: { reason: reason }
  )['event_id']
end
send_html(room, html, clean = nil) click to toggle source

Sends a message formatted using HTML markup.

The `body` field in the content will have the HTML stripped out, and is usually presented in clients that don't support the formatting.

The `formatted_body` field in the content will contain the actual HTML formatted message (as passed to the `html` parameter).

@param room [String] The room to send to. @param html [String] The HTML formatted text to send. @param clean [String, nil] If set, this will be put in the `body`

field of the content, to be used as the message when the formatted
version cannot be displayed.

@return (see send_message_raw)

@example Sending an HTML message

send_html('#html:matrix.org',
          '<strong>Hello</strong> <em>world</em>!')
# File lib/chatrix/api/room_actions.rb, line 214
def send_html(room, html, clean = nil)
  send_message_raw(
    room,
    msgtype: 'm.text',
    format: 'org.matrix.custom.html',
    body: clean || html.gsub(%r{</?[^>]*?>}, ''), # TODO: Make this better
    formatted_body: html
  )
end
send_message(room, content, type = 'm.text') click to toggle source

A helper method to send a simple message construct.

@param room [String] The room to send the message to. @param content [String] The message to send. @param type [String] The type of message this is.

For example: `'m.text'`, `'m.notice'`, `'m.emote'`.

@return (see send_message_raw)

# File lib/chatrix/api/room_actions.rb, line 191
def send_message(room, content, type = 'm.text')
  send_message_raw room, msgtype: type, body: content
end
send_message_raw(room, content, type = 'm.room.message') click to toggle source

Sends a message object to a room.

@param room [String] The room to send to. @param content [Hash] The message content to send. @param type [String] The type of message to send. @return [String] The event ID of the sent message is returned. @see send_message_type @see send_message @see send_emote @see send_notice @see send_html

# File lib/chatrix/api/room_actions.rb, line 176
def send_message_raw(room, content, type = 'm.room.message')
  make_request(
    :put,
    "/rooms/#{room}/send/#{type}/#{@transaction_id += 1}",
    content: content
  )['event_id']
end
send_typing(room, user, typing = true, duration = 30_000) click to toggle source

Sends a message to the server informing it about a user having started or stopped typing.

@param room [String] The affected room. @param user [String] The user that started or stopped typing. @param typing [Boolean] Whether the user is typing. @param duration [Fixnum] How long the user will be typing for

(in milliseconds).

@return [Boolean] `true` if the message sent successfully, otherwise

`false`.
# File lib/chatrix/api/room_actions.rb, line 234
def send_typing(room, user, typing = true, duration = 30_000)
  make_request(
    :put,
    "/rooms/#{room}/typing/#{user}",
    content: { typingState: { typing: typing, timeout: duration } }
  ).code == 200
end
set_receipt(room, event, type = 'm.read', data = {}) click to toggle source

Updates the marker for the given receipt type to point to the specified event.

@param room [String] The room to update the receipt in. @param event [String] The new event to point the receipt to. @param type [String] The receipt type to update. @param data [Hash] Any additional data to attach to `content`. @return [Boolean] `true` if the receipt was successfully updated,

otherwise `false`.
# File lib/chatrix/api/room_actions.rb, line 251
def set_receipt(room, event, type = 'm.read', data = {})
  make_request(
    :post,
    "/rooms/#{room}/receipt/#{type}/#{event}",
    content: data
  ).code == 200
end
unban(room, user) click to toggle source

Unbans a user from a room.

@param room [String] The room to unban the user from. @param user [String] The user to unban. @return [Boolean] `true` if the user was successfully unbanned,

otherwise `false`.
# File lib/chatrix/api/room_actions.rb, line 160
def unban(room, user)
  make_request(:post, "/rooms/#{room}/unban", content: { user_id: user })
    .code == 200
end