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

#bitrateInteger

Returns the bitrate (in bps) of the channel.

Returns:

  • (Integer)

    the bitrate (in bps) of the channel


1245
1246
1247
# File 'lib/discordrb/data.rb', line 1245

def bitrate
  @bitrate
end

#nameString

Returns this channel's name.

Returns:

  • (String)

    this channel's name.


1227
1228
1229
# File 'lib/discordrb/data.rb', line 1227

def name
  @name
end

#nsfwtrue, false Also known as: nsfw?

Returns if this channel is marked as nsfw.

Returns:

  • (true, false)

    if this channel is marked as nsfw


1255
1256
1257
# File 'lib/discordrb/data.rb', line 1255

def nsfw
  @nsfw
end

#owner_idInteger? (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.


1236
1237
1238
# File 'lib/discordrb/data.rb', line 1236

def owner_id
  @owner_id
end

#positionInteger

Returns the channel's position on the channel list.

Returns:

  • (Integer)

    the channel's position on the channel list


1252
1253
1254
# File 'lib/discordrb/data.rb', line 1252

def position
  @position
end

#recipientsArray<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


1239
1240
1241
# File 'lib/discordrb/data.rb', line 1239

def recipients
  @recipients
end

#serverServer? (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.


1230
1231
1232
# File 'lib/discordrb/data.rb', line 1230

def server
  @server
end

#topicString

Returns the channel's topic.

Returns:

  • (String)

    the channel's topic


1242
1243
1244
# File 'lib/discordrb/data.rb', line 1242

def topic
  @topic
end

#typeInteger (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)


1233
1234
1235
# File 'lib/discordrb/data.rb', line 1233

def type
  @type
end

#user_limitInteger 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.


1248
1249
1250
# File 'lib/discordrb/data.rb', line 1248

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:


1713
1714
1715
1716
1717
1718
1719
1720
# File 'lib/discordrb/data.rb', line 1713

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:


1674
1675
1676
# File 'lib/discordrb/data.rb', line 1674

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

Parameters:

  • user_ids (Array<Integer>)

    Array of user IDs to add to the new group channel (Excluding the recipient of the PM channel).

Returns:

  • (Channel)

    the created channel.


1703
1704
1705
1706
1707
1708
# File 'lib/discordrb/data.rb', line 1703

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

#default_channel?true, false Also known as: default?

Returns whether or not this channel is the default channel.

Returns:

  • (true, false)

    whether or not this channel is the default channel


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

def default_channel?
  server.default_channel == self
end

#define_overwrite(overwrite) ⇒ Object #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.

Overloads:

  • #define_overwrite(overwrite) ⇒ Object

    Parameters:

    • thing (Overwrite)

      an Overwrite object to apply to this channel

    • reason (String)

      The reason the for defining the overwrite.

  • #define_overwrite(thing, allow, deny) ⇒ Object

    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)

    • reason (String)

      The reason the for defining the overwrite.


1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
# File 'lib/discordrb/data.rb', line 1532

def define_overwrite(thing, allow = 0, deny = 0, reason: nil)
  unless thing.is_a? Overwrite
    allow_bits = allow.respond_to?(:bits) ? allow.bits : allow
    deny_bits = deny.respond_to?(:bits) ? deny.bits : deny

    thing = Overwrite.new thing, allow: allow_bits, deny: deny_bits
  end

  API::Channel.update_permission(@bot.token, @id, thing.id, thing.allow.bits, thing.deny.bits, thing.type, reason)
end

#delete(reason = nil) ⇒ Object

Permanently deletes this channel

Parameters:

  • reason (String) (defaults to: nil)

    The reason the for the channel deletion.


1450
1451
1452
# File 'lib/discordrb/data.rb', line 1450

def delete(reason = nil)
  API::Channel.delete(@bot.token, @id, reason)
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:


1444
1445
1446
# File 'lib/discordrb/data.rb', line 1444

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

#delete_messages(messages, strict = false) ⇒ Integer

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.

Returns:

  • (Integer)

    The amount of messages that were successfully deleted

Raises:

  • (ArgumentError)

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


1657
1658
1659
1660
1661
1662
# File 'lib/discordrb/data.rb', line 1657

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, reason = nil) ⇒ Object

Deletes a permission overwrite for this channel

Parameters:


1546
1547
1548
1549
1550
# File 'lib/discordrb/data.rb', line 1546

def delete_overwrite(target, reason = nil)
  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, reason)
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.


1336
1337
1338
# File 'lib/discordrb/data.rb', line 1336

def group?
  @type == 3
end

#history(amount, before_id = nil, after_id = nil, around_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.

  • around_id (Integer) (defaults to: nil)

    The ID of the message retrieval should start from, reading in both directions

Returns:

  • (Array<Message>)

    the retrieved messages.


1589
1590
1591
1592
# File 'lib/discordrb/data.rb', line 1589

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

#inspectObject

The inspect method is overwritten to give more useful output


1763
1764
1765
# File 'lib/discordrb/data.rb', line 1763

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

#invitesArray<Invite>

Requests a list of Invites to the channel

Returns:

  • (Array<Invite>)

    invites to the channel.


1756
1757
1758
1759
1760
# File 'lib/discordrb/data.rb', line 1756

def invites
  raise 'Tried to request invites from a non-server channel' unless server
  invites = JSON.parse(API::Channel.invites(@bot.token, @id))
  invites.map { |invite_data| Invite.new(invite_data, @bot) }
end

#leave_groupObject Also known as: leave

Leaves the group


1739
1740
1741
1742
# File 'lib/discordrb/data.rb', line 1739

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, nil)

    the retrieved message, or nil if it couldn't be found.


1605
1606
1607
1608
1609
1610
# File 'lib/discordrb/data.rb', line 1605

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, unique = false, reason = nil) ⇒ 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).

  • unique (true, false) (defaults to: false)

    If true, Discord will always send a unique invite instead of possibly re-using a similar one

  • reason (String) (defaults to: nil)

    The reason the for the creation of this invite.

Returns:

  • (Invite)

    the created invite.


1685
1686
1687
1688
# File 'lib/discordrb/data.rb', line 1685

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

#member_overwritesOverwrite

Returns any member-type permission overwrites on this channel.

Returns:

  • (Overwrite)

    any member-type permission overwrites on this channel


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

def member_overwrites
  permission_overwrites :member
end

#mentionString

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.


1264
1265
1266
# File 'lib/discordrb/data.rb', line 1264

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

#permission_overwritesHash<Integer => Overwrite> #permission_overwrites(type) ⇒ Array<Overwrite> Also known as: overwrites

This channel's permission overwrites

Overloads:

  • #permission_overwritesHash<Integer => Overwrite>

    The overwrites represented as a hash of role/user ID to an Overwrite object

    Returns:

  • #permission_overwrites(type) ⇒ Array<Overwrite>

    Return an array of a certain type of overwrite

    Parameters:

    • type (Symbol)

      the kind of overwrite to return

    Returns:


1359
1360
1361
1362
# File 'lib/discordrb/data.rb', line 1359

def permission_overwrites(type = nil)
  return @permission_overwrites unless type
  @permission_overwrites.values.select { |e| e.type == type }
end

#pinsArray<Message>

Requests all pinned messages of a channel.

Returns:

  • (Array<Message>)

    the received messages.


1616
1617
1618
1619
# File 'lib/discordrb/data.rb', line 1616

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.


1326
1327
1328
# File 'lib/discordrb/data.rb', line 1326

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.


1259
1260
1261
# File 'lib/discordrb/data.rb', line 1259

def private?
  pm? || group?
end

#prune(amount, strict = false) {|message| ... } ⇒ Integer

Delete the last N messages on this channel.

Examples:

Pruning messages from a specific user ID

channel.prune(100) { |m| m.author.id == 83283213010599936 }

Parameters:

  • amount (Integer)

    The amount of message history to consider for pruning. 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.

Yields:

  • (message)

    Yields each message in this channels history for filtering the messages to delete

Returns:

  • (Integer)

    The amount of messages that were successfully deleted

Raises:

  • (ArgumentError)

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


1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
# File 'lib/discordrb/data.rb', line 1630

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

  messages =
    if block_given?
      history(amount).select(&block).map(&:id)
    else
      history_ids(amount)
    end

  case messages.size
  when 0
    0
  when 1
    API::Channel.delete_message(@bot.token, @id, messages.first)
    1
  else
    bulk_delete(messages, strict)
  end
end

#recipientRecipient?

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


1269
1270
1271
# File 'lib/discordrb/data.rb', line 1269

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:


1727
1728
1729
1730
1731
1732
1733
1734
# File 'lib/discordrb/data.rb', line 1727

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

#role_overwritesOverwrite

Returns any role-type permission overwrites on this channel.

Returns:

  • (Overwrite)

    any role-type permission overwrites on this channel


1372
1373
1374
# File 'lib/discordrb/data.rb', line 1372

def role_overwrites
  permission_overwrites :role
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:

Returns:

  • (Message)

    The resulting message.


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

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.

Examples:

Send a file from disk

channel.send_file(File.open('rubytaco.png', 'r'))

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.


1438
1439
1440
# File 'lib/discordrb/data.rb', line 1438

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.


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

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.


1422
1423
1424
# File 'lib/discordrb/data.rb', line 1422

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.


1399
1400
1401
# File 'lib/discordrb/data.rb', line 1399

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!


1428
1429
1430
# File 'lib/discordrb/data.rb', line 1428

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

#start_typingObject

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)


1695
1696
1697
# File 'lib/discordrb/data.rb', line 1695

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


1321
1322
1323
# File 'lib/discordrb/data.rb', line 1321

def text?
  @type.zero?
end

#update(name: @name, bitrate: @bitrate, user_limit: @user_limit, topic: @topic, position: @position, reason: nil) ⇒ Object

Updates this channel's settings.

Parameters:

  • name (String) (defaults to: @name)

    Name of the channel to create

  • bitrate (Integer) (defaults to: @bitrate)

    The new bitrate (in bps). Number has to be between 8000-96000 (128000 for VIP servers)

  • user_limit (Integer) (defaults to: @user_limit)

    The new user limit. 0 for unlimited, has to be a number between 0-99

  • topic (String) (defaults to: @topic)

    The new topic.

  • position (Integer) (defaults to: @position)

    The new position.

  • reason (String) (defaults to: nil)

    The reason the for the changes requested for this channel.


1501
1502
1503
1504
1505
1506
1507
1508
1509
# File 'lib/discordrb/data.rb', line 1501

def update(name: @name, bitrate: @bitrate, user_limit: @user_limit, topic: @topic, position: @position, reason: nil)
  API::Channel.create_channel(@bot.token, @id, name, type, bitrate, user_limit, permission_overwrites, reason)
  @topic = topic
  @name = name
  @position = position
  @topic = topic
  @bitrate = bitrate
  @user_limit = user_limit
end

#usersArray<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


1570
1571
1572
1573
1574
1575
1576
# File 'lib/discordrb/data.rb', line 1570

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.


1331
1332
1333
# File 'lib/discordrb/data.rb', line 1331

def voice?
  @type == 2
end

#webhooksArray<Webhook>

Requests a list of Webhooks on the channel

Returns:

  • (Array<Webhook>)

    webhooks on the channel.


1748
1749
1750
1751
1752
# File 'lib/discordrb/data.rb', line 1748

def webhooks
  raise 'Tried to request webhooks from a non-server channel' unless server
  webhooks = JSON.parse(API::Channel.webhooks(@bot.token, @id))
  webhooks.map { |webhook_data| Webhook.new(webhook_data, @bot) }
end