Class: Chatrix::Api::RoomActions

Inherits:
ApiComponent show all
Defined in:
lib/chatrix/api/room_actions.rb

Overview

Contains methods for performing actions on rooms.

Instance Method Summary collapse

Methods inherited from ApiComponent

#make_request

Constructor Details

#initialize(matrix) ⇒ RoomActions

Initializes a new RoomActions instance.

Parameters:

  • matrix (Matrix) —

    The matrix API instance.



10
11
12
13
 
# File 'lib/chatrix/api/room_actions.rb', line 10

def initialize(matrix)
  super
  @transaction_id = 0
end

Instance Method Details

#ban(room, user, reason) ⇒ Boolean

Kicks and bans a user from a room.

Examples:

Banning a spammer

ban('#haven:matrix.org', '@spammer:spam.com', 'Spamming the room')

Parameters:

  • room (String) —

    The room to ban the user from.

  • user (String) —

    The user to ban.

  • reason (String) —

    Reason why the ban was made.

Returns:

  • (Boolean) —

    true if the ban was carried out successfully, otherwise false.



146
147
148
149
150
151
152
 
# 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 = {}) ⇒ String

Creates a new room on the server.

Examples:

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!"

Parameters:

  • data (Hash) (defaults to: {}) —

    Additional data to send when creating the room. None of these are required when creating a new room.

Options Hash (data):

  • :invite (Array<String>) —

    A list of user IDs to invite when the room has been created.

  • :name (String) —

    A custom name to give the room.

  • :visibility ('public', 'private') —

    The visibility to create the room with.

  • :invite_3pid (Array<Hash>) —

    A list of third-party ID objects to invite to the room.

  • :topic (String) —

    A topic to set for the room.

  • :preset ('public_chat', 'trusted_private_chat', 'private_chat') —

    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.
  • :creation_content (Hash{String => Object}) —

    Additional data to add to the 'm.room.create' content.

  • :initial_state (Array<Hash>) —

    A list of state events to set in the room.

  • :room_alias_name (String) —

    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.

Returns:

  • (String) —

    the ID of the created room.



57
58
59
 
# File 'lib/chatrix/api/room_actions.rb', line 57

def create(data = {})
  make_request(:post, '/createRoom', content: data)['room_id']
end

#forget(room) ⇒ Boolean

Forgets about a room.

Parameters:

  • room (String) —

    The room to forget about.

Returns:

  • (Boolean) —

    true if the room was forgotten successfully, otherwise false.



111
112
113
 
# File 'lib/chatrix/api/room_actions.rb', line 111

def forget(room)
  make_request(:post, "/rooms/#{room}/forget").code == 200
end

#invite(room, user) ⇒ Boolean #invite(room, data) ⇒ Boolean

Overloads:

  • #invite(room, user) ⇒ Boolean

    Invites a user to a room by ID.

    Parameters:

    • room (String) —

      The room to invite the user to.

    • user (String) —

      The user ID to send the invite to.

    Returns:

    • (Boolean) —

      true if the user was successfully invited, otherwise false.

  • #invite(room, data) ⇒ Boolean

    Invites a user to a room by their 3PID information.

    Parameters:

    • room (String) —

      The room to invite the user to.

    • data (Hash) —

      3PID info for the user.

    Returns:

    • (Boolean) —

      true if the user was successfully invited, otherwise false.



92
93
94
95
 
# 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) ⇒ String

Joins a room on the homeserver.

Parameters:

  • room (String) —

    The room to join.

  • third_party_signed (Hash, nil) (defaults to: 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.

Returns:

  • (String) —

    The ID of the room that was joined is returned.



68
69
70
71
72
73
74
75
76
77
78
 
# 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) ⇒ Boolean

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.

Examples:

Kicking an annoying user

kick('#fun:matrix.org', '@anon:4chan.org', 'Bad cropping')

Parameters:

  • room (String) —

    The room to kick the user from.

  • user (String) —

    The user to kick.

  • reason (String) —

    The reason for the kick.

Returns:

  • (Boolean) —

    true if the user was successfully kicked, otherwise false.



128
129
130
131
132
133
134
 
# 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) ⇒ Boolean

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

Parameters:

  • room (String) —

    The room to leave.

Returns:

  • (Boolean) —

    true if the room was left successfully, otherwise false.



102
103
104
 
# 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) ⇒ String

Redacts a room event from the server.

Parameters:

  • room (String) —

    The room to redact the event from.

  • event (String) —

    The event to redact.

  • reason (String) —

    The reason for redacting the event.

Returns:

  • (String) —

    The ID for the redaction event.



265
266
267
268
269
270
271
 
# 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) ⇒ String

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).

Examples:

Sending an HTML message

send_html('#html:matrix.org',
          '<strong>Hello</strong> <em>world</em>!')

Parameters:

  • room (String) —

    The room to send to.

  • html (String) —

    The HTML formatted text to send.

  • clean (String, nil) (defaults to: 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.

Returns:

  • (String) —

    The event ID of the sent message is returned.



214
215
216
217
218
219
220
221
222
 
# 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') ⇒ String

A helper method to send a simple message construct.

Parameters:

  • room (String) —

    The room to send the message to.

  • content (String) —

    The message to send.

  • type (String) (defaults to: 'm.text') —

    The type of message this is. For example: 'm.text', 'm.notice', 'm.emote'.

Returns:

  • (String) —

    The event ID of the sent message is returned.



191
192
193
 
# 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') ⇒ String

Sends a message object to a room.

Parameters:

  • room (String) —

    The room to send to.

  • content (Hash) —

    The message content to send.

  • type (String) (defaults to: 'm.room.message') —

    The type of message to send.

Returns:

  • (String) —

    The event ID of the sent message is returned.

See Also:



176
177
178
179
180
181
182
 
# 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) ⇒ Boolean

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

Parameters:

  • room (String) —

    The affected room.

  • user (String) —

    The user that started or stopped typing.

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

    Whether the user is typing.

  • duration (Fixnum) (defaults to: 30_000) —

    How long the user will be typing for (in milliseconds).

Returns:

  • (Boolean) —

    true if the message sent successfully, otherwise false.



234
235
236
237
238
239
240
 
# 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 = {}) ⇒ Boolean

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

Parameters:

  • room (String) —

    The room to update the receipt in.

  • event (String) —

    The new event to point the receipt to.

  • type (String) (defaults to: 'm.read') —

    The receipt type to update.

  • data (Hash) (defaults to: {}) —

    Any additional data to attach to content.

Returns:

  • (Boolean) —

    true if the receipt was successfully updated, otherwise false.



251
252
253
254
255
256
257
 
# 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) ⇒ Boolean

Unbans a user from a room.

Parameters:

  • room (String) —

    The room to unban the user from.

  • user (String) —

    The user to unban.

Returns:

  • (Boolean) —

    true if the user was successfully unbanned, otherwise false.



160
161
162
163
 
# 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