GuildMember

class GuildMember

A user’s membership state within one guild, including roles, nickname, permissions, and moderation state. Unlike User, this object contains server-specific data and is only valid for guildId.

Implements:

Properties

Property

Type

Description

communicationDisabledUntil

Date | null | undefined

When the member’s timeout expires, or null if not timed out.

createdAt

Date

When the underlying user account was created, decoded from the member/user snowflake.

displayName

string

Get the display name (nickname, then global name, then username as fallback).

guildId

string

ID of the guild this member belongs to.

id

string

User ID for this guild member.

isTimedOut

boolean

Whether the member is currently timed out.

joinedAt

Date | undefined

When the member joined the guild. undefined when the payload omitted it (not invented as “now”).

nick

string | null | undefined

The member’s nickname (server name), or null if not set.

pending

boolean | undefined

Whether the member has not yet passed the guild’s membership screening requirements.

permissions

bigint | undefined

Combined permission bitmask for this member (guild-level + role-based). undefined when the payload omitted it; not invented as 0.

premiumSince

Date | null | undefined

When the member started boosting, or null if not boosting.

roles

string[] | undefined

Array of role IDs assigned to this member.

user

User

The underlying user object.

Methods

async GuildMember.addRole(roleId: string, reason: string) → Promise<void>

Add a role to this member.

Parameters:

  • roleId: The ID of the role to add.

  • reason: Audit-log reason for adding the role.

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

Ban this member from the guild.

Parameters:

  • options: Options for the ban. deleteMessageSeconds must be an integer from 0 through 604800.

GuildMember.can(permission: bigint) → boolean

Checks the permission snapshot included in this member payload. Returns false when Discord omitted permissions; use resolvePermissions to fetch and calculate it.

Parameters:

  • permission: The permission flag to check.

Returns:

Whether the member has the permission.

async GuildMember.canIn(channelId: string, permission: bigint) → Promise<boolean>

Check if this member has a specific permission in a given channel.

Parameters:

  • channelId: The channel to resolve permissions for.

  • permission: The permission flag(s) to test.

Returns:

Whether every requested permission flag is set.

GuildMember.displayAvatarURL(options: { format?: “png” | “jpg” | “webp” | “gif”; size?: number; }) → string

Get the CDN URL for the member’s guild-specific avatar (falls back to user avatar).

Parameters:

  • options: Optional size and image format for the avatar.

Returns:

The CDN URL string.

async GuildMember.edit(options: GuildMemberEditOptions) → Promise<GuildMember>

Edit this member’s guild-specific state.

Parameters:

  • options: Member properties to update and optional audit-log reason.

Returns:

The updated member.

async GuildMember.fetch() → Promise<GuildMember>

Requests the latest guild-member data from Discord. This is useful after role, nickname, timeout, or membership changes.

Returns:

The updated member object.

async GuildMember.fetchGuild() → Promise<Guild>

Fetch the guild this member belongs to from Discord.

Returns:

The guild object.

async GuildMember.getCachedPresence(userId: string) → Promise<Presence | null>

Get this member’s cached presence, or another member’s presence by user ID. Returns null when Discord has not provided a cached presence.

Parameters:

  • userId: Optional user ID. Defaults to this member’s user ID.

Returns:

The cached presence, or null when unavailable.

async GuildMember.getVoiceState() → Promise<VoiceState | null>

Get this member’s current voice state from Weeble’s gateway cache.

GuildMember.hasRole(roleId: string) → boolean

Check if this member has a specific role.

Parameters:

  • roleId: The ID of the role to check.

Returns:

Whether the member has the role.

async GuildMember.highestRole() → Promise<Role | null>

Get the highest-positioned role this member has.

Returns:

The highest role, or null if the member has no roles.

async GuildMember.kick(reason: string) → Promise<void>

Kick this member from the guild.

Parameters:

  • reason: Audit-log reason for removing the member.

async GuildMember.removeRole(roleId: string, reason: string) → Promise<void>

Remove a role from this member.

Parameters:

  • roleId: The ID of the role to remove.

  • reason: Audit-log reason for removing the role.

async GuildMember.resolvePermissions(channelId: string) → Promise<bigint>

Fetches the guild and resolves effective permissions using Discord’s hierarchy: guild owner bypass →

Parameters:

  • channelId: Optional channel ID to apply permission overwrites for. When omitted, only guild-level and role permissions are computed.

Returns:

The resolved permission bitmask.

async GuildMember.roleObjects() → Promise<Role[]>

Get all role objects assigned to this member.

Returns:

Array of role objects.

async GuildMember.setNickname(nickname: string | null, reason: string) → Promise<void>

Set or clear the member’s nickname. Requires MANAGE_NICKNAMES permission.

Parameters:

  • nickname: The new nickname, or null to clear.

  • reason: The reason for the audit log.

async GuildMember.timeout(durationMs: number | null, reason: string) → Promise<void>

Time-out the member for a duration in milliseconds, or null to remove timeout.

Parameters:

  • durationMs: Positive integer duration in milliseconds, no greater than 28 days, or null to remove timeout.

  • reason: The reason for the audit log.

GuildMember.toMention() → string

Returns <@userId> mention syntax.

Returns:

The mention string for this member.