Class: Discordrb::Channel

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/discordrb/data.rb

Overview

A Discord channel, including data like the topic

Instance Attribute Summary collapse

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from IDObject

#==, #creation_time, synthesise

Instance Attribute Details

#bitrate ⇒ Integer

Returns the bitrate (in bps) of the channel.

Returns:

  • (Integer) —

    the bitrate (in bps) of the channel



1058
1059
1060
 
# File 'lib/discordrb/data.rb', line 1058

def bitrate
  @bitrate
end

#name ⇒ String

Returns this channel's name.

Returns:

  • (String) —

    this channel's name.



1040
1041
1042
 
# File 'lib/discordrb/data.rb', line 1040

def name
  @name
end

#owner_id ⇒ Integer? (readonly)

Returns the id of the owner of the group channel or nil if this is not a group channel.

Returns:

  • (Integer, nil) —

    the id of the owner of the group channel or nil if this is not a group channel.



1049
1050
1051
 
# File 'lib/discordrb/data.rb', line 1049

def owner_id
  @owner_id
end

#permission_overwrites ⇒ Hash<Integer => OpenStruct> (readonly) Also known as: overwrites

This channel's permission overwrites, represented as a hash of role/user ID to an OpenStruct which has the allow and deny properties which are Permissions objects respectively.

Returns:

  • (Hash<Integer => OpenStruct>) —

    the channel's permission overwrites



1070
1071
1072
 
# File 'lib/discordrb/data.rb', line 1070

def permission_overwrites
  @permission_overwrites
end

#position ⇒ Integer

Returns the channel's position on the channel list.

Returns:

  • (Integer) —

    the channel's position on the channel list



1065
1066
1067
 
# File 'lib/discordrb/data.rb', line 1065

def position
  @position
end

#recipients ⇒ Array<Recipient>? (readonly)

Returns the array of recipients of the private messages, or nil if this is not a Private channel.

Returns:

  • (Array<Recipient>, nil) —

    the array of recipients of the private messages, or nil if this is not a Private channel



1052
1053
1054
 
# File 'lib/discordrb/data.rb', line 1052

def recipients
  @recipients
end

#server ⇒ Server? (readonly)

Returns the server this channel is on. If this channel is a PM channel, it will be nil.

Returns:

  • (Server, nil) —

    the server this channel is on. If this channel is a PM channel, it will be nil.



1043
1044
1045
 
# File 'lib/discordrb/data.rb', line 1043

def server
  @server
end

#topic ⇒ String

Returns the channel's topic.

Returns:

  • (String) —

    the channel's topic



1055
1056
1057
 
# File 'lib/discordrb/data.rb', line 1055

def topic
  @topic
end

#type ⇒ Integer (readonly)

Returns the type of this channel (0: text, 1: private, 2: voice, 3: group).

Returns:

  • (Integer) —

    the type of this channel (0: text, 1: private, 2: voice, 3: group)



1046
1047
1048
 
# File 'lib/discordrb/data.rb', line 1046

def type
  @type
end

#user_limit ⇒ Integer Also known as: limit

Returns the amount of users that can be in the channel. 0 means it is unlimited.

Returns:

  • (Integer) —

    the amount of users that can be in the channel. 0 means it is unlimited.



1061
1062
1063
 
# File 'lib/discordrb/data.rb', line 1061

def user_limit
  @user_limit
end

Instance Method Details

#add_group_users(user_ids) ⇒ Channel Also known as: add_group_user

Adds a user to a Group channel

Parameters:

  • user_ids (Array<#resolve_id>, #resolve_id) —

    User ID or array of user IDs to add to the group channel.

Returns:



1442
1443
1444
1445
1446
1447
1448
1449
 
# File 'lib/discordrb/data.rb', line 1442

def add_group_users(user_ids)
  raise 'Attempted to add a user to a non-group channel!' unless group?
  user_ids = [user_ids] unless user_ids.is_a? Array
  user_ids.each do |user_id|
    API::Channel.add_group_user(@bot.token, @id, user_id.resolve_id)
  end
  self
end

#await(key, attributes = {}, &block) ⇒ Object

Add an Await for a message in this channel. This is identical in functionality to adding a Events::MessageEvent await with the in attribute as this channel.

See Also:



1405
1406
1407
 
# File 'lib/discordrb/data.rb', line 1405

def await(key, attributes = {}, &block)
  @bot.add_await(key, Discordrb::Events::MessageEvent, { in: @id }.merge(attributes), &block)
end

#create_group(user_ids) ⇒ Channel

Creates a Group channel the recipient of the PM channel).

Parameters:

  • user_ids (Array<Integer>) —

    Array of user IDs to add to the new group channel (Excluding

Returns:

  • (Channel) —

    the created channel.



1432
1433
1434
1435
1436
1437
 
# File 'lib/discordrb/data.rb', line 1432

def create_group(user_ids)
  raise 'Attempted to create group channel on a non-pm channel!' unless pm?
  response = API::Channel.create_group(@bot.token, @id, user_ids.shift)
  channel = Channel.new(JSON.parse(response), @bot)
  channel.add_group_users(user_ids)
end

#define_overwrite(thing, allow, deny) ⇒ Object

Defines a permission overwrite for this channel that sets the specified thing to the specified allow and deny permission sets, or change an existing one.

Examples:

Define a permission overwrite for a user that can then mention everyone and use TTS, but not create any invites

allow = Discordrb::Permissions.new
allow.can_mention_everyone = true
allow.can_send_tts_messages = true

deny = Discordrb::Permissions.new
deny.can_create_instant_invite = true

channel.define_overwrite(user, allow, deny)

Parameters:

  • thing (User, Role) —

    What to define an overwrite for.

  • allow (#bits, Permissions, Integer) —

    The permission sets that should receive an allow override (i. e. a green checkmark on Discord)

  • deny (#bits, Permissions, Integer) —

    The permission sets that should receive a deny override (i. e. a red cross on Discord)



1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
 
# File 'lib/discordrb/data.rb', line 1281

def define_overwrite(thing, allow, deny)
  allow_bits = allow.respond_to?(:bits) ? allow.bits : allow
  deny_bits = deny.respond_to?(:bits) ? deny.bits : deny

  type = if thing.is_a?(User) || thing.is_a?(Member) || thing.is_a?(Recipient) || thing.is_a?(Profile)
           :member
         elsif thing.is_a? Role
           :role
         else
           raise ArgumentError, '`thing` in define_overwrite needs to be a kind of User (User, Member, Recipient, Profile) or a Role!'
         end

  API::Channel.update_permission(@bot.token, @id, thing.id, allow_bits, deny_bits, type)
end

#delete ⇒ Object

Permanently deletes this channel



1221
1222
1223
 
# File 'lib/discordrb/data.rb', line 1221

def delete
  API::Channel.delete(@bot.token, @id)
end

#delete_message(message) ⇒ Object

Deletes a message on this channel. Mostly useful in case a message needs to be deleted when only the ID is known

Parameters:



1216
1217
1218
 
# File 'lib/discordrb/data.rb', line 1216

def delete_message(message)
  API::Channel.delete_message(@bot.token, @id, message.resolve_id)
end

#delete_messages(messages, strict = false) ⇒ Object

Deletes a collection of messages

Parameters:

  • messages (Array<Message, Integer>) —

    the messages (or message IDs) to delete. Total must be an amount between 2 and 100 (Discord limitation)

  • strict (true, false) (defaults to: false) —

    Whether an error should be raised when a message is reached that is too old to be bulk deleted. If this is false only a warning message will be output to the console.

Raises:

  • (ArgumentError) —

    if the amount of messages is not a value between 2 and 100



1388
1389
1390
1391
1392
1393
 
# File 'lib/discordrb/data.rb', line 1388

def delete_messages(messages, strict = false)
  raise ArgumentError, 'Can only delete between 2 and 100 messages!' unless messages.count.between?(2, 100)

  messages.map!(&:resolve_id)
  bulk_delete(messages, strict)
end

#delete_overwrite(target) ⇒ Object

Deletes a permission overwrite for this channel

Parameters:



1298
1299
1300
1301
1302
 
# File 'lib/discordrb/data.rb', line 1298

def delete_overwrite(target)
  raise 'Tried deleting a overwrite for an invalid target' unless target.is_a?(Member) || target.is_a?(User) || target.is_a?(Role) || target.is_a?(Profile) || target.is_a?(Recipient) || target.respond_to?(:resolve_id)

  API::Channel.delete_permission(@bot.token, @id, target.resolve_id)
end

#group? ⇒ true, false

Returns whether or not this channel is a group channel.

Returns:

  • (true, false) —

    whether or not this channel is a group channel.



1153
1154
1155
 
# File 'lib/discordrb/data.rb', line 1153

def group?
  @type == 3
end

#history(amount, before_id = nil, after_id = nil) ⇒ Array<Message>

Retrieves some of this channel's message history.

Examples:

Count the number of messages in the last 50 messages that contain the letter 'e'.

message_count = channel.history(50).count {|message| message.content.include? "e"}

Parameters:

  • amount (Integer) —

    How many messages to retrieve. This must be less than or equal to 100, if it is higher than 100 it will be treated as 100 on Discord's side.

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

    The ID of the most recent message the retrieval should start at, or nil if it should start at the current message.

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

    The ID of the oldest message the retrieval should start at, or nil if it should start as soon as possible with the specified amount.

Returns:

  • (Array<Message>) —

    the retrieved messages.



1339
1340
1341
1342
 
# File 'lib/discordrb/data.rb', line 1339

def history(amount, before_id = nil, after_id = nil)
  logs = API::Channel.messages(@bot.token, @id, amount, before_id, after_id)
  JSON.parse(logs).map { |message| Message.new(message, @bot) }
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



1476
1477
1478
 
# File 'lib/discordrb/data.rb', line 1476

def inspect
  "<Channel name=#{@name} id=#{@id} topic=\"#{@topic}\" type=#{@type} position=#{@position} server=#{@server}>"
end

#leave_group ⇒ Object Also known as: leave

Leaves the group



1468
1469
1470
1471
 
# File 'lib/discordrb/data.rb', line 1468

def leave_group
  raise 'Attempted to leave a non-group channel!' unless group?
  API::Channel.leave_group(@bot.token, @id)
end

#load_message(message_id) ⇒ Message Also known as: message

Returns a single message from this channel's history by ID.

Parameters:

  • message_id (Integer) —

    The ID of the message to retrieve.

Returns:

  • (Message) —

    the retrieved message.



1355
1356
1357
1358
1359
1360
 
# File 'lib/discordrb/data.rb', line 1355

def load_message(message_id)
  response = API::Channel.message(@bot.token, @id, message_id)
  return Message.new(JSON.parse(response), @bot)
rescue RestClient::ResourceNotFound
  return nil
end

#make_invite(max_age = 0, max_uses = 0, temporary = false) ⇒ Invite Also known as: invite

Creates a new invite to this channel.

Parameters:

  • max_age (Integer) (defaults to: 0) —

    How many seconds this invite should last.

  • max_uses (Integer) (defaults to: 0) —

    How many times this invite should be able to be used.

  • temporary (true, false) (defaults to: false) —

    Whether membership should be temporary (kicked after going offline).

Returns:

  • (Invite) —

    the created invite.



1414
1415
1416
1417
 
# File 'lib/discordrb/data.rb', line 1414

def make_invite(max_age = 0, max_uses = 0, temporary = false)
  response = API::Channel.create_invite(@bot.token, @id, max_age, max_uses, temporary)
  Invite.new(JSON.parse(response), @bot)
end

#mention ⇒ String

Returns a string that will mention the channel as a clickable link on Discord.

Returns:

  • (String) —

    a string that will mention the channel as a clickable link on Discord.



1079
1080
1081
 
# File 'lib/discordrb/data.rb', line 1079

def mention
  "<##{@id}>"
end

#pins ⇒ Array<Message>

Requests all pinned messages of a channel.

Returns:

  • (Array<Message>) —

    the received messages.



1366
1367
1368
1369
 
# File 'lib/discordrb/data.rb', line 1366

def pins
  msgs = API::Channel.pinned_messages(@bot.token, @id)
  JSON.parse(msgs).map { |msg| Message.new(msg, @bot) }
end

#pm? ⇒ true, false

Returns whether or not this channel is a PM channel.

Returns:

  • (true, false) —

    whether or not this channel is a PM channel.



1143
1144
1145
 
# File 'lib/discordrb/data.rb', line 1143

def pm?
  @type == 1
end

#private? ⇒ true, false

Returns whether or not this channel is a PM or group channel.

Returns:

  • (true, false) —

    whether or not this channel is a PM or group channel.



1074
1075
1076
 
# File 'lib/discordrb/data.rb', line 1074

def private?
  pm? || group?
end

#prune(amount, strict = false) ⇒ Object

Delete the last N messages on this channel.

Parameters:

  • amount (Integer) —

    How many messages to delete. Must be a value between 2 and 100 (Discord limitation)

  • strict (true, false) (defaults to: false) —

    Whether an error should be raised when a message is reached that is too old to be bulk deleted. If this is false only a warning message will be output to the console.

Raises:

  • (ArgumentError) —

    if the amount of messages is not a value between 2 and 100



1376
1377
1378
1379
1380
1381
 
# File 'lib/discordrb/data.rb', line 1376

def prune(amount, strict = false)
  raise ArgumentError, 'Can only prune between 2 and 100 messages!' unless amount.between?(2, 100)

  messages = history_ids(amount)
  bulk_delete(messages, strict)
end

#recipient ⇒ Recipient?

Returns the recipient of the private messages, or nil if this is not a PM channel.

Returns:

  • (Recipient, nil) —

    the recipient of the private messages, or nil if this is not a PM channel



1084
1085
1086
 
# File 'lib/discordrb/data.rb', line 1084

def recipient
  @recipients.first if pm?
end

#remove_group_users(user_ids) ⇒ Channel Also known as: remove_group_user

Removes a user from a group channel.

Parameters:

  • user_ids (Array<#resolve_id>, #resolve_id) —

    User ID or array of user IDs to remove from the group channel.

Returns:



1456
1457
1458
1459
1460
1461
1462
1463
 
# File 'lib/discordrb/data.rb', line 1456

def remove_group_users(user_ids)
  raise 'Attempted to remove a user from a non-group channel!' unless group?
  user_ids = [user_ids] unless user_ids.is_a? Array
  user_ids.each do |user_id|
    API::Channel.remove_group_user(@bot.token, @id, user_id.resolve_id)
  end
  self
end

#send_embed(message = '', embed = nil) {|embed| ... } ⇒ Message

Convenience method to send a message with an embed.

Examples:

Send a message with an embed

channel.send_embed do |embed|
  embed.title = 'The Ruby logo'
  embed.image = Discordrb::Webhooks::EmbedImage.new(url: 'https://www.ruby-lang.org/images/header-ruby-logo.png')
end

Parameters:

  • message (String) (defaults to: '') —

    The message that should be sent along with the embed. If this is the empty string, only the embed will be shown.

  • embed (Discordrb::Webhooks::Embed, nil) (defaults to: nil) —

    The embed to start the building process with, or nil if one should be created anew.

Yields:

  • (embed) —

    Yields the embed to allow for easy building inside a block.

Yield Parameters:

  • embed (Discordrb::Webhooks::Embed) —

    The embed from the parameters, or a new one.

Returns:

  • (Message) —

    The resulting message.



1188
1189
1190
1191
1192
 
# File 'lib/discordrb/data.rb', line 1188

def send_embed(message = '', embed = nil)
  embed ||= Discordrb::Webhooks::Embed.new
  yield(embed) if block_given?
  send_message(message, false, embed)
end

#send_file(file, caption: nil, tts: false) ⇒ Object

Sends a file to this channel. If it is an image, it will be embedded.

Parameters:

  • file (File) —

    The file to send. There's no clear size limit for this, you'll have to attempt it for yourself (most non-image files are fine, large images may fail to embed)

  • caption (string) (defaults to: nil) —

    The caption for the file.

  • tts (true, false) (defaults to: false) —

    Whether or not this file's caption should be sent using Discord text-to-speech.



1210
1211
1212
 
# File 'lib/discordrb/data.rb', line 1210

def send_file(file, caption: nil, tts: false)
  @bot.send_file(@id, file, caption: caption, tts: tts)
end

#send_message(content, tts = false, embed = nil) ⇒ Message Also known as: send

Sends a message to this channel.

Parameters:

  • content (String) —

    The content to send. Should not be longer than 2000 characters or it will result in an error.

  • tts (true, false) (defaults to: false) —

    Whether or not this message should be sent using Discord text-to-speech.

  • embed (Hash, Discordrb::Webhooks::Embed, nil) (defaults to: nil) —

    The rich embed to append to this message.

Returns:

  • (Message) —

    the message that was sent.



1162
1163
1164
 
# File 'lib/discordrb/data.rb', line 1162

def send_message(content, tts = false, embed = nil)
  @bot.send_message(@id, content, tts, embed)
end

#send_multiple(content) ⇒ Object

Sends multiple messages to a channel

Parameters:

  • content (Array<String>) —

    The messages to send.



1196
1197
1198
 
# File 'lib/discordrb/data.rb', line 1196

def send_multiple(content)
  content.each { |e| send_message(e) }
end

#send_temporary_message(content, timeout, tts = false, embed = nil) ⇒ Object

Sends a temporary message to this channel.

Parameters:

  • content (String) —

    The content to send. Should not be longer than 2000 characters or it will result in an error.

  • timeout (Float) —

    The amount of time in seconds after which the message sent will be deleted.

  • tts (true, false) (defaults to: false) —

    Whether or not this message should be sent using Discord text-to-speech.

  • embed (Hash, Discordrb::Webhooks::Embed, nil) (defaults to: nil) —

    The rich embed to append to this message.



1173
1174
1175
 
# File 'lib/discordrb/data.rb', line 1173

def send_temporary_message(content, timeout, tts = false, embed = nil)
  @bot.send_temporary_message(@id, content, timeout, tts, embed)
end

#split_send(content) ⇒ Object

Splits a message into chunks whose length is at most the Discord character limit, then sends them individually. Useful for sending long messages, but be wary of rate limits!



1202
1203
1204
 
# File 'lib/discordrb/data.rb', line 1202

def split_send(content)
  send_multiple(Discordrb.split_message(content))
end

#start_typing ⇒ Object

Starts typing, which displays the typing indicator on the client for five seconds. If you want to keep typing you'll have to resend this every five seconds. (An abstraction for this will eventually be coming)



1424
1425
1426
 
# File 'lib/discordrb/data.rb', line 1424

def start_typing
  API::Channel.start_typing(@bot.token, @id)
end

#text? ⇒ true, false

Returns whether or not this channel is a text channel.

Returns:

  • (true, false) —

    whether or not this channel is a text channel



1138
1139
1140
 
# File 'lib/discordrb/data.rb', line 1138

def text?
  @type.zero?
end

#users ⇒ Array<Member>

The list of users currently in this channel. For a voice channel, it will return all the members currently in that channel. For a text channel, it will return all online members that have permission to read it.

Returns:

  • (Array<Member>) —

    the users in this channel



1321
1322
1323
1324
1325
1326
1327
 
# File 'lib/discordrb/data.rb', line 1321

def users
  if text?
    @server.online_members(include_idle: true).select { |u| u.can_read_messages? self }
  elsif voice?
    @server.voice_states.map { |id, voice_state| @server.member(id) if !voice_state.voice_channel.nil? && voice_state.voice_channel.id == @id }.compact
  end
end

#voice? ⇒ true, false

Returns whether or not this channel is a voice channel.

Returns:

  • (true, false) —

    whether or not this channel is a voice channel.



1148
1149
1150
 
# File 'lib/discordrb/data.rb', line 1148

def voice?
  @type == 2
end