Pincer Objects Guild#

Audit Log#

AuditLogEvent#

Attributes
class AuditLogEvent#

Bases: IntEnum

Audit log action type. This represents the action which got performed, and logged.

GUILD_UPDATE#

Guild updated.

CHANNEL_CREATE#

Channel created.

CHANNEL_UPDATE#

Channel updated.

CHANNEL_DELETE#

Channel deleted.

CHANNEL_OVERWRITE_CREATE#

Channel overwrites created.

CHANNEL_OVERWRITE_UPDATE#

Channel overwrites updated.

CHANNEL_OVERWRITE_DELETE#

Channel overwrites deleted.

MEMBER_KICK#

Member kicked.

MEMBER_PRUNE#

Members pruned.

MEMBER_BAN_ADD#

Member banned.

MEMBER_BAN_REMOVE#

Member unbanned.

MEMBER_UPDATE#

Member edit.

MEMBER_ROLE_UPDATE#

Member role change.

MEMBER_MOVE#

Member voice channel move.

MEMBER_DISCONNECT#

Member voice channel disconnect.

BOT_ADD#

Bot added.

ROLE_CREATE#

Role created.

ROLE_UPDATE#

Role updated.

ROLE_DELETE#

Role deleted.

INVITE_CREATE#

Invite created.

INVITE_UPDATE#

Invite updated.

INVITE_DELETE#

Invite deleted.

WEBHOOK_CREATE#

Webhook created.

WEBHOOK_UPDATE#

Webhook updated.

WEBHOOK_DELETE#

Webhook deleted.

EMOJI_CREATE#

Emoji created.

EMOJI_UPDATE#

Emoji updated.

EMOJI_DELETE#

Emoji deleted.

MESSAGE_DELETE#

Message deleted.

MESSAGE_BULK_DELETE#

Message bulk delete.

MESSAGE_PIN#

Message pinned.

MESSAGE_UNPIN#

Message unpinned.

INTEGRATION_CREATE#

Integration created.

INTEGRATION_UPDATE#

Integration updated.

INTEGRATION_DELETE#

Integration deleted.

STAGE_INSTANCE_CREATE#

Stage instance created.

STAGE_INSTANCE_UPDATE#

Stage instance updated.

STAGE_INSTANCE_DELETE#

Stage instance deleted.

STICKER_CREATE#

Sticker created.

STICKER_UPDATE#

Sticker updated.

STICKER_DELETE#

Sticker deleted.

THREAD_CREATE1#

Thread created.

THREAD_UPDATE1#

Thread updated.

THREAD_DELETE1#

Thread deleted.

AuditLogChange#

Attributes
class AuditLogChange#

Bases: APIObject

Representation of Discord Audit Log Change object

new_value#

New value of the key

Type

Any

old_value#

Old value of the key

Type

Any

key#

Name of audit log change key

Type

str

AuditEntryInfo#

Attributes
class AuditEntryInfo#

Bases: APIObject, ChannelProperty

Represents Discord Optional Audit Entry Info

delete_member_days#

Number of days after which inactive members were kicked

Type

str

members_removed#

Number of members removed by the prune

Type

str

channel_id#

Channel in which the entities were targeted

Type

Snowflake

message_id#

Id of the message that was targeted

Type

Snowflake

count#

Number of entities that were targeted

Type

str

id#

Id of the overwritten entity

Type

Snowflake

type#

Type of overwritten entity - “0” for “role” or “1” for “member”

Type

str

role_name#

Name of the role if type is “0” (not present if type is “1”)

Type

str

AuditLogEntry#

Attributes
class AuditLogEntry#

Bases: APIObject

Represents a Discord Audit Log Entry object.

target_id#

Id of the affected entity x(webhook, user, role, etc.)

Type

Optional[str]

user_id#

The user who made the changes

Type

Snowflake

id#

Id of the entry

Type

Snowflake

action_type#

Type of action that occurred

Type

AuditLogEvent

changes#

Changes made to the target_id

Type

APINullable[List[AuditLogChange]]

options#

Additional info for certain action types

Type

APINullable[List[AuditLogChange]]

reason#

The reason for the change x(0-512 characters)

Type

APINullable[str]

AuditLog#

class AuditLog#

Bases: APIObject

Represents a Discord Audit Log object.

webhooks: List[Webhook]

list of webhooks found in the audit log

users: List[User]

list of users found in the audit log

audit_log_entries: List[AuditLogEntry]

list of audit log entries

integrations: List[Integration]

list of partial integration objects

threads: List[Channel]

list of threads found in the audit log

Ban#

Ban#

Attributes
class Ban#

Bases: APIObject

Representation of the Discord Ban object

reason#

The reason for the ban

Type

Optional[str]

user#

The banned user

Type

User

Channel#

ChannelType#

Attributes
class ChannelType#

Bases: IntEnum

Represents a channel its type.

GUILD_TEXT#

A text channel.

DM#

A DM channel.

GUILD_VOICE#

A voice channel.

GROUP_DM#

A group DM channel.

GUILD_CATEGORY#

A category channel.

GUILD_NEWS#

A news channel.

GUILD_STORE#

A store channel.

GUILD_NEWS_THREAD#

A news thread.

GUILD_PUBLIC_THREAD#

A public thread.

GUILD_PRIVATE_THREAD#

A private thread.

GUILD_STAGE_VOICE#

A stage channel.

Channel#

Attributes
Methods
class Channel#

Bases: APIObject, GuildProperty

Represents a Discord Channel Mention object

id#

The id of this channel

Type

Snowflake

type#

The type of channel

Type

ChannelType

application_id#

Application id of the group DM creator if it is bot-created

Type

APINullable[Snowflake]

bitrate#

The bitrate (in bits) of the voice channel

Type

APINullable[int]

default_auto_archive_duration#

Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080

Type

APINullable[int]

guild_id#

The id of the guild (maybe missing for some channel objects received over gateway guild dispatches)

Type

APINullable[Snowflake]

icon#

Icon hash

Type

APINullable[Optional[str]]

last_message_id#

The id of the last message sent in this channel (may not point to an existing or valid message)

Type

APINullable[Optional[Snowflake]]

last_pin_timestamp#

When the last pinned message was pinned. This may be null in events such as GUILD_CREATE when a message is not pinned.

Type

APINullable[Optional[Timestamp]]

member#

Thread member object for the current user, if they have joined the thread, only included on certain API endpoints

Type

APINullable[GuildMember]

member_count#

An approximate count of users in a thread, stops counting at 50

Type

APINullable[int]

message_count#

An approximate count of messages in a thread, stops counting at 50

Type

int

name#

The name of the channel (1-100 characters)

Type

APINullable[str]

nsfw#

Whether the channel is nsfw

Type

APINullable[bool]

owner_id#

Id of the creator of the group DM or thread

Type

APINullable[Snowflake]

parent_id#

For guild channels: id of the parent category for a channel (each parent category can contain up to 50 channels), for threads: id of the text channel this thread was created

Type

APINullable[Optional[Snowflake]]

permissions#

Computed permissions for the invoking user in the channel, including overwrites, only included when part of the resolved data received on a slash command interaction

Type

APINullable[str]

permission_overwrites#

Explicit permission overwrites for members and roles

Type

APINullable[List[Overwrite]]

position#

Sorting position of the channel

Type

APINullable[int]

rate_limit_per_user#

Amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages or manage_channel, are unaffected

Type

APINullable[int]

recipients#

The recipients of the DM

Type

APINullable[List[User]]

rtc_region#

Voice region id for the voice channel, automatic when set to null

Type

APINullable[Optional[str]]

thread_metadata#

Thread-specific fields not needed by other channels

Type

APINullable[ThreadMetadata]

topic#

The channel topic (0-1024 characters)

Type

APINullable[Optional[str]]

user_limit#

The user limit of the voice channel

Type

APINullable[int]

video_quality_mode#

The camera video quality mode of the voice channel, 1 when not present

Type

APINullable[int]

await bulk_delete_messages(messages, reason=None)#

This function is a coroutine. Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the MANAGE_MESSAGES permission.

This endpoint will not delete messages older than 2 weeks, and will fail with a 400 BAD REQUEST if any message provided is older than that or if any duplicate message IDs are provided.

Parameters

  • messages (List[Snowflake]) – The list of message IDs to delete (2-100).

  • reason (Optional[str]) – The reason of the channel bulk delete.

await create_invite(max_age=86400, max_uses=0, temporary=False, unique=False, target_type=None, target_user_id=None, target_application_id=None, reason=None)#

This function is a coroutine. Create a new invite object for the channel. Only usable for guild channels. Requires the CREATE_INSTANT_INVITE permission.

Parameters

  • max_age (Optional[int]) – Duration of invite in seconds before expiry, or 0 for never. between 0 and 604800 (7 days).

    Default: 86400

  • max_uses (Optional[int]) – Maximum number of uses. 0 for unlimited. Values between 0 and 100.

    Default: 0

  • temporary (Optional[bool]) – Whether the invite only grants temporary membership.

    Default: False

  • unique (Optional[bool]) – If True, don’t try to reuse a similar invite (useful for creating many unique one time use invites).

    Default: False

  • target_type (Optional[InviteTargetType]) – The type of target for the invite.

    Default: None

  • target_user_id (Optional[Snowflake]) – The id of the user whose stream to display for this invite. Required if target_type is STREAM, the user must be streaming in the channel.

    Default: None

  • target_application_id (Optional[Snowflake]) – The id of the embedded application to open for this invite. Required if target_type is EMBEDDED_APPLICATION, the application must have the EMBEDDED flag.

    Default: None

  • reason (Optional[str]) – The reason of the invite creation.

    Default: None

Returns

The invite object.

Return type

Invite

await delete(reason=None, /, channel_id=None)#

This function is a coroutine.

Delete the current channel.

:param reason Optional[str]: The reason of the channel delete. :param channel_id Snowflake: The id of the channel, defaults to the current object id.

await delete_permission(overwrite, reason=None)#

This function is a coroutine. Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission.

Parameters

  • overwrite (Overwrite) – The overwrite object.

  • reason (Optional[str]) – The reason of the channel permission delete.

await edit(reason=None, **kwargs)#

This function is a coroutine. Edit a channel with the given keyword arguments.

:param reason Optional[str]: The reason of the channel edit. :param **kwargs: The keyword arguments to edit the channel with.

Returns

The updated channel object.

Return type

Channel

await edit_permissions(overwrite, allow, deny, type, reason=None)#

This function is a coroutine. Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Only permissions your bot has in the guild or channel can be allowed/denied (unless your bot has a MANAGE_ROLES overwrite in the channel).

Parameters

  • overwrite (Overwrite) – The overwrite object.

  • allow (str) – The bitwise value of all allowed permissions.

  • deny (str) – The bitwise value of all denied permissions.

  • type (int) – 0 for a role or 1 for a member.

  • reason (Optional[str]) – The reason of the channel permission edit.

await follow_news_channel(webhook_channel_id)#

This function is a coroutine. Follow a News Channel to send messages to a target channel. Requires the MANAGE_WEBHOOKS permission in the target channel. Returns a followed channel object.

Parameters

webhook_channel_id (Snowflake) – The ID of the channel to follow.

Returns

The followed channel object.

Return type

NewsChannel

classmethod await from_id(client, channel_id)#

This function is a coroutine. Creates a channel object. You should use the get_channel method from Client most of the time. The get_dm_channel method from User should be used if you need to create a dm_channel. Using the send() method from User is preferred.

Parameters

  • client (Client) – Client object to use the HTTP class of.

  • channel_id (int) – ID of the channel you want.

Returns

The channel object.

Return type

Channel

get_invites()#

This function is a coroutine. Fetches all the invite objects for the channel. Only usable for guild channels. Requires the MANAGE_CHANNELS permission.

Returns

Invites iterator.

Return type

AsyncIterator[Invite]

get_pinned_messages()#

This function is a coroutine. Fetches all pinned messages in the channel. Returns an iterator of pinned messages.

Returns

An iterator of pinned messages.

Return type

AsyncIterator[:class:`~pincer.objects.guild.message.UserMessage]`

get_webhooks()#

This function is a coroutine. Get all webhooks in the channel. Requires the MANAGE_WEBHOOKS permission.

Yields

AsyncGenerator[Webhook, None]

await group_dm_add_recipient(user, access_token=None, nick=None)#

This function is a coroutine. Adds a recipient to a Group DM using their access token.

Parameters

  • user (User) – The user to add.

  • access_token (Optional[str]) – The access token of the user that has granted your app the gdm.join scope.

  • nick (Optional[str]) – The nickname of the user being added.

await group_dm_remove_recipient(user)#

This function is a coroutine. Removes a recipient from a Group DM.

Parameters

user (User) – The user to remove.

await list_active_threads()#

This function is a coroutine. Returns all active threads in the channel, including public and private threads. Threads are ordered by their id, in descending order.

Returns

The response object.

Return type

ThreadsResponse

await list_joined_private_archived_threads(before=None, limit=None)#

This function is a coroutine. Returns archived threads in the channel that are of type GUILD_PRIVATE_THREAD, and the user has joined. Threads are ordered by their id, in descending order. Requires the READ_MESSAGE_HISTORY permission.

Parameters

  • before (Optional[Timestamp]) – Returns threads before this timestamp.

    Default: None

  • limit (Optional[int]) – The maximum number of threads to return.

    Default: None

Returns

The response object.

Return type

ThreadsResponse

await list_private_archived_threads(before=None, limit=None)#

This function is a coroutine. Returns archived threads in the channel that are of type GUILD_PRIVATE_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires both the READ_MESSAGE_HISTORY and MANAGE_THREADS permissions.

Parameters

  • before (Optional[Timestamp]) – Returns threads before this timestamp.

    Default: None

  • limit (Optional[int]) – The maximum number of threads to return.

    Default: None

Returns

The response object.

Return type

ThreadsResponse

await list_public_archived_threads(before=None, limit=None)#

This function is a coroutine. Returns archived threads in the channel that are public. When called on a GUILD_TEXT channel, returns threads of type GUILD_PUBLIC_THREAD. When called on a GUILD_NEWS channel returns threads of type GUILD_NEWS_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires the READ_MESSAGE_HISTORY permission.

Parameters

  • before (Optional[Timestamp]) – Returns threads before this timestamp.

    Default: None

  • limit (Optional[int]) – The maximum number of threads to return.

    Default: None

Returns

The response object.

Return type

ThreadsResponse

await pin_message(message, reason=None)#

This function is a coroutine. Pin a message in a channel. Requires the MANAGE_MESSAGES permission. The maximum number of pinned messages is 50.

Parameters

reason (Optional[str]) – The reason of the channel message pin.

await send(message)#

This function is a coroutine.

Send a message in the channel.

:param message Message: The message which must be sent

Returns

The message that was sent.

Return type

UserMessage

await trigger_typing_indicator()#

This function is a coroutine. Post a typing indicator for the specified channel. Generally bots should not implement this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message.

await unpin_message(message, reason=None)#

This function is a coroutine. Unpin a message in a channel. Requires the MANAGE_MESSAGES permission.

Parameters

reason (Optional[str]) – The reason of the channel message unpin.

TextChannel#

Methods
class TextChannel#

Bases: Channel

A subclass of Channel for text channels with all the same attributes.

await edit(**kwargs)#

This function is a coroutine. Edit a text channel with the given keyword arguments.

Parameters

**kwargs – The keyword arguments to edit the channel with.

Returns

The updated channel object.

Return type

Channel

await fetch_message(message_id)#

This function is a coroutine. Returns a UserMessage from this channel with the given id.

Parameters

message_id – The message ID to look for.

Returns

The requested message.

Return type

UserMessage

async for ... in history(limit=50, before=None, after=None, around=None)#

This function is a coroutine. Returns a list of messages in this channel.

Parameters

  • around (Optional[Union[int, Snowflake]]) – The message ID to look around.

  • after (Optional[Union[int, Snowflake]]) – The message ID to look after.

  • before (Optional[Union[int, Snowflake]]) – The message ID to look before.

  • limit (Optional[Union[int, Snowflake]]) – The maximum number of messages to return.

Returns

An iterator of messages.

Return type

AsyncIterator[UserMessage]

VoiceChannel#

Methods
class VoiceChannel#

Bases: Channel

A subclass of Channel for voice channels with all the same attributes.

await edit(**kwargs)#

This function is a coroutine. Edit a voice channel with the given keyword arguments.

Parameters

**kwargs – The keyword arguments to edit the channel with.

Returns

The updated channel object.

Return type

Channel

CategoryChannel#

class CategoryChannel#

Bases: Channel

A subclass of Channel for categories channels with all the same attributes.

NewsChannel#

Methods
class NewsChannel#

Bases: Channel

A subclass of Channel for news channels with all the same attributes.

await edit(**kwargs)#

This function is a coroutine. Edit a news channel with the given keyword arguments.

Parameters

**kwargs – The keyword arguments to edit the channel with.

Returns

The updated channel object.

Return type

Channel

ChannelMention#

Attributes
class ChannelMention#

Bases: APIObject

Represents a Discord Channel Mention object

id#

Id of the channel

Type

Snowflake

guild_id#

Id of the guild containing the channel

Type

Snowflake

type#

The type of channel

Type

ChannelType

name#

The name of the channel

Type

str

Features#

GuildFeature#

Attributes
class GuildFeature#

Bases: Enum

Represents Guild Features strings.

ANIMATED_ICON#

Guild can have an animated icon.

Type

str

BANNER#

Guild can have a banner.

Type

str

COMMERCE#

Guild can have commerce.

Type

str

COMMUNITY#

Guild is a community.

Type

str

DISCOVERABLE#

Guild can be discovered.

Type

str

FEATURABLE#

Guild can be featureurable.Guild can have an invite splash.

Type

str

INVITE_SPLASH#

Guild can be featureurable.

Type

str

MEMBER_VERIFICATION_GATE_ENABLED#

Guild has member verification enabled.

Type

str

NEWS#

Guild has a news channel.

Type

str

PARTNERED#

Guild is a partner.

Type

str

PREVIEW_ENABLED#

Guild has preview enabled.

Type

str

VANITY_URL#

Guild has a vanity url.

Type

str

VERIFIED#

Guild is verified.

Type

str

VIP_REGIONS#

Guild can have VIP regions.

Type

str

WELCOME_SCREEN_ENABLED#

Guild has welcome screen enabled.

Type

str

TICKETED_EVENTS_ENABLED#

Guild has ticketed events enabled.

Type

str

MONETIZATION_ENABLED#

Guild has monetization enabled.

Type

str

MORE_STICKERS#

Guild can have more stickers.

Type

str

THREE_DAY_THREAD_ARCHIVE#

Guild can have three day archive time for threads.

Type

str

SEVEN_DAY_THREAD_ARCHIVE#

Guild can have seven day archive time for threads.

Type

str

PRIVATE_THREADS#

Guild can have private threads.

Type

str

THREADS_ENABLED#

Guild can have threads enabled.

Type

str

Followed Channel#

FollowedChannel#

Attributes
class FollowedChannel#

Bases: APIObject, ChannelProperty

Represents a Discord Followed Channel object

channel_id#

Source channel id

Type

Snowflake

webhook_id#

Created target webhook id

Type

Snowflake

Guild#

PremiumTier#

Attributes
class PremiumTier#

Bases: IntEnum

Represents the boost tier of a guild. .. attribute:: NONE

Guild has not unlocked any Server Boost perks.

TIER_1#

Guild has unlocked Server Boost level 1 perks.

TIER_2#

Guild has unlocked Server Boost level 2 perks.

TIER_3#

Guild has unlocked Server Boost level 3 perks.

GuildNSFWLevel#

Attributes
class GuildNSFWLevel#

Bases: IntEnum

Represents the NSFW level of a guild. .. attribute:: DEFAULT

Default NSFW level.

EXPLICIT#

Explicit NSFW level.

SAFE#

SAFE NSFW level.

AGE_RESTRICTED#

Age restricted NSFW level.

ExplicitContentFilterLevel#

Attributes
class ExplicitContentFilterLevel#

Bases: IntEnum

Represents the filter content level of a guild. .. attribute:: DISABLED

Media content will not be scanned.

MEMBERS_WITHOUT_ROLES#

Media content sent by members without roles will be scanned.

ALL_MEMBERS#

Media content sent by all members will be scanned.

MFALevel#

Attributes
class MFALevel#

Bases: IntEnum

Represents the multi-factor authentication level of a guild. .. attribute:: NONE

Guild has no MFA/2FA requirement for moderation actions.

ELEVATED#

Guild has a 2FA requirement for moderation actions

VerificationLevel#

Attributes
class VerificationLevel#

Bases: IntEnum

Represents the verification level of a guild. .. attribute:: NONE

Unrestricted.

LOW#

Must have verified email on account.

MEDIUM#

Must be registered on Discord for longer than 5 minutes.

HIGH#

Must be a member of the server for longer than 10 minutes.

VERY_HIGH#

Must have a verified phone number.

DefaultMessageNotificationLevel#

Attributes
class DefaultMessageNotificationLevel#

Bases: IntEnum

Represents the default message notification level of a guild. .. attribute:: ALL_MESSAGES

Members will receive notifications for all messages by default.

ONLY_MENTIONS#

Members will receive notifications only for messages that @mention them by default.

SystemChannelFlags#

Attributes
class SystemChannelFlags#

Bases: IntEnum

Represents the system channel flags of a guild. .. attribute:: SUPPRESS_JOIN_NOTIFICATIONS

Suppress member join notifications.

SUPPRESS_PREMIUM_SUBSCRIPTIONS#

Suppress server boost notifications.

SUPPRESS_GUILD_REMINDER_NOTIFICATIONS#

Suppress server setup tips.

SUPPRESS_JOIN_NOTIFICATION_REPLIES#

Hide member join sticker reply buttons

Guild#

Attributes
Methods
class Guild#

Bases: APIObject

Represents a Discord guild/server in which your client resides. .. attribute:: afk_channel_id

Id of afk channel

type

Optional[Snowflake]

afk_timeout#

Afk timeout in seconds

Type

int

application_id#

Application id of the guild creator if it is bot-created

Type

Optional[Snowflake]

banner#

Banner hash

Type

Optional[str]

default_message_notifications#

Default message notifications level

Type

DefaultMessageNotificationLevel

description#

The description of a Community guild

Type

Optional[str]

discovery_splash#

Discovery splash hash; only present for guilds with the “DISCOVERABLE” feature

Type

Optional[str]

emojis#

Custom guild emojis

Type

List[Emoji]

explicit_content_filter#

Explicit content filter level

Type

ExplicitContentFilterLevel

features#

Enabled guild features

Type

List[GuildFeature]

id#

Guild id

Type

Snowflake

icon#

Icon hash

Type

Optional[str]

mfa_level#

Required MFA level for the guild

Type

MFALevel

name#

Guild name (2-100 characters, excluding trailing and leading whitespace)

Type

str

nsfw_level#

Guild NSFW level

Type

NSFWLevel

owner_id#

Id of owner

Type

Snowflake

preferred_locale#

The preferred locale of a Community guild; used in server discovery and notices from Discord; defaults to “en-US”

Type

str

premium_tier#

Premium tier (Server Boost level)

Type

PremiumTier

public_updates_channel_id#

The id of the channel where admins and moderators of Community guilds receive notices from Discord

Type

Optional[Snowflake]

roles#

Roles in the guild

Type

List[Role]

rules_channel_id#

The id of the channel where Community guilds can display rules and/or guidelines

Type

Optional[Snowflake]

splash#

Splash hash

Type

Optional[str]

system_channel_flags#

System channel flags

Type

SystemChannelFlags

system_channel_id#

The id of the channel where guild notices such as welcome messages and boost events are posted

Type

Optional[Snowflake]

vanity_url_code#

The vanity url code for the guild

Type

Optional[str]

verification_level#

Verification level required for the guild

Type

VerificationLevel

approximate_member_count#

Approximate number of members in this guild, returned from the GET /guilds/<id> endpoint when with_counts is true

Type

APINullable[int]

approximate_presence_count#

Approximate number of non-offline members in this guild, returned from the GET /guilds/<id> endpoint when with_counts is true

Type

APINullable[int]

channels#

Channels in the guild

Type

APINullable[List[Channel]]

icon_hash#

Icon hash, returned when in the template object

Type

APINullable[Optional[str]]

joined_at#

When this guild was joined at

Type

APINullable[Timestamp]

large#

True if this is considered a large guild

Type

APINullable[bool]

max_members#

The maximum number of members for the guild

Type

APINullable[int]

max_presences#

The maximum number of presences for the guild (null is always returned, apart from the largest of guilds)

Type

APINullable[Optional[int]]

max_video_channel_users#

The maximum amount of users in a video channel

Type

APINullable[int]

members#

Users in the guild

Type

APINullable[List[GuildMember]]

member_count#

Total number of members in this guild

Type

APINullable[bool]

nsfw#

Boolean if the server is NSFW

Type

APINullable[bool]

owner#

True if the user is the owner of the guild

Type

APINullable[bool]

permissions#

Total permissions for the user in the guild (excludes overwrites)

Type

APINullable[str]

premium_subscription_count#

The number of boosts this guild currently has

Type

APINullable[int]

presences#

Presences of the members in the guild, will only include non-offline members if the size is greater than large threshold

Type

APINullable[List[PresenceUpdateEvent]]

stage_instances#

Stage instances in the guild

Type

APINullable[List[StageInstance]]

stickers#

Custom guild stickers

Type

Optional[List[Sticker]]

region#

Voice region id for the guild (deprecated)

Type

APINullable[Optional[str]]

threads#

All active threads in the guild that current user has permission to view

Type

APINullable[List[Channel]]

unavailable#

True if this guild is unavailable due to an outage

Type

APINullable[bool]

voice_states#

States of members currently in voice channels; lacks the guild_id key

Type

APINullable[List[VoiceState]]

widget_enabled#

True if the server widget is enabled

Type

APINullable[bool]

widget_channel_id#

The channel id that the widget will generate an invite to, or null if set to no invite

Type

APINullable[Optional[Snowflake]]

welcome_screen#

The welcome screen of a Community guild, shown to new members, returned in an Invite’s guild object

Type

APINullable[WelcomeScreen]

await add_guild_member_role(user_id, role_id, reason=None)#

This function is a coroutine. Adds a role to a guild member.

Parameters

  • user_id (int) – id of the user to give a role to

  • role_id (int) – id of a role

  • reason (Optional[str]) – audit log reason

    Default: None

await ban(member, reason=None, delete_message_days=None)#

Ban a guild member.

Parameters

  • member (Union[int, GuildMember]) – ID or object of the guild member to ban.

  • reason (Optional[str]) – Reason for the kick.

  • delete_message_days (Optional[int]) – Number of days to delete messages for (0-7)

await create_emoji(*, name, image, roles=None, reason=None)#

This function is a coroutine. Creates a new emoji for the guild. Requires the MANAGE_EMOJIS_AND_STICKERS permission.

Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail.

Parameters

  • name (str) – Name of the emoji

  • image (File) – The File for the 128x128 emoji image data

  • roles (Optional[List[Snowflake]]) – Roles allowed to use this emoji

    Default: []

  • reason (Optional[str]) – The reason for creating the emoji

    Default: None

Returns

The newly created emoji object.

Return type

Emoji

await create_scheduled_event(name, privacy_level, entity_type, scheduled_start_time, scheduled_end_time=None, entity_metadata=None, channel_id=None, description=None, reason=None)#

Create a new scheduled event for the guild.

Parameters

  • name (str) – The name of the scheduled event.

  • privacy_level (int) – The privacy level of the scheduled event.

  • entity_type (int) – The type of entity to be scheduled.

  • scheduled_start_time (datetime) – The scheduled start time of the event.

  • scheduled_end_time (Optional[datetime]) – The scheduled end time of the event.

  • entity_metadata (Optional[str]) – The metadata of the entity to be scheduled.

  • channel_id (Optional[int]) – The channel id of the channel to be scheduled.

  • description (Optional[str]) – The description of the scheduled event.

  • reason (Optional[str]) – The reason for creating the scheduled event.

Raises

ValueError: – If an event is created in the past or if an event ends before it starts

Returns

The newly created scheduled event.

Return type

ScheduledEvent

await create_sticker(name, tags, description, file, reason=None)#

This function is a coroutine. Create a new sticker for the guild. Requires the MANAGE_EMOJIS_AND_STICKERS permission.

Parameters

  • name (str) – name of the sticker (2-30 characters)

  • tags (str) – autocomplete/suggestion tags for the sticker (max 200 characters)

  • file (File) – the sticker file to upload, must be a PNG, APNG, or Lottie JSON file, max 500 KB

  • description (str) – description of the sticker (empty or 2-100 characters)

    Default: ""

  • reason (Optional[str]

    Default: None) – reason for creating the sticker

Returns

the newly created sticker

Return type

Sticker

await create_template(name, description=None)#

This function is a coroutine. Creates a new template for the guild. Requires the MANAGE_GUILD permission.

Parameters

  • name (str) – Name of the template (1-100 characters)

  • description (Optional[str]) – Description of the template (0-120 characters)

    Default: None

Returns

The newly created template object.

Return type

GuildTemplate

await delete()#

This function is a coroutine. Deletes the guild. Returns 204 No Content on success.

await delete_emoji(id, *, reason=None)#

This function is a coroutine. Deletes the given emoji. Requires the MANAGE_EMOJIS_AND_STICKERS permission.

Parameters

  • id (Snowflake) – The ID of the emoji

  • reason (Optional[str]) – The reason for deleting the emoji

    Default: None

await delete_integration(integration, reason=None)#

This function is a coroutine. Deletes an integration. Requires the MANAGE_GUILD permission.

Parameters

  • integration (Integration) – The integration to delete.

  • reason (Optional[str]) – Reason for the deletion

    Default: None

await delete_invite(code)#

This function is a coroutine. Deletes an invite. Requires the MANAGE_GUILD intent.

Parameters

code (str) – The code of the invite to delete.

await delete_role(id, reason=None)#

This function is a coroutine. Deletes a role. Requires the MANAGE_ROLES permission.

Parameters

  • id (Snowflake) – The role ID

  • reason (Optional[str]) – The reason for deleting the role

    Default: None

await delete_scheduled_event(_id)#

Delete a scheduled event.

Parameters

_id (int) – The id of the scheduled event.

await delete_sticker(_id)#

This function is a coroutine. Delete the given sticker. Requires the MANAGE_EMOJIS_AND_STICKERS permission.

Parameters

_id (Snowflake) – id of the sticker

await delete_template(template)#

This function is a coroutine. Deletes the given template. Requires the MANAGE_GUILD permission.

Parameters

template (GuildTemplate) – The template to delete

Returns

The deleted template object.

Return type

GuildTemplate

await edit_emoji(id, *, name=None, roles=None, reason=None)#

This function is a coroutine. Modifies the given emoji. Requires the MANAGE_EMOJIS_AND_STICKERS permission.

Parameters

  • id (Snowflake) – The ID of the emoji

  • name (Optional[str]) – Name of the emoji

    Default: None

  • roles (Optional[List[Snowflake]]) – Roles allowed to use this emoji

    Default: None

  • reason (Optional[str]) – The reason for editing the emoji

    Default: None

Returns

The modified emoji object.

Return type

Emoji

edit_role_position(id, reason=None, position=None)#

This function is a coroutine. Edits the position of a role.

Parameters

  • id (Snowflake) – The role ID

  • reason (Optional[str]) – Reason for editing the role position.

    Default: None

  • position (Optional[int]) – Sorting position of the role

    Default: None

Yields

AsyncGenerator[Role, None] – An async generator of all the guild’s role objects.

await edit_template(template, *, name=None, description=None)#

This function is a coroutine. Modifies the template’s metadata. Requires the MANAGE_GUILD permission.

Parameters

  • template (GuildTemplate) – The template to edit

  • name (Optional[str]) – Name of the template (1-100 characters)

    Default: None

  • description (Optional[str]) – Description of the template (0-120 characters)

    Default: None

Returns

The edited template object.

Return type

GuildTemplate

classmethod from_dict(data)#
Parameters

data (Dict) – Guild data received from the discord API.

Returns

The new guild object.

Return type

Guild

Raises

UnavailableGuildError – The guild is unavailable due to a discord outage.

classmethod await from_id(client, _id, with_counts=False)#
Parameters

  • client (Client) – Client object to use the http gateway from.

  • _id (Snowflake) – Guild ID.

  • with_counts (bool) – Whether to fetch approximate member and presence counts.

Returns

The new guild object.

Return type

Guild

await get_audit_log()#

This function is a coroutine. Returns an audit log object for the guild. Requires the VIEW_AUDIT_LOG permission.

Returns

The audit log object for the guild.

Return type

AuditLog

await get_ban(id)#

This function is a coroutine. Fetches a ban from the guild.

Parameters

id (Snowflake) – The user ID

Returns

The Ban object.

Return type

Ban

get_bans()#

This function is a coroutine. Fetches all the bans in the guild.

Yields

AsyncGenerator[Ban, None] – An async generator of Ban objects.

await get_emoji(id)#

This function is a coroutine. Returns an emoji object for the given ID.

Parameters

id (Snowflake) – The ID of the emoji

Returns

The emoji object.

Return type

Emoji

get_emojis()#

This function is a coroutine. Returns an async generator of the emojis in the guild.

Yields

Emoji – The emoji object.

get_guild_scheduled_event_users(_id, limit=100, with_member=False, before=None, after=None)#

Get the users of a scheduled event.

Parameters

  • _id (int) – The id of the scheduled event.

  • limit (int) – The number of users to retrieve.

  • with_member (bool) – Whether to include the member object in the scheduled event user.

  • before (Optional[int]) – consider only users before given user id

  • after (Optional[int]) – consider only users after given user id

Yields

GuildScheduledEventUser – The scheduled event user object.

get_integrations()#

This function is a coroutine. Returns an async generator of integrations for the guild. Requires the MANAGE_GUILD permission.

Yields

AsyncGenerator[Integration, None] – An async generator of integrations.

await get_invite(code)#

This function is a coroutine. Returns an Invite object for the given invite code.

Parameters

code (str) – The invite code to get the invite for.

Returns

The invite object.

Return type

Invite

get_invites()#

This function is a coroutine. Returns an async generator of invites for the guild. Requires the MANAGE_GUILD permission.

Yields

AsyncGenerator[Invite, None] – An async generator of invites.

await get_member(_id)#

This function is a coroutine. Fetches a GuildMember from its identifier

Parameters

_id (int) – The id of the guild member which should be fetched from the Discord gateway.

Returns

A GuildMember object.

Return type

GuildMember

get_roles()#

This function is a coroutine. Fetches all the roles in the guild.

Yields

AsyncGenerator[Role, None] – An async generator of Role objects.

await get_scheduled_event(_id, with_user_count=False)#

Get a scheduled event by id.

Parameters

  • _id (int) – The id of the scheduled event.

  • with_user_count (bool) – Whether to include the user count in the scheduled event.

Returns

The scheduled event object.

Return type

ScheduledEvent

get_scheduled_events(with_user_count=False)#

Returns an async generator of the guild scheduled events.

Parameters

with_user_count (bool) – Whether to include the user count in the scheduled event.

Yields

ScheduledEvent – The scheduled event object.

await get_sticker(_id)#

This function is a coroutine. Returns a sticker object for the current guild and sticker IDs. Includes the user field if the bot has the MANAGE_EMOJIS_AND_STICKERS permission.

Parameters

_id (int) – id of the sticker

Returns

the sticker requested

Return type

Sticker

get_templates()#

This function is a coroutine. Returns an async generator of the guild templates.

Yields

AsyncGenerator[GuildTemplate, None] – The guild template object.

get_voice_regions()#

This function is a coroutine. Returns an async generator of voice regions.

Yields

AsyncGenerator[VoiceRegion, None] – An async generator of voice regions.

get_webhooks()#

This function is a coroutine. Returns an async generator of the guild webhooks.

Yields

AsyncGenerator[Webhook, None] – The guild webhook object.

await get_welcome_screen()#

Returns the welcome screen for the guild.

Returns

The welcome screen for the guild.

Return type

WelcomeScreen

await get_widget()#

This function is a coroutine. Returns the widget for the guild

await get_widget_image(style='shield')#

This function is a coroutine. Returns a PNG image widget for the guild. Requires no permissions or authentication.

Widget Style Options#

param style

Style of the widget image returned

Default: "shield"

type style

Optional[str]

returns

A PNG image of the guild widget.

rtype

str

await get_widget_settings()#

This function is a coroutine. Returns the guild widget settings. Requires the MANAGE_GUILD permission.

Returns

The guild widget settings.

Return type

GuildWidget

await kick(member, reason=None)#

This function is a coroutine. Kicks a guild member.

Parameters

  • member (Union[int, GuildMember]) – ID or object of the guild member to kick.

  • reason (Optional[str]) – Reason for the kick.

await list_active_threads()#

This function is a coroutine. Returns all active threads in the guild, including public and private threads.

Returns

The new member object.

Return type

Generator[Union[PublicThread, PrivateThread]], Generator[GuildMember]]

list_guild_members(limit=1, after=0)#

This function is a coroutine. Returns a list of guild member objects that are members of the guild.

Parameters

  • limit (int) – max number of members to return (1-1000)

    Default: 1

  • after (int) – the highest user id in the previous page

    Default: 0

Yields

GuildMember – the guild member object that is in the guild

list_stickers()#

This function is a coroutine. Yields sticker objects for the current guild. Includes user fields if the bot has the MANAGE_EMOJIS_AND_STICKERS permission.

Yields

Sticker – a sticker for the current guild

await modify_channel_positions(reason=None, *channel)#

This function is a coroutine. Create a new channel object for the guild.

Parameters

  • reason (Optional[str]) – audit log reason

    Default: None

  • *channel (Dict[str, Optional[Union[int, bool, Snowflake]) –

    Keys:

await modify_current_member(nick, reason=None)#

This function is a coroutine. Modifies the current member in a guild.

Parameters

  • nick (str) – value to set users nickname to

  • reason (Optional[str]) – audit log reason

    Default: None

Returns

class – current guild member

Return type

`~pincer.objects.guild.member.GuildMember

await modify_current_user_voice_state(channel_id, suppress=None, request_to_speak_timestamp=None)#

This function is a coroutine. Updates the current user’s voice state.

There are currently several caveats for this endpoint: * channel_id must currently point to a stage channel * current user must already have joined channel_id * You must have the MUTE_MEMBERS permission to

unsuppress yourself. You can always suppress yourself.

  • You must have the REQUEST_TO_SPEAK permission to request to speak. You can always clear your own request to speak.

  • You are able to set request_to_speak_timestamp to any present or future time.

Parameters

  • channel_id (Snowflake) – The ID of the channel the user is currently in

  • suppress (Optional[bool]) – Toggles the user’s suppress state

    Default: None

  • request_to_speak_timestamp (Optional[Timestamp]) – Sets the user’s request to speak

await modify_scheduled_event(_id, name=None, entity_type=None, privacy_level=None, scheduled_start_time=None, scheduled_end_time=None, entity_metadata=None, channel_id=None, description=None, status=None, reason=None)#

Modify a scheduled event.

Parameters

  • _id (int) – The id of the scheduled event.

  • name (Optional[str]) – The name of the scheduled event.

  • entity_type (Optional[int]) – The type of entity to be scheduled.

  • privacy_level (Optional[int]) – The privacy level of the scheduled event.

  • scheduled_start_time (Optional[datetime]) – The scheduled start time of the event.

  • scheduled_end_time (Optional[datetime]) – The scheduled end time of the event.

  • entity_metadata (Optional[str]) – The metadata of the entity to be scheduled.

  • channel_id (Optional[int]) – The channel id of the channel to be scheduled.

  • description (Optional[str]) – The description of the scheduled event.

  • status (Optional[int]) – The status of the scheduled event.

  • reason (Optional[str]) – The reason for modifying the scheduled event.

Raises

ValueError – If the scheduled event is in the past, or if the scheduled end time is before the scheduled start time.

Returns

The scheduled event object.

Return type

ScheduledEvent

await modify_user_voice_state(user, channel_id, suppress=None)#

This function is a coroutine. Updates another user’s voice state.

There are currently several caveats for this endpoint: * channel_id must currently point to a stage channel * User must already have joined channel_id * You must have the MUTE_MEMBERS permission.

(Since suppression is the only thing that is available currently.)

  • When unsuppressed, non-bot users will have their request_to_speak_timestamp set to the current time. Bot users will not.

  • When suppressed, the user will have their request_to_speak_timestamp removed.

Parameters

  • user (Member) – The user to update

  • channel_id (Snowflake) – The ID of the channel the user is currently in

  • suppress (Optional[bool]) – Toggles the user’s suppress state

    Default: None

await modify_welcome_screen(enabled=None, welcome_channels=None, description=None, reason=None)#

This function is a coroutine. Modifies the guild’s Welcome Screen. Requires the MANAGE_GUILD permission.

Parameters

  • enabled (Optional[bool]) – Whether the welcome screen is enabled

    Default: None

  • welcome_channels (Optional[List[WelcomeScreenChannel]]) – Channels linked in the welcome screen and their display options

    Default: None

  • description (Optional[str]) – The server description to show in the welcome screen

    Default: None

  • reason (Optional[str]) – Reason for the modification

    Default: None

Returns

The updated WelcomeScreen object

Return type

WelcomeScreen

await modify_widget(reason=None, **kwargs)#

This function is a coroutine. Modifies the guild widget for the guild. Requires the MANAGE_GUILD permission.

Parameters

  • reason (Optional[str]) – Reason for the modification

    Default: None

  • **kwargs – The widget settings to modify

Returns

The updated GuildWidget object

Return type

GuildWidget

await preview()#

This function is a coroutine. Previews the guild.

Returns

The guild preview object.

Return type

GuildPreview

await prune(days=7, compute_prune_days=True, include_roles=None, reason=None)#

This function is a coroutine. Prunes members from the guild. Requires the KICK_MEMBERS permission.

Parameters

Parameters

  • days (Optional[int]) – Number of days to prune (1-30)

    Default: 7

  • compute_prune_days (Optional[bool]) – Whether pruned is returned, discouraged for large guilds

    Default: True

  • include_roles (Optional[List[Snowflake]]) – role(s) to include

    Default: None

  • reason (Optional[str]) – Reason for the prune

    Default: None

Returns

The number of members that were removed.

Return type

int

await prune_count(days=7, include_roles=None)#

This function is a coroutine. Returns the number of members that would be removed in a prune operation. Requires the KICK_MEMBERS permission.

Parameters

  • days (Optional[int]) – Number of days to count prune for (1-30)

    Default: 7

  • include_roles (Optional[str]) – Comma-delimited array of Snowflakes; role(s) to include

    Default: None

Returns

The number of members that would be removed.

Return type

int

await remove_guild_member(user_id, reason=None)#

This function is a coroutine. Remove a member from a guild.

Parameters

  • user_id (int) – id of the user to remove from the guild

  • reason (Optional[str]) – audit log reason

    Default: None

await remove_guild_member_role(user_id, role_id, reason=None)#

This function is a coroutine. Removes a role from a guild member.

Parameters

  • user_id (int) – id of the user to remove a role from

  • role_id (int) – id of a role

  • reason (Optional[str]) – audit log reason

    Default: None

search_guild_members(query, limit=None)#

This function is a coroutine. Returns a list of guild member objects whose username or nickname starts with a provided string.

Parameters

  • query (str) – Query string to match username(s) and nickname(s) against.

  • limit (Optional[int]) – max number of members to return (1-1000)

    Default: 1

Yields

GuildMember – guild member objects

await sync_template(template)#

This function is a coroutine. Syncs the given template. Requires the MANAGE_GUILD permission.

Parameters

template (GuildTemplate) – The template to sync

Returns

The synced template object.

Return type

GuildTemplate

await unban(id, reason=None)#

This function is a coroutine. Unbans a user from the guild.

Parameters

  • id (Snowflake) – The user ID

  • reason (Optional[str]) – The reason for unbanning the user

    Default: None

property vanity_url#

This function is a coroutine. Returns the Vanity URL for the guild. Requires the MANAGE_GUILD permission. code will be null if a vanity URL has not been set.

Returns

The vanity url for the guild.

Return type

Invite

Invite#

InviteTargetType#

Attributes
class InviteTargetType#

Bases: IntEnum

Represents the type of the invite.

STREAM#

A normal Discord invite, e.g. for a channel or guild.

EMBEDDED_APPLICATION#

An embedded application invite, e.g. poker-night etc.

InviteStageInstance#

Attributes
class InviteStageInstance#

Bases: APIObject

Represents an invite for a Discord stages channel.

members#

the members speaking in the Stage

Type

List[GuildMember]

participant_count#

the number of users in the Stage

Type

int

speaker_count#

the number of users speaking in the Stage

Type

int

topic#

the topic of the Stage instance (1-120 characters)

Type

str

Invite#

Attributes
Methods
class Invite#

Bases: APIObject

Represents a Discord invite. Can also include information from InviteMetadata.

channel#

The channel this invite is for

Type

Channel

code#

The invite code (unique ID)

Type

str

approximate_member_count#

Approximate count of total members, returned from the GET /invites/<code> endpoint when with_counts is true

Type

APINullable[int]

approximate_presence_count#

Approximate count of online members, returned from the GET /invites/<code> endpoint when with_counts is true

Type

APINullable[int]

expires_at#

The expiration date of this invite, returned from the GET /invites/<code> endpoint when with_expiration is true

Type

APINullable[Optional[Timestamp]]

inviter#

The user who created the invite

Type

APINullable[User]

guild#

The guild this invite is for

Type

Guild

stage_instance#

Stage instance data if there is a public Stage instance in the Stage channel this invite is for

Type

InviteStageInstance

target_type#

The type of target for this voice channel invite

Type

InviteTargetType

target_user#

The user whose stream to display for this voice channel stream invite

Type

User

target_application#

The embedded application to open for this voice channel embedded application invite

Type

Application

uses#

number of times this invite has been used

Type

APINullable[int]

max_uses#

Max number of times this invite can be used

Type

APINullable[int]

max_age#

Duration (in seconds) after which the invite expires

Type

APINullable[int]

temporary#

Whether this invite only grants temporary membership

Type

APINullable[bool]

created_at#

When this invite was created

Type

APINullable[Timestamp]

await delete()#

Delete this invite.

Raises

  • Forbidden – You do not have permission to delete this invite

  • NotFound – This invite does not exist

  • HTTPException – Deleting the invite failed

Member#

BaseMember#

Attributes
class BaseMember#

Bases: APIObject

Represents the base of a guild member.

deaf#

Whether the user is deafened in voice channels

Type

bool

joined_at#

Then the user joined the guild

Type

Timestamp

mute#

Whether the user is muted in voice channels

Type

bool

roles#

Array of role object ids

Type

List[Snowflake]

hoisted_role#

The user’s top role in the guild.

Type

APINullable[Snowflake]

PartialGuildMember#

Attributes
class PartialGuildMember#

Bases: APIObject

Represents a partial guild member. This is a reference to a member from a guild which does not contain all information.

This gets used in form example message mentions.

id#

The user’s id

Type

Snowflake

username#

The user’s username, not unique across the platform

Type

str

discriminator#

The user’s 4-digit discord-tag

Type

str

avatar#

The user’s avatar hash

Type

str

public_flags#

The flags on a user’s account

Type

int

member#

The user their (partial) guild information.

Type

BaseMember

GuildMember#

Attributes
Methods
class GuildMember#

Bases: BaseMember, User

Represents a member which resides in a guild/server.

nick#

This users guild nickname

Type

APINullable[Optional[str]]

pending#

Whether the user has not yet passed the guild’s Membership Screening requirements

Type

APINullable[bool]

is_pending#

Deprecated version of pending.

Type

APINullable[bool]

permissions#

Total permissions of the member in the channel, including overwrites, returned when in the interaction object

Type

APINullable[str]

premium_since#

When the user started boosting the guild

Type

APINullable[Optional[Timestamp]]

user#

The user this guild member represents

Type

APINullable[User]

avatar#

The user’s avatar.

Type

APINullable[str]

communication_disabled_until#

The timestamp at which the user is no longer timed out.

Note

This may be in the past if the user has been timed out recently.

Type

APINullable[Optional[Timestamp]]

classmethod await from_id(client, guild_id, user_id)#
Parameters

  • client –

  • user_id –

set_user_data(user)#

Used to set the user parameters of a GuildMember instance

user: APINullable[User]

A user class to copy the fields from

Overwrite#

Overwrite#

Attributes
class Overwrite#

Bases: APIObject

Represents a Discord Overwrite object

id#

Role or user id

Type

Snowflake

type#

Either 0 (role) or 1 (member)

Type

int

allow#

Permission bit set

Type

str

deny#

Permission bit set

Type

str

property permissions#

Returns the permissions for this overwrite

Role#

RoleTags#

Attributes
class RoleTags#

Bases: APIObject

Special tags/flags which have been defined for a role.

bot_id#

The id of the bot this role belongs to. (the role got created by adding the bot with this id)

Type

APINullable[Snowflake]

integration_id#

The id of the integration this role belongs to. (the role got created by adding an integration with this id)

Type

APINullable[Snowflake]

premium_subscriber#

Whether this is the guild’s premium subscriber role or not.

Type

APINullable[bool]

Role#

Attributes
class Role#

Bases: APIObject

Represents a Discord guild/server role.

color#

Integer representation of hexadecimal color code

Type

Color

hoist#

If this role is pinned in the user listing

Type

bool

id#

Role id

Type

Snowflake

managed#

Whether this role is managed by an integration

Type

bool

mentionable#

Whether this role is mentionable

Type

bool

name#

Role name

Type

str

permissions#

Permission bit set

Type

str

position#

Position of this role

Type

int

icon#

The role’s icon

Type

APINullable[str]

unicode_emoji#

The unicode emoji for this role

Type

APINullable[str]

tags#

The tags this role has

Type

RoleTags

property mention#

Returns the mention string for this role.

Type

str

Stage#

PrivacyLevel#

Attributes
class PrivacyLevel#

Bases: IntEnum

Represents the level of publicity of a stage.

PUBLIC#

The stage is public.

GUILD_ONLY#

The stage of for guild members only.

StageInstance#

Attributes
Methods
class StageInstance#

Bases: APIObject, ChannelProperty, GuildProperty

Represents a Stage Instance object

id#

Id of this Stage instance

Type

Snowflake

guild_id#

Guild id of the associated Stage channel

Type

Snowflake

channel_id#

Id of the associated Stage channel

Type

Snowflake

topic#

Topic of the Stage instance (1-120 characters)

Type

str

privacy_level#

Privacy level of the Stage instance

Type

PrivacyLevel

discoverable#

Is Stage Discovery enabled

Type

bool

await modify(topic=None, privacy_level=None, reason=None)#

This function is a coroutine. Updates fields of an existing Stage instance. Requires the user to be a moderator of the Stage channel.

Parameters

  • topic (Optional[str]) – The topic of the Stage instance (1-120 characters)

  • privacy_level (Optional[PrivacyLevel]) – The privacy level of the Stage instance

  • reason (Optional[str]) – The reason for the modification

Template#

GuildTemplate#

Attributes
class GuildTemplate#

Bases: APIObject

Represents a code that when used, creates a guild based on a snapshot of an existing guild.

code#

the template code (unique ID)

Type

str

name#

template name

Type

str

description#

the description for the template

Type

Optional[str]

usage_count#

number of times this template has been used

Type

int

creator_id#

the ID of the user who created the template

Type

Snowflake

creator#

user who created the template

Type

User

created_at#

when this template was created

Type

Timestamp

updated_at#

when this template was last synced to the source guild

Type

Timestamp

source_guild_id#

the ID of the guild this template is based on

Type

Snowflake

serialized_source_guild#

the guild snapshot this template contains

Type

Guild

is_dirty#

whether the template has unsynced changes

Type

Optional[bool]

Thread#

ThreadMetadata#

Attributes
class ThreadMetadata#

Bases: APIObject

Represents a Discord Thread Metadata object

archived#

Whether the thread is archived

Type

bool

auto_archive_duration#

Duration in minutes to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080

Type

int

archive_timestamp#

Timestamp when the thread’s archive status was last changed, used for calculating recent activity

Type

Timestamp

locked#

Whether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it

Type

bool

invitable#

Whether non-moderators can add other non-moderators to a thread; only available on private threads

Type

APINullable[bool]

ThreadMember#

Attributes
class ThreadMember#

Bases: APIObject

Represents a Discord Thread Member object

join_timestamp#

The time the current user last joined the thread

Type

Timestamp

flags#

Any user-thread settings, currently only used for notifications

Type

int

id#

Id of the thread

Type

APINullable[Snowflake]

user_id#

Id of the user

Type

APINullable[Snowflake]

Webhook#

WebhookType#

Attributes
class WebhookType#

Bases: IntEnum

Represents the type of webhook.

INCOMING#

Incoming Webhooks can post messages to channel with a generated token.

CHANNEL_FOLLOWER#

Channel Follower Webhooks are internal webhooks used with Channel Following to post new messages into channels.

APPLICATION#

Application webhooks are webhooks used with Interactions

Webhook#

Attributes
Methods
class Webhook#

Bases: APIObject

Represents a Discord channel webhook.

id#

The id of the webhook

Type

Snowflake

type#

The type of the webhook

Type

WebhookType

channel_id#

The channel id this webhook is for, if any

Type

Optional[Snowflake]

name#

The default name of the webhook

Type

Optional[str]

avatar#

The default user avatar hash of the webhook

Type

Optional[str]

application_id#

The bot/OAuth2 application that created this webhook

Type

Optional[Snowflake]

user#

The user this webhook was created by (not returned when getting a webhook with its token)

Type

APINullable[User]

token#

The secure token of the webhook (returned for Incoming Webhooks)

Type

APINullable[str]

source_guild#

The guild of the channel that this webhook is following (returned for Channel Follower Webhooks)

Type

APINullable[Guild]

source_channel#

The channel that this webhook is following (returned for Channel Follower Webhooks)

Type

APINullable[Channel]

url#

The url used for executing the webhook (returned by the webhooks OAuth2 flow)

Type

APINullable[str]

guild_id#

The guild id this webhook is for, if any

Type

APINullable[Optional[Guild]]

await delete(token=None)#

Deletes a webhook. Requires the MANAGE_WEBHOOKS permission.

Parameters

token (Optional[str]) – The token of the webhook

await delete_message(message_id, thread_id)#

This function is a coroutine. Deletes a message created by a webhook.

Parameters

  • message_id (Snowflake) – The ID of the message to delete

  • thread_id (Snowflake) – The ID of the thread to delete the message from

await edit(*, name=None, avatar=None, channel_id=None, token=None)#

Modifies a webhook and returns it. Requires the MANAGE_WEBHOOKS permission.

Parameters

  • name (Optional[str]) – The new name of the webhook

  • avatar (Optional[str]) – The new avatar hash of the webhook

  • channel_id (Optional[Snowflake]) – The new channel id this webhook is for

  • token (Optional[str]) – The new token of the webhook

await execute_github(*, thread_id=None, wait=None)#

This function is a coroutine. Executes a GitHub compatible webhook.

Parameters

  • thread_id (Optional[Snowflake]) – ID of the thread to send message in

  • wait (Optional[bool]) – Waits for server confirmation of message send before response (defaults to true, when false a message that is not saved does not return an error)

await execute_slack(*, thread_id=None, wait=None)#

This function is a coroutine. Executes a Slack compatible webhook.

Parameters

  • thread_id (Optional[Snowflake]) – ID of the thread to send message in

  • wait (Optional[bool]) – Waits for server confirmation of message send before response (defaults to true, when false a message that is not saved does not return an error)

classmethod await from_id(client, id, token=None)#

This function is a coroutine. Gets a webhook by its ID.

Parameters

  • client (~pincer.client.Client) – The client to use to make the request.

  • id (~pincer.utils.snowflake.Snowflake) – The ID of the webhook to get.

  • token (Optional[str]) – The token of the webhook to get.

Returns

The webhook with the given ID.

Return type

~pincer.objects.guild.webhook.Webhook

await get_message(message_id, thread_id)#

This function is a coroutine. Returns a previously-sent webhook message from the same token.

Parameters

  • message_id (Snowflake) – The ID of the message to get

  • thread_id (Snowflake) – The ID of the thread to get the message from

Returns

The message

Return type

Message

Welcome Screen#

WelcomeScreenChannel#

Attributes
class WelcomeScreenChannel#

Bases: APIObject, ChannelProperty

Represents a welcome screen channel. This is a channel which gets shown on the welcome screen.

channel_id#

The channel’s id

Type

Snowflake

description#

The description shown for the channel

Type

str

emoji_id#

The emoji id, if the emoji is custom

Type

Optional[int]

emoji_name#

The emoji name if custom, the unicode character if standard, or null if no emoji is set

Type

Optional[str]

WelcomeScreen#

Attributes
class WelcomeScreen#

Bases: APIObject

Representation of a Discord guild/server welcome screen.

description#

The server description shown in the welcome screen

Type

LIst[WelcomeScreenChannel]

welcome_channels#

The channels shown in the welcome screen, up to 5

Type

Optional[str]

Widget#

GuildWidget#

Attributes
class GuildWidget#

Bases: APIObject

Represents a Discord Guild Widget object

enabled#

Whether the widget is enabled

Type

bool

channel_id#

The widget channel id

Type

Optional[Snowflake]