Widgets

This section documents everything related to widgets — dynamically generated elements which show basic info about your server and invites to join it easily, which can be displayed on websites.

Discord Models

Widget

Attributes
Methods
class disnake.Widget[source]

Represents a Guild widget.

x == y

Checks if two widgets are the same.

x != y

Checks if two widgets are not the same.

str(x)

Returns the widget’s JSON URL.

id

The guild’s ID.

Type:

int

name

The guild’s name.

Type:

str

channels

The publicly accessible voice and stage channels in the guild.

Type:

list[WidgetChannel]

members

The online members in the server. Offline members do not appear in the widget.

Note

Due to a Discord limitation, if this data is available the users will be “anonymized” with linear IDs. Likewise, the number of members retrieved is capped.

Type:

list[WidgetMember]

presence_count

The number of online members in the server.

New in version 2.6.

Type:

int

property created_at[source]

Returns the member’s creation time in UTC.

Type:

datetime.datetime

property json_url[source]

The JSON URL of the widget.

Type:

str

property invite_url[source]

The invite URL for the guild, if available.

Type:

str | None

await fetch_invite(*, with_counts=True)[source]

This function is a coroutine.

Retrieves an Invite from the widget’s invite URL. This is the same as Client.fetch_invite(); the invite code is abstracted away.

Changed in version 2.6: This may now return None if the widget does not have an attached invite URL.

Parameters:

with_counts (bool) – Whether to include count information in the invite. This fills the Invite.approximate_member_count and Invite.approximate_presence_count fields.

Returns:

The invite from the widget’s invite URL, if available.

Return type:

Invite | None

await edit(*, enabled=..., channel=..., reason=None)[source]

This function is a coroutine.

Edits the widget.

You must have manage_guild permission to do this

New in version 2.4.

Parameters:

  • enabled (bool) – Whether to enable the widget.

  • channel (Snowflake | None) – The new widget channel. Pass None to remove the widget channel.

  • reason (str | None) – The reason for editing the widget. Shows up on the audit log.

Raises:
image_url(style=WidgetStyle.shield)[source]

Returns an URL to the widget’s .png image.

New in version 2.5.

Parameters:

style (WidgetStyle) – The widget style.

Returns:

The widget image URL.

Return type:

str

WidgetSettings

Attributes
Methods
class disnake.WidgetSettings[source]

Represents a Guild’s widget settings.

New in version 2.5.

guild

The widget’s guild.

Type:

Guild

enabled

Whether the widget is enabled.

Type:

bool

channel_id

The widget channel ID. If set, an invite link for this channel will be generated, which allows users to join the guild from the widget.

Type:

int | None

property channel[source]

The widget channel, if set.

Type:

abc.GuildChannel | None

await edit(*, enabled=..., channel=..., reason=None)[source]

This function is a coroutine.

Edits the widget.

You must have manage_guild permission to do this.

Parameters:

  • enabled (bool) – Whether to enable the widget.

  • channel (Snowflake | None) – The new widget channel. Pass None to remove the widget channel. If set, an invite link for this channel will be generated, which allows users to join the guild from the widget.

  • reason (str | None) – The reason for editing the widget. Shows up on the audit log.

Raises:
Returns:

The new widget settings.

Return type:

WidgetSettings

WidgetChannel

Attributes
class disnake.WidgetChannel[source]

Represents a “partial” widget channel.

x == y

Checks if two partial channels are the same.

x != y

Checks if two partial channels are not the same.

hash(x)

Return the partial channel’s hash.

str(x)

Returns the partial channel’s name.

id

The channel’s ID.

Type:

int

name

The channel’s name.

Type:

str

position

The channel’s position

Type:

int

property mention[source]

The string that allows you to mention the channel.

Type:

str

property created_at[source]

Returns the channel’s creation time in UTC.

Type:

datetime.datetime

WidgetMember

Attributes
class disnake.WidgetMember[source]

Represents a “partial” member of the widget’s guild.

x == y

Checks if two widget members are the same.

x != y

Checks if two widget members are not the same.

hash(x)

Return the widget member’s hash.

str(x)

Returns the widget member’s name.

id

The member’s anonymized ID.

Type:

int

name

The member’s name.

Type:

str

discriminator

The member’s anonymized discriminator.

Note

This is being phased out by Discord; the username system is moving away from username#discriminator to users having a globally unique username. See the help article for details.

Type:

str

status

The member’s status.

Type:

Status

activity

The member’s activity. This generally only has the name set.

Type:

BaseActivity | Spotify | None

deafened

Whether the member is currently deafened.

Type:

bool | None

muted

Whether the member is currently muted.

Type:

bool | None

suppress

Whether the member is currently being suppressed.

Type:

bool | None

connected_channel

Which channel the member is connected to.

Type:

WidgetChannel | None

property avatar[source]

The user’s avatar. The size can be chosen using Asset.with_size(), however the format is always static and cannot be changed through Asset.with_format() or similar methods.

Type:

Asset | None

property display_name[source]

Returns the member’s name.

Type:

str

property display_avatar[source]

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type:

Asset

Enumerations

WidgetStyle

class disnake.WidgetStyle[source]

Represents the supported widget image styles.

New in version 2.5.

shield

A shield style image with a Discord icon and the online member count.

banner1

A large image with guild icon, name and online member count and a footer.

banner2

A small image with guild icon, name and online member count.

banner3

A large image with guild icon, name and online member count and a footer, with a “Chat Now” label on the right.

banner4

A large image with a large Discord logo, guild icon, name and online member count, with a “Join My Server” label at the bottom.