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

Instance Attribute Details

#bitrate ⇒ Integer

Returns the bitrate (in bps) of the channel.

Returns:

  • (Integer) —

    the bitrate (in bps) of the channel



1021
1022
1023
 
# File 'lib/discordrb/data.rb', line 1021

def bitrate
  @bitrate
end

#name ⇒ String

Returns this channel's name.

Returns:

  • (String) —

    this channel's name.



1003
1004
1005
 
# File 'lib/discordrb/data.rb', line 1003

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.



1012
1013
1014
 
# File 'lib/discordrb/data.rb', line 1012

def owner_id
  @owner_id
end

#permission_overwrites ⇒ Hash<Integer => OpenStruct> (readonly)

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



1033
1034
1035
 
# File 'lib/discordrb/data.rb', line 1033

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



1028
1029
1030
 
# File 'lib/discordrb/data.rb', line 1028

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



1015
1016
1017
 
# File 'lib/discordrb/data.rb', line 1015

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.



1006
1007
1008
 
# File 'lib/discordrb/data.rb', line 1006

def server
  @server
end

#topic ⇒ String

Returns the channel's topic.

Returns:

  • (String) —

    the channel's topic



1018
1019
1020
 
# File 'lib/discordrb/data.rb', line 1018

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)



1009
1010
1011
 
# File 'lib/discordrb/data.rb', line 1009

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.



1024
1025
1026
 
# File 'lib/discordrb/data.rb', line 1024

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:



1362
1363
1364
1365
1366
1367
1368
1369
 
# File 'lib/discordrb/data.rb', line 1362

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:



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

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.



1352
1353
1354
1355
1356
1357
 
# File 'lib/discordrb/data.rb', line 1352

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)



1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
 
# File 'lib/discordrb/data.rb', line 1218

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



1158
1159
1160
 
# File 'lib/discordrb/data.rb', line 1158

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

#delete_messages(messages) ⇒ 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)

Raises:

  • (ArgumentError) —

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



1308
1309
1310
1311
1312
1313
 
# File 'lib/discordrb/data.rb', line 1308

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

  messages.map!(&:resolve_id)
  API::Channel.bulk_delete_messages(@bot.token, @id, messages)
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.



1115
1116
1117
 
# File 'lib/discordrb/data.rb', line 1115

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.



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

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



1396
1397
1398
 
# File 'lib/discordrb/data.rb', line 1396

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



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

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.



1279
1280
1281
1282
1283
1284
 
# File 'lib/discordrb/data.rb', line 1279

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.



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

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.



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

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

#pins ⇒ Array<Message>

Requests all pinned messages of a channel.

Returns:

  • (Array<Message>) —

    the received messages.



1290
1291
1292
1293
 
# File 'lib/discordrb/data.rb', line 1290

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.



1105
1106
1107
 
# File 'lib/discordrb/data.rb', line 1105

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.



1036
1037
1038
 
# File 'lib/discordrb/data.rb', line 1036

def private?
  pm? || group?
end

#prune(amount) ⇒ 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)

Raises:

  • (ArgumentError) —

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



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

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

  messages = history_ids(amount)
  API::Channel.bulk_delete_messages(@bot.token, @id, messages)
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



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

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:



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

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



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

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

#send_message(content, tts = false) ⇒ 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.

Returns:

  • (Message) —

    the message that was sent.



1123
1124
1125
 
# File 'lib/discordrb/data.rb', line 1123

def send_message(content, tts = false)
  @bot.send_message(@id, content, tts, @server && @server.id)
end

#send_multiple(content) ⇒ Object

Sends multiple messages to a channel

Parameters:

  • content (Array<String>) —

    The messages to send.



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

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

#send_temporary_message(content, timeout, tts = false) ⇒ 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.



1133
1134
1135
 
# File 'lib/discordrb/data.rb', line 1133

def send_temporary_message(content, timeout, tts = false)
  @bot.send_temporary_message(@id, content, timeout, tts, @server && @server.id)
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!



1145
1146
1147
 
# File 'lib/discordrb/data.rb', line 1145

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)



1344
1345
1346
 
# File 'lib/discordrb/data.rb', line 1344

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



1100
1101
1102
 
# File 'lib/discordrb/data.rb', line 1100

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



1245
1246
1247
1248
1249
1250
1251
 
# File 'lib/discordrb/data.rb', line 1245

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.



1110
1111
1112
 
# File 'lib/discordrb/data.rb', line 1110

def voice?
  @type == 2
end