Guild

class Guild

A Discord server. Most methods call Discord; the few that read Weeble’s gateway cache say so.

A field is undefined when Discord didn’t send it and null when Discord sent null. A guild from fetchGuild() can come from the cache and then only has id, name, and ownerId.

Example

const guild = await message.fetchGuild();
const member = guild && message.author
  ? await guild.fetchMember(message.author.id)
  : null;

Properties

Property	Type	Description
`afkChannelId`	string \| null \| undefined
`afkTimeout`	number \| undefined
`applicationId`	string \| null \| undefined
`approximateMemberCount`	number \| null \| undefined
`approximatePresenceCount`	number \| null \| undefined
`banner`	string \| null \| undefined	Hash of the guild’s banner, or `null` if not set.
`createdAt`	Date	When this guild was created.
`createdTimestamp`	number
`defaultMessageNotifications`	NotificationsLevel \| undefined	Default notification level for the guild.
`description`	string \| null \| undefined	The guild’s description shown in the Server Discovery listing, or `null`. `undefined` when the payload omitted it.
`discoverySplash`	string \| null \| undefined
`emojis`	Map<string, `Emoji`> \| undefined
`explicitContentFilter`	ExplicitContentFilterLevel \| undefined	Level of content filtering applied to messages.
`features`	Feature[] \| undefined	Array of feature flags the guild has enabled.
`icon`	string \| null \| undefined	Hash of the guild’s icon, or `null` if not set. `undefined` when the payload omitted it (cache-backed fetches do not invent `null`).
`id`	string	Guild ID.
`invitesPausedUntil`	Date \| null	When paused invites resume, or `null` when invites are not paused. See `pauseInvites()`.
`maxMembers`	number \| null \| undefined
`maxPresences`	number \| null \| undefined
`maxStageVideoChannelUsers`	number \| null \| undefined
`maxVideoChannelUsers`	number \| null \| undefined
`memberCount`	number \| undefined	Member count reported by the gateway or latest guild REST response. `undefined` when the payload did not include a count.
`mfaLevel`	number \| undefined
`name`	string	The guild’s name.
`nsfwLevel`	number \| undefined
`ownerId`	string \| null \| undefined	ID of the guild owner, when the payload included it.
`preferredLocale`	string \| undefined	The guild’s preferred locale (e.g. `"en-US"`).
`premiumProgressBarEnabled`	boolean \| undefined
`premiumSubscriptionCount`	number \| undefined	Number of Nitro boosts the guild currently has.
`premiumTier`	PremiumTier \| undefined	The guild’s Nitro boost tier. `undefined` when omitted; `0` only when Discord sent 0.
`publicUpdatesChannelId`	string \| null \| undefined
`roles`	Map<string, `Role`> \| undefined
`rulesChannelId`	string \| null \| undefined
`safetyAlertsChannelId`	string \| null \| undefined
`splash`	string \| null \| undefined
`stickers`	Map<string, `Sticker`> \| undefined
`systemChannelFlags`	number \| undefined
`systemChannelId`	string \| null \| undefined
`vanityUrlCode`	string \| null \| undefined	The vanity invite code, or `null` if the guild doesn’t have a vanity URL.
`verificationLevel`	VerificationLevel \| undefined	Verification level required to send messages.
`widgetChannelId`	string \| null \| undefined
`widgetEnabled`	boolean \| undefined

Methods

async Guild.addRole(userId: string, roleId: string, reason: string) → Promise<void>: Add a role to a guild member.

async Guild.ban(userId: string, options: { deleteMessageSeconds?: number; reason?: string; }) → Promise<void>

Ban a user from the guild.

Parameters:

userId: The ID of the user to ban.
options: Ban options (message deletion duration, reason).

Guild.bannerURL(options: { format?: “png” | “jpg” | “webp”; size?: number; }) → string | null: Get the CDN URL for the guild’s banner.

async Guild.beginPrune(options: GuildPruneOptions) → Promise<{ pruned: number | null; }>

Permanently removes members that match Discord’s inactivity rules. Use previewPrune first when you need to inspect the estimated count.

Parameters:

options: Prune options (inactivity days, included roles, reason).

Returns:

The prune result with member count.

async Guild.bulkBan(userIds: string[], options: BulkBanOptions) → Promise<BulkBanResult>

Ban up to 200 users in one request. Needs Ban Members and Manage Server. Users who are already banned, or who can’t be banned, are returned in failedUsers.

const { bannedUsers, failedUsers } = await guild.bulkBan(raiderIds, {
  deleteMessageSeconds: 3600,
  reason: "Raid",
});

async Guild.createAutoModRule(options: AutoModRuleCreateOptions) → Promise<AutoModRule>

Create a new auto moderation rule.

Parameters:

options: Auto moderation rule options.

Returns:

The newly created rule.

async Guild.createChannel(options: GuildChannelCreateOptions) → Promise<AnyGuildChannel>

Create a new channel in this guild.

Parameters:

options: Channel creation options.

Returns:

The newly created channel.

async Guild.createEmoji(options: EmojiCreateOptions) → Promise<Emoji>

Create a new custom emoji.

Parameters:

options: Emoji creation options.

Returns:

The newly created emoji.

async Guild.createRole(options: RoleCreateOptions) → Promise<Role>

Create a new role.

Parameters:

options: Role creation options.

Returns:

The newly created role.

async Guild.createScheduledEvent(options: ScheduledEventCreateOptions) → Promise<ScheduledEvent>

Create a new scheduled event.

Parameters:

options: Event creation options.

Returns:

The newly created event.

async Guild.createSoundboardSound(options: SoundboardSoundCreateOptions) → Promise<SoundboardSound>

Upload a sound to this guild’s soundboard.

Parameters:

options: The sound file and its settings.

Returns:

The uploaded sound.

Example

const sound = await guild.createSoundboardSound({
  name: "airhorn",
  sound: `data:audio/mpeg;base64,${base64Mp3}`,
  emojiName: "📯",
});

async Guild.createStageInstance(options: StageInstanceCreateOptions) → Promise<StageInstance>

Create a stage instance in a stage channel.

Parameters:

options: Stage instance creation options.

Returns:

The newly created stage instance.

async Guild.createSticker(options: StickerCreateOptions) → Promise<Sticker>

Create a new sticker.

Parameters:

options: Sticker creation options.

Returns:

The newly created sticker.

async Guild.createTemplate(options: { description?: string; name: string; }) → Promise<GuildTemplate>

Create a new guild template from current settings.

Parameters:

options: Template creation options.

Returns:

The newly created template.

async Guild.deleteIntegration(integrationId: string, reason: string) → Promise<void>: Remove an integration. Removing a bot’s integration also removes the bot from the server. Needs Manage Server.

async Guild.deleteStageInstance(channelId: string, reason: string) → Promise<void>

Delete the active stage instance.

Parameters:

channelId: Stage channel whose active instance should be deleted.
reason: Reason for deletion, shown in audit log.

async Guild.edit(options: GuildEditOptions) → Promise<Guild>

Edit guild properties.

Parameters:

options: Guild properties to update.

async Guild.editChannelPositions(positions: ChannelPosition[]) → Promise<void>

Move several channels at once. Only the fields you set change.

await guild.editChannelPositions([
  { id: rulesId, position: 0 },
  { id: logsId, parentId: staffCategoryId, lockPermissions: true },
]);

async Guild.editOnboarding(options: GuildOnboardingEditOptions) → Promise<GuildOnboarding>: Replace parts of the onboarding flow. prompts replaces every prompt: include existing prompts and options by id to keep them. Needs Manage Server and Manage Roles.

async Guild.editRolePositions(positions: { id: string; position: number; }[], reason: string) → Promise<Role[]>

Batch-edit role positions.

Parameters:

positions: Array of role entries with new positions.
reason: Audit-log reason for changing the positions.

Returns:

The updated roles in their new order.

async Guild.editWelcomeScreen(options: WelcomeScreenEditOptions) → Promise<WelcomeScreen>: Edit the welcome screen. welcomeChannels holds at most 5 channels. Needs Manage Server.

async Guild.editWidgetSettings(options: GuildWidgetSettingsEditOptions) → Promise<GuildWidgetSettings>: Enable or disable the server widget, or change its invite channel. Needs Manage Server.

async Guild.fetch() → Promise<Guild>

Refetch the latest guild data from Discord.

Returns:: The updated guild object.

async Guild.fetchActiveThreads() → Promise<ThreadChannel[]>: List every active thread in the server.

async Guild.fetchAuditLogs(options: AuditLogFetchOptions) → Promise<AuditLog>

Fetch a page of guild audit log entries and related resolved resources. Requires the bot to have PermissionFlags.VIEW_AUDIT_LOG.

Parameters:

options: Optional filters and pagination options.

async Guild.fetchAutoModRules() → Promise<AutoModRule[]>

Fetch all auto moderation rules.

Returns:: An array of all auto moderation rules.

async Guild.fetchBan(userId: string) → Promise<GuildBan | null>

Fetch the ban record for a specific user.

Parameters:

userId: The ID of the banned user.

Returns:

The ban object.

async Guild.fetchBans() → Promise<GuildBan[]>

Fetch all bans in this guild.

Returns:: An array of all guild bans.

async Guild.fetchChannel(channelId: string) → Promise<AnyGuildChannel | null>

Fetch a specific channel by ID.

Parameters:

channelId: The ID of the channel to fetch.

Returns:

The channel, or null if not found.

async Guild.fetchChannels() → Promise<AnyGuildChannel[]>

Fetch all channels in this guild.

Returns:: An array of all guild channels.

async Guild.fetchEmoji(emojiId: string) → Promise<Emoji | null>

Fetch a specific emoji by ID.

Parameters:

emojiId: The ID of the emoji to fetch.

Returns:

The emoji, or null if not found.

async Guild.fetchEmojis() → Promise<Emoji[]>

Fetch all emojis for this guild.

Returns:: An array of all custom emojis.

async Guild.fetchIntegrations() → Promise<GuildIntegration[]>: List the server’s integrations, such as bots and Twitch or YouTube links. Needs Manage Server.

async Guild.fetchInvites() → Promise<Invite[]>

Fetch all invites for this guild.

Returns:: An array of all guild invites.

async Guild.fetchMember(userId: string) → Promise<GuildMember | null>

Fetches a guild member from Discord by user ID.

Parameters:

userId: The ID of the user to fetch.

Returns:

The guild member, or null when it cannot be retrieved.

async Guild.fetchOnboarding() → Promise<GuildOnboarding>: Read the server’s onboarding flow.

async Guild.fetchRole(roleId: string) → Promise<Role | null>

Fetch a role by ID.

Parameters:

roleId: The ID of the role to fetch.

Returns:

The role, or null if not found.

async Guild.fetchRoles() → Promise<Role[]>

Fetch all roles in this guild.

Returns:: An array of all roles.

async Guild.fetchScheduledEvents(options: { withUserCount?: boolean; }) → Promise<ScheduledEvent[]>

Fetch all scheduled events.

Returns:: An array of all scheduled events.

async Guild.fetchSoundboardSounds() → Promise<SoundboardSound[]>

Fetch the sounds uploaded to this guild’s soundboard.

Returns:: An array of the guild’s sounds. Discord’s default sounds are not included.

async Guild.fetchStageInstance(channelId: string) → Promise<StageInstance | null>

Fetch the active stage instance.

Returns:: The stage instance, or null if none is running.

async Guild.fetchStickers() → Promise<Sticker[]>

Fetch all stickers for this guild.

Returns:: An array of all stickers.

async Guild.fetchTemplates() → Promise<GuildTemplate[]>

Fetch all guild templates.

Returns:: An array of all templates.

async Guild.fetchVanityUrl() → Promise<GuildVanityUrl>: Read the vanity invite code and how many times it has been used. Needs Manage Server.

async Guild.fetchWebhooks() → Promise<Webhook[]>

Fetch all webhooks for this guild.

Returns:: An array of all webhooks.

async Guild.fetchWelcomeScreen() → Promise<WelcomeScreen>: Read the welcome screen shown to new members of a Community server.

async Guild.fetchWidgetSettings() → Promise<GuildWidgetSettings>: Read whether the server widget is enabled and which channel it invites to.

async Guild.getCachedPresence(userId: string) → Promise<Presence | null>: Read a member’s presence from Weeble’s gateway cache, if currently known.

async Guild.getChannels() → Promise<AnyGuildChannel[]>: Gets this guild’s channels from the gateway cache. Cached channels have their name, type, category, nsfw flag and permission overwrites, but not topic, position or slowmode. Falls back to fetchChannels() when the cache is empty.

async Guild.getMember(userId: string) → Promise<GuildMember | null>

Gets a member from the gateway cache. The cached member has user, nick, roles and joinedAt, which covers role checks and display names; avatar, timeout and boost fields are missing. Falls back to fetchMember() when the member isn’t cached.

const member = await guild.getMember(message.author.id);
if (member?.hasRole(modRoleId)) await message.reply("Hi, mod.");

Parameters:

userId: The member’s user ID.

async Guild.getRole(roleId: string) → Promise<Role | null>

Gets one role from the gateway cache. See getRoles() for which fields a cached role has.

Parameters:

roleId: The role ID.

async Guild.getRoles() → Promise<Role[]>: Gets this guild’s roles from the gateway cache. Cached roles have name, permissions and position, which is enough for permission and hierarchy checks; color, icon and flags are missing. Falls back to fetchRoles() when the cache is empty.

Guild.iconURL(options: { format?: “png” | “jpg” | “webp” | “gif”; size?: number; }) → string | null

Get the CDN URL for the guild’s icon.

Parameters:

options: Icon size and format options.

Returns:

The icon URL, or null if no icon is set.

Guild.iterAuditLogs(options: { actionType?: AuditLogActionType; limit?: number; userId?: string; }) → AsyncIterableIterator<AnyAuditLogEntry>: Iterate guild audit log entries, optionally filtered by action or user.

Guild.iterMembers(options: FetchMembersOptions) → AsyncIterableIterator<GuildMember>

Iterate over all guild members with optional pagination.

Parameters:

options: Pagination options (limit, after, etc.).

Returns:

An async iterable yielding members one at a time.

async Guild.kick(userId: string, reason: string) → Promise<void>: Remove a member from the guild.

async Guild.me() → Promise<GuildMember>

Fetch the bot’s own member object for this guild.

Returns:: The bot’s guild member object.

async Guild.pauseInvites(until: Date | null, reason: string) → Promise<void>: Stop new members from joining through invites until until, at most 24 hours ahead. Pass null to resume invites early. Needs Manage Server. Discord’s member-DM pause setting is left as it is.

async Guild.previewPrune(options: { days?: number; includeRoles?: string[]; }) → Promise<{ pruned: number | null; }>

Preview how many members would be pruned.

Parameters:

options: Prune criteria (inactivity days, excluded roles).

Returns:

The estimated prune count.

async Guild.removeRole(userId: string, roleId: string, reason: string) → Promise<void>: Remove a role from a guild member.

async Guild.searchMembers(query: string, options: { limit?: number; }) → Promise<GuildMember[]>

Search for guild members by username or nickname prefix via Discord API.

Parameters:

query: The username or nickname prefix to search for.
options: Optional search options.

Returns:

Matching guild members.

async Guild.searchMessages(options: GuildMessageSearchOptions) → Promise<GuildMessageSearchResult>

Search messages across the guild. A server that was just added may still be indexing: check status and retry after retryAfter seconds.

const result = await guild.searchMessages({ content: "refund", limit: 10 });
if (result.status === "ready") console.log(result.totalResults);

async Guild.unban(userId: string, reason: string) → Promise<void>

Remove (unban) a user.

Parameters:

userId: The ID of the user to unban.
reason: Reason for the unban, shown in audit log.

Guild

Type aliases