Class: Discordrb::Server

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

Overview

An isolated collection of channels and member's 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
MFA_LEVELS =

A map of possible multi-factor authentication levels to symbol names

{
  none: 0,
  elevated: 1
}.freeze
NSFW_LEVELS =

A map of possible NSFW levels to symbol names

{
  default: 0,
  explicit: 1,
  safe: 2,
  age_restricted: 3
}.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.



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

def afk_timeout
  @afk_timeout
end

Returns the hash of the server's banner image or GIF.

Returns:

  • (String, nil) —

    the hash of the server's banner image or GIF.



66
67
68
 
# File 'lib/discordrb/data/server.rb', line 66

def banner_id
  @banner_id
end

#boost_level ⇒ Integer (readonly)

Returns the server's Nitro boost level, 0 if no level.

Returns:

  • (Integer) —

    the server's Nitro boost level, 0 if no level.



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

def boost_level
  @boost_level
end

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

Returns whether or not the server has the boost progress bar enabled.

Returns:

  • (true, false) —

    whether or not the server has the boost progress bar enabled.



95
96
97
 
# File 'lib/discordrb/data/server.rb', line 95

def boost_progress_bar
  @boost_progress_bar
end

#booster_count ⇒ Integer (readonly)

Returns the server's amount of Nitro boosters, 0 if no one has boosted.

Returns:

  • (Integer) —

    the server's amount of Nitro boosters, 0 if no one has boosted.



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

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

#description ⇒ String? (readonly)

Returns the description of the server. Shown in server discovery and external embeds.

Returns:

  • (String, nil) —

    the description of the server. Shown in server discovery and external embeds.



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

def description
  @description
end

#discovery_splash_id ⇒ String? (readonly)

Returns the hash of the server's discovery splash image.

Returns:

  • (String, nil) —

    the hash of the server's discovery splash image.



83
84
85
 
# File 'lib/discordrb/data/server.rb', line 83

def discovery_splash_id
  @discovery_splash_id
end

#dm_spam_detected_at ⇒ Time? (readonly)

Returns the time at when DM spam was last detected on the server.

Returns:

  • (Time, nil) —

    the time at when DM spam was last detected on the server.



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

def dm_spam_detected_at
  @dm_spam_detected_at
end

#dms_disabled_until ⇒ Time? (readonly)

Returns the time at when non-friend direct messages will be re-enabled on the server.

Returns:

  • (Time, nil) —

    the time at when non-friend direct messages will be re-enabled on the server.



108
109
110
 
# File 'lib/discordrb/data/server.rb', line 108

def dms_disabled_until
  @dms_disabled_until
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.



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

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



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

def features
  @features
end

#invites_disabled_until ⇒ Time? (readonly)

Returns the time at when invites will be re-enabled on the server.

Returns:

  • (Time, nil) —

    the time at when invites will be re-enabled on the server.



105
106
107
 
# File 'lib/discordrb/data/server.rb', line 105

def invites_disabled_until
  @invites_disabled_until
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,



38
39
40
 
# File 'lib/discordrb/data/server.rb', line 38

def large
  @large
end

#locale ⇒ String (readonly)

Returns the preferred locale of the server. Used in server discovery and notices from Discord.

Returns:

  • (String) —

    the preferred locale of the server. Used in server discovery and notices from Discord.



60
61
62
 
# File 'lib/discordrb/data/server.rb', line 60

def locale
  @locale
end

#max_member_count ⇒ Integer (readonly)

Returns the maximum number of members that can join the server.

Returns:

  • (Integer) —

    the maximum number of members that can join the server.



73
74
75
 
# File 'lib/discordrb/data/server.rb', line 73

def max_member_count
  @max_member_count
end

#max_presence_count ⇒ Integer? (readonly)

Returns the maximum number of members that can concurrently be online in the server. Always set to nil except for the largest of servers.

Returns:

  • (Integer, nil) —

    the maximum number of members that can concurrently be online in the server. Always set to nil except for the largest of servers.



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

def max_presence_count
  @max_presence_count
end

#max_stage_video_channel_members ⇒ Integer (readonly)

Returns the maximum number of members that can concurrently watch a stream in a stage channel.

Returns:

  • (Integer) —

    the maximum number of members that can concurrently watch a stream in a stage channel.



92
93
94
 
# File 'lib/discordrb/data/server.rb', line 92

def max_stage_video_channel_members
  @max_stage_video_channel_members
end

#max_video_channel_members ⇒ Integer (readonly)

Returns the maximum number of members that can concurrently watch a stream in a video channel.

Returns:

  • (Integer) —

    the maximum number of members that can concurrently watch a stream in a video channel.



89
90
91
 
# File 'lib/discordrb/data/server.rb', line 89

def max_video_channel_members
  @max_video_channel_members
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.



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

def member_count
  @member_count
end

#raid_detected_at ⇒ Time? (readonly)

Returns the time at when the last raid was detected on the server.

Returns:

  • (Time, nil) —

    the time at when the last raid was detected on the server.



99
100
101
 
# File 'lib/discordrb/data/server.rb', line 99

def raid_detected_at
  @raid_detected_at
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

#splash_id ⇒ String? (readonly) Also known as: splash_hash

Returns the hash of the server's invite splash image.

Returns:

  • (String, nil) —

    the hash of the server's invite splash image.



69
70
71
 
# File 'lib/discordrb/data/server.rb', line 69

def splash_id
  @splash_id
end

#system_channel_flags ⇒ Integer (readonly)

Returns the flags for the server's designated system channel.

Returns:

  • (Integer) —

    the flags for the server's designated system channel.



86
87
88
 
# File 'lib/discordrb/data/server.rb', line 86

def system_channel_flags
  @system_channel_flags
end

#vanity_invite_code ⇒ String? (readonly)

Returns the code of the server's custom vanity invite link.

Returns:

  • (String, nil) —

    the code of the server's custom vanity invite link.



76
77
78
 
# File 'lib/discordrb/data/server.rb', line 76

def vanity_invite_code
  @vanity_invite_code
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



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

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.



630
631
632
633
634
635
636
 
# File 'lib/discordrb/data/server.rb', line 630

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.



337
338
339
340
341
342
343
344
 
# File 'lib/discordrb/data/server.rb', line 337

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?

Get the AFK channel of the server.

Returns:

  • (Channel, nil) —

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



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

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.



818
819
820
 
# File 'lib/discordrb/data/server.rb', line 818

def afk_channel=(afk_channel)
  modify(afk_channel: afk_channel)
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.



918
919
920
 
# File 'lib/discordrb/data/server.rb', line 918

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:



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

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



789
790
791
792
793
794
795
796
 
# File 'lib/discordrb/data/server.rb', line 789

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.



731
732
733
734
735
736
737
738
739
 
# File 'lib/discordrb/data/server.rb', line 731

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

Utility method to get a server's banner URL.

Parameters:

  • format (String) (defaults to: 'webp') —

    The URL will default to webp. You can otherwise specify one of jpg or png to override this.

Returns:

  • (String, nil) —

    The URL to the server's banner image, or nil if the server doesn't have a banner image.



430
431
432
 
# File 'lib/discordrb/data/server.rb', line 430

def banner_url(format: 'webp')
  API.banner_url(@id, @banner_id, format) if @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.



689
690
691
692
693
694
 
# File 'lib/discordrb/data/server.rb', line 689

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, @bot.ensure_user(e['user']), e['reason'])
  end
end

#bans!(limit: 1000, before: nil, after: nil) ⇒ Array<ServerBan>

Note:

When using the before parameter, bans will be sorted in descending order by user ID (newest users first), and in ascending order by user ID (oldest users first) otherwise.

Get the users who have been banned from the server.

Parameters:

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

    The max number of bans to return, or nil for no limit.

  • after (User, Member, Time, Integer, String, nil) (defaults to: nil) —

    Get bans after this user ID.

  • before (User, Member, Time, Integer, String, nil) (defaults to: nil) —

    Get bans before this user ID.

Returns:

  • (Array<ServerBan>) —

    The users who have been banned from the server.

Raises:

  • (ArgumentError) 


703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
 
# File 'lib/discordrb/data/server.rb', line 703

def bans!(limit: 1000, before: nil, after: nil)
  raise ArgumentError, "'before' and 'after' are mutually exclusive" if before && after

  f_limit = limit && limit <= 1000 ? limit : 1000
  f_after = after.is_a?(Time) ? IDObject.synthesize(after) : after&.resolve_id
  f_before = before.is_a?(Time) ? IDObject.synthesize(before) : before&.resolve_id

  get_bans = lambda do |before: nil, after: nil|
    data = API::Server.bans(@bot.token, @id, f_limit, before&.id || f_before, after&.id || f_after)
    JSON.parse(data).map { |ban| ServerBan.new(self, @bot.ensure_user(ban['user']), ban['reason']) }
  end

  paginator = Paginator.new(limit, before ? :up : :down) do |page|
    if before
      get_bans.call(before: page&.first&.user)
    else
      get_bans.call(after: page&.last&.user)
    end
  end

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



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

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



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

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.



212
213
214
 
# File 'lib/discordrb/data/server.rb', line 212

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) 


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

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



382
383
384
 
# File 'lib/discordrb/data/server.rb', line 382

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)



568
569
570
571
572
573
574
575
576
 
# File 'lib/discordrb/data/server.rb', line 568

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.



593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
 
# File 'lib/discordrb/data/server.rb', line 593

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.id] = role
end

#create_scheduled_event(name:, start_time:, entity_type:, end_time: nil, channel: nil, location: nil, description: nil, cover: nil, recurrence_rule: nil, reason: nil) {|builder| ... } ⇒ ScheduledEvent

Create a scheduled event on this server.

Parameters:

  • name (String) —

    The 1-100 character name of the scheduled event to create.

  • start_time (Time) —

    The start time of the scheduled event to create.

  • entity_type (Integer, Symbol) —

    The entity type of the scheduled event to create.

  • end_time (Time, nil) (defaults to: nil) —

    The end time of the scheduled event to create.

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

    The channel where the scheduled event will take place.

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

    The external location of the scheduled event to create.

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

    The 1-100 character description of the scheduled event to create.

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

    The cover image of the scheduled event to create.

  • recurrence_rule (#to_h, nil) (defaults to: nil) —

    The recurrence rule of the scheduled event to create.

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

    The audit log reason for creating the scheduled event.

Yield Parameters:

Returns:



1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
 
# File 'lib/discordrb/data/server.rb', line 1013

def create_scheduled_event(name:, start_time:, entity_type:, end_time: nil, channel: nil, location: nil, description: nil, cover: nil, recurrence_rule: nil, reason: nil)
  yield((builder = ScheduledEvent::RecurrenceRule::Builder.new)) if block_given?

  options = {
    name: name,
    privacy_level: 2,
    scheduled_start_time: start_time&.iso8601,
    entity_type: ScheduledEvent::ENTITY_TYPES[entity_type] || entity_type,
    channel_id: channel&.resolve_id,
    entity_metadata: location ? { location: location } : nil,
    scheduled_end_time: end_time&.iso8601,
    description: description,
    image: cover.respond_to?(:read) ? Discordrb.encode64(cover) : cover,
    recurrence_rule: block_given? ? builder.to_h : recurrence_rule&.to_h
  }

  event = JSON.parse(API::Server.create_scheduled_event(@bot.token, @id, **options, reason: reason))
  scheduled_event = ScheduledEvent.new(event, self, @bot)
  @scheduled_events[scheduled_event.id] = scheduled_event
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.



136
137
138
139
140
141
142
143
144
145
 
# File 'lib/discordrb/data/server.rb', line 136

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_messages = 'All messages', :only_mentions = 'Only @mentions').

Returns:

  • (Symbol) —

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



861
862
863
 
# File 'lib/discordrb/data/server.rb', line 861

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:



867
868
869
 
# File 'lib/discordrb/data/server.rb', line 867

def default_message_notifications=(notification_level)
  modify(notification_level: 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.



641
642
643
 
# File 'lib/discordrb/data/server.rb', line 641

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

#discovery_splash_url(format: 'webp') ⇒ String?

Utility method to get a server's discovery splash URL.

Parameters:

  • format (String) (defaults to: 'webp') —

    The URL will default to webp. You can otherwise specify one of jpg or png to override this.

Returns:

  • (String, nil) —

    The URL to the server's discovery splash image, or nil if the server doesn't have a discovery splash image.



437
438
439
 
# File 'lib/discordrb/data/server.rb', line 437

def discovery_splash_url(format: 'webp')
  API.discovery_splash_url(@id, @discovery_splash_id, format) if @discovery_splash_id
end

#dm_spam_detected? ⇒ true, false

Check if the auto-moderation system has detected DM spam.

Returns:

  • (true, false) —

    Whether or not Discord's anti-spam system has detected dm-spam in the server.



943
944
945
 
# File 'lib/discordrb/data/server.rb', line 943

def dm_spam_detected?
  !@dm_spam_detected_at.nil?
end

#dms_disabled? ⇒ true, false

Check if the server has disabled non-friend DMs.

Returns:

  • (true, false) —

    Whether or not the server has stopped member's who aren't friends from DMing each other.



949
950
951
 
# File 'lib/discordrb/data/server.rb', line 949

def dms_disabled?
  !@dms_disabled_until.nil? && @dms_disabled_until > Time.now
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.



651
652
653
654
655
656
 
# File 'lib/discordrb/data/server.rb', line 651

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



150
151
152
 
# File 'lib/discordrb/data/server.rb', line 150

def everyone_role
  @roles[@id]
end

#explicit_content_filter ⇒ Symbol Also known as: content_filter_level

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

Returns:

  • (Symbol) —

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



881
882
883
 
# File 'lib/discordrb/data/server.rb', line 881

def explicit_content_filter
  FILTER_LEVELS.key(@explicit_content_filter)
end

#explicit_content_filter=(filter_level) ⇒ Object

Sets the server content filter.

Parameters:



889
890
891
 
# File 'lib/discordrb/data/server.rb', line 889

def explicit_content_filter=(filter_level)
  modify(explicit_content_filter: filter_level)
end

#icon=(icon) ⇒ Object

Sets the server's icon.

Parameters:

  • icon (String, #read, nil) —

    The new icon, in base64-encoded JPG format.



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

def icon=(icon)
  modify(icon: icon)
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



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

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>

Note:

If the server has more than 50 integrations, they cannot be accessed.

Returns an array of the integrations in this server.

Returns:

  • (Array<Integration>) —

    an array of the integrations in this server.



228
229
230
231
 
# File 'lib/discordrb/data/server.rb', line 228

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.



969
970
971
972
 
# File 'lib/discordrb/data/server.rb', line 969

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

#invites_disabled? ⇒ true, false

Check if the server has paused invites.

Returns:

  • (true, false) —

    Whether or not the server has stopped new members from joining, either via incident actions or the :invites_disabled feature.



956
957
958
 
# File 'lib/discordrb/data/server.rb', line 956

def invites_disabled?
  (!@invites_disabled_until.nil? && @invites_disabled_until > Time.now) || @features.include?(:invites_disabled)
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.



765
766
767
 
# File 'lib/discordrb/data/server.rb', line 765

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

#leave ⇒ Object

Leave the server.



778
779
780
 
# File 'lib/discordrb/data/server.rb', line 778

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



442
443
444
 
# File 'lib/discordrb/data/server.rb', line 442

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



660
661
662
663
664
665
666
667
668
669
670
671
 
# File 'lib/discordrb/data/server.rb', line 660

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



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/discordrb/data/server.rb', line 183

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



196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/discordrb/data/server.rb', line 196

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

#mfa_level ⇒ Symbol

Returns The multi-factor authentication level of the server (:none = 'no MFA/2FA requirement for moderation actions', :elevated = 'MFA/2FA is required for moderation actions').

Returns:

  • (Symbol) —

    The multi-factor authentication level of the server (:none = 'no MFA/2FA requirement for moderation actions', :elevated = 'MFA/2FA is required for moderation actions')



900
901
902
 
# File 'lib/discordrb/data/server.rb', line 900

def mfa_level
  MFA_LEVELS.key @mfa_level
end

#modify(name: :undef, verification_level: :undef, notification_level: :undef, explicit_content_filter: :undef, afk_channel: :undef, afk_timeout: :undef, icon: :undef, splash: :undef, discovery_splash: :undef, banner: :undef, system_channel: :undef, system_channel_flags: :undef, rules_channel: :undef, public_updates_channel: :undef, locale: :undef, features: :undef, description: :undef, boost_progress_bar: :undef, safety_alerts_channel: :undef, dms_disabled_until: :undef, invites_disabled_until: :undef, reason: nil) ⇒ nil

Modify the properties of the server.

Parameters:

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

    The new 2-32 character name of the server.

  • verification_level (Symbol, Integer, nil) (defaults to: :undef) —

    The new verification level of the server.

  • notification_level (Symbol, Integer, nil) (defaults to: :undef) —

    The new default message notification level of the server.

  • explicit_content_filter (Symbol, Integer, nil) (defaults to: :undef) —

    The new explicit content filter level of the server.

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

    The new AFK voice channel members should be automatically moved to.

  • afk_timeout (Integer) (defaults to: :undef) —

    The new AFK timeout in seconds. Can be set to one of 60, 300, 900, 1800, or 3600.

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

    The new icon of the server. Should be a file-like object that responds to #read.

  • splash (#read, File, nil) (defaults to: :undef) —

    The new invite splash of the server. Should be a file-like object that responds to #read.

  • discovery_splash (#read, File, nil) (defaults to: :undef) —

    The new discovery splash of the server. Should be a file-like object that responds to #read.

  • banner (#read, File, nil) (defaults to: :undef) —

    The new banner of the server. Should be a file-like object that responds to #read.

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

    The new channel where system messages should be sent.

  • system_channel_flags (Integer) (defaults to: :undef) —

    The new system channel flags to set for the server's system channel expressed as a bitfield.

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

    The new channel where the server displays its rules or guidelines.

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

    The new channel where public updates should be sent.

  • locale (String, Symbol, nil) (defaults to: :undef) —

    The new preferred locale of the server; primarily for community servers.

  • features (Array<String, Symbol>) (defaults to: :undef) —

    The new features to set for the server.

  • description (String, nil) (defaults to: :undef) —

    The new description of the server.

  • boost_progress_bar (true, false) (defaults to: :undef) —

    Whether or not the server boosting progress bar should be visible.

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

    The new channel where safety alerts should be sent.

  • dms_disabled_until (Time, nil) (defaults to: :undef) —

    The time at when non-friend direct messages will be enabled again.

  • invites_disabled_until (Time, nil) (defaults to: :undef) —

    The time at when invites will no longer be disabled.

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

    The reason to show in the server's audit log for modifying the server.

Returns:

  • (nil) 


1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
 
# File 'lib/discordrb/data/server.rb', line 1103

def modify(
  name: :undef, verification_level: :undef, notification_level: :undef, explicit_content_filter: :undef,
  afk_channel: :undef, afk_timeout: :undef, icon: :undef, splash: :undef, discovery_splash: :undef, banner: :undef,
  system_channel: :undef, system_channel_flags: :undef, rules_channel: :undef, public_updates_channel: :undef,
  locale: :undef, features: :undef, description: :undef, boost_progress_bar: :undef, safety_alerts_channel: :undef,
  dms_disabled_until: :undef, invites_disabled_until: :undef, reason: nil
)
  data = {
    name: name,
    verification_level: VERIFICATION_LEVELS[verification_level] || verification_level,
    default_message_notifications: NOTIFICATION_LEVELS[notification_level] || notification_level,
    explicit_content_filter: FILTER_LEVELS[explicit_content_filter] || explicit_content_filter,
    afk_channel_id: afk_channel == :undef ? afk_channel : afk_channel&.resolve_id,
    afk_timeout: afk_timeout,
    icon: icon.respond_to?(:read) ? Discordrb.encode64(icon) : icon,
    splash: splash.respond_to?(:read) ? Discordrb.encode64(splash) : splash,
    discovery_splash: discovery_splash.respond_to?(:read) ? Discordrb.encode64(discovery_splash) : discovery_splash,
    banner: banner.respond_to?(:read) ? Discordrb.encode64(banner) : banner,
    system_channel_id: system_channel == :undef ? system_channel : system_channel&.resolve_id,
    system_channel_flags: system_channel_flags,
    rules_channel_id: rules_channel == :undef ? rules_channel : rules_channel&.resolve_id,
    public_updates_channel_id: public_updates_channel == :undef ? public_updates_channel : public_updates_channel&.resolve_id,
    preferred_locale: locale,
    features: features == :undef ? features : features.map(&:upcase),
    description: description,
    premium_progress_bar_enabled: boost_progress_bar,
    safety_alerts_channel_id: safety_alerts_channel == :undef ? safety_alerts_channel : safety_alerts_channel&.resolve_id
  }

  if invites_disabled_until != :undef || dms_disabled_until != :undef
    incidents_data = {
      dms_disabled_until: dms_disabled_until == :undef ? @dms_disabled_until&.iso8601 : dms_disabled_until&.iso8601,
      invites_disabled_until: invites_disabled_until == :undef ? @invites_disabled_until&.iso8601 : invites_disabled_until&.iso8601
    }

    process_incident_actions(JSON.parse(API::Server.update_incident_actions(@bot.token, @id, **incidents_data, reason: reason)))
    return unless data.any? { |_, value| value != :undef }
  end

  update_data(JSON.parse(API::Server.update!(@bot.token, @id, **data, reason: reason)))
  nil
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



306
307
308
309
310
311
312
 
# File 'lib/discordrb/data/server.rb', line 306

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)



773
774
775
 
# File 'lib/discordrb/data/server.rb', line 773

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.



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

def name=(name)
  modify(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.



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

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

#nsfw_level ⇒ Symbol

Returns The NSFW level of the server (:default = 'no NSFW level has been set', :explicit = 'the server may contain explicit content', :safe = 'the server does not contain NSFW content', :age_restricted = 'server membership is restricted to adults').

Returns:

  • (Symbol) —

    The NSFW level of the server (:default = 'no NSFW level has been set', :explicit = 'the server may contain explicit content', :safe = 'the server does not contain NSFW content', :age_restricted = 'server membership is restricted to adults')



913
914
915
 
# File 'lib/discordrb/data/server.rb', line 913

def nsfw_level
  NSFW_LEVELS.key @nsfw_level
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.



318
319
320
321
322
 
# File 'lib/discordrb/data/server.rb', line 318

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



387
388
389
 
# File 'lib/discordrb/data/server.rb', line 387

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

#owner ⇒ Member

Returns The server owner.

Returns:

  • (Member) —

    The server owner.



128
129
130
 
# File 'lib/discordrb/data/server.rb', line 128

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.



392
393
394
 
# File 'lib/discordrb/data/server.rb', line 392

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)



350
351
352
353
354
355
 
# File 'lib/discordrb/data/server.rb', line 350

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

#public_updates_channel ⇒ Channel?

Get the public updates channel of the server.

Returns:

  • (Channel, nil) —

    The channel where Community servers receive public updates from Discord, or nil if none is set.



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

def public_updates_channel
  @bot.channel(@public_updates_channel_id) if @public_updates_channel_id
end

#raid_detected? ⇒ true, false

Check if the auto-moderation system has detected a raid.

Returns:

  • (true, false) —

    Whether or not Discord's anti-spam system has detected a raid in the server.



937
938
939
 
# File 'lib/discordrb/data/server.rb', line 937

def raid_detected?
  !@raid_detected_at.nil?
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



800
801
802
 
# File 'lib/discordrb/data/server.rb', line 800

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.



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

def region=(region)
  update_data(JSON.parse(API::Server.update!(@bot.token, @id, 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.



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

def role(id)
  @roles[id.resolve_id]
end

#role_member_counts ⇒ Hash<Integer => Integer>

Get a mapping of role IDs to the amount of members who have the role.

Examples:

Print out the name of the roles in a server followed by the role's member count.

server = bot.server(81384788765712384)

server.role_member_counts.each do |id, count|
  puts("Name: #{server.role(id).name}, Count: #{count}")
end

Returns:

  • (Hash<Integer => Integer>) —

    A hash mapping role IDs to their respective member counts.



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

def role_member_counts
  response = JSON.parse(API::Server.role_member_counts(@bot.token, @id))
  response.transform_keys!(&:to_i)
  response.tap { |hash| hash[@id] = @member_count }
end

#roles ⇒ Array<Role>

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

Returns:

  • (Array<Role>) —

    an array of all the roles available on this server.



155
156
157
 
# File 'lib/discordrb/data/server.rb', line 155

def roles
  @roles.values
end

#rules_channel ⇒ Channel?

Get the rules channel of the server.

Returns:

  • (Channel, nil) —

    The channel where community servers can display rules or guidelines, or nil if none is set.



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

def rules_channel
  @bot.channel(@rules_channel_id) if @rules_channel_id
end

#safety_alerts_channel ⇒ Channel?

Get the safety alerts channel of the server.

Returns:

  • (Channel, nil) —

    The channel where Community servers receive safety alerts from Discord, or nil if none is set.



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

def safety_alerts_channel
  @bot.channel(@safety_alerts_channel_id) if @safety_alerts_channel_id
end

#scheduled_event(scheduled_event_id, request: true) ⇒ ScheduledEvent?

Get a specific scheduled event on the server.

Parameters:

  • scheduled_event_id (Integer, String, ScheduledEvent) —

    The scheduled event to get.

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

    Whether to request the event from discord if it isn't cached.

Returns:

  • (ScheduledEvent, nil) —

    The scheduled event for the ID, or nil if it couldn't be found.



988
989
990
991
992
993
994
995
996
997
998
 
# File 'lib/discordrb/data/server.rb', line 988

def scheduled_event(scheduled_event_id, request: true)
  id = scheduled_event_id.resolve_id
  return @scheduled_events[id] if @scheduled_events[id]
  return nil unless request

  event = JSON.parse(API::Server.get_scheduled_event(@bot.token, @id, id, with_user_count: true))
  scheduled_event = ScheduledEvent.new(event, self, @bot)
  @scheduled_events[scheduled_event.id] = scheduled_event
rescue StandardError
  nil
end

#scheduled_events(bypass_cache: false) ⇒ Array<ScheduledEvent>

Get the scheduled events on the server.

Parameters:

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

    Whether the cached scheduled events should be ignored and re-fetched via an HTTP request.

Returns:



978
979
980
981
982
 
# File 'lib/discordrb/data/server.rb', line 978

def scheduled_events(bypass_cache: false)
  process_scheduled_events(JSON.parse(API::Server.list_scheduled_events(@bot.token, @id, with_user_count: true))) if bypass_cache

  @scheduled_events.values
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.



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

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



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

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



282
283
284
 
# File 'lib/discordrb/data/server.rb', line 282

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

#splash_url(format: 'webp') ⇒ String?

Utility method to get a server's splash URL.

Parameters:

  • format (String) (defaults to: 'webp') —

    The URL will default to webp. You can otherwise specify one of jpg or png to override this.

Returns:

  • (String, nil) —

    The URL to the server's splash image, or nil if the server doesn't have a splash image.



422
423
424
 
# File 'lib/discordrb/data/server.rb', line 422

def splash_url(format: 'webp')
  API.splash_url(@id, @splash_id, format) if @splash_id
end

#system_channel ⇒ Channel?

Get the system channel of the server.

Returns:

  • (Channel, nil) —

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



1063
1064
1065
 
# File 'lib/discordrb/data/server.rb', line 1063

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.



824
825
826
 
# File 'lib/discordrb/data/server.rb', line 824

def system_channel=(system_channel)
  modify(system_channel: system_channel)
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



372
373
374
 
# File 'lib/discordrb/data/server.rb', line 372

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.



744
745
746
 
# File 'lib/discordrb/data/server.rb', line 744

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

#vanity_invite_url ⇒ String? Also known as: vanity_invite_link

Create an invite link using the server's vanity code.

Returns:

  • (String, nil) —

    The server's vanity invite URL, or nil if the server does not have a vanity invite code.



927
928
929
930
931
 
# File 'lib/discordrb/data/server.rb', line 927

def vanity_invite_url
  return unless @vanity_invite_code

  "https://discord.gg/#{@vanity_invite_code}"
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').



844
845
846
 
# File 'lib/discordrb/data/server.rb', line 844

def verification_level
  VERIFICATION_LEVELS.key(@verification_level)
end

#verification_level=(level) ⇒ Object

Sets the verification level of the server

Parameters:



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

def verification_level=(level)
  modify(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



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

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.



962
963
964
965
 
# File 'lib/discordrb/data/server.rb', line 962

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.



412
413
414
415
416
 
# File 'lib/discordrb/data/server.rb', line 412

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

  API.widget_url(@id, style) if @widget_enabled
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.



266
267
268
269
 
# File 'lib/discordrb/data/server.rb', line 266

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:



289
290
291
 
# File 'lib/discordrb/data/server.rb', line 289

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) 


274
275
276
 
# File 'lib/discordrb/data/server.rb', line 274

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



257
258
259
260
 
# File 'lib/discordrb/data/server.rb', line 257

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.



398
399
400
401
402
 
# File 'lib/discordrb/data/server.rb', line 398

def widget_url
  update_data if @widget_enabled.nil?

  API.widget_url(@id) if @widget_enabled
end