Class: Discordrb::Server

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

Overview

A server on Discord

Constant Summary collapse

VERIFICATION_LEVELS =

A map of possible server verification levels to symbol names

{
  none: 0,
  low: 1,
  medium: 2,
  high: 3,
  very_high: 4
}.freeze
NOTIFICATION_LEVELS =

A map of possible message notification levels to symbol names

{
  all_messages: 0,
  only_mentions: 1
}.freeze
FILTER_LEVELS =

A map of possible content filter levels to symbol names

{
  disabled: 0,
  members_without_roles: 1,
  all_members: 2
}.freeze

Instance Attribute Summary collapse

Attributes included from ServerAttributes

#icon_id, #name

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from ServerAttributes

#icon_url

Methods included from IDObject

#==, #creation_time, synthesise

Instance Attribute Details

#afk_timeout ⇒ Integer

Returns the amount of time after which a voice user gets moved into the AFK channel, in seconds.

Returns:

  • (Integer) —

    the amount of time after which a voice user gets moved into the AFK channel, in seconds.



51
52
53
 
# File 'lib/discordrb/data/server.rb', line 51

def afk_timeout
  @afk_timeout
end

#boost_level ⇒ Integer (readonly)

The server's Nitro boost level.

Returns:

  • (Integer) —

    the boost level, 0 if no level.



62
63
64
 
# File 'lib/discordrb/data/server.rb', line 62

def boost_level
  @boost_level
end

#booster_count ⇒ Integer (readonly)

The server's amount of Nitro boosters.

Returns:

  • (Integer) —

    the amount of boosters, 0 if no one has boosted.



58
59
60
 
# File 'lib/discordrb/data/server.rb', line 58

def booster_count
  @booster_count
end

#channels ⇒ Array<Channel> (readonly)

Returns an array of all the channels (text and voice) on this server.

Returns:

  • (Array<Channel>) —

    an array of all the channels (text and voice) on this server.



30
31
32
 
# File 'lib/discordrb/data/server.rb', line 30

def channels
  @channels
end

#emoji ⇒ Hash<Integer => Emoji> (readonly) Also known as: emojis

Returns a hash of all the emoji available on this server.

Returns:

  • (Hash<Integer => Emoji>) —

    a hash of all the emoji available on this server.



36
37
38
 
# File 'lib/discordrb/data/server.rb', line 36

def emoji
  @emoji
end

#features ⇒ Array<Symbol> (readonly)

Returns the features of the server (eg. "INVITE_SPLASH").

Returns:

  • (Array<Symbol>) —

    the features of the server (eg. "INVITE_SPLASH")



45
46
47
 
# File 'lib/discordrb/data/server.rb', line 45

def features
  @features
end

#large ⇒ true, false (readonly) Also known as: large?

it means the members list may be inaccurate for a couple seconds after starting up the bot.

Returns:

  • (true, false) —

    whether or not this server is large (members > 100). If it is,



41
42
43
 
# File 'lib/discordrb/data/server.rb', line 41

def large
  @large
end

#member_count ⇒ Integer (readonly)

Returns the absolute number of members on this server, offline or not.

Returns:

  • (Integer) —

    the absolute number of members on this server, offline or not.



48
49
50
 
# File 'lib/discordrb/data/server.rb', line 48

def member_count
  @member_count
end

#region_id ⇒ String (readonly)

Returns the ID of the region the server is on (e.g. amsterdam).

Returns:

  • (String) —

    the ID of the region the server is on (e.g. amsterdam).



27
28
29
 
# File 'lib/discordrb/data/server.rb', line 27

def region_id
  @region_id
end

#roles ⇒ Array<Role> (readonly)

Returns an array of all the roles created on this server.

Returns:

  • (Array<Role>) —

    an array of all the roles created on this server.



33
34
35
 
# File 'lib/discordrb/data/server.rb', line 33

def roles
  @roles
end

#voice_states ⇒ Hash<Integer => VoiceState> (readonly)

Returns the hash (user ID => voice state) of voice states of members on this server.

Returns:

  • (Hash<Integer => VoiceState>) —

    the hash (user ID => voice state) of voice states of members on this server



54
55
56
 
# File 'lib/discordrb/data/server.rb', line 54

def voice_states
  @voice_states
end

Instance Method Details

#add_emoji(name, image, roles = [], reason: nil) ⇒ Emoji

Adds a new custom emoji on this server.

Parameters:

  • name (String) —

    The name of emoji to create.

  • image (String, #read) —

    A base64 encoded string with the image data, or an object that responds to #read, such as File.

  • roles (Array<Role, String, Integer>) (defaults to: []) —

    An array of roles, or role IDs to be whitelisted for this emoji.

  • reason (String) (defaults to: nil) —

    The reason the for the creation of this emoji.

Returns:

  • (Emoji) —

    The emoji that has been added.



562
563
564
565
566
567
568
 
# File 'lib/discordrb/data/server.rb', line 562

def add_emoji(name, image, roles = [], reason: nil)
  image = image.respond_to?(:read) ? Discordrb.encode64(image) : image

  data = JSON.parse(API::Server.add_emoji(@bot.token, @id, image, name, roles.map(&:resolve_id), reason))
  new_emoji = Emoji.new(data, @bot, self)
  @emoji[new_emoji.id] = new_emoji
end

#add_member_using_token(user, access_token, nick: nil, roles: [], deaf: false, mute: false) ⇒ Member?

Note:

Your bot must be present in this server, and have permission to create instant invites for this to work.

Adds a member to this guild that has granted this bot's application an OAuth2 access token with the guilds.join scope. For more information about Discord's OAuth2 implementation, see: https://discord.com/developers/docs/topics/oauth2

Parameters:

  • user (User, String, Integer) —

    the user, or ID of the user to add to this server

  • access_token (String) —

    the OAuth2 Bearer token that has been granted the guilds.join scope

  • nick (String) (defaults to: nil) —

    the nickname to give this member upon joining

  • roles (Role, Array<Role, String, Integer>) (defaults to: []) —

    the role (or roles) to give this member upon joining

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

    whether this member will be server deafened upon joining

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

    whether this member will be server muted upon joining

Returns:

  • (Member, nil) —

    the created member, or nil if the user is already a member of this server.



271
272
273
274
275
276
277
278
 
# File 'lib/discordrb/data/server.rb', line 271

def add_member_using_token(user, access_token, nick: nil, roles: [], deaf: false, mute: false)
  user_id = user.resolve_id
  roles = roles.is_a?(Array) ? roles.map(&:resolve_id) : [roles.resolve_id]
  response = API::Server.add_member(@bot.token, @id, user_id, access_token, nick, roles, deaf, mute)
  return nil if response.empty?

  add_member Member.new(JSON.parse(response), self, @bot)
end

#afk_channel ⇒ Channel?

Returns the AFK voice channel of this server, or nil if none is set.

Returns:

  • (Channel, nil) —

    the AFK voice channel of this server, or nil if none is set.



849
850
851
 
# File 'lib/discordrb/data/server.rb', line 849

def afk_channel
  @bot.channel(@afk_channel_id) if @afk_channel_id
end

#afk_channel=(afk_channel) ⇒ Object

Sets the server's AFK channel.

Parameters:

  • afk_channel (Channel, nil) —

    The new AFK channel, or nil if there should be none set.



724
725
726
 
# File 'lib/discordrb/data/server.rb', line 724

def afk_channel=(afk_channel)
  update_server_data(afk_channel_id: afk_channel.resolve_id)
end

#any_emoji? ⇒ true, false Also known as: has_emoji?, emoji?

Returns whether this server has any emoji or not.

Returns:

  • (true, false) —

    whether this server has any emoji or not.



812
813
814
 
# File 'lib/discordrb/data/server.rb', line 812

def any_emoji?
  @emoji.any?
end

#audit_logs(action: nil, user: nil, limit: 50, before: nil) ⇒ AuditLogs

Returns The server's audit logs.

Parameters:

  • action (Symbol) (defaults to: nil) —

    The action to only include.

  • user (User, String, Integer) (defaults to: nil) —

    The user, or their ID, to filter entries to.

  • limit (Integer) (defaults to: 50) —

    The amount of entries to limit it to.

  • before (Entry, String, Integer) (defaults to: nil) —

    The entry, or its ID, to use to not include all entries after it.

Returns:



172
173
174
175
176
177
178
179
 
# File 'lib/discordrb/data/server.rb', line 172

def audit_logs(action: nil, user: nil, limit: 50, before: nil)
  raise 'Invalid audit log action!' if action && AuditLogs::ACTIONS.key(action).nil?

  action = AuditLogs::ACTIONS.key(action)
  user = user.resolve_id if user
  before = before.resolve_id if before
  AuditLogs.new(self, @bot, JSON.parse(API::Server.audit_logs(@bot.token, @id, limit, user, action, before)))
end

#available_voice_regions ⇒ Array<VoiceRegion>

Returns collection of available voice regions to this guild.

Returns:

  • (Array<VoiceRegion>) —

    collection of available voice regions to this guild



691
692
693
694
695
696
697
698
 
# File 'lib/discordrb/data/server.rb', line 691

def available_voice_regions
  return @available_voice_regions if @available_voice_regions

  @available_voice_regions = {}

  data = JSON.parse API::Server.regions(@bot.token, @id)
  @available_voice_regions = data.map { |e| VoiceRegion.new e }
end

#ban(user, message_days = 0, message_seconds: nil, reason: nil) ⇒ Object

Bans a user from this server.

Parameters:

  • user (User, String, Integer) —

    The user to ban.

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

    How many days worth of messages sent by the user should be deleted. This is deprecated and will be removed in 4.0.

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

    How many seconds of messages sent by the user should be deleted.

  • reason (String) (defaults to: nil) —

    The reason the user is being banned.



633
634
635
636
637
638
639
640
641
 
# File 'lib/discordrb/data/server.rb', line 633

def ban(user, message_days = 0, message_seconds: nil, reason: nil)
  delete_messages = if message_days != 0 && message_days
                      message_days * 86_400
                    else
                      message_seconds || 0
                    end

  API::Server.ban_user!(@bot.token, @id, user.resolve_id, delete_messages, reason)
end

Returns the hexadecimal ID used to identify this server's banner image, shown by the server name.

Returns:

  • (String) —

    the hexadecimal ID used to identify this server's banner image, shown by the server name.



370
371
372
 
# File 'lib/discordrb/data/server.rb', line 370

def banner_id
  @banner_id ||= JSON.parse(API::Server.resolve(@bot.token, @id))['banner']
end

Returns the banner image URL for the server's banner image, or nil if there is no banner image.

Returns:

  • (String, nil) —

    the banner image URL for the server's banner image, or nil if there is no banner image.



376
377
378
379
380
381
 
# File 'lib/discordrb/data/server.rb', line 376

def banner_url
  banner_id if @banner_id.nil?
  return unless banner_id

  API.banner_url(@id, @banner_id)
end

#bans(limit: nil, before_id: nil, after_id: nil) ⇒ Array<ServerBan>

Retrieve banned users from this server.

Parameters:

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

    Number of users to return (up to maximum 1000, default 1000).

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

    Consider only users before given user id.

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

    Consider only users after given user id.

Returns:

  • (Array<ServerBan>) —

    a list of banned users on this server and the reason they were banned.



621
622
623
624
625
626
 
# File 'lib/discordrb/data/server.rb', line 621

def bans(limit: nil, before_id: nil, after_id: nil)
  response = JSON.parse(API::Server.bans(@bot.token, @id, limit, before_id, after_id))
  response.map do |e|
    ServerBan.new(self, User.new(e['user'], @bot), e['reason'])
  end
end

#begin_prune(days, reason = nil) ⇒ Integer Also known as: prune

Prunes (kicks) an amount of members for inactivity

Parameters:

  • days (Integer) —

    the number of days to consider for inactivity (between 1 and 30)

  • reason (String) (defaults to: nil) —

    The reason the for the prune.

Returns:

  • (Integer) —

    the number of members removed at the end of the operation

Raises:

  • (ArgumentError) —

    if days is not between 1 and 30 (inclusive)



296
297
298
299
300
301
 
# File 'lib/discordrb/data/server.rb', line 296

def begin_prune(days, reason = nil)
  raise ArgumentError, 'Days must be between 1 and 30' unless days.between?(1, 30)

  response = JSON.parse API::Server.begin_prune(@bot.token, @id, days, reason)
  response['pruned']
end

#bot ⇒ Member

Returns the bot's own Member on this server.

Returns:

  • (Member) —

    the bot's own Member on this server



157
158
159
 
# File 'lib/discordrb/data/server.rb', line 157

def bot
  member(@bot.profile)
end

#bot_members ⇒ Array<Member>

Returns an array of all the bot members on this server.

Returns:

  • (Array<Member>) —

    an array of all the bot members on this server.



147
148
149
 
# File 'lib/discordrb/data/server.rb', line 147

def bot_members
  members.select(&:bot_account?)
end

#bulk_ban(users:, message_seconds: 0, reason: nil) ⇒ BulkBan

Ban up to 200 users from this server in one go.

Parameters:

  • users (Array<User, String, Integer>) —

    Array of up to 200 users to ban.

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

    How many seconds of messages sent by the users should be deleted.

  • reason (String) (defaults to: nil) —

    The reason these users are being banned.

Returns:

Raises:

  • (ArgumentError) 


655
656
657
658
659
660
661
662
 
# File 'lib/discordrb/data/server.rb', line 655

def bulk_ban(users:, message_seconds: 0, reason: nil)
  raise ArgumentError, 'Can only ban between 1 and 200 users!' unless users.size.between?(1, 200)

  return ban(users.first, 0, message_seconds: message_seconds, reason: reason) if users.size == 1

  response = API::Server.bulk_ban(@bot.token, @id, users.map(&:resolve_id), message_seconds, reason)
  BulkBan.new(JSON.parse(response), self, reason)
end

#categories ⇒ Array<Channel>

Returns an array of category channels on this server.

Returns:

  • (Array<Channel>) —

    an array of category channels on this server



316
317
318
 
# File 'lib/discordrb/data/server.rb', line 316

def categories
  @channels.select(&:category?)
end

#create_channel(name, type = 0, topic: nil, bitrate: nil, user_limit: nil, permission_overwrites: nil, parent: nil, nsfw: false, rate_limit_per_user: nil, position: nil, reason: nil) ⇒ Channel

Note:

If parent is provided, permission overwrites have the follow behavior:

  1. If overwrites is null, the new channel inherits the parent's permissions.
  2. If overwrites is [], the new channel inherits the parent's permissions.
  3. If you supply one or more overwrites, the channel will be created with those permissions and ignore the parents.

Creates a channel on this server with the given name.

Parameters:

  • name (String) —

    Name of the channel to create

  • type (Integer, Symbol) (defaults to: 0) —

    Type of channel to create (0: text, 2: voice, 4: category, 5: news, 6: store)

  • topic (String) (defaults to: nil) —

    the topic of this channel, if it will be a text channel

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

    the bitrate of this channel, if it will be a voice channel

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

    the user limit of this channel, if it will be a voice channel

  • permission_overwrites (Array<Hash>, Array<Overwrite>) (defaults to: nil) —

    permission overwrites for this channel

  • parent (Channel, String, Integer) (defaults to: nil) —

    parent category, or its ID, for this channel to be created in.

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

    whether this channel should be created as nsfw

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

    how many seconds users need to wait in between messages.

  • reason (String) (defaults to: nil) —

    The reason the for the creation of this channel.

Returns:

  • (Channel) —

    the created channel.

Raises:

  • (ArgumentError) —

    if type is not 0 (text), 2 (voice), 4 (category), 5 (news), or 6 (store)



499
500
501
502
503
504
505
506
507
 
# File 'lib/discordrb/data/server.rb', line 499

def create_channel(name, type = 0, topic: nil, bitrate: nil, user_limit: nil, permission_overwrites: nil, parent: nil, nsfw: false, rate_limit_per_user: nil, position: nil, reason: nil)
  type = Channel::TYPES[type] if type.is_a?(Symbol)
  raise ArgumentError, 'Channel type must be either 0 (text), 2 (voice), 4 (category), news (5), or store (6)!' unless [0, 2, 4, 5, 6].include?(type)

  permission_overwrites.map! { |e| e.is_a?(Overwrite) ? e.to_hash : e } if permission_overwrites.is_a?(Array)
  parent_id = parent.respond_to?(:resolve_id) ? parent.resolve_id : nil
  response = API::Server.create_channel(@bot.token, @id, name, type, topic, bitrate, user_limit, permission_overwrites, parent_id, nsfw, rate_limit_per_user, position, reason)
  Channel.new(JSON.parse(response), @bot)
end

#create_role(name: 'new role', colour: 0, hoist: false, mentionable: false, permissions: 104_324_161, secondary_colour: nil, tertiary_colour: nil, icon: nil, unicode_emoji: nil, display_icon: nil, reason: nil) ⇒ Role

Creates a role on this server which can then be modified. It will be initialized with the regular role defaults the client uses unless specified, i.e. name is "new role", permissions are the default, colour is the default etc.

Parameters:

  • name (String) (defaults to: 'new role') —

    Name of the role to create.

  • colour (Integer, ColourRGB, #combined) (defaults to: 0) —

    The primary colour of the role to create.

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

    whether members of this role should be displayed seperately in the members list.

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

    whether this role can mentioned by anyone in the server.

  • permissions (Integer, Array<Symbol>, Permissions, #bits) (defaults to: 104_324_161) —

    The permissions to write to the new role.

  • icon (String, #read, nil) (defaults to: nil) —

    The base64 encoded image data, or a file like object that responds to #read.

  • unicode_emoji (String, nil) (defaults to: nil) —

    The unicode emoji of the role to create, or nil.

  • display_icon (String, File, #read, nil) (defaults to: nil) —

    The icon to display for the role. Overrides the icon and unicode_emoji parameters if passed.

  • reason (String) (defaults to: nil) —

    The reason the for the creation of this role.

  • secondary_colour (Integer, ColourRGB, nil) (defaults to: nil) —

    The secondary colour of the role to create.

  • tertiary_colour (Integer, ColourRGB, nil) (defaults to: nil) —

    The tertiary colour of the role to create.

Returns:

  • (Role) —

    the created role.



524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
 
# File 'lib/discordrb/data/server.rb', line 524

def create_role(name: 'new role', colour: 0, hoist: false, mentionable: false, permissions: 104_324_161, secondary_colour: nil, tertiary_colour: nil, icon: nil, unicode_emoji: nil, display_icon: nil, reason: nil)
  colour = colour.respond_to?(:combined) ? colour.combined : colour

  permissions = if permissions.is_a?(Array)
                  Permissions.bits(permissions)
                elsif permissions.respond_to?(:bits)
                  permissions.bits
                else
                  permissions
                end

  icon = icon.respond_to?(:read) ? Discordrb.encode64(icon) : icon

  colours = {
    primary_color: colour&.to_i,
    tertiary_color: tertiary_colour&.to_i,
    secondary_color: secondary_colour&.to_i
  }

  if display_icon.is_a?(String)
    unicode_emoji = display_icon
  elsif display_icon.respond_to?(:read)
    icon = Discordrb.encode64(display_icon)
  end

  response = API::Server.create_role(@bot.token, @id, name, nil, hoist, mentionable, permissions&.to_s, reason, colours, icon, unicode_emoji)

  role = Role.new(JSON.parse(response), @bot, self)
  @roles << role
  role
end

#default_channel(send_messages = false) ⇒ Channel? Also known as: general_channel

The default channel is the text channel on this server with the highest position that the bot has Read Messages permission on.

Parameters:

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

    whether to additionally consider if the bot has Send Messages permission

Returns:

  • (Channel, nil) —

    The default channel on this server, or nil if there are no channels that the bot can read.



89
90
91
92
93
94
95
96
97
98
 
# File 'lib/discordrb/data/server.rb', line 89

def default_channel(send_messages = false)
  bot_member = member(@bot.profile)
  text_channels.sort_by { |e| [e.position, e.id] }.find do |e|
    if send_messages
      bot_member.can_read_messages?(e) && bot_member.can_send_messages?(e)
    else
      bot_member.can_read_messages?(e)
    end
  end
end

#default_message_notifications ⇒ Symbol

Returns the default message notifications settings of the server (:all = 'All messages', :mentions = 'Only @mentions').

Returns:

  • (Symbol) —

    the default message notifications settings of the server (:all = 'All messages', :mentions = 'Only @mentions').



769
770
771
 
# File 'lib/discordrb/data/server.rb', line 769

def default_message_notifications
  NOTIFICATION_LEVELS.key @default_message_notifications
end

#default_message_notifications=(notification_level) ⇒ Object Also known as: notification_level=

Sets the default message notification level

Parameters:



775
776
777
778
779
 
# File 'lib/discordrb/data/server.rb', line 775

def default_message_notifications=(notification_level)
  notification_level = NOTIFICATION_LEVELS[notification_level] if notification_level.is_a?(Symbol)

  update_server_data(default_message_notifications: notification_level)
end

#delete_emoji(emoji, reason: nil) ⇒ Object

Delete a custom emoji on this server

Parameters:

  • emoji (Emoji, String, Integer) —

    The emoji or emoji ID to be deleted.

  • reason (String) (defaults to: nil) —

    The reason the for the deletion of this emoji.



573
574
575
 
# File 'lib/discordrb/data/server.rb', line 573

def delete_emoji(emoji, reason: nil)
  API::Server.delete_emoji(@bot.token, @id, emoji.resolve_id, reason)
end

#edit_emoji(emoji, name: nil, roles: nil, reason: nil) ⇒ Emoji

Changes the name and/or role whitelist of an emoji on this server.

Parameters:

  • emoji (Emoji, String, Integer) —

    The emoji or emoji ID to edit.

  • name (String) (defaults to: nil) —

    The new name for the emoji.

  • roles (Array<Role, String, Integer>) (defaults to: nil) —

    A new array of roles, or role IDs, to whitelist.

  • reason (String) (defaults to: nil) —

    The reason for the editing of this emoji.

Returns:

  • (Emoji) —

    The edited emoji.



583
584
585
586
587
588
 
# File 'lib/discordrb/data/server.rb', line 583

def edit_emoji(emoji, name: nil, roles: nil, reason: nil)
  emoji = @emoji[emoji.resolve_id]
  data = JSON.parse(API::Server.edit_emoji(@bot.token, @id, emoji.resolve_id, name || emoji.name, (roles || emoji.roles).map(&:resolve_id), reason))
  new_emoji = Emoji.new(data, @bot, self)
  @emoji[new_emoji.id] = new_emoji
end

#everyone_role ⇒ Role

Returns The @everyone role on this server.

Returns:

  • (Role) —

    The @everyone role on this server



103
104
105
 
# File 'lib/discordrb/data/server.rb', line 103

def everyone_role
  role(@id)
end

#explicit_content_filter ⇒ Symbol Also known as: content_filter_level

Returns the explicit content filter level of the server (:none = 'Don't scan any messages.', :exclude_roles = 'Scan messages for members without a role.', :all = 'Scan messages sent by all members.').

Returns:

  • (Symbol) —

    the explicit content filter level of the server (:none = 'Don't scan any messages.', :exclude_roles = 'Scan messages for members without a role.', :all = 'Scan messages sent by all members.').



797
798
799
 
# File 'lib/discordrb/data/server.rb', line 797

def explicit_content_filter
  FILTER_LEVELS.key @explicit_content_filter
end

#explicit_content_filter=(filter_level) ⇒ Object

Sets the server content filter.

Parameters:



805
806
807
808
809
 
# File 'lib/discordrb/data/server.rb', line 805

def explicit_content_filter=(filter_level)
  filter_level = FILTER_LEVELS[filter_level] if filter_level.is_a?(Symbol)

  update_server_data(explicit_content_filter: filter_level)
end

#icon=(icon) ⇒ Object

Sets the server's icon.

Parameters:

  • icon (String, #read) —

    The new icon, in base64-encoded JPG format.



714
715
716
717
718
719
720
 
# File 'lib/discordrb/data/server.rb', line 714

def icon=(icon)
  if icon.respond_to?(:read)
    update_server_data(icon_id: Discordrb.encode64(icon))
  else
    update_server_data(icon_id: icon)
  end
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



925
926
927
 
# File 'lib/discordrb/data/server.rb', line 925

def inspect
  "<Server name=#{@name} id=#{@id} large=#{@large} region=#{@region} owner=#{@owner} afk_channel_id=#{@afk_channel_id} system_channel_id=#{@system_channel_id} afk_timeout=#{@afk_timeout}>"
end

#integrations ⇒ Array<Integration>

Returns an array of all the integrations connected to this server.

Returns:

  • (Array<Integration>) —

    an array of all the integrations connected to this server.



162
163
164
165
 
# File 'lib/discordrb/data/server.rb', line 162

def integrations
  integration = JSON.parse(API::Server.integrations(@bot.token, @id))
  integration.map { |element| Integration.new(element, @bot, self) }
end

#invites ⇒ Array<Invite>

Requests a list of Invites to the server.

Returns:

  • (Array<Invite>) —

    invites to the server.



828
829
830
831
 
# File 'lib/discordrb/data/server.rb', line 828

def invites
  invites = JSON.parse(API::Server.invites(@bot.token, @id))
  invites.map { |invite| Invite.new(invite, @bot) }
end

#kick(user, reason = nil) ⇒ Object

Kicks a user from this server.

Parameters:

  • user (User, String, Integer) —

    The user to kick.

  • reason (String) (defaults to: nil) —

    The reason the user is being kicked.



667
668
669
 
# File 'lib/discordrb/data/server.rb', line 667

def kick(user, reason = nil)
  API::Server.remove_member(@bot.token, @id, user.resolve_id, reason)
end

#leave ⇒ Object

Leave the server.



680
681
682
 
# File 'lib/discordrb/data/server.rb', line 680

def leave
  API::User.leave_server(@bot.token, @id)
end

#link ⇒ String Also known as: jump_link

Returns a URL that a user can use to navigate to this server in the client.

Returns:

  • (String) —

    a URL that a user can use to navigate to this server in the client



384
385
386
 
# File 'lib/discordrb/data/server.rb', line 384

def link
  "https://discord.com/channels/#{@id}"
end

#max_emoji ⇒ Integer

The amount of emoji the server can have, based on its current Nitro Boost Level.

Returns:

  • (Integer) —

    the max amount of emoji



592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'lib/discordrb/data/server.rb', line 592

def max_emoji
  case @boost_level
  when 1
    100
  when 2
    150
  when 3
    250
  else
    50
  end
end

#member(id, request = true) ⇒ Object

Gets a member on this server based on user ID

Parameters:

  • id (Integer) —

    The user ID to look for

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

    Whether the member should be requested from Discord if it's not cached



118
119
120
121
122
123
124
125
126
127
 
# File 'lib/discordrb/data/server.rb', line 118

def member(id, request = true)
  id = id.resolve_id
  return @members[id] if member_cached?(id)
  return nil unless request

  member = @bot.member(self, id)
  @members[id] = member unless member.nil?
rescue StandardError
  nil
end

#members ⇒ Array<Member> Also known as: users

Returns an array of all the members on this server.

Returns:

  • (Array<Member>) —

    an array of all the members on this server.

Raises:

  • (RuntimeError) —

    if the bot was not started with the :server_member intent



131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/discordrb/data/server.rb', line 131

def members
  return @members.values if @chunked

  @bot.debug("Members for server #{@id} not chunked yet - initiating")

  # If the SERVER_MEMBERS intent flag isn't set, the gateway won't respond when we ask for members.
  raise 'The :server_members intent is required to get server members' if @bot.gateway.intents.nobits?(INTENTS[:server_members])

  @bot.request_chunks(@id)
  sleep 0.05 until @chunked
  @members.values
end

#modify_widget(enabled, channel, reason = nil) ⇒ Object Also known as: modify_embed

Changes the channel on the server's widget, and sets whether it is enabled.

Parameters:

  • enabled (true, false) —

    whether the widget is enabled

  • channel (Channel, String, Integer) —

    the channel, or its ID, to be referenced by the widget

  • reason (String, nil) (defaults to: nil) —

    the reason to be shown in the audit log for this action



240
241
242
243
244
245
246
 
# File 'lib/discordrb/data/server.rb', line 240

def modify_widget(enabled, channel, reason = nil)
  cache_widget_data if @widget_enabled.nil?
  channel_id = channel ? channel.resolve_id : @widget_channel_id
  response = JSON.parse(API::Server.modify_widget(@bot.token, @id, enabled, channel_id, reason))
  @widget_enabled = response['enabled']
  @widget_channel_id = response['channel_id']
end

#move(user, channel) ⇒ Object

Forcibly moves a user into a different voice channel. Only works if the bot has the permission needed and if the user is already connected to some voice channel on this server.

Parameters:

  • user (User, String, Integer) —

    The user to move.

  • channel (Channel, String, Integer, nil) —

    The voice channel to move into. (If nil, the user is disconnected from the voice channel)



675
676
677
 
# File 'lib/discordrb/data/server.rb', line 675

def move(user, channel)
  API::Server.update_member(@bot.token, @id, user.resolve_id, channel_id: channel&.resolve_id)
end

#name=(name) ⇒ Object

Sets the server's name.

Parameters:

  • name (String) —

    The new server name.



686
687
688
 
# File 'lib/discordrb/data/server.rb', line 686

def name=(name)
  update_server_data(name: name)
end

#non_bot_members ⇒ Array<Member>

Returns an array of all the non bot members on this server.

Returns:

  • (Array<Member>) —

    an array of all the non bot members on this server.



152
153
154
 
# File 'lib/discordrb/data/server.rb', line 152

def non_bot_members
  members.reject(&:bot_account?)
end

#online_members(include_idle: false, include_bots: true) ⇒ Array<Member> Also known as: online_users

Returns an array of online members on this server.

Parameters:

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

    Whether to count idle members as online.

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

    Whether to include bot accounts in the count.

Returns:

  • (Array<Member>) —

    an array of online members on this server.



252
253
254
255
256
 
# File 'lib/discordrb/data/server.rb', line 252

def online_members(include_idle: false, include_bots: true)
  @members.values.select do |e|
    ((include_idle ? e.idle? : false) || e.online?) && (include_bots ? true : !e.bot_account?)
  end
end

#orphan_channels ⇒ Array<Channel>

Returns an array of channels on this server that are not in a category.

Returns:

  • (Array<Channel>) —

    an array of channels on this server that are not in a category



321
322
323
 
# File 'lib/discordrb/data/server.rb', line 321

def orphan_channels
  @channels.reject { |c| c.parent || c.category? }
end

#owner ⇒ Member

Returns The server owner.

Returns:

  • (Member) —

    The server owner.



81
82
83
 
# File 'lib/discordrb/data/server.rb', line 81

def owner
  member(@owner_id)
end

#preview ⇒ ServerPreview

Returns the preview of this server shown in the discovery page.

Returns:

  • (ServerPreview) —

    the preview of this server shown in the discovery page.



326
327
328
 
# File 'lib/discordrb/data/server.rb', line 326

def preview
  @bot.server_preview(@id)
end

#prune_count(days) ⇒ Integer

Returns the amount of members that are candidates for pruning

Parameters:

  • days (Integer) —

    the number of days to consider for inactivity

Returns:

  • (Integer) —

    number of members to be removed

Raises:

  • (ArgumentError) —

    if days is not between 1 and 30 (inclusive)



284
285
286
287
288
289
 
# File 'lib/discordrb/data/server.rb', line 284

def prune_count(days)
  raise ArgumentError, 'Days must be between 1 and 30' unless days.between?(1, 30)

  response = JSON.parse API::Server.prune_count(@bot.token, @id, days)
  response['pruned']
end

#region ⇒ VoiceRegion?

Note:

This may return nil if this server's voice region is deprecated.

Returns voice region data for this server's region.

Returns:

  • (VoiceRegion, nil) —

    voice region data for this server's region



702
703
704
 
# File 'lib/discordrb/data/server.rb', line 702

def region
  available_voice_regions.find { |e| e.id == @region_id }
end

#region=(region) ⇒ Object

Moves the server to another region. This will cause a voice interruption of at most a second.

Parameters:

  • region (String) —

    The new region the server should be in.



708
709
710
 
# File 'lib/discordrb/data/server.rb', line 708

def region=(region)
  update_server_data(region: region.to_s)
end

#role(id) ⇒ Role?

Gets a role on this server based on its ID.

Parameters:

Returns:

  • (Role, nil) —

    The role identified by the ID, or nil if it couldn't be found.



110
111
112
113
 
# File 'lib/discordrb/data/server.rb', line 110

def role(id)
  id = id.resolve_id
  @roles.find { |e| e.id == id }
end

#search_members(name:, limit: nil) ⇒ Array<Member>?

Searches a server for members that matches a username or a nickname.

Parameters:

  • name (String) —

    The username or nickname to search for.

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

    The maximum number of members between 1-1000 to return. Returns 1 member by default.

Returns:

  • (Array<Member>, nil) —

    An array of member objects that match the given parameters, or nil for no members.



609
610
611
612
613
614
 
# File 'lib/discordrb/data/server.rb', line 609

def search_members(name:, limit: nil)
  response = JSON.parse(API::Server.search_guild_members(@bot.token, @id, name, limit))
  return nil if response.empty?

  response.map { |mem| Member.new(mem, self, @bot) }
end

#set_widget_channel(channel, reason = nil) ⇒ Object Also known as: set_embed_channel

Changes the channel on the server's widget

Parameters:

  • channel (Channel, String, Integer) —

    the channel, or its ID, to be referenced by the widget

  • reason (String, nil) (defaults to: nil) —

    the reason to be shown in the audit log for this action



231
232
233
 
# File 'lib/discordrb/data/server.rb', line 231

def set_widget_channel(channel, reason = nil)
  modify_widget(widget?, channel, reason)
end

#set_widget_enabled(value, reason = nil) ⇒ Object Also known as: set_embed_enabled

Sets whether this server's widget is enabled

Parameters:

  • value (true, false)
  • reason (String, nil) (defaults to: nil) —

    the reason to be shown in the audit log for this action



216
217
218
 
# File 'lib/discordrb/data/server.rb', line 216

def set_widget_enabled(value, reason = nil)
  modify_widget(value, widget_channel, reason)
end

#splash=(splash_hash) ⇒ Object

Sets the server splash

Parameters:

  • splash_hash (String) —

    The splash hash



785
786
787
 
# File 'lib/discordrb/data/server.rb', line 785

def splash=(splash_hash)
  update_server_data(splash: splash_hash)
end

#splash_id ⇒ String Also known as: splash_hash

Returns the hexadecimal ID used to identify this server's splash image for their VIP invite page.

Returns:

  • (String) —

    the hexadecimal ID used to identify this server's splash image for their VIP invite page.



355
356
357
 
# File 'lib/discordrb/data/server.rb', line 355

def splash_id
  @splash_id ||= JSON.parse(API::Server.resolve(@bot.token, @id))['splash']
end

#splash_url ⇒ String?

Returns the splash image URL for the server's VIP invite page. nil if there is no splash image.

Returns:

  • (String, nil) —

    the splash image URL for the server's VIP invite page. nil if there is no splash image.



362
363
364
365
366
367
 
# File 'lib/discordrb/data/server.rb', line 362

def splash_url
  splash_id if @splash_id.nil?
  return nil unless @splash_id

  API.splash_url(@id, @splash_id)
end

#system_channel ⇒ Channel?

Returns the system channel (used for automatic welcome messages) of a server, or nil if none is set.

Returns:

  • (Channel, nil) —

    the system channel (used for automatic welcome messages) of a server, or nil if none is set.



854
855
856
 
# File 'lib/discordrb/data/server.rb', line 854

def system_channel
  @bot.channel(@system_channel_id) if @system_channel_id
end

#system_channel=(system_channel) ⇒ Object

Sets the server's system channel.

Parameters:

  • system_channel (Channel, String, Integer, nil) —

    The new system channel, or nil should it be disabled.



730
731
732
 
# File 'lib/discordrb/data/server.rb', line 730

def system_channel=(system_channel)
  update_server_data(system_channel_id: system_channel.resolve_id)
end

#text_channels ⇒ Array<Channel>

Returns an array of text channels on this server.

Returns:

  • (Array<Channel>) —

    an array of text channels on this server



306
307
308
 
# File 'lib/discordrb/data/server.rb', line 306

def text_channels
  @channels.select(&:text?)
end

#unban(user, reason = nil) ⇒ Object

Unbans a previously banned user from this server.

Parameters:

  • user (User, String, Integer) —

    The user to unban.

  • reason (String) (defaults to: nil) —

    The reason the user is being unbanned.



646
647
648
 
# File 'lib/discordrb/data/server.rb', line 646

def unban(user, reason = nil)
  API::Server.unban_user(@bot.token, @id, user.resolve_id, reason)
end

#verification_level ⇒ Symbol

Returns the verification level of the server (:none = none, :low = 'Must have a verified email on their Discord account', :medium = 'Has to be registered with Discord for at least 5 minutes', :high = 'Has to be a member of this server for at least 10 minutes', :very_high = 'Must have a verified phone on their Discord account').

Returns:

  • (Symbol) —

    the verification level of the server (:none = none, :low = 'Must have a verified email on their Discord account', :medium = 'Has to be registered with Discord for at least 5 minutes', :high = 'Has to be a member of this server for at least 10 minutes', :very_high = 'Must have a verified phone on their Discord account').



750
751
752
 
# File 'lib/discordrb/data/server.rb', line 750

def verification_level
  VERIFICATION_LEVELS.key @verification_level
end

#verification_level=(level) ⇒ Object

Sets the verification level of the server

Parameters:



756
757
758
759
760
 
# File 'lib/discordrb/data/server.rb', line 756

def verification_level=(level)
  level = VERIFICATION_LEVELS[level] if level.is_a?(Symbol)

  update_server_data(verification_level: level)
end

#voice_channels ⇒ Array<Channel>

Returns an array of voice channels on this server.

Returns:

  • (Array<Channel>) —

    an array of voice channels on this server



311
312
313
 
# File 'lib/discordrb/data/server.rb', line 311

def voice_channels
  @channels.select(&:voice?)
end

#webhooks ⇒ Array<Webhook>

Requests a list of Webhooks on the server.

Returns:

  • (Array<Webhook>) —

    webhooks on the server.



821
822
823
824
 
# File 'lib/discordrb/data/server.rb', line 821

def webhooks
  webhooks = JSON.parse(API::Server.webhooks(@bot.token, @id))
  webhooks.map { |webhook| Webhook.new(webhook, @bot) }
end

#widget_banner_url(style) ⇒ String?

Returns the widget banner URL to the server that displays the amount of online members, server icon and server name in a stylish way. nil if the widget is not enabled.

Parameters:

  • style (Symbol) —

    The style the picture should have. Possible styles are:

    • :banner1 creates a rectangular image with the server name, member count and icon, a "Powered by Discord" message on the bottom and an arrow on the right.
    • :banner2 creates a less tall rectangular image that has the same information as banner1, but the Discord logo on the right - together with the arrow and separated by a diagonal separator.
    • :banner3 creates an image similar in size to banner1, but it has the arrow in the bottom part, next to the Discord logo and with a "Chat now" text.
    • :banner4 creates a tall, almost square, image that prominently features the Discord logo at the top and has a "Join my server" in a pill-style button on the bottom. The information about the server is in the same format as the other three banner styles.
    • :shield creates a very small, long rectangle, of the style you'd find at the top of GitHub README.md files. It features a small version of the Discord logo at the left and the member count at the right.

Returns:

  • (String, nil) —

    the widget banner URL to the server that displays the amount of online members, server icon and server name in a stylish way. nil if the widget is not enabled.



347
348
349
350
351
352
 
# File 'lib/discordrb/data/server.rb', line 347

def widget_banner_url(style)
  update_data if @widget_enabled.nil?
  return unless @widget_enabled

  API.widget_url(@id, style)
end

#widget_channel ⇒ Channel? Also known as: embed_channel

Returns the channel the server widget will make an invite for.

Returns:

  • (Channel, nil) —

    the channel the server widget will make an invite for.



200
201
202
203
 
# File 'lib/discordrb/data/server.rb', line 200

def widget_channel
  cache_widget_data if @widget_enabled.nil?
  @bot.channel(@widget_channel_id) if @widget_channel_id
end

#widget_channel=(channel) ⇒ Object Also known as: embed_channel=

Changes the channel on the server's widget

Parameters:



223
224
225
 
# File 'lib/discordrb/data/server.rb', line 223

def widget_channel=(channel)
  modify_widget(widget?, channel)
end

#widget_enabled=(value) ⇒ Object Also known as: embed_enabled=

Sets whether this server's widget is enabled

Parameters:

  • value (true, false) 


208
209
210
 
# File 'lib/discordrb/data/server.rb', line 208

def widget_enabled=(value)
  modify_widget(value, widget_channel)
end

#widget_enabled? ⇒ true, false Also known as: widget?, embed_enabled, embed?

Returns whether or not the server has widget enabled.

Returns:

  • (true, false) —

    whether or not the server has widget enabled



191
192
193
194
 
# File 'lib/discordrb/data/server.rb', line 191

def widget_enabled?
  cache_widget_data if @widget_enabled.nil?
  @widget_enabled
end

#widget_url ⇒ String?

Returns the widget URL to the server that displays the amount of online members in a stylish way. nil if the widget is not enabled.

Returns:

  • (String, nil) —

    the widget URL to the server that displays the amount of online members in a stylish way. nil if the widget is not enabled.



332
333
334
335
336
337
 
# File 'lib/discordrb/data/server.rb', line 332

def widget_url
  update_data if @widget_enabled.nil?
  return unless @widget_enabled

  API.widget_url(@id)
end