> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Guild

> Read everything about a server and manage its members, roles, channels and bans

A `Guild` is a server ("guild" is the name Discord gives servers in its API). You get one as the `guild` of a [command](https://www.chapterjs.org/reference/interaction.md) used in a server, with the events that happen in one, and as `member.guild`, `role.guild` or `channel.guild`.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import type { Guild } from 'chapterjs';

async function describe(guild: Guild) {
  const owner = await guild.fetchOwner();
  return `${guild.name} has ${guild.memberCount} members and belongs to ${owner.displayName}.`;
}
```

> [!NOTE]
>
> How your functions receive a server is in [Commands](https://www.chapterjs.org/commands.md) and [Events](https://www.chapterjs.org/events.md). What a server remembers about its members, and why not all of them, is in [Memory](https://www.chapterjs.org/memory.md).

## Properties

**id** `Snowflake`

The unique id Discord gave it.

**createdAt** `Date`

When it was created: a Discord id contains its creation date.

**name** `string`

The name of the server.

**description** `string | null`

The description of the server, when it has one.

**ownerId** `Snowflake`

The id of the user who owns the server.

**available** `boolean`

`false` during an outage of Discord: the data may be out of date.

**memberCount** `number | null`

How many members the server has. Exact when the bot receives member events, approximate otherwise; `null` when Discord never said it.

**features** `readonly GuildFeature[]`

What the server has enabled or unlocked (`COMMUNITY`, `VANITY_URL`...). See [GuildFeature](#guildfeature).

**verificationLevel** `VerificationLevel`

What Discord asks of new members before they can write. See [VerificationLevel](https://www.chapterjs.org/reference/enums.md#verificationlevel).

**premiumTier** `PremiumTier`

The boost level of the server. See [PremiumTier](https://www.chapterjs.org/reference/enums.md#premiumtier).

**boostCount** `number`

How many boosts the server has.

**preferredLocale** `Locale`

The language of the server, used for what Discord sends to it. See [Locale](https://www.chapterjs.org/reference/enums.md#locale).

**vanityUrlCode** `string | null`

The code of the custom invite link of the server, when it has one.

**systemChannelId** `Snowflake | null`

The id of the channel where Discord posts welcome messages.

**rulesChannelId** `Snowflake | null`

The id of the channel that shows the rules, in a community server.

**afkChannelId** `Snowflake | null`

The id of the voice channel inactive members are moved to.

**joinedAt** `Date | null`

When the bot joined the server, when Discord said it.

**roles** `ReadonlyMap\<Snowflake, Role\>`

The roles of the server, @everyone included.

**members** `ReadonlyMap\<Snowflake, GuildMember\>`

The members of the server the bot knows: the ones seen the most recently, not all of them.

**channels** `ReadonlyMap\<Snowflake, GuildChannel | ThreadChannel\>`

The channels and active threads of the server.

**emojis** `ReadonlyMap\<Snowflake, GuildEmoji\>`

The custom emojis of the server.

**voice** `VoiceConnection | null`

The bot in voice in this server, to play or leave; `null` when it is in no voice channel here. See [VoiceConnection](https://www.chapterjs.org/reference/voice-connection.md).

**everyoneRole** `Role`

The @everyone role, which every member has.

**me** `GuildMember`

The bot as a member of this server.

> [!NOTE]
>
> `members` only holds the members the bot has seen lately (see [Memory](https://www.chapterjs.org/memory.md)). Use [`fetchMember()`](#fetchmember) to get one for sure. `me` is always there, whatever the bot remembers.

## Helpers

These read what the bot remembers: they never send a request.

### iconURL()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
iconURL(options?: ImageOptions): string | null
```

The URL of the icon of the server, when it has one. See [ImageOptions](https://www.chapterjs.org/reference/helpers.md#imageoptions).

### bannerURL()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
bannerURL(options?: ImageOptions): string | null
```

The URL of the banner of the server, when it has one. See [ImageOptions](https://www.chapterjs.org/reference/helpers.md#imageoptions).

### splashURL()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
splashURL(options?: ImageOptions): string | null
```

The URL of the invite background of the server, when it has one. See [ImageOptions](https://www.chapterjs.org/reference/helpers.md#imageoptions).

### toString()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
toString(): string
```

The name of the server.

### toJSON()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
toJSON(): object
```

The data of Discord as a plain object, with camelCase names.

## Reading from Discord

### fetch()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetch(): Promise<Guild>
```

Asks Discord for the latest data of the server.

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild)

### fetchMember()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchMember(user: Snowflake | { id: Snowflake }, options?: { force?: boolean }): Promise<GuildMember>
```

A member of the server: from what the bot remembers, or else from Discord.

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-member)

### fetchMembers()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchMembers(options?: { limit?: number; after?: Snowflake | { id: Snowflake } }): Promise<GuildMember[]>
```

Members of the server, by pages of 1000 at most, ordered by id. Needs the Server Members intent to be enabled for the bot.

`limit` is a whole number between 1 and 1000 (the default); `after` is the id of the last member of the previous page.

[Discord documentation](https://docs.discord.com/developers/resources/guild#list-guild-members)

### searchMembers()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
searchMembers(query: string, limit?: number): Promise<GuildMember[]>
```

Members whose username or nickname starts with the given text. `limit` is `1` by default.

[Discord documentation](https://docs.discord.com/developers/resources/guild#search-guild-members)

### fetchOwner()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchOwner(): Promise<GuildMember>
```

The member who owns the server.

### fetchBan()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchBan(user: Snowflake | { id: Snowflake }): Promise<Ban | null>
```

The ban of a user; `null` when they are not banned. See [Ban](https://www.chapterjs.org/reference/data.md#ban).

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-ban)

### fetchBans()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchBans(options?: { limit?: number; before?: Snowflake; after?: Snowflake }): Promise<Ban[]>
```

The bans of the server, by pages of 1000 at most. See [Ban](https://www.chapterjs.org/reference/data.md#ban).

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-bans)

### fetchRoles()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchRoles(): Promise<Role[]>
```

Asks Discord for the roles of the server.

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-roles)

### fetchChannels()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchChannels(): Promise<GuildChannel[]>
```

The channels of the server (threads are not included).

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-channels)

### fetchActiveThreads()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchActiveThreads(): Promise<ThreadChannel[]>
```

The threads of the server that are not archived.

[Discord documentation](https://docs.discord.com/developers/resources/guild#list-active-guild-threads)

### fetchEmojis()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchEmojis(): Promise<GuildEmoji[]>
```

Asks Discord for the custom emojis of the server.

[Discord documentation](https://docs.discord.com/developers/resources/emoji#list-guild-emojis)

### fetchInvites()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchInvites(): Promise<Invite[]>
```

The invites of the server, with how many times each was used.

[Discord documentation](https://docs.discord.com/developers/resources/guild#get-guild-invites)

### fetchWebhooks()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchWebhooks(): Promise<Webhook[]>
```

The webhooks of every channel of the server.

[Discord documentation](https://docs.discord.com/developers/resources/webhook#get-guild-webhooks)

### fetchAuditLog()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchAuditLog(options?: {
  userId?: Snowflake;
  actionType?: AuditLogEvent;
  before?: Snowflake;
  after?: Snowflake;
  limit?: number;
}): Promise<AuditLog>
```

What moderators and bots did in the server. The options are the [audit log filters](#audit-log-filters); the result is an [AuditLog](https://www.chapterjs.org/reference/data.md#auditlog).

[Discord documentation](https://docs.discord.com/developers/resources/audit-log#get-guild-audit-log)

### fetchScheduledEvents()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchScheduledEvents(): Promise<ScheduledEvent[]>
```

The scheduled events of the server. See [ScheduledEvent](https://www.chapterjs.org/reference/data.md#scheduledevent).

[Discord documentation](https://docs.discord.com/developers/resources/guild-scheduled-event#list-scheduled-events-for-guild)

### fetchAutoModerationRules()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchAutoModerationRules(): Promise<AutoModerationRule[]>
```

The auto moderation rules of the server. See [AutoModerationRule](https://www.chapterjs.org/reference/data.md#automoderationrule).

[Discord documentation](https://docs.discord.com/developers/resources/auto-moderation#list-auto-moderation-rules-for-guild)

### fetchStickers()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
fetchStickers(): Promise<Sticker[]>
```

The custom stickers of the server. See [Sticker](https://www.chapterjs.org/reference/data.md#sticker).

[Discord documentation](https://docs.discord.com/developers/resources/sticker#list-guild-stickers)

## Actions

### edit()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
edit(options: GuildEditOptions, reason?: string): Promise<Guild>
```

Changes the settings of the server. See [GuildEditOptions](https://www.chapterjs.org/reference/options.md#guildeditoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#modify-guild)

### leave()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
leave(): Promise<void>
```

Makes the bot leave the server.

[Discord documentation](https://docs.discord.com/developers/resources/user#leave-guild)

### kick()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
kick(user: Snowflake | { id: Snowflake }, reason?: string): Promise<void>
```

Removes a member from the server; they can come back with an invite.

[Discord documentation](https://docs.discord.com/developers/resources/guild#remove-guild-member)

### ban()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
ban(user: Snowflake | { id: Snowflake }, options?: BanOptions): Promise<void>
```

Bans a user from the server, member or not. See [BanOptions](https://www.chapterjs.org/reference/member.md#banoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#create-guild-ban)

### bulkBan()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
bulkBan(
  users: readonly (Snowflake | { id: Snowflake })[],
  options?: BanOptions
): Promise<{ bannedUsers: Snowflake[]; failedUsers: Snowflake[] }>
```

Bans up to 200 users at once. Returns the ids of the users that were banned, and of those that could not be. See [BanOptions](https://www.chapterjs.org/reference/member.md#banoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#bulk-guild-ban)

### unban()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
unban(user: Snowflake | { id: Snowflake }, reason?: string): Promise<void>
```

Lifts the ban of a user.

[Discord documentation](https://docs.discord.com/developers/resources/guild#remove-guild-ban)

### createRole()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
createRole(options?: RoleCreateOptions, reason?: string): Promise<Role>
```

Creates a role. See [RoleCreateOptions](https://www.chapterjs.org/reference/options.md#rolecreateoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#create-guild-role)

### createChannel()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
createChannel(options: ChannelCreateOptions, reason?: string): Promise<GuildChannel>
```

Creates a channel. See [ChannelCreateOptions](https://www.chapterjs.org/reference/options.md#channelcreateoptions).

[Discord documentation](https://docs.discord.com/developers/resources/guild#create-guild-channel)

### createEmoji()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
createEmoji(
  options: { name: string; image: string; roles?: (Snowflake | { id: Snowflake })[] },
  reason?: string
): Promise<GuildEmoji>
```

Adds a custom emoji to the server. `options.image` is the image as a data URI (`data:image/png;base64,...`).

[Discord documentation](https://docs.discord.com/developers/resources/emoji#create-guild-emoji)

### createScheduledEvent()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
createScheduledEvent(
  options: {
    name: string;
    privacyLevel: number;
    scheduledStartTime: string;
    entityType: number;
    channelId?: Snowflake;
    entityMetadata?: { location?: string };
    scheduledEndTime?: string;
    description?: string;
    image?: string;
    recurrenceRule?: object;
  },
  reason?: string
): Promise<ScheduledEvent>
```

Schedules an event in the server. The options are the [scheduled event options](#scheduled-event-options); the result is a [ScheduledEvent](https://www.chapterjs.org/reference/data.md#scheduledevent).

[Discord documentation](https://docs.discord.com/developers/resources/guild-scheduled-event#create-guild-scheduled-event)

## Types

### GuildFeature

What a server has enabled or unlocked, as Discord names it: one of `'ANIMATED_BANNER'`, `'ANIMATED_ICON'`, `'APPLICATION_COMMAND_PERMISSIONS_V2'`, `'AUTO_MODERATION'`, `'BANNER'`, `'COMMUNITY'`, `'CREATOR_MONETIZABLE_PROVISIONAL'`, `'CREATOR_STORE_PAGE'`, `'DEVELOPER_SUPPORT_SERVER'`, `'DISCOVERABLE'`, `'ENHANCED_ROLE_COLORS'`, `'FEATURABLE'`, `'GUILD_TAGS'`, `'GUESTS_ENABLED'`, `'INVITES_DISABLED'`, `'INVITE_SPLASH'`, `'MEMBER_VERIFICATION_GATE_ENABLED'`, `'MORE_SOUNDBOARD'`, `'MORE_STICKERS'`, `'NEWS'`, `'PARTNERED'`, `'PREVIEW_ENABLED'`, `'PRUNE_REQUIRES_ADMIN'`, `'RAID_ALERTS_DISABLED'`, `'ROLE_ICONS'`, `'ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASE'`, `'ROLE_SUBSCRIPTIONS_ENABLED'`, `'SOUNDBOARD'`, `'TICKETED_EVENTS_ENABLED'`, `'VANITY_URL'`, `'VERIFIED'`, `'VIP_REGIONS'`, `'WELCOME_SCREEN_ENABLED'`.

Discord adds features over time, so any other text is accepted too: `guild.features.includes('COMMUNITY')` is typed, and an unknown feature does not break anything.

[Discord documentation](https://docs.discord.com/developers/resources/guild#guild-object-guild-features)

### Audit log filters

What `fetchAuditLog()` takes. Every field can be left out.

**userId** `Snowflake`

Only the entries of this user.

**actionType** `AuditLogEvent`

Only the entries of this kind of action. See [AuditLogEvent](https://www.chapterjs.org/reference/enums.md#auditlogevent).

**before** `Snowflake`

Only the entries with an id lower than this audit log entry id.

**after** `Snowflake`

Only the entries with an id higher than this audit log entry id.

**limit** `number`

How many entries at most, between 1 and 100; 50 by default.

[Discord documentation](https://docs.discord.com/developers/resources/audit-log#get-guild-audit-log-query-string-params)

### Scheduled event options

What `createScheduledEvent()` takes. Dates are ISO 8601 texts (`date.toISOString()`); the image is a data URI (`data:image/png;base64,...`).

**name** `string` *required*

The name of the scheduled event.

**privacyLevel** `number` *required*

The privacy level of the scheduled event: `2` (only the members of the server).

**scheduledStartTime** `string` *required*

The time to schedule the scheduled event.

**entityType** `number` *required*

Where the event takes place: `1` in a stage channel, `2` in a voice channel, `3` somewhere else (`entityMetadata.location` then says where).

**channelId** `Snowflake`

The channel id of the scheduled event.

**entityMetadata** `\{ location?: string \}`

The entity metadata of the scheduled event: `location` is where it takes place (1-100 characters).

**scheduledEndTime** `string`

The time when the scheduled event is scheduled to end.

**description** `string`

The description of the scheduled event.

**image** `string`

The cover image of the scheduled event.

**recurrenceRule** `object`

The definition for how often this event should recur, as Discord describes it.

[Discord documentation](https://docs.discord.com/developers/resources/guild-scheduled-event#create-guild-scheduled-event-json-params)

### Other types

* [`GuildEditOptions`](https://www.chapterjs.org/reference/options#guildeditoptions), [`ChannelCreateOptions`](https://www.chapterjs.org/reference/options#channelcreateoptions) and [`RoleCreateOptions`](https://www.chapterjs.org/reference/options#rolecreateoptions) are in [Options](https://www.chapterjs.org/reference/options.md).
* [`AuditLog`](https://www.chapterjs.org/reference/data#auditlog), [`AutoModerationRule`](https://www.chapterjs.org/reference/data#automoderationrule), [`Ban`](https://www.chapterjs.org/reference/data#ban), [`ScheduledEvent`](https://www.chapterjs.org/reference/data#scheduledevent) and [`Sticker`](https://www.chapterjs.org/reference/data#sticker) are in [Data](https://www.chapterjs.org/reference/data.md).
* [`BanOptions`](https://www.chapterjs.org/reference/member#banoptions) is in [GuildMember](https://www.chapterjs.org/reference/member.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.