View Documentation For
settings
menu settings

# API Reference

The following section outlines the API of discord.py.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, these logs will not be output anywhere. See Setting Up Logging for more information on how to set up and use the logging module with discord.py.

## Version Related Info

There are two main ways to query version information about the library. For guarantees, check Version Guarantees.

discord.version_info

  A named tuple that is similar to `py:sys.version_info`.

  Just like `py:sys.version_info` the valid values for `releaselevel` are ‘alpha’, ‘beta’, ‘candidate’ and ‘final’.

discord.__version__

  A string representation of the version. e.g. `'1.0.0rc1'`. This is based off of PEP 440.

## Clients

### Client

Attributes

- activity
- allowed_mentions
- application
- application_flags
- application_id
- cached_messages
- emojis
- guilds
- intents
- latency
- persistent_views
- private_channels
- soundboard_sounds
- status
- stickers
- user
- users
- voice_clients
- ws

Methods

- def add_dynamic_items
- def add_view
- async application_info
- async before_identify_hook
- async change_presence
- def clear
- async close
- async connect
- async create_application_emoji
- async create_dm
- async create_entitlement
- async create_guild
- async delete_invite
- async for entitlements
- @event
- async fetch_application_emoji
- async fetch_application_emojis
- async fetch_channel
- async fetch_entitlement
- async fetch_guild
- async fetch_guild_preview
- async for fetch_guilds
- async fetch_invite
- async fetch_premium_sticker_pack
- async fetch_premium_sticker_packs
- async fetch_skus
- async fetch_soundboard_default_sounds
- async fetch_stage_instance
- async fetch_sticker
- async fetch_template
- async fetch_user
- async fetch_webhook
- async fetch_widget
- def get_all_channels
- def get_all_members
- def get_channel
- def get_emoji
- def get_guild
- def get_partial_messageable
- def get_soundboard_sound
- def get_stage_instance
- def get_sticker
- def get_user
- def is_closed
- def is_ready
- def is_ws_ratelimited
- async login
- async on_error
- def remove_dynamic_items
- def run
- async setup_hook
- async start
- async wait_for
- async wait_until_ready

class discord.Client(*, intents, **options)

  Represents a client connection that connects to Discord. This class is used to interact with the Discord WebSocket and API.

  async with x

    Asynchronously initialises the client and automatically cleans up.

    Added in version 2.0.

  A number of options can be passed to the `Client`.

  Parameters:

    - max_messages (Optional[`int`]) –

      The maximum number of messages to store in the internal message cache. This defaults to `1000`. Passing in `None` disables the message cache.

      Changed in version 1.3: Allow disabling the message cache and change the default size to `1000`.

    - proxy (Optional[`str`]) – Proxy URL.

    - proxy_auth (Optional[`aiohttp.BasicAuth`]) – An object that represents proxy HTTP Basic Authorization.

    - shard_id (Optional[`int`]) – Integer starting at `0` and less than `shard_count`.

    - shard_count (Optional[`int`]) – The total number of shards.

    - application_id (`int`) – The client’s application ID.

    - intents (`Intents`) –

      The intents that you want to enable for the session. This is a way of disabling and enabling certain gateway events from triggering and being sent.

      Added in version 1.5.

      Changed in version 2.0: Parameter is now required.

    - member_cache_flags (`MemberCacheFlags`) –

      Allows for finer control over how the library caches members. If not given, defaults to cache as much as possible with the currently selected intents.

      Added in version 1.5.

    - chunk_guilds_at_startup (`bool`) –

      Indicates if `on_ready()` should be delayed to chunk all guilds at start-up if necessary. This operation is incredibly slow for large amounts of guilds. The default is `True` if `Intents.members` is `True`.

      Added in version 1.5.

    - status (Optional[`Status`]) – A status to start your presence with upon logging on to Discord.

    - activity (Optional[`BaseActivity`]) – An activity to start your presence with upon logging on to Discord.

    - allowed_mentions (Optional[`AllowedMentions`]) –

      Control how the client handles mentions by default on every message sent.

      Added in version 1.4.

    - heartbeat_timeout (`float`) – The maximum numbers of seconds before timing out and restarting the WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if processing the initial packets take too long to the point of disconnecting you. The default timeout is 60 seconds.

    - guild_ready_timeout (`float`) –

      The maximum number of seconds to wait for the GUILD_CREATE stream to end before preparing the member cache and firing READY. The default timeout is 2 seconds.

      Added in version 1.4.

    - assume_unsync_clock (`bool`) –

      Whether to assume the system clock is unsynced. This applies to the ratelimit handling code. If this is set to `True`, the default, then the library uses the time to reset a rate limit bucket given by Discord. If this is `False` then your system clock is used to calculate how long to sleep for. If this is set to `False` it is recommended to sync your system clock to Google’s NTP server.

      Added in version 1.3.

    - enable_debug_events (`bool`) –

      Whether to enable events that are useful only for debugging gateway related information.

      Right now this involves `on_socket_raw_receive()` and `on_socket_raw_send()`. If this is `False` then those events will not be dispatched (due to performance considerations). To enable these events, this must be set to `True`. Defaults to `False`.

      Added in version 2.0.

    - enable_raw_presences (`bool`) –

      Whether to manually enable or disable the `on_raw_presence_update()` event.

      Setting this flag to `True` requires `Intents.presences` to be enabled.

      By default, this flag is set to `True` only when `Intents.presences` is enabled and `Intents.members` is disabled, otherwise it’s set to `False`.

      Added in version 2.5.

    - http_trace (`aiohttp.TraceConfig`) –

      The trace configuration to use for tracking HTTP requests the library does using `aiohttp`. This allows you to check requests the library is using. For more information, check the aiohttp documentation.

      Added in version 2.0.

    - max_ratelimit_timeout (Optional[`float`]) –

      The maximum number of seconds to wait when a non-global rate limit is encountered. If a request requires sleeping for more than the seconds passed in, then `RateLimited` will be raised. By default, there is no timeout limit. In order to prevent misuse and unnecessary bans, the minimum value this can be set to is `30.0` seconds.

      Added in version 2.0.

    - connector (Optional[`aiohttp.BaseConnector`]) –

      The aiohttp connector to use for this client. This can be used to control underlying aiohttp behavior, such as setting a dns resolver or sslcontext.

      Added in version 2.5.

  ws

    The websocket gateway the client is currently connected to. Could be `None`.

  @event

    A decorator that registers an event to listen to.

    You can find more info about the events on the documentation below.

    The events must be a coroutine, if not, `TypeError` is raised.

    Example

        @client.event
        async def on_ready():
            print('Ready!')

    Changed in version 2.0: `coro` parameter is now positional-only.

    Raises:

      TypeError – The coroutine passed is not actually a coroutine.

  property latency

    Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

    This could be referred to as the Discord WebSocket protocol latency.

    Type:

      `float`

  is_ws_ratelimited()

    `bool`: Whether the websocket is currently rate limited.

    This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

    Added in version 1.6.

  property user

    Represents the connected client. `None` if not logged in.

    Type:

      Optional[`ClientUser`]

  property guilds

    The guilds that the connected client is a member of.

    Type:

      Sequence[`Guild`]

  property emojis

    The emojis that the connected client has.

    Note

    This not include the emojis that are owned by the application. Use `fetch_application_emoji()` to get those.

    Type:

      Sequence[`Emoji`]

  property stickers

    The stickers that the connected client has.

    Added in version 2.0.

    Type:

      Sequence[`GuildSticker`]

  property soundboard_sounds

    The soundboard sounds that the connected client has.

    Added in version 2.5.

    Type:

      List[`SoundboardSound`]

  property cached_messages

    Read-only list of messages the connected client has cached.

    Added in version 1.1.

    Type:

      Sequence[`Message`]

  property private_channels

    The private channels that the connected client is participating on.

    Note

    This returns only up to 128 most recent private channels due to an internal working on how Discord deals with private channels.

    Type:

      Sequence[`abc.PrivateChannel`]

  property voice_clients

    Represents a list of voice connections.

    These are usually `VoiceClient` instances.

    Type:

      List[`VoiceProtocol`]

  property application_id

    The client’s application ID.

    If this is not passed via `__init__` then this is retrieved through the gateway when an event contains the data or after a call to `login()`. Usually after `on_connect()` is called.

    Added in version 2.0.

    Type:

      Optional[`int`]

  property application_flags

    The client’s application flags.

    Added in version 2.0.

    Type:

      `ApplicationFlags`

  property application

    The client’s application info.

    This is retrieved on `login()` and is not updated afterwards. This allows populating the application_id without requiring a gateway connection.

    This is `None` if accessed before `login()` is called.

    See also

    The `application_info()` API call

    Added in version 2.0.

    Type:

      Optional[`AppInfo`]

  is_ready()

    `bool`: Specifies if the client’s internal cache is ready for use.

  await on_error(event_method, /, *args, **kwargs)

    This function is a coroutine.

    The default error handler provided by the client.

    By default this logs to the library logger however it could be overridden to have a different implementation. Check `on_error()` for more details.

    Changed in version 2.0: `event_method` parameter is now positional-only and instead of writing to `sys.stderr` it logs instead.

  await before_identify_hook(shard_id, *, initial=False)

    This function is a coroutine.

    A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients.

    The default implementation sleeps for 5 seconds.

    Added in version 1.4.

    Parameters:

      - shard_id (`int`) – The shard ID that requested being IDENTIFY’d

      - initial (`bool`) – Whether this IDENTIFY is the first initial IDENTIFY.

  await setup_hook()

    This function is a coroutine.

    A coroutine to be called to setup the bot, by default this is blank.

    To perform asynchronous setup after the bot is logged in but before it has connected to the Websocket, overwrite this coroutine.

    This is only called once, in `login()`, and will be called before any events are dispatched, making it a better solution than doing such setup in the `on_ready()` event.

    Warning

    Since this is called before the websocket connection is made therefore anything that waits for the websocket will deadlock, this includes things like `wait_for()` and `wait_until_ready()`.

    Added in version 2.0.

  await login(token)

    This function is a coroutine.

    Logs in the client with the specified credentials and calls the `setup_hook()`.

    Parameters:

      token (`str`) – The authentication token. Do not prefix this token with anything as the library will do it for you.

    Raises:

      - LoginFailure – The wrong credentials are passed.

      - HTTPException – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code.

  await connect(*, reconnect=True)

    This function is a coroutine.

    Creates a websocket connection and lets the websocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

    Parameters:

      reconnect (`bool`) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

    Raises:

      - GatewayNotFound – If the gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

      - ConnectionClosed – The websocket connection has been terminated.

  await close()

    This function is a coroutine.

    Closes the connection to Discord.

  clear()

    Clears the internal state of the bot.

    After this, the bot can be considered “re-opened”, i.e. `is_closed()` and `is_ready()` both return `False` along with the bot’s internal cache cleared.

  await start(token, *, reconnect=True)

    This function is a coroutine.

    A shorthand coroutine for `login()` + `connect()`.

    Parameters:

      - token (`str`) – The authentication token. Do not prefix this token with anything as the library will do it for you.

      - reconnect (`bool`) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

    Raises:

      TypeError – An unexpected keyword argument was received.

  run(token, *, reconnect=True, log_handler=..., log_formatter=..., log_level=..., root_logger=False)

    A blocking call that abstracts away the event loop initialisation from you.

    If you want more control over the event loop then this function should not be used. Use `start()` coroutine or `connect()` + `login()`.

    This function also sets up the logging library to make it easier for beginners to know what is going on with the library. For more advanced users, this can be disabled by passing `None` to the `log_handler` parameter.

    Warning

    This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns.

    Parameters:

      - token (`str`) – The authentication token. Do not prefix this token with anything as the library will do it for you.

      - reconnect (`bool`) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

      - log_handler (Optional[`logging.Handler`]) –

        The log handler to use for the library’s logger. If this is `None` then the library will not set up anything logging related. Logging will still work if `None` is passed, though it is your responsibility to set it up.

        The default log handler if not provided is `logging.StreamHandler`.

        Added in version 2.0.

      - log_formatter (`logging.Formatter`) –

        The formatter to use with the given log handler. If not provided then it defaults to a colour based logging formatter (if available).

        Added in version 2.0.

      - log_level (`int`) –

        The default log level for the library’s logger. This is only applied if the `log_handler` parameter is not `None`. Defaults to `logging.INFO`.

        Added in version 2.0.

      - root_logger (`bool`) –

        Whether to set up the root logger rather than the library logger. By default, only the library logger (`'discord'`) is set up. If this is set to `True` then the root logger is set up as well.

        Defaults to `False`.

        Added in version 2.0.

  is_closed()

    `bool`: Indicates if the websocket connection is closed.

  property activity

    The activity being used upon logging in.

    Type:

      Optional[`BaseActivity`]

  property status

    `Status`: The status being used upon logging on to Discord.

  property allowed_mentions

    The allowed mention configuration.

    Added in version 1.4.

    Type:

      Optional[`AllowedMentions`]

  property intents

    The intents configured for this connection.

    Added in version 1.5.

    Type:

      `Intents`

  property users

    Returns a list of all the users the bot can see.

    Type:

      List[`User`]

  get_channel(id, /)

    Returns a channel or thread with the given ID.

    Changed in version 2.0: `id` parameter is now positional-only.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The returned channel or `None` if not found.

    Return type:

      Optional[Union[`abc.GuildChannel`, `Thread`, `abc.PrivateChannel`]]

  get_partial_messageable(id, *, guild_id=None, type=None)

    Returns a partial messageable with the given channel ID.

    This is useful if you have a channel_id but don’t want to do an API call to send messages to it.

    Added in version 2.0.

    Parameters:

      - id (`int`) – The channel ID to create a partial messageable for.

      - guild_id (Optional[`int`]) –

        The optional guild ID to create a partial messageable for.

        This is not required to actually send messages, but it does allow the `jump_url()` and `guild` properties to function properly.

      - type (Optional[`ChannelType`]) – The underlying channel type for the partial messageable.

    Returns:

      The partial messageable

    Return type:

      `PartialMessageable`

  get_stage_instance(id, /)

    Returns a stage instance with the given stage channel ID.

    Added in version 2.0.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The stage instance or `None` if not found.

    Return type:

      Optional[`StageInstance`]

  get_guild(id, /)

    Returns a guild with the given ID.

    Changed in version 2.0: `id` parameter is now positional-only.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The guild or `None` if not found.

    Return type:

      Optional[`Guild`]

  get_user(id, /)

    Returns a user with the given ID.

    Changed in version 2.0: `id` parameter is now positional-only.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The user or `None` if not found.

    Return type:

      Optional[`User`]

  get_emoji(id, /)

    Returns an emoji with the given ID.

    Changed in version 2.0: `id` parameter is now positional-only.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The custom emoji or `None` if not found.

    Return type:

      Optional[`Emoji`]

  get_sticker(id, /)

    Returns a guild sticker with the given ID.

    Added in version 2.0.

    Note

    To retrieve standard stickers, use `fetch_sticker()`. or `fetch_premium_sticker_packs()`.

    Returns:

      The sticker or `None` if not found.

    Return type:

      Optional[`GuildSticker`]

  get_soundboard_sound(id, /)

    Returns a soundboard sound with the given ID.

    Added in version 2.5.

    Parameters:

      id (`int`) – The ID to search for.

    Returns:

      The soundboard sound or `None` if not found.

    Return type:

      Optional[`SoundboardSound`]

  for ... in get_all_channels()

    A generator that retrieves every `abc.GuildChannel` the client can ‘access’.

    This is equivalent to:

        for guild in client.guilds:
            for channel in guild.channels:
                yield channel

    Note

    Just because you receive a `abc.GuildChannel` does not mean that you can communicate in said channel. `abc.GuildChannel.permissions_for()` should be used for that.

    Yields:

      `abc.GuildChannel` – A channel the client can ‘access’.

  for ... in get_all_members()

    Returns a generator with every `Member` the client can see.

    This is equivalent to:

        for guild in client.guilds:
            for member in guild.members:
                yield member

    Yields:

      `Member` – A member the client can see.

  await wait_until_ready()

    This function is a coroutine.

    Waits until the client’s internal cache is all ready.

    Warning

    Calling this inside `setup_hook()` can lead to a deadlock.

  wait_for(event, /, *, check=None, timeout=None)

    This function is a coroutine.

    Waits for a WebSocket event to be dispatched.

    This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

    The `timeout` parameter is passed onto `asyncio.wait_for()`. By default, it does not timeout. Note that this does propagate the `asyncio.TimeoutError` for you in case of timeout and is provided for ease of use.

    In case the event returns multiple arguments, a `tuple` containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

    This function returns the first event that meets the requirements.

    Examples

    Waiting for a user reply:

        @client.event
        async def on_message(message):
            if message.content.startswith('$greet'):
                channel = message.channel
                await channel.send('Say hello!')

                def check(m):
                    return m.content == 'hello' and m.channel == channel

                msg = await client.wait_for('message', check=check)
                await channel.send(f'Hello {msg.author}!')

    Waiting for a thumbs up reaction from the message author:

        @client.event
        async def on_message(message):
            if message.content.startswith('$thumb'):
                channel = message.channel
                await channel.send('Send me that 👍 reaction, mate')

                def check(reaction, user):
                    return user == message.author and str(reaction.emoji) == '👍'

                try:
                    reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
                except asyncio.TimeoutError:
                    await channel.send('👎')
                else:
                    await channel.send('👍')

    Changed in version 2.0: `event` parameter is now positional-only.

    Parameters:

      - event (`str`) – The event name, similar to the event reference, but without the `on_` prefix, to wait for.

      - check (Optional[Callable[…, `bool`]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

      - timeout (Optional[`float`]) – The number of seconds to wait before timing out and raising `asyncio.TimeoutError`.

    Raises:

      asyncio.TimeoutError – If a timeout is provided and it was reached.

    Returns:

      Returns no arguments, a single argument, or a `tuple` of multiple arguments that mirrors the parameters passed in the event reference.

    Return type:

      Any

  await change_presence(*, activity=None, status=None)

    This function is a coroutine.

    Changes the client’s presence.

    Example

        game = discord.Game("with the API")
        await client.change_presence(status=discord.Status.idle, activity=game)

    Changed in version 2.0: Removed the `afk` keyword-only parameter.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - activity (Optional[`BaseActivity`]) – The activity being done. `None` if no currently active activity is done.

      - status (Optional[`Status`]) – Indicates what status to change to. If `None`, then `Status.online` is used.

    Raises:

      TypeError – If the `activity` parameter is not the proper type.

  async for ... in fetch_guilds(*, limit=200, before=None, after=None, with_counts=True)

    Retrieves an asynchronous iterator that enables receiving your guilds.

    Note

    Using this, you will only receive `Guild.owner`, `Guild.icon`, `Guild.id`, `Guild.name`, `Guild.approximate_member_count`, and `Guild.approximate_presence_count` per `Guild`.

    Note

    This method is an API call. For general usage, consider `guilds` instead.

    Examples

    Usage

        async for guild in client.fetch_guilds(limit=150):
            print(guild.name)

    Flattening into a list

        guilds = [guild async for guild in client.fetch_guilds(limit=150)]
        # guilds is now a list of Guild...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) –

        The number of guilds to retrieve. If `None`, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to `200`.

        Changed in version 2.0: The default has been changed to 200.

      - before (Union[`abc.Snowflake`, `datetime.datetime`]) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Union[`abc.Snowflake`, `datetime.datetime`]) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - with_counts (`bool`) –

        Whether to include count information in the guilds. This fills the `Guild.approximate_member_count` and `Guild.approximate_presence_count` attributes without needing any privileged intents. Defaults to `True`.

        Added in version 2.3.

    Raises:

      HTTPException – Getting the guilds failed.

    Yields:

      `Guild` – The guild with the guild data parsed.

  await fetch_template(code)

    This function is a coroutine.

    Gets a `Template` from a discord.new URL or code.

    Parameters:

      code (Union[`Template`, `str`]) – The Discord Template Code or URL (must be a discord.new URL).

    Raises:

      - NotFound – The template is invalid.

      - HTTPException – Getting the template failed.

    Returns:

      The template from the URL/code.

    Return type:

      `Template`

  await fetch_guild(guild_id, /, *, with_counts=True)

    This function is a coroutine.

    Retrieves a `Guild` from an ID.

    Note

    Using this, you will not receive `Guild.channels`, `Guild.members`, `Member.activity` and `Member.voice` per `Member`.

    Note

    This method is an API call. For general usage, consider `get_guild()` instead.

    Changed in version 2.0: `guild_id` parameter is now positional-only.

    Parameters:

      - guild_id (`int`) – The guild’s ID to fetch from.

      - with_counts (`bool`) –

        Whether to include count information in the guild. This fills the `Guild.approximate_member_count` and `Guild.approximate_presence_count` attributes without needing any privileged intents. Defaults to `True`.

        Added in version 2.0.

    Raises:

      - NotFound – The guild doesn’t exist or you got no access to it.

      - HTTPException – Getting the guild failed.

    Returns:

      The guild from the ID.

    Return type:

      `Guild`

  await fetch_guild_preview(guild_id)

    This function is a coroutine.

    Retrieves a preview of a `Guild` from an ID. If the guild is discoverable, you don’t have to be a member of it.

    Added in version 2.5.

    Raises:

      - NotFound – The guild doesn’t exist, or is not discoverable and you are not in it.

      - HTTPException – Getting the guild failed.

    Returns:

      The guild preview from the ID.

    Return type:

      `GuildPreview`

  await create_guild(*, name, icon=..., code=...)

    This function is a coroutine.

    Creates a `Guild`.

    Bot accounts in more than 10 guilds are not allowed to create guilds.

    Changed in version 2.0: `name` and `icon` parameters are now keyword-only. The `region` parameter has been removed.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The name of the guild.

      - icon (Optional[`bytes`]) – The py:bytes-like object representing the icon. See `ClientUser.edit()` for more details on what is expected.

      - code (`str`) –

        The code for a template to create the guild with.

        Added in version 1.4.

    Raises:

      - HTTPException – Guild creation failed.

      - ValueError – Invalid icon image format given. Must be PNG or JPG.

    Returns:

      The guild created. This is not the same guild that is added to cache.

    Return type:

      `Guild`

  await fetch_stage_instance(channel_id, /)

    This function is a coroutine.

    Gets a `StageInstance` for a stage channel id.

    Added in version 2.0.

    Parameters:

      channel_id (`int`) – The stage channel ID.

    Raises:

      - NotFound – The stage instance or channel could not be found.

      - HTTPException – Getting the stage instance failed.

    Returns:

      The stage instance from the stage channel ID.

    Return type:

      `StageInstance`

  await fetch_invite(url, *, with_counts=True, with_expiration=True, scheduled_event_id=None)

    This function is a coroutine.

    Gets an `Invite` from a discord.gg URL or ID.

    Note

    If the invite is for a guild you have not joined, the guild and channel attributes of the returned `Invite` will be `PartialInviteGuild` and `PartialInviteChannel` respectively.

    Parameters:

      - url (Union[`Invite`, `str`]) – The Discord invite ID or URL (must be a discord.gg URL).

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

      - with_expiration (`bool`) –

        Whether to include the expiration date of the invite. This fills the `Invite.expires_at` field.

        Added in version 2.0.

      - scheduled_event_id (Optional[`int`]) –

        The ID of the scheduled event this invite is for.

        Note

        It is not possible to provide a url that contains an `event_id` parameter when using this parameter.

        Added in version 2.0.

    Raises:

      - ValueError – The url contains an `event_id`, but `scheduled_event_id` has also been provided.

      - NotFound – The invite has expired or is invalid.

      - HTTPException – Getting the invite failed.

    Returns:

      The invite from the URL/ID.

    Return type:

      `Invite`

  await delete_invite(invite, /)

    This function is a coroutine.

    Revokes an `Invite`, URL, or ID to an invite.

    You must have `manage_channels` in the associated guild to do this.

    Changed in version 2.0: `invite` parameter is now positional-only.

    Parameters:

      invite (Union[`Invite`, `str`]) – The invite to revoke.

    Raises:

      - Forbidden – You do not have permissions to revoke invites.

      - NotFound – The invite is invalid or expired.

      - HTTPException – Revoking the invite failed.

  await fetch_widget(guild_id, /)

    This function is a coroutine.

    Gets a `Widget` from a guild ID.

    Note

    The guild must have the widget enabled to get this information.

    Changed in version 2.0: `guild_id` parameter is now positional-only.

    Parameters:

      guild_id (`int`) – The ID of the guild.

    Raises:

      - Forbidden – The widget for this guild is disabled.

      - HTTPException – Retrieving the widget failed.

    Returns:

      The guild’s widget.

    Return type:

      `Widget`

  await application_info()

    This function is a coroutine.

    Retrieves the bot’s application information.

    Raises:

      HTTPException – Retrieving the information failed somehow.

    Returns:

      The bot’s application information.

    Return type:

      `AppInfo`

  await fetch_user(user_id, /)

    This function is a coroutine.

    Retrieves a `User` based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

    Note

    This method is an API call. If you have `discord.Intents.members` and member cache enabled, consider `get_user()` instead.

    Changed in version 2.0: `user_id` parameter is now positional-only.

    Parameters:

      user_id (`int`) – The user’s ID to fetch from.

    Raises:

      - NotFound – A user with this ID does not exist.

      - HTTPException – Fetching the user failed.

    Returns:

      The user you requested.

    Return type:

      `User`

  await fetch_channel(channel_id, /)

    This function is a coroutine.

    Retrieves a `abc.GuildChannel`, `abc.PrivateChannel`, or `Thread` with the specified ID.

    Note

    This method is an API call. For general usage, consider `get_channel()` instead.

    Added in version 1.2.

    Changed in version 2.0: `channel_id` parameter is now positional-only.

    Raises:

      - InvalidData – An unknown channel type was received from Discord.

      - HTTPException – Retrieving the channel failed.

      - NotFound – Invalid Channel ID.

      - Forbidden – You do not have permission to fetch this channel.

    Returns:

      The channel from the ID.

    Return type:

      Union[`abc.GuildChannel`, `abc.PrivateChannel`, `Thread`]

  await fetch_webhook(webhook_id, /)

    This function is a coroutine.

    Retrieves a `Webhook` with the specified ID.

    Changed in version 2.0: `webhook_id` parameter is now positional-only.

    Raises:

      - HTTPException – Retrieving the webhook failed.

      - NotFound – Invalid webhook ID.

      - Forbidden – You do not have permission to fetch this webhook.

    Returns:

      The webhook you requested.

    Return type:

      `Webhook`

  await fetch_sticker(sticker_id, /)

    This function is a coroutine.

    Retrieves a `Sticker` with the specified ID.

    Added in version 2.0.

    Raises:

      - HTTPException – Retrieving the sticker failed.

      - NotFound – Invalid sticker ID.

    Returns:

      The sticker you requested.

    Return type:

      Union[`StandardSticker`, `GuildSticker`]

  await fetch_skus()

    This function is a coroutine.

    Retrieves the bot’s available SKUs.

    Added in version 2.4.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Retrieving the SKUs failed.

    Returns:

      The bot’s available SKUs.

    Return type:

      List[`SKU`]

  await fetch_entitlement(entitlement_id, /)

    This function is a coroutine.

    Retrieves a `Entitlement` with the specified ID.

    Added in version 2.4.

    Parameters:

      entitlement_id (`int`) – The entitlement’s ID to fetch from.

    Raises:

      - NotFound – An entitlement with this ID does not exist.

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Fetching the entitlement failed.

    Returns:

      The entitlement you requested.

    Return type:

      `Entitlement`

  async for ... in entitlements(*, limit=100, before=None, after=None, skus=None, user=None, guild=None, exclude_ended=False, exclude_deleted=True)

    Retrieves an asynchronous iterator of the `Entitlement` that applications has.

    Added in version 2.4.

    Examples

    Usage

        async for entitlement in client.entitlements(limit=100):
            print(entitlement.user_id, entitlement.ends_at)

    Flattening into a list

        entitlements = [entitlement async for entitlement in client.entitlements(limit=100)]
        # entitlements is now a list of Entitlement...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of entitlements to retrieve. If `None`, it retrieves every entitlement for this application. Note, however, that this would make it a slow operation. Defaults to `100`.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve entitlements before this date or entitlement. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve entitlements after this date or entitlement. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - skus (Optional[Sequence[`Snowflake`]]) – A list of SKUs to filter by.

      - user (Optional[`Snowflake`]) – The user to filter by.

      - guild (Optional[`Snowflake`]) – The guild to filter by.

      - exclude_ended (`bool`) – Whether to exclude ended entitlements. Defaults to `False`.

      - exclude_deleted (`bool`) –

        Whether to exclude deleted entitlements. Defaults to `True`.

        Added in version 2.5.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Fetching the entitlements failed.

      - TypeError – Both `after` and `before` were provided, as Discord does not support this type of pagination.

    Yields:

      `Entitlement` – The entitlement with the application.

  await create_entitlement(sku, owner, owner_type)

    This function is a coroutine.

    Creates a test `Entitlement` for the application.

    Added in version 2.4.

    Parameters:

      - sku (`Snowflake`) – The SKU to create the entitlement for.

      - owner (`Snowflake`) – The ID of the owner.

      - owner_type (`EntitlementOwnerType`) – The type of the owner.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - NotFound – The SKU or owner could not be found.

      - HTTPException – Creating the entitlement failed.

  await fetch_premium_sticker_packs()

    This function is a coroutine.

    Retrieves all available premium sticker packs.

    Added in version 2.0.

    Raises:

      HTTPException – Retrieving the sticker packs failed.

    Returns:

      All available premium sticker packs.

    Return type:

      List[`StickerPack`]

  await fetch_premium_sticker_pack(sticker_pack_id, /)

    This function is a coroutine.

    Retrieves a premium sticker pack with the specified ID.

    Added in version 2.5.

    Parameters:

      sticker_pack_id (`int`) – The sticker pack’s ID to fetch from.

    Raises:

      - NotFound – A sticker pack with this ID does not exist.

      - HTTPException – Retrieving the sticker pack failed.

    Returns:

      The retrieved premium sticker pack.

    Return type:

      `StickerPack`

  await fetch_soundboard_default_sounds()

    This function is a coroutine.

    Retrieves all default soundboard sounds.

    Added in version 2.5.

    Raises:

      HTTPException – Retrieving the default soundboard sounds failed.

    Returns:

      All default soundboard sounds.

    Return type:

      List[`SoundboardDefaultSound`]

  await create_dm(user)

    This function is a coroutine.

    Creates a `DMChannel` with this user.

    This should be rarely called, as this is done transparently for most people.

    Added in version 2.0.

    Parameters:

      user (`Snowflake`) – The user to create a DM with.

    Returns:

      The channel that was created.

    Return type:

      `DMChannel`

  add_dynamic_items(*items)

    Registers `DynamicItem` classes for persistent listening.

    This method accepts class types rather than instances.

    Added in version 2.4.

    Parameters:

      *items (Type[`DynamicItem`]) – The classes of dynamic items to add.

    Raises:

      TypeError – A class is not a subclass of `DynamicItem`.

  remove_dynamic_items(*items)

    Removes `DynamicItem` classes from persistent listening.

    This method accepts class types rather than instances.

    Added in version 2.4.

    Parameters:

      *items (Type[`DynamicItem`]) – The classes of dynamic items to remove.

    Raises:

      TypeError – A class is not a subclass of `DynamicItem`.

  add_view(view, *, message_id=None)

    Registers a `View` for persistent listening.

    This method should be used for when a view is comprised of components that last longer than the lifecycle of the program.

    Added in version 2.0.

    Parameters:

      - view (`discord.ui.View`) – The view to register for dispatching.

      - message_id (Optional[`int`]) – The message ID that the view is attached to. This is currently used to refresh the view’s state during message update events. If not given then message update events are not propagated for the view.

    Raises:

      - TypeError – A view was not passed.

      - ValueError – The view is not persistent or is already finished. A persistent view has no timeout and all their components have an explicitly provided custom_id.

  property persistent_views

    A sequence of persistent views added to the client.

    Added in version 2.0.

    Type:

      Sequence[`View`]

  await create_application_emoji(*, name, image)

    This function is a coroutine.

    Create an emoji for the current application.

    Added in version 2.5.

    Parameters:

      - name (`str`) – The emoji name. Must be between 2 and 32 characters long.

      - image (`bytes`) – The py:bytes-like object representing the image data to use. Only JPG, PNG and GIF images are supported.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Creating the emoji failed.

    Returns:

      The emoji that was created.

    Return type:

      `Emoji`

  await fetch_application_emoji(emoji_id, /)

    This function is a coroutine.

    Retrieves an emoji for the current application.

    Added in version 2.5.

    Parameters:

      emoji_id (`int`) – The emoji ID to retrieve.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Retrieving the emoji failed.

    Returns:

      The emoji requested.

    Return type:

      `Emoji`

  await fetch_application_emojis()

    This function is a coroutine.

    Retrieves all emojis for the current application.

    Added in version 2.5.

    Raises:

      - MissingApplicationID – The application ID could not be found.

      - HTTPException – Retrieving the emojis failed.

    Returns:

      The list of emojis for the current application.

    Return type:

      List[`Emoji`]

### AutoShardedClient

Attributes

- latencies
- latency
- shard_connect_timeout
- shard_ids
- shards

Methods

- async change_presence
- async close
- async connect
- async fetch_session_start_limits
- def get_shard
- def is_ws_ratelimited

class discord.AutoShardedClient(*args, intents, **kwargs)

  A client similar to `Client` except it handles the complications of sharding for the user into a more manageable and transparent single process bot.

  When using this client, you will be able to use it as-if it was a regular `Client` with a single shard when implementation wise internally it is split up into multiple shards. This allows you to not have to deal with IPC or other complicated infrastructure.

  It is recommended to use this client only if you have surpassed at least 1000 guilds.

  If no `shard_count` is provided, then the library will use the Bot Gateway endpoint call to figure out how many shards to use.

  If a `shard_ids` parameter is given, then those shard IDs will be used to launch the internal shards. Note that `shard_count` must be provided if this is used. By default, when omitted, the client will launch shards from 0 to `shard_count - 1`.

  async with x

    Asynchronously initialises the client and automatically cleans up.

    Added in version 2.0.

  shard_ids

    An optional list of shard_ids to launch the shards with.

    Type:

      Optional[List[`int`]]

  shard_connect_timeout

    The maximum number of seconds to wait before timing out when launching a shard. Defaults to 180 seconds.

    Added in version 2.4.

    Type:

      Optional[`float`]

  property latency

    Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

    This operates similarly to `Client.latency()` except it uses the average latency of every shard’s latency. To get a list of shard latency, check the `latencies` property. Returns `nan` if there are no shards ready.

    Type:

      `float`

  property latencies

    A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

    This returns a list of tuples with elements `(shard_id, latency)`.

    Type:

      List[Tuple[`int`, `float`]]

  get_shard(shard_id, /)

    Gets the shard information at a given shard ID or `None` if not found.

    Changed in version 2.0: `shard_id` parameter is now positional-only.

    Returns:

      Information about the shard with given ID. `None` if not found.

    Return type:

      Optional[`ShardInfo`]

  property shards

    Returns a mapping of shard IDs to their respective info object.

    Type:

      Mapping[int, `ShardInfo`]

  await fetch_session_start_limits()

    This function is a coroutine.

    Get the session start limits.

    This is not typically needed, and will be handled for you by default.

    At the point where you are launching multiple instances with manual shard ranges and are considered required to use large bot sharding by Discord, this function when used along IPC and a before_identity_hook can speed up session start.

    Added in version 2.5.

    Returns:

      A class containing the session start limits

    Return type:

      `SessionStartLimits`

    Raises:

      GatewayNotFound – The gateway was unreachable

  await connect(*, reconnect=True)

    This function is a coroutine.

    Creates a websocket connection and lets the websocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

    Parameters:

      reconnect (`bool`) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

    Raises:

      - GatewayNotFound – If the gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

      - ConnectionClosed – The websocket connection has been terminated.

  await close()

    This function is a coroutine.

    Closes the connection to Discord.

  await change_presence(*, activity=None, status=None, shard_id=None)

    This function is a coroutine.

    Changes the client’s presence.

    Example:

        game = discord.Game("with the API")
        await client.change_presence(status=discord.Status.idle, activity=game)

    Changed in version 2.0: Removed the `afk` keyword-only parameter.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - activity (Optional[`BaseActivity`]) – The activity being done. `None` if no currently active activity is done.

      - status (Optional[`Status`]) – Indicates what status to change to. If `None`, then `Status.online` is used.

      - shard_id (Optional[`int`]) – The shard_id to change the presence to. If not specified or `None`, then it will change the presence of every shard the bot can see.

    Raises:

      TypeError – If the `activity` parameter is not of proper type.

  is_ws_ratelimited()

    `bool`: Whether the websocket is currently rate limited.

    This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

    This implementation checks if any of the shards are rate limited. For more granular control, consider `ShardInfo.is_ws_ratelimited()`.

    Added in version 1.6.

## Application Info

### AppInfo

Attributes

- approximate_guild_count
- approximate_user_install_count
- bot_public
- bot_require_code_grant
- cover_image
- custom_install_url
- description
- flags
- guild
- guild_id
- guild_integration_config
- icon
- id
- install_params
- interactions_endpoint_url
- name
- owner
- primary_sku_id
- privacy_policy_url
- redirect_uris
- role_connections_verification_url
- rpc_origins
- slug
- tags
- team
- terms_of_service_url
- user_integration_config
- verify_key

Methods

- async edit

class discord.AppInfo

  Represents the application info for the bot provided by Discord.

  id

    The application ID.

    Type:

      `int`

  name

    The application name.

    Type:

      `str`

  owner

    The application owner.

    Type:

      `User`

  team

    The application’s team.

    Added in version 1.3.

    Type:

      Optional[`Team`]

  description

    The application description.

    Type:

      `str`

  bot_public

    Whether the bot can be invited by anyone or if it is locked to the application owner.

    Type:

      `bool`

  bot_require_code_grant

    Whether the bot requires the completion of the full oauth2 code grant flow to join.

    Type:

      `bool`

  rpc_origins

    A list of RPC origin URLs, if RPC is enabled.

    Type:

      Optional[List[`str`]]

  verify_key

    The hex encoded key for verification in interactions and the GameSDK’s GetTicket.

    Added in version 1.3.

    Type:

      `str`

  guild_id

    If this application is a game sold on Discord, this field will be the guild to which it has been linked to.

    Added in version 1.3.

    Type:

      Optional[`int`]

  primary_sku_id

    If this application is a game sold on Discord, this field will be the id of the “Game SKU” that is created, if it exists.

    Added in version 1.3.

    Type:

      Optional[`int`]

  slug

    If this application is a game sold on Discord, this field will be the URL slug that links to the store page.

    Added in version 1.3.

    Type:

      Optional[`str`]

  terms_of_service_url

    The application’s terms of service URL, if set.

    Added in version 2.0.

    Type:

      Optional[`str`]

  privacy_policy_url

    The application’s privacy policy URL, if set.

    Added in version 2.0.

    Type:

      Optional[`str`]

  tags

    The list of tags describing the functionality of the application.

    Added in version 2.0.

    Type:

      List[`str`]

  custom_install_url

    The custom authorization URL for the application, if enabled.

    Added in version 2.0.

    Type:

      List[`str`]

  install_params

    The settings for custom authorization URL of application, if enabled.

    Added in version 2.0.

    Type:

      Optional[`AppInstallParams`]

  role_connections_verification_url

    The application’s connection verification URL which will render the application as a verification method in the guild’s role verification configuration.

    Added in version 2.2.

    Type:

      Optional[`str`]

  interactions_endpoint_url

    The interactions endpoint url of the application to receive interactions over this endpoint rather than over the gateway, if configured.

    Added in version 2.4.

    Type:

      Optional[`str`]

  redirect_uris

    A list of authentication redirect URIs.

    Added in version 2.4.

    Type:

      List[`str`]

  approximate_guild_count

    The approximate count of the guilds the bot was added to.

    Added in version 2.4.

    Type:

      `int`

  approximate_user_install_count

    The approximate count of the user-level installations the bot has.

    Added in version 2.5.

    Type:

      Optional[`int`]

  property icon

    Retrieves the application’s icon asset, if any.

    Type:

      Optional[`Asset`]

  property cover_image

    Retrieves the cover image on a store embed, if any.

    This is only available if the application is a game sold on Discord.

    Type:

      Optional[`Asset`]

  property guild

    If this application is a game sold on Discord, this field will be the guild to which it has been linked

    Added in version 1.3.

    Type:

      Optional[`Guild`]

  property flags

    The application’s flags.

    Added in version 2.0.

    Type:

      `ApplicationFlags`

  property guild_integration_config

    The default settings for the application’s installation context in a guild.

    Added in version 2.5.

    Type:

      Optional[`IntegrationTypeConfig`]

  property user_integration_config

    The default settings for the application’s installation context as a user.

    Added in version 2.5.

    Type:

      Optional[`IntegrationTypeConfig`]

  await edit(*, reason=..., custom_install_url=..., description=..., role_connections_verification_url=..., install_params_scopes=..., install_params_permissions=..., flags=..., icon=..., cover_image=..., interactions_endpoint_url=..., tags=..., guild_install_scopes=..., guild_install_permissions=..., user_install_scopes=..., user_install_permissions=...)

    This function is a coroutine.

    Edits the application info.

    Added in version 2.4.

    Parameters:

      - custom_install_url (Optional[`str`]) – The new custom authorization URL for the application. Can be `None` to remove the URL.

      - description (Optional[`str`]) – The new application description. Can be `None` to remove the description.

      - role_connections_verification_url (Optional[`str`]) – The new application’s connection verification URL which will render the application as a verification method in the guild’s role verification configuration. Can be `None` to remove the URL.

      - install_params_scopes (Optional[List[`str`]]) – The new list of OAuth2 scopes of the `install_params`. Can be `None` to remove the scopes.

      - install_params_permissions (Optional[`Permissions`]) – The new permissions of the `install_params`. Can be `None` to remove the permissions.

      - flags (Optional[`ApplicationFlags`]) –

        The new application’s flags. Only limited intent flags (`gateway_presence_limited`, `gateway_guild_members_limited`, `gateway_message_content_limited`) can be edited. Can be `None` to remove the flags.

        Warning

        Editing the limited intent flags leads to the termination of the bot.

      - icon (Optional[`bytes`]) – The new application’s icon as a py:bytes-like object. Can be `None` to remove the icon.

      - cover_image (Optional[`bytes`]) – The new application’s cover image as a py:bytes-like object on a store embed. The cover image is only available if the application is a game sold on Discord. Can be `None` to remove the image.

      - interactions_endpoint_url (Optional[`str`]) – The new interactions endpoint url of the application to receive interactions over this endpoint rather than over the gateway. Can be `None` to remove the URL.

      - tags (Optional[List[`str`]]) – The new list of tags describing the functionality of the application. Can be `None` to remove the tags.

      - guild_install_scopes (Optional[List[`str`]]) –

        The new list of OAuth2 scopes of the default guild installation context. Can be `None` to remove the scopes.

      - guild_install_permissions (Optional[`Permissions`]) –

        The new permissions of the default guild installation context. Can be `None` to remove the permissions.

      - user_install_scopes (Optional[List[`str`]]) –

        The new list of OAuth2 scopes of the default user installation context. Can be `None` to remove the scopes.

      - user_install_permissions (Optional[`Permissions`]) –

        The new permissions of the default user installation context. Can be `None` to remove the permissions.

      - reason (Optional[`str`]) – The reason for editing the application. Shows up on the audit log.

    Raises:

      - HTTPException – Editing the application failed

      - ValueError – The image format passed in to `icon` or `cover_image` is invalid. This is also raised when `install_params_scopes` and `install_params_permissions` are incompatible with each other, or when `guild_install_scopes` and `guild_install_permissions` are incompatible with each other.

    Returns:

      The newly updated application info.

    Return type:

      `AppInfo`

### PartialAppInfo

Attributes

- approximate_guild_count
- cover_image
- description
- flags
- icon
- id
- interactions_endpoint_url
- name
- privacy_policy_url
- redirect_uris
- role_connections_verification_url
- rpc_origins
- terms_of_service_url
- verify_key

class discord.PartialAppInfo

  Represents a partial AppInfo given by `create_invite()`

  Added in version 2.0.

  id

    The application ID.

    Type:

      `int`

  name

    The application name.

    Type:

      `str`

  description

    The application description.

    Type:

      `str`

  rpc_origins

    A list of RPC origin URLs, if RPC is enabled.

    Type:

      Optional[List[`str`]]

  verify_key

    The hex encoded key for verification in interactions and the GameSDK’s GetTicket.

    Type:

      `str`

  terms_of_service_url

    The application’s terms of service URL, if set.

    Type:

      Optional[`str`]

  privacy_policy_url

    The application’s privacy policy URL, if set.

    Type:

      Optional[`str`]

  approximate_guild_count

    The approximate count of the guilds the bot was added to.

    Added in version 2.3.

    Type:

      `int`

  redirect_uris

    A list of authentication redirect URIs.

    Added in version 2.3.

    Type:

      List[`str`]

  interactions_endpoint_url

    The interactions endpoint url of the application to receive interactions over this endpoint rather than over the gateway, if configured.

    Added in version 2.3.

    Type:

      Optional[`str`]

  role_connections_verification_url

    The application’s connection verification URL which will render the application as a verification method in the guild’s role verification configuration.

    Added in version 2.3.

    Type:

      Optional[`str`]

  property icon

    Retrieves the application’s icon asset, if any.

    Type:

      Optional[`Asset`]

  property cover_image

    Retrieves the cover image of the application’s default rich presence.

    This is only available if the application is a game sold on Discord.

    Added in version 2.3.

    Type:

      Optional[`Asset`]

  property flags

    The application’s flags.

    Added in version 2.0.

    Type:

      `ApplicationFlags`

### AppInstallParams

Attributes

- permissions
- scopes

class discord.AppInstallParams

  Represents the settings for custom authorization URL of an application.

  Added in version 2.0.

  scopes

    The list of OAuth2 scopes to add the application to a guild with.

    Type:

      List[`str`]

  permissions

    The permissions to give to application in the guild.

    Type:

      `Permissions`

### IntegrationTypeConfig

Attributes

- oauth2_install_params

class discord.IntegrationTypeConfig

  Represents the default settings for the application’s installation context.

  Added in version 2.5.

  oauth2_install_params

    The install params for this installation context’s default in-app authorization link.

    Type:

      Optional[`AppInstallParams`]

### Team

Attributes

- icon
- id
- members
- name
- owner
- owner_id

class discord.Team

  Represents an application team for a bot provided by Discord.

  id

    The team ID.

    Type:

      `int`

  name

    The team name

    Type:

      `str`

  owner_id

    The team’s owner ID.

    Type:

      `int`

  members

    A list of the members in the team

    Added in version 1.3.

    Type:

      List[`TeamMember`]

  property icon

    Retrieves the team’s icon asset, if any.

    Type:

      Optional[`Asset`]

  property owner

    The team’s owner.

    Type:

      Optional[`TeamMember`]

### TeamMember

Attributes

- accent_color
- accent_colour
- avatar
- avatar_decoration
- avatar_decoration_sku_id
- banner
- bot
- color
- colour
- created_at
- default_avatar
- discriminator
- display_avatar
- display_name
- global_name
- id
- membership_state
- mention
- name
- public_flags
- role
- team

Methods

- def mentioned_in

class discord.TeamMember

  Represents a team member in a team.

  x == y

    Checks if two team members are equal.

  x != y

    Checks if two team members are not equal.

  hash(x)

    Return the team member’s hash.

  str(x)

    Returns the team member’s handle (e.g. `name` or `name#discriminator`).

  Added in version 1.3.

  name

    The team member’s username.

    Type:

      `str`

  id

    The team member’s unique ID.

    Type:

      `int`

  discriminator

    The team member’s discriminator. This is a legacy concept that is no longer used.

    Type:

      `str`

  global_name

    The team member’s global nickname, taking precedence over the username in display.

    Added in version 2.3.

    Type:

      Optional[`str`]

  bot

    Specifies if the user is a bot account.

    Type:

      `bool`

  team

    The team that the member is from.

    Type:

      `Team`

  membership_state

    The membership state of the member (e.g. invited or accepted)

    Type:

      `TeamMembershipState`

  role

    The role of the member within the team.

    Added in version 2.4.

    Type:

      `TeamMemberRole`

  property accent_color

    Returns the user’s accent color, if applicable.

    A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

    There is an alias for this named `accent_colour`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property accent_colour

    Returns the user’s accent colour, if applicable.

    A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

    There is an alias for this named `accent_color`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property avatar

    Returns an `Asset` for the avatar the user has.

    If the user has not uploaded a global avatar, `None` is returned. If you want the avatar that a user has displayed, consider `display_avatar`.

    Type:

      Optional[`Asset`]

  property avatar_decoration

    Returns an `Asset` for the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`Asset`]

  property avatar_decoration_sku_id

    Returns the SKU ID of the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`int`]

  property banner

    Returns the user’s banner asset, if available.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Asset`]

  property color

    A property that returns a color denoting the rendered color for the user. This always returns `Colour.default()`.

    There is an alias for this named `colour`.

    Type:

      `Colour`

  property colour

    A property that returns a colour denoting the rendered colour for the user. This always returns `Colour.default()`.

    There is an alias for this named `color`.

    Type:

      `Colour`

  property created_at

    Returns the user’s creation time in UTC.

    This is when the user’s Discord account was created.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar for a given user.

    Type:

      `Asset`

  property display_avatar

    Returns the user’s display avatar.

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

    Added in version 2.0.

    Type:

      `Asset`

  property display_name

    Returns the user’s display name.

    For regular users this is just their global name or their username, but if they have a guild specific nickname then that is returned instead.

    Type:

      `str`

  property mention

    Returns a string that allows you to mention the given user.

    Type:

      `str`

  mentioned_in(message)

    Checks if the user is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the user is mentioned in the message.

    Return type:

      `bool`

  property public_flags

    The publicly available flags the user has.

    Type:

      `PublicUserFlags`

## Voice Related

### VoiceClient

Attributes

- average_latency
- channel
- endpoint
- guild
- latency
- session_id
- source
- token
- user

Methods

- async disconnect
- def is_connected
- def is_paused
- def is_playing
- async move_to
- def pause
- def play
- def resume
- def send_audio_packet
- def stop

class discord.VoiceClient

  Represents a Discord voice connection.

  You do not create these, you typically get them from e.g. `VoiceChannel.connect()`.

  Warning

  In order to use PCM based AudioSources, you must have the opus library installed on your system and loaded through `opus.load_opus()`. Otherwise, your AudioSources must be opus encoded (e.g. using `FFmpegOpusAudio`) or the library will not be able to transmit audio.

  session_id

    The voice connection session ID.

    Type:

      `str`

  token

    The voice connection token.

    Type:

      `str`

  endpoint

    The endpoint we are connecting to.

    Type:

      `str`

  channel

    The voice channel connected to.

    Type:

      Union[`VoiceChannel`, `StageChannel`]

  property guild

    The guild we’re connected to.

    Type:

      `Guild`

  property user

    The user connected to voice (i.e. ourselves).

    Type:

      `ClientUser`

  property latency

    Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

    This could be referred to as the Discord Voice WebSocket latency and is an analogue of user’s voice latencies as seen in the Discord client.

    Added in version 1.4.

    Type:

      `float`

  property average_latency

    Average of most recent 20 HEARTBEAT latencies in seconds.

    Added in version 1.4.

    Type:

      `float`

  await disconnect(*, force=False)

    This function is a coroutine.

    Disconnects this voice client from voice.

  await move_to(channel, *, timeout=30.0)

    This function is a coroutine.

    Moves you to a different voice channel.

    Parameters:

      - channel (Optional[`abc.Snowflake`]) – The channel to move to. Must be a voice channel.

      - timeout (Optional[`float`]) –

        How long to wait for the move to complete.

        Added in version 2.4.

    Raises:

      asyncio.TimeoutError – The move did not complete in time, but may still be ongoing.

  is_connected()

    Indicates if the voice client is connected to voice.

  play(source, *, after=None, application='audio', bitrate=128, fec=True, expected_packet_loss=0.15, bandwidth='full', signal_type='auto')

    Plays an `AudioSource`.

    The finalizer, `after` is called after the source has been exhausted or an error occurred.

    If an error happens while the audio player is running, the exception is caught and the audio player is then stopped. If no after callback is passed, any caught exception will be logged using the library logger.

    Extra parameters may be passed to the internal opus encoder if a PCM based source is used. Otherwise, they are ignored.

    Changed in version 2.0: Instead of writing to `sys.stderr`, the library’s logger is used.

    Changed in version 2.4: Added encoder parameters as keyword arguments.

    Parameters:

      - source (`AudioSource`) – The audio source we’re reading from.

      - after (Callable[[Optional[`Exception`]], Any]) – The finalizer that is called after the stream is exhausted. This function must have a single parameter, `error`, that denotes an optional exception that was raised during playing.

      - application (`str`) – Configures the encoder’s intended application. Can be one of: `'audio'`, `'voip'`, `'lowdelay'`. Defaults to `'audio'`.

      - bitrate (`int`) – Configures the bitrate in the encoder. Can be between `16` and `512`. Defaults to `128`.

      - fec (`bool`) – Configures the encoder’s use of inband forward error correction. Defaults to `True`.

      - expected_packet_loss (`float`) – Configures the encoder’s expected packet loss percentage. Requires FEC. Defaults to `0.15`.

      - bandwidth (`str`) – Configures the encoder’s bandpass. Can be one of: `'narrow'`, `'medium'`, `'wide'`, `'superwide'`, `'full'`. Defaults to `'full'`.

      - signal_type (`str`) – Configures the type of signal being encoded. Can be one of: `'auto'`, `'voice'`, `'music'`. Defaults to `'auto'`.

    Raises:

      - ClientException – Already playing audio or not connected.

      - TypeError – Source is not a `AudioSource` or after is not a callable.

      - OpusNotLoaded – Source is not opus encoded and opus is not loaded.

      - ValueError – An improper value was passed as an encoder parameter.

  is_playing()

    Indicates if we’re currently playing audio.

  is_paused()

    Indicates if we’re playing audio, but if we’re paused.

  stop()

    Stops playing audio.

  pause()

    Pauses the audio playing.

  resume()

    Resumes the audio playing.

  property source

    The audio source being played, if playing.

    This property can also be used to change the audio source currently being played.

    Type:

      Optional[`AudioSource`]

  send_audio_packet(data, *, encode=True)

    Sends an audio packet composed of the data.

    You must be connected to play audio.

    Parameters:

      - data (`bytes`) – The py:bytes-like object denoting PCM or Opus voice data.

      - encode (`bool`) – Indicates if `data` should be encoded into Opus.

    Raises:

      - ClientException – You are not connected.

      - opus.OpusError – Encoding the data failed.

### VoiceProtocol

Methods

- def cleanup
- async connect
- async disconnect
- async on_voice_server_update
- async on_voice_state_update

class discord.VoiceProtocol(client, channel)

  A class that represents the Discord voice protocol.

  This is an abstract class. The library provides a concrete implementation under `VoiceClient`.

  This class allows you to implement a protocol to allow for an external method of sending voice, such as Lavalink or a native library implementation.

  These classes are passed to `abc.Connectable.connect`.

  Parameters:

    - client (`Client`) – The client (or its subclasses) that started the connection request.

    - channel (`abc.Connectable`) – The voice channel that is being connected to.

  await on_voice_state_update(data, /)

    This function is a coroutine.

    An abstract method that is called when the client’s voice state has changed. This corresponds to `VOICE_STATE_UPDATE`.

    Warning

    This method is not the same as the event. See: `on_voice_state_update()`

    Parameters:

      data (`dict`) – The raw voice state payload.

  await on_voice_server_update(data, /)

    This function is a coroutine.

    An abstract method that is called when initially connecting to voice. This corresponds to `VOICE_SERVER_UPDATE`.

    Parameters:

      data (`dict`) – The raw voice server update payload.

  await connect(*, timeout, reconnect, self_deaf=False, self_mute=False)

    This function is a coroutine.

    An abstract method called when the client initiates the connection request.

    When a connection is requested initially, the library calls the constructor under `__init__` and then calls `connect()`. If `connect()` fails at some point then `disconnect()` is called.

    Within this method, to start the voice connection flow it is recommended to use `Guild.change_voice_state()` to start the flow. After which, `on_voice_server_update()` and `on_voice_state_update()` will be called. The order that these two are called is unspecified.

    Parameters:

      - timeout (`float`) – The timeout for the connection.

      - reconnect (`bool`) – Whether reconnection is expected.

      - self_mute (`bool`) –

        Indicates if the client should be self-muted.

        Added in version 2.0.

      - self_deaf (`bool`) –

        Indicates if the client should be self-deafened.

        Added in version 2.0.

  await disconnect(*, force)

    This function is a coroutine.

    An abstract method called when the client terminates the connection.

    See `cleanup()`.

    Parameters:

      force (`bool`) – Whether the disconnection was forced.

  cleanup()

    This method must be called to ensure proper clean-up during a disconnect.

    It is advisable to call this from within `disconnect()` when you are completely done with the voice protocol instance.

    This method removes it from the internal state cache that keeps track of currently alive voice clients. Failure to clean-up will cause subsequent connections to report that it’s still connected.

### AudioSource

Methods

- def cleanup
- def is_opus
- def read

class discord.AudioSource

  Represents an audio stream.

  The audio stream can be Opus encoded or not, however if the audio stream is not Opus encoded then the audio format must be 16-bit 48KHz stereo PCM.

  Warning

  The audio source reads are done in a separate thread.

  read()

    Reads 20ms worth of audio.

    Subclasses must implement this.

    If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

    If `is_opus()` method returns `True`, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).

    Returns:

      A bytes like object that represents the PCM or Opus data.

    Return type:

      `bytes`

  is_opus()

    Checks if the audio source is already encoded in Opus.

  cleanup()

    Called when clean-up is needed to be done.

    Useful for clearing buffer data or processes after it is done playing audio.

### PCMAudio

Attributes

- stream

Methods

- def read

class discord.PCMAudio(stream)

  Represents raw 16-bit 48KHz stereo PCM audio source.

  stream

    A file-like object that reads byte data representing raw PCM.

    Type:

      py:file object

  read()

    Reads 20ms worth of audio.

    Subclasses must implement this.

    If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

    If `is_opus()` method returns `True`, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).

    Returns:

      A bytes like object that represents the PCM or Opus data.

    Return type:

      `bytes`

### FFmpegAudio

Methods

- def cleanup

class discord.FFmpegAudio(source, *, executable='ffmpeg', args, **subprocess_kwargs)

  Represents an FFmpeg (or AVConv) based AudioSource.

  User created AudioSources using FFmpeg differently from how `FFmpegPCMAudio` and `FFmpegOpusAudio` work should subclass this.

  Added in version 1.3.

  cleanup()

    Called when clean-up is needed to be done.

    Useful for clearing buffer data or processes after it is done playing audio.

### FFmpegPCMAudio

Methods

- def is_opus
- def read

class discord.FFmpegPCMAudio(source, *, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)

  An audio source from FFmpeg (or AVConv).

  This launches a sub-process to a specific input file given.

  Warning

  You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.

  Parameters:

    - source (Union[`str`, `io.BufferedIOBase`]) – The input that ffmpeg will take and convert to PCM bytes. If `pipe` is `True` then this is a file-like object that is passed to the stdin of ffmpeg.

    - executable (`str`) –

      The executable name (and path) to use. Defaults to `ffmpeg`.

      Warning

      Since this class spawns a subprocess, care should be taken to not pass in an arbitrary executable name when using this parameter.

    - pipe (`bool`) – If `True`, denotes that `source` parameter will be passed to the stdin of ffmpeg. Defaults to `False`.

    - stderr (Optional[py:file object]) – A file-like object to pass to the Popen constructor.

    - before_options (Optional[`str`]) – Extra command line arguments to pass to ffmpeg before the `-i` flag.

    - options (Optional[`str`]) – Extra command line arguments to pass to ffmpeg after the `-i` flag.

  Raises:

    ClientException – The subprocess failed to be created.

  read()

    Reads 20ms worth of audio.

    Subclasses must implement this.

    If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

    If `is_opus()` method returns `True`, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).

    Returns:

      A bytes like object that represents the PCM or Opus data.

    Return type:

      `bytes`

  is_opus()

    Checks if the audio source is already encoded in Opus.

### FFmpegOpusAudio

Methods

- async from_probe
- def is_opus
- async probe
- def read

class discord.FFmpegOpusAudio(source, *, bitrate=None, codec=None, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)

  An audio source from FFmpeg (or AVConv).

  This launches a sub-process to a specific input file given. However, rather than producing PCM packets like `FFmpegPCMAudio` does that need to be encoded to Opus, this class produces Opus packets, skipping the encoding step done by the library.

  Alternatively, instead of instantiating this class directly, you can use `FFmpegOpusAudio.from_probe()` to probe for bitrate and codec information. This can be used to opportunistically skip pointless re-encoding of existing Opus audio data for a boost in performance at the cost of a short initial delay to gather the information. The same can be achieved by passing `copy` to the `codec` parameter, but only if you know that the input source is Opus encoded beforehand.

  Added in version 1.3.

  Warning

  You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.

  Parameters:

    - source (Union[`str`, `io.BufferedIOBase`]) – The input that ffmpeg will take and convert to Opus bytes. If `pipe` is `True` then this is a file-like object that is passed to the stdin of ffmpeg.

    - bitrate (`int`) – The bitrate in kbps to encode the output to. Defaults to `128`.

    - codec (Optional[`str`]) –

      The codec to use to encode the audio data. Normally this would be just `libopus`, but is used by `FFmpegOpusAudio.from_probe()` to opportunistically skip pointlessly re-encoding Opus audio data by passing `copy` as the codec value. Any values other than `copy`, `opus`, or `libopus` will be considered `libopus`. Defaults to `libopus`.

      Warning

      Do not provide this parameter unless you are certain that the audio input is already Opus encoded. For typical use `FFmpegOpusAudio.from_probe()` should be used to determine the proper value for this parameter.

    - executable (`str`) –

      The executable name (and path) to use. Defaults to `ffmpeg`.

      Warning

      Since this class spawns a subprocess, care should be taken to not pass in an arbitrary executable name when using this parameter.

    - pipe (`bool`) – If `True`, denotes that `source` parameter will be passed to the stdin of ffmpeg. Defaults to `False`.

    - stderr (Optional[py:file object]) – A file-like object to pass to the Popen constructor.

    - before_options (Optional[`str`]) – Extra command line arguments to pass to ffmpeg before the `-i` flag.

    - options (Optional[`str`]) – Extra command line arguments to pass to ffmpeg after the `-i` flag.

  Raises:

    ClientException – The subprocess failed to be created.

  classmethod await from_probe(source, *, method=None, **kwargs)

    This function is a coroutine.

    A factory method that creates a `FFmpegOpusAudio` after probing the input source for audio codec and bitrate information.

    Examples

    Use this function to create an `FFmpegOpusAudio` instance instead of the constructor:

        source = await discord.FFmpegOpusAudio.from_probe("song.webm")
        voice_client.play(source)

    If you are on Windows and don’t have ffprobe installed, use the `fallback` method to probe using ffmpeg instead:

        source = await discord.FFmpegOpusAudio.from_probe("song.webm", method='fallback')
        voice_client.play(source)

    Using a custom method of determining codec and bitrate:

        def custom_probe(source, executable):
            # some analysis code here
            return codec, bitrate

        source = await discord.FFmpegOpusAudio.from_probe("song.webm", method=custom_probe)
        voice_client.play(source)

    Parameters:

      - source – Identical to the `source` parameter for the constructor.

      - method (Optional[Union[`str`, Callable[`str`, `str`]]]) – The probing method used to determine bitrate and codec information. As a string, valid values are `native` to use ffprobe (or avprobe) and `fallback` to use ffmpeg (or avconv). As a callable, it must take two string arguments, `source` and `executable`. Both parameters are the same values passed to this factory function. `executable` will default to `ffmpeg` if not provided as a keyword argument.

      - kwargs – The remaining parameters to be passed to the `FFmpegOpusAudio` constructor, excluding `bitrate` and `codec`.

    Raises:

      - AttributeError – Invalid probe method, must be `'native'` or `'fallback'`.

      - TypeError – Invalid value for `probe` parameter, must be `str` or a callable.

    Returns:

      An instance of this class.

    Return type:

      `FFmpegOpusAudio`

  classmethod await probe(source, *, method=None, executable=None)

    This function is a coroutine.

    Probes the input source for bitrate and codec information.

    Parameters:

      - source – Identical to the `source` parameter for `FFmpegOpusAudio`.

      - method – Identical to the `method` parameter for `FFmpegOpusAudio.from_probe()`.

      - executable (`str`) – Identical to the `executable` parameter for `FFmpegOpusAudio`.

    Raises:

      - AttributeError – Invalid probe method, must be `'native'` or `'fallback'`.

      - TypeError – Invalid value for `probe` parameter, must be `str` or a callable.

    Returns:

      A 2-tuple with the codec and bitrate of the input source.

    Return type:

      Optional[Tuple[Optional[`str`], `int`]]

  read()

    Reads 20ms worth of audio.

    Subclasses must implement this.

    If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

    If `is_opus()` method returns `True`, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).

    Returns:

      A bytes like object that represents the PCM or Opus data.

    Return type:

      `bytes`

  is_opus()

    Checks if the audio source is already encoded in Opus.

### PCMVolumeTransformer

Attributes

- volume

Methods

- def cleanup
- def read

class discord.PCMVolumeTransformer(original, volume=1.0)

  Transforms a previous `AudioSource` to have volume controls.

  This does not work on audio sources that have `AudioSource.is_opus()` set to `True`.

  Parameters:

    - original (`AudioSource`) – The original AudioSource to transform.

    - volume (`float`) – The initial volume to set it to. See `volume` for more info.

  Raises:

    - TypeError – Not an audio source.

    - ClientException – The audio source is opus encoded.

  property volume

    Retrieves or sets the volume as a floating point percentage (e.g. `1.0` for 100%).

  cleanup()

    Called when clean-up is needed to be done.

    Useful for clearing buffer data or processes after it is done playing audio.

  read()

    Reads 20ms worth of audio.

    Subclasses must implement this.

    If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

    If `is_opus()` method returns `True`, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).

    Returns:

      A bytes like object that represents the PCM or Opus data.

    Return type:

      `bytes`

### Opus Library

discord.opus.load_opus(name)

  Loads the libopus shared library for use with voice.

  If this function is not called then the library uses the function `ctypes.util.find_library()` and then loads that one if available.

  Not loading a library and attempting to use PCM based AudioSources will lead to voice not working.

  This function propagates the exceptions thrown.

  Warning

  The bitness of the library must match the bitness of your python interpreter. If the library is 64-bit then your python interpreter must be 64-bit as well. Usually if there’s a mismatch in bitness then the load will throw an exception.

  Note

  On Windows, this function should not need to be called as the binaries are automatically loaded.

  Note

  On Windows, the .dll extension is not necessary. However, on Linux the full extension is required to load the library, e.g. `libopus.so.1`. On Linux however, `ctypes.util.find_library()` will usually find the library automatically without you having to call this.

  Parameters:

    name (`str`) – The filename of the shared library.

discord.opus.is_loaded()

  Function to check if opus lib is successfully loaded either via the `ctypes.util.find_library()` call of `load_opus()`.

  This must return `True` for voice to work.

  Returns:

    Indicates if the opus library has been loaded.

  Return type:

    `bool`

## Event Reference

This section outlines the different types of events listened by `Client`.

There are two ways to register an event, the first way is through the use of `Client.event()`. The second way is through subclassing `Client` and overriding the specific events. For example:

    import discord

    class MyClient(discord.Client):
        async def on_message(self, message):
            if message.author == self.user:
                return

            if message.content.startswith('$hello'):
                await message.channel.send('Hello World!')

If an event handler raises an exception, `on_error()` will be called to handle it, which defaults to logging the traceback and ignoring the exception.

Warning

All the events must be a coroutine. If they aren’t, then you might get unexpected errors. In order to turn a function into a coroutine they must be `async def` functions.

### App Commands

discord.on_raw_app_command_permissions_update(payload)

  Called when application command permissions are updated.

  Added in version 2.0.

  Parameters:

    payload (`RawAppCommandPermissionsUpdateEvent`) – The raw event payload data.

discord.on_app_command_completion(interaction, command)

  Called when a `app_commands.Command` or `app_commands.ContextMenu` has successfully completed without error.

  Added in version 2.0.

  Parameters:

    - interaction (`Interaction`) – The interaction of the command.

    - command (Union[`app_commands.Command`, `app_commands.ContextMenu`]) – The command that completed successfully

### AutoMod

discord.on_automod_rule_create(rule)

  Called when a `AutoModRule` is created. You must have `manage_guild` to receive this.

  This requires `Intents.auto_moderation_configuration` to be enabled.

  Added in version 2.0.

  Parameters:

    rule (`AutoModRule`) – The rule that was created.

discord.on_automod_rule_update(rule)

  Called when a `AutoModRule` is updated. You must have `manage_guild` to receive this.

  This requires `Intents.auto_moderation_configuration` to be enabled.

  Added in version 2.0.

  Parameters:

    rule (`AutoModRule`) – The rule that was updated.

discord.on_automod_rule_delete(rule)

  Called when a `AutoModRule` is deleted. You must have `manage_guild` to receive this.

  This requires `Intents.auto_moderation_configuration` to be enabled.

  Added in version 2.0.

  Parameters:

    rule (`AutoModRule`) – The rule that was deleted.

discord.on_automod_action(execution)

  Called when a `AutoModAction` is created/performed. You must have `manage_guild` to receive this.

  This requires `Intents.auto_moderation_execution` to be enabled.

  Added in version 2.0.

  Parameters:

    execution (`AutoModAction`) – The rule execution that was performed.

### Channels

discord.on_guild_channel_delete(channel)
discord.on_guild_channel_create(channel)

  Called whenever a guild channel is deleted or created.

  Note that you can get the guild from `guild`.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    channel (`abc.GuildChannel`) – The guild channel that got created or deleted.

discord.on_guild_channel_update(before, after)

  Called whenever a guild channel is updated. e.g. changed name, topic, permissions.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    - before (`abc.GuildChannel`) – The updated guild channel’s old info.

    - after (`abc.GuildChannel`) – The updated guild channel’s new info.

discord.on_guild_channel_pins_update(channel, last_pin)

  Called whenever a message is pinned or unpinned from a guild channel.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    - channel (Union[`abc.GuildChannel`, `Thread`]) – The guild channel that had its pins updated.

    - last_pin (Optional[`datetime.datetime`]) – The latest message that was pinned as an aware datetime in UTC. Could be `None`.

discord.on_private_channel_update(before, after)

  Called whenever a private group DM is updated. e.g. changed name or topic.

  This requires `Intents.messages` to be enabled.

  Parameters:

    - before (`GroupChannel`) – The updated group channel’s old info.

    - after (`GroupChannel`) – The updated group channel’s new info.

discord.on_private_channel_pins_update(channel, last_pin)

  Called whenever a message is pinned or unpinned from a private channel.

  Parameters:

    - channel (`abc.PrivateChannel`) – The private channel that had its pins updated.

    - last_pin (Optional[`datetime.datetime`]) – The latest message that was pinned as an aware datetime in UTC. Could be `None`.

discord.on_typing(channel, user, when)

  Called when someone begins typing a message.

  The `channel` parameter can be a `abc.Messageable` instance. Which could either be `TextChannel`, `GroupChannel`, or `DMChannel`.

  If the `channel` is a `TextChannel` then the `user` parameter is a `Member`, otherwise it is a `User`.

  If the channel or user could not be found in the internal cache this event will not be called, you may use `on_raw_typing()` instead.

  This requires `Intents.typing` to be enabled.

  Parameters:

    - channel (`abc.Messageable`) – The location where the typing originated from.

    - user (Union[`User`, `Member`]) – The user that started typing.

    - when (`datetime.datetime`) – When the typing started as an aware datetime in UTC.

discord.on_raw_typing(payload)

  Called when someone begins typing a message. Unlike `on_typing()` this is called regardless of the channel and user being in the internal cache.

  This requires `Intents.typing` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawTypingEvent`) – The raw event payload data.

### Connection

discord.on_connect()

  Called when the client has successfully connected to Discord. This is not the same as the client being fully prepared, see `on_ready()` for that.

  The warnings on `on_ready()` also apply.

discord.on_disconnect()

  Called when the client has disconnected from Discord, or a connection attempt to Discord has failed. This could happen either through the internet being disconnected, explicit calls to close, or Discord terminating the connection one way or the other.

  This function can be called many times without a corresponding `on_connect()` call.

discord.on_shard_connect(shard_id)

  Similar to `on_connect()` except used by `AutoShardedClient` to denote when a particular shard ID has connected to Discord.

  Added in version 1.4.

  Parameters:

    shard_id (`int`) – The shard ID that has connected.

discord.on_shard_disconnect(shard_id)

  Similar to `on_disconnect()` except used by `AutoShardedClient` to denote when a particular shard ID has disconnected from Discord.

  Added in version 1.4.

  Parameters:

    shard_id (`int`) – The shard ID that has disconnected.

### Debug

discord.on_error(event, *args, **kwargs)

  Usually when an event raises an uncaught exception, a traceback is logged to stderr and the exception is ignored. If you want to change this behaviour and handle the exception for whatever reason yourself, this event can be overridden. Which, when done, will suppress the default action of printing the traceback.

  The information of the exception raised and the exception itself can be retrieved with a standard call to `sys.exc_info()`.

  Note

  `on_error` will only be dispatched to `Client.event()`.

  It will not be received by `Client.wait_for()`, or, if used, Bots listeners such as `listen()` or `listener()`.

  Changed in version 2.0: The traceback is now logged rather than printed.

  Parameters:

    - event (`str`) – The name of the event that raised the exception.

    - args – The positional arguments for the event that raised the exception.

    - kwargs – The keyword arguments for the event that raised the exception.

discord.on_socket_event_type(event_type)

  Called whenever a websocket event is received from the WebSocket.

  This is mainly useful for logging how many events you are receiving from the Discord gateway.

  Added in version 2.0.

  Parameters:

    event_type (`str`) – The event type from Discord that is received, e.g. `'READY'`.

discord.on_socket_raw_receive(msg)

  Called whenever a message is completely received from the WebSocket, before it’s processed and parsed. This event is always dispatched when a complete message is received and the passed data is not parsed in any way.

  This is only really useful for grabbing the WebSocket stream and debugging purposes.

  This requires setting the `enable_debug_events` setting in the `Client`.

  Note

  This is only for the messages received from the client WebSocket. The voice WebSocket will not trigger this event.

  Parameters:

    msg (`str`) – The message passed in from the WebSocket library.

discord.on_socket_raw_send(payload)

  Called whenever a send operation is done on the WebSocket before the message is sent. The passed parameter is the message that is being sent to the WebSocket.

  This is only really useful for grabbing the WebSocket stream and debugging purposes.

  This requires setting the `enable_debug_events` setting in the `Client`.

  Note

  This is only for the messages sent from the client WebSocket. The voice WebSocket will not trigger this event.

  Parameters:

    payload (Union[`bytes`, `str`]) – The message that is about to be passed on to the WebSocket library. It can be `bytes` to denote a binary message or `str` to denote a regular text message.

### Entitlements

discord.on_entitlement_create(entitlement)

  Called when a user subscribes to a SKU.

  Added in version 2.4.

  Parameters:

    entitlement (`Entitlement`) – The entitlement that was created.

discord.on_entitlement_update(entitlement)

  Called when a user updates their subscription to a SKU. This is usually called when the user renews or cancels their subscription.

  Added in version 2.4.

  Parameters:

    entitlement (`Entitlement`) – The entitlement that was updated.

discord.on_entitlement_delete(entitlement)

  Called when a users subscription to a SKU is cancelled. This is typically only called when:

  - Discord issues a refund for the subscription.

  - Discord removes an entitlement from a user.

  Warning

  This event won’t be called if the user cancels their subscription manually, instead `on_entitlement_update()` will be called with `Entitlement.ends_at` set to the end of the current billing period.

  Added in version 2.4.

  Parameters:

    entitlement (`Entitlement`) – The entitlement that was deleted.

### Gateway

discord.on_ready()

  Called when the client is done preparing the data received from Discord. Usually after login is successful and the `Client.guilds` and co. are filled up.

  Warning

  This function is not guaranteed to be the first event called. Likewise, this function is not guaranteed to only be called once. This library implements reconnection logic and thus will end up calling this event whenever a RESUME request fails.

discord.on_resumed()

  Called when the client has resumed a session.

discord.on_shard_ready(shard_id)

  Similar to `on_ready()` except used by `AutoShardedClient` to denote when a particular shard ID has become ready.

  Parameters:

    shard_id (`int`) – The shard ID that is ready.

discord.on_shard_resumed(shard_id)

  Similar to `on_resumed()` except used by `AutoShardedClient` to denote when a particular shard ID has resumed a session.

  Added in version 1.4.

  Parameters:

    shard_id (`int`) – The shard ID that has resumed.

### Guilds

discord.on_guild_available(guild)
discord.on_guild_unavailable(guild)

  Called when a guild becomes available or unavailable. The guild must have existed in the `Client.guilds` cache.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    guild – The `Guild` that has changed availability.

discord.on_guild_join(guild)

  Called when a `Guild` is either created by the `Client` or when the `Client` joins a guild.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    guild (`Guild`) – The guild that was joined.

discord.on_guild_remove(guild)

  Called when a `Guild` is removed from the `Client`.

  This happens through, but not limited to, these circumstances:

  - The client got banned.

  - The client got kicked.

  - The client left the guild.

  - The client or the guild owner deleted the guild.

  In order for this event to be invoked then the `Client` must have been part of the guild to begin with. (i.e. it is part of `Client.guilds`)

  This requires `Intents.guilds` to be enabled.

  Parameters:

    guild (`Guild`) – The guild that got removed.

discord.on_guild_update(before, after)

  Called when a `Guild` updates, for example:

  - Changed name

  - Changed AFK channel

  - Changed AFK timeout

  - etc

  This requires `Intents.guilds` to be enabled.

  Parameters:

    - before (`Guild`) – The guild prior to being updated.

    - after (`Guild`) – The guild after being updated.

discord.on_guild_emojis_update(guild, before, after)

  Called when a `Guild` adds or removes `Emoji`.

  This requires `Intents.emojis_and_stickers` to be enabled.

  Parameters:

    - guild (`Guild`) – The guild who got their emojis updated.

    - before (Sequence[`Emoji`]) – A list of emojis before the update.

    - after (Sequence[`Emoji`]) – A list of emojis after the update.

discord.on_guild_stickers_update(guild, before, after)

  Called when a `Guild` updates its stickers.

  This requires `Intents.emojis_and_stickers` to be enabled.

  Added in version 2.0.

  Parameters:

    - guild (`Guild`) – The guild who got their stickers updated.

    - before (Sequence[`GuildSticker`]) – A list of stickers before the update.

    - after (Sequence[`GuildSticker`]) – A list of stickers after the update.

discord.on_audit_log_entry_create(entry)

  Called when a `Guild` gets a new audit log entry. You must have `view_audit_log` to receive this.

  This requires `Intents.moderation` to be enabled.

  Added in version 2.2.

  Warning

  Audit log entries received through the gateway are subject to data retrieval from cache rather than REST. This means that some data might not be present when you expect it to be. For example, the `AuditLogEntry.target` attribute will usually be a `discord.Object` and the `AuditLogEntry.user` attribute will depend on user and member cache.

  To get the user ID of entry, `AuditLogEntry.user_id` can be used instead.

  Parameters:

    entry (`AuditLogEntry`) – The audit log entry that was created.

discord.on_invite_create(invite)

  Called when an `Invite` is created. You must have `manage_channels` to receive this.

  Added in version 1.3.

  Note

  There is a rare possibility that the `Invite.guild` and `Invite.channel` attributes will be of `Object` rather than the respective models.

  This requires `Intents.invites` to be enabled.

  Parameters:

    invite (`Invite`) – The invite that was created.

discord.on_invite_delete(invite)

  Called when an `Invite` is deleted. You must have `manage_channels` to receive this.

  Added in version 1.3.

  Note

  There is a rare possibility that the `Invite.guild` and `Invite.channel` attributes will be of `Object` rather than the respective models.

  Outside of those two attributes, the only other attribute guaranteed to be filled by the Discord gateway for this event is `Invite.code`.

  This requires `Intents.invites` to be enabled.

  Parameters:

    invite (`Invite`) – The invite that was deleted.

### Integrations

discord.on_integration_create(integration)

  Called when an integration is created.

  This requires `Intents.integrations` to be enabled.

  Added in version 2.0.

  Parameters:

    integration (`Integration`) – The integration that was created.

discord.on_integration_update(integration)

  Called when an integration is updated.

  This requires `Intents.integrations` to be enabled.

  Added in version 2.0.

  Parameters:

    integration (`Integration`) – The integration that was updated.

discord.on_guild_integrations_update(guild)

  Called whenever an integration is created, modified, or removed from a guild.

  This requires `Intents.integrations` to be enabled.

  Added in version 1.4.

  Parameters:

    guild (`Guild`) – The guild that had its integrations updated.

discord.on_webhooks_update(channel)

  Called whenever a webhook is created, modified, or removed from a guild channel.

  This requires `Intents.webhooks` to be enabled.

  Parameters:

    channel (`abc.GuildChannel`) – The channel that had its webhooks updated.

discord.on_raw_integration_delete(payload)

  Called when an integration is deleted.

  This requires `Intents.integrations` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawIntegrationDeleteEvent`) – The raw event payload data.

### Interactions

discord.on_interaction(interaction)

  Called when an interaction happened.

  This currently happens due to slash command invocations or components being used.

  Warning

  This is a low level function that is not generally meant to be used. If you are working with components, consider using the callbacks associated with the `View` instead as it provides a nicer user experience.

  Added in version 2.0.

  Parameters:

    interaction (`Interaction`) – The interaction data.

### Members

discord.on_member_join(member)

  Called when a `Member` joins a `Guild`.

  This requires `Intents.members` to be enabled.

  Parameters:

    member (`Member`) – The member who joined.

discord.on_member_remove(member)

  Called when a `Member` leaves a `Guild`.

  If the guild or member could not be found in the internal cache this event will not be called, you may use `on_raw_member_remove()` instead.

  This requires `Intents.members` to be enabled.

  Parameters:

    member (`Member`) – The member who left.

discord.on_raw_member_remove(payload)

  Called when a `Member` leaves a `Guild`.

  Unlike `on_member_remove()` this is called regardless of the guild or member being in the internal cache.

  This requires `Intents.members` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawMemberRemoveEvent`) – The raw event payload data.

discord.on_member_update(before, after)

  Called when a `Member` updates their profile.

  This is called when one or more of the following things change:

  - nickname

  - roles

  - pending

  - timeout

  - guild avatar

  - flags

  Due to a Discord limitation, this event is not dispatched when a member’s timeout expires.

  This requires `Intents.members` to be enabled.

  Parameters:

    - before (`Member`) – The updated member’s old info.

    - after (`Member`) – The updated member’s updated info.

discord.on_user_update(before, after)

  Called when a `User` updates their profile.

  This is called when one or more of the following things change:

  - avatar

  - username

  - discriminator

  This requires `Intents.members` to be enabled.

  Parameters:

    - before (`User`) – The updated user’s old info.

    - after (`User`) – The updated user’s updated info.

discord.on_member_ban(guild, user)

  Called when a user gets banned from a `Guild`.

  This requires `Intents.moderation` to be enabled.

  Parameters:

    - guild (`Guild`) – The guild the user got banned from.

    - user (Union[`User`, `Member`]) – The user that got banned. Can be either `User` or `Member` depending if the user was in the guild or not at the time of removal.

discord.on_member_unban(guild, user)

  Called when a `User` gets unbanned from a `Guild`.

  This requires `Intents.moderation` to be enabled.

  Parameters:

    - guild (`Guild`) – The guild the user got unbanned from.

    - user (`User`) – The user that got unbanned.

discord.on_presence_update(before, after)

  Called when a `Member` updates their presence.

  This is called when one or more of the following things change:

  - status

  - activity

  This requires `Intents.presences` and `Intents.members` to be enabled.

  Added in version 2.0.

  Parameters:

    - before (`Member`) – The updated member’s old info.

    - after (`Member`) – The updated member’s updated info.

discord.on_raw_presence_update(payload)

  Called when a `Member` updates their presence.

  This requires `Intents.presences` to be enabled.

  Unlike `on_presence_update()`, when enabled, this is called regardless of the state of internal guild and member caches, and does not provide a comparison between the previous and updated states of the `Member`.

  Important

  By default, this event is only dispatched when `Intents.presences` is enabled and `Intents.members` is disabled.

  You can manually override this behaviour by setting the enable_raw_presences flag in the `Client`, however `Intents.presences` is always required for this event to work.

  Added in version 2.5.

  Parameters:

    payload (`RawPresenceUpdateEvent`) – The raw presence update event model.

### Messages

discord.on_message(message)

  Called when a `Message` is created and sent.

  This requires `Intents.messages` to be enabled.

  Warning

  Your bot’s own messages and private messages are sent through this event. This can lead cases of ‘recursion’ depending on how your bot was programmed. If you want the bot to not reply to itself, consider checking the user IDs. Note that `Bot` does not have this problem.

  Parameters:

    message (`Message`) – The current message.

discord.on_message_edit(before, after)

  Called when a `Message` receives an update event. If the message is not found in the internal message cache, then these events will not be called. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

  If this occurs increase the `max_messages` parameter or use the `on_raw_message_edit()` event instead.

  The following non-exhaustive cases trigger this event:

  - A message has been pinned or unpinned.

  - The message content has been changed.

  - The message has received an embed.

    > - For performance reasons, the embed server does not do this in a “consistent” manner.

  - The message’s embeds were suppressed or unsuppressed.

  - A call message has received an update to its participants or ending time.

  This requires `Intents.messages` to be enabled.

  Parameters:

    - before (`Message`) – The previous version of the message.

    - after (`Message`) – The current version of the message.

discord.on_message_delete(message)

  Called when a message is deleted. If the message is not found in the internal message cache, then this event will not be called. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

  If this occurs increase the `max_messages` parameter or use the `on_raw_message_delete()` event instead.

  This requires `Intents.messages` to be enabled.

  Parameters:

    message (`Message`) – The deleted message.

discord.on_bulk_message_delete(messages)

  Called when messages are bulk deleted. If none of the messages deleted are found in the internal message cache, then this event will not be called. If individual messages were not found in the internal message cache, this event will still be called, but the messages not found will not be included in the messages list. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

  If this occurs increase the `max_messages` parameter or use the `on_raw_bulk_message_delete()` event instead.

  This requires `Intents.messages` to be enabled.

  Parameters:

    messages (List[`Message`]) – The messages that have been deleted.

discord.on_raw_message_edit(payload)

  Called when a message is edited. Unlike `on_message_edit()`, this is called regardless of the state of the internal message cache.

  If the message is found in the message cache, it can be accessed via `RawMessageUpdateEvent.cached_message`. The cached message represents the message before it has been edited. For example, if the content of a message is modified and triggers the `on_raw_message_edit()` coroutine, the `RawMessageUpdateEvent.cached_message` will return a `Message` object that represents the message before the content was modified.

  Due to the inherently raw nature of this event, the data parameter coincides with the raw data given by the gateway.

  Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. One example of a common case of partial data is when the `'content'` key is inaccessible. This denotes an “embed” only edit, which is an edit in which only the embeds are updated by the Discord embed server.

  This requires `Intents.messages` to be enabled.

  Parameters:

    payload (`RawMessageUpdateEvent`) – The raw event payload data.

discord.on_raw_message_delete(payload)

  Called when a message is deleted. Unlike `on_message_delete()`, this is called regardless of the message being in the internal message cache or not.

  If the message is found in the message cache, it can be accessed via `RawMessageDeleteEvent.cached_message`

  This requires `Intents.messages` to be enabled.

  Parameters:

    payload (`RawMessageDeleteEvent`) – The raw event payload data.

discord.on_raw_bulk_message_delete(payload)

  Called when a bulk delete is triggered. Unlike `on_bulk_message_delete()`, this is called regardless of the messages being in the internal message cache or not.

  If the messages are found in the message cache, they can be accessed via `RawBulkMessageDeleteEvent.cached_messages`

  This requires `Intents.messages` to be enabled.

  Parameters:

    payload (`RawBulkMessageDeleteEvent`) – The raw event payload data.

### Polls

discord.on_poll_vote_add(user, answer)
discord.on_poll_vote_remove(user, answer)

  Called when a `Poll` gains or loses a vote. If the `user` or `answer`’s poll parent message are not cached then this event will not be called.

  This requires `Intents.message_content` and `Intents.polls` to be enabled.

  Note

  If the poll allows multiple answers and the user removes or adds multiple votes, this event will be called as many times as votes that are added or removed.

  Added in version 2.4.

  Parameters:

    - user (Union[`User`, `Member`]) – The user that performed the action.

    - answer (`PollAnswer`) – The answer the user voted or removed their vote from.

discord.on_raw_poll_vote_add(payload)
discord.on_raw_poll_vote_remove(payload)

  Called when a `Poll` gains or loses a vote. Unlike `on_poll_vote_add()` and `on_poll_vote_remove()` this is called regardless of the state of the internal user and message cache.

  This requires `Intents.message_content` and `Intents.polls` to be enabled.

  Note

  If the poll allows multiple answers and the user removes or adds multiple votes, this event will be called as many times as votes that are added or removed.

  Added in version 2.4.

  Parameters:

    payload (`RawPollVoteActionEvent`) – The raw event payload data.

### Reactions

discord.on_reaction_add(reaction, user)

  Called when a message has a reaction added to it. Similar to `on_message_edit()`, if the message is not found in the internal message cache, then this event will not be called. Consider using `on_raw_reaction_add()` instead.

  Note

  To get the `Message` being reacted, access it via `Reaction.message`.

  This requires `Intents.reactions` to be enabled.

  Note

  This doesn’t require `Intents.members` within a guild context, but due to Discord not providing updated user information in a direct message it’s required for direct messages to receive this event. Consider using `on_raw_reaction_add()` if you need this and do not otherwise want to enable the members intent.

  Warning

  This event does not have a way of differentiating whether a reaction is a burst reaction (also known as “super reaction”) or not. If you need this, consider using `on_raw_reaction_add()` instead.

  Parameters:

    - reaction (`Reaction`) – The current state of the reaction.

    - user (Union[`Member`, `User`]) – The user who added the reaction.

discord.on_reaction_remove(reaction, user)

  Called when a message has a reaction removed from it. Similar to on_message_edit, if the message is not found in the internal message cache, then this event will not be called.

  Note

  To get the message being reacted, access it via `Reaction.message`.

  This requires both `Intents.reactions` and `Intents.members` to be enabled.

  Note

  Consider using `on_raw_reaction_remove()` if you need this and do not want to enable the members intent.

  Warning

  This event does not have a way of differentiating whether a reaction is a burst reaction (also known as “super reaction”) or not. If you need this, consider using `on_raw_reaction_remove()` instead.

  Parameters:

    - reaction (`Reaction`) – The current state of the reaction.

    - user (Union[`Member`, `User`]) – The user whose reaction was removed.

discord.on_reaction_clear(message, reactions)

  Called when a message has all its reactions removed from it. Similar to `on_message_edit()`, if the message is not found in the internal message cache, then this event will not be called. Consider using `on_raw_reaction_clear()` instead.

  This requires `Intents.reactions` to be enabled.

  Parameters:

    - message (`Message`) – The message that had its reactions cleared.

    - reactions (List[`Reaction`]) – The reactions that were removed.

discord.on_reaction_clear_emoji(reaction)

  Called when a message has a specific reaction removed from it. Similar to `on_message_edit()`, if the message is not found in the internal message cache, then this event will not be called. Consider using `on_raw_reaction_clear_emoji()` instead.

  This requires `Intents.reactions` to be enabled.

  Added in version 1.3.

  Parameters:

    reaction (`Reaction`) – The reaction that got cleared.

discord.on_raw_reaction_add(payload)

  Called when a message has a reaction added. Unlike `on_reaction_add()`, this is called regardless of the state of the internal message cache.

  This requires `Intents.reactions` to be enabled.

  Parameters:

    payload (`RawReactionActionEvent`) – The raw event payload data.

discord.on_raw_reaction_remove(payload)

  Called when a message has a reaction removed. Unlike `on_reaction_remove()`, this is called regardless of the state of the internal message cache.

  This requires `Intents.reactions` to be enabled.

  Parameters:

    payload (`RawReactionActionEvent`) – The raw event payload data.

discord.on_raw_reaction_clear(payload)

  Called when a message has all its reactions removed. Unlike `on_reaction_clear()`, this is called regardless of the state of the internal message cache.

  This requires `Intents.reactions` to be enabled.

  Parameters:

    payload (`RawReactionClearEvent`) – The raw event payload data.

discord.on_raw_reaction_clear_emoji(payload)

  Called when a message has a specific reaction removed from it. Unlike `on_reaction_clear_emoji()` this is called regardless of the state of the internal message cache.

  This requires `Intents.reactions` to be enabled.

  Added in version 1.3.

  Parameters:

    payload (`RawReactionClearEmojiEvent`) – The raw event payload data.

### Roles

discord.on_guild_role_create(role)
discord.on_guild_role_delete(role)

  Called when a `Guild` creates or deletes a new `Role`.

  To get the guild it belongs to, use `Role.guild`.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    role (`Role`) – The role that was created or deleted.

discord.on_guild_role_update(before, after)

  Called when a `Role` is changed guild-wide.

  This requires `Intents.guilds` to be enabled.

  Parameters:

    - before (`Role`) – The updated role’s old info.

    - after (`Role`) – The updated role’s updated info.

### Scheduled Events

discord.on_scheduled_event_create(event)
discord.on_scheduled_event_delete(event)

  Called when a `ScheduledEvent` is created or deleted.

  This requires `Intents.guild_scheduled_events` to be enabled.

  Added in version 2.0.

  Parameters:

    event (`ScheduledEvent`) – The scheduled event that was created or deleted.

discord.on_scheduled_event_update(before, after)

  Called when a `ScheduledEvent` is updated.

  This requires `Intents.guild_scheduled_events` to be enabled.

  The following, but not limited to, examples illustrate when this event is called:

  - The scheduled start/end times are changed.

  - The channel is changed.

  - The description is changed.

  - The status is changed.

  - The image is changed.

  Added in version 2.0.

  Parameters:

    - before (`ScheduledEvent`) – The scheduled event before the update.

    - after (`ScheduledEvent`) – The scheduled event after the update.

discord.on_scheduled_event_user_add(event, user)
discord.on_scheduled_event_user_remove(event, user)

  Called when a user is added or removed from a `ScheduledEvent`.

  This requires `Intents.guild_scheduled_events` to be enabled.

  Added in version 2.0.

  Parameters:

    - event (`ScheduledEvent`) – The scheduled event that the user was added or removed from.

    - user (`User`) – The user that was added or removed.

### Soundboard

discord.on_soundboard_sound_create(sound)
discord.on_soundboard_sound_delete(sound)

  Called when a `SoundboardSound` is created or deleted.

  Added in version 2.5.

  Parameters:

    sound (`SoundboardSound`) – The soundboard sound that was created or deleted.

discord.on_soundboard_sound_update(before, after)

  Called when a `SoundboardSound` is updated.

  The following examples illustrate when this event is called:

  - The name is changed.

  - The emoji is changed.

  - The volume is changed.

  Added in version 2.5.

  Parameters:

    sound (`SoundboardSound`) – The soundboard sound that was updated.

### Stages

discord.on_stage_instance_create(stage_instance)
discord.on_stage_instance_delete(stage_instance)

  Called when a `StageInstance` is created or deleted for a `StageChannel`.

  Added in version 2.0.

  Parameters:

    stage_instance (`StageInstance`) – The stage instance that was created or deleted.

discord.on_stage_instance_update(before, after)

  Called when a `StageInstance` is updated.

  The following, but not limited to, examples illustrate when this event is called:

  - The topic is changed.

  - The privacy level is changed.

  Added in version 2.0.

  Parameters:

    - before (`StageInstance`) – The stage instance before the update.

    - after (`StageInstance`) – The stage instance after the update.

### Subscriptions

discord.on_subscription_create(subscription)

  Called when a subscription is created.

  Added in version 2.5.

  Parameters:

    subscription (`Subscription`) – The subscription that was created.

discord.on_subscription_update(subscription)

  Called when a subscription is updated.

  Added in version 2.5.

  Parameters:

    subscription (`Subscription`) – The subscription that was updated.

discord.on_subscription_delete(subscription)

  Called when a subscription is deleted.

  Added in version 2.5.

  Parameters:

    subscription (`Subscription`) – The subscription that was deleted.

### Threads

discord.on_thread_create(thread)

  Called whenever a thread is created.

  Note that you can get the guild from `Thread.guild`.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    thread (`Thread`) – The thread that was created.

discord.on_thread_join(thread)

  Called whenever a thread is joined.

  Note that you can get the guild from `Thread.guild`.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    thread (`Thread`) – The thread that got joined.

discord.on_thread_update(before, after)

  Called whenever a thread is updated. If the thread could not be found in the internal cache this event will not be called. Threads will not be in the cache if they are archived.

  If you need this information use `on_raw_thread_update()` instead.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    - before (`Thread`) – The updated thread’s old info.

    - after (`Thread`) – The updated thread’s new info.

discord.on_thread_remove(thread)

  Called whenever a thread is removed. This is different from a thread being deleted.

  Note that you can get the guild from `Thread.guild`.

  This requires `Intents.guilds` to be enabled.

  Warning

  Due to technical limitations, this event might not be called as soon as one expects. Since the library tracks thread membership locally, the API only sends updated thread membership status upon being synced by joining a thread.

  Added in version 2.0.

  Parameters:

    thread (`Thread`) – The thread that got removed.

discord.on_thread_delete(thread)

  Called whenever a thread is deleted. If the thread could not be found in the internal cache this event will not be called. Threads will not be in the cache if they are archived.

  If you need this information use `on_raw_thread_delete()` instead.

  Note that you can get the guild from `Thread.guild`.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    thread (`Thread`) – The thread that got deleted.

discord.on_raw_thread_update(payload)

  Called whenever a thread is updated. Unlike `on_thread_update()` this is called regardless of the thread being in the internal thread cache or not.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawThreadUpdateEvent`) – The raw event payload data.

discord.on_raw_thread_delete(payload)

  Called whenever a thread is deleted. Unlike `on_thread_delete()` this is called regardless of the thread being in the internal thread cache or not.

  This requires `Intents.guilds` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawThreadDeleteEvent`) – The raw event payload data.

discord.on_thread_member_join(member)
discord.on_thread_member_remove(member)

  Called when a `ThreadMember` leaves or joins a `Thread`.

  You can get the thread a member belongs in by accessing `ThreadMember.thread`.

  This requires `Intents.members` to be enabled.

  Added in version 2.0.

  Parameters:

    member (`ThreadMember`) – The member who joined or left.

discord.on_raw_thread_member_remove(payload)

  Called when a `ThreadMember` leaves a `Thread`. Unlike `on_thread_member_remove()` this is called regardless of the member being in the internal thread’s members cache or not.

  This requires `Intents.members` to be enabled.

  Added in version 2.0.

  Parameters:

    payload (`RawThreadMembersUpdate`) – The raw event payload data.

### Voice

discord.on_voice_state_update(member, before, after)

  Called when a `Member` changes their `VoiceState`.

  The following, but not limited to, examples illustrate when this event is called:

  - A member joins a voice or stage channel.

  - A member leaves a voice or stage channel.

  - A member is muted or deafened by their own accord.

  - A member is muted or deafened by a guild administrator.

  This requires `Intents.voice_states` to be enabled.

  Parameters:

    - member (`Member`) – The member whose voice states changed.

    - before (`VoiceState`) – The voice state prior to the changes.

    - after (`VoiceState`) – The voice state after the changes.

discord.on_voice_channel_effect(effect)

  Called when a `Member` sends a `VoiceChannelEffect` in a voice channel the bot is in.

  This requires `Intents.voice_states` to be enabled.

  Added in version 2.5.

  Parameters:

    effect (`VoiceChannelEffect`) – The effect that is sent.

## Utility Functions

discord.utils.find(predicate, iterable, /)

  A helper to return the first element found in the sequence that meets the predicate. For example:

      member = discord.utils.find(lambda m: m.name == 'Mighty', channel.guild.members)

  would find the first `Member` whose name is ‘Mighty’ and return it. If an entry is not found, then `None` is returned.

  This is different from `py:filter()` due to the fact it stops the moment it finds a valid entry.

  Changed in version 2.0: Both parameters are now positional-only.

  Changed in version 2.0: The `iterable` parameter supports asynchronous iterables.

  Parameters:

    - predicate – A function that returns a boolean-like result.

    - iterable (Union[`collections.abc.Iterable`, `collections.abc.AsyncIterable`]) – The iterable to search through. Using a `collections.abc.AsyncIterable`, makes this function return a coroutine.

discord.utils.get(iterable, /, **attrs)

  A helper that returns the first element in the iterable that meets all the traits passed in `attrs`. This is an alternative for `find()`.

  When multiple attributes are specified, they are checked using logical AND, not logical OR. Meaning they have to meet every attribute passed in and not one of them.

  To have a nested attribute search (i.e. search by `x.y`) then pass in `x__y` as the keyword argument.

  If nothing is found that matches the attributes passed, then `None` is returned.

  Changed in version 2.0: The `iterable` parameter is now positional-only.

  Changed in version 2.0: The `iterable` parameter supports asynchronous iterables.

  Examples

  Basic usage:

      member = discord.utils.get(message.guild.members, name='Foo')

  Multiple attribute matching:

      channel = discord.utils.get(guild.voice_channels, name='Foo', bitrate=64000)

  Nested attribute matching:

      channel = discord.utils.get(client.get_all_channels(), guild__name='Cool', name='general')

  Async iterables:

      msg = await discord.utils.get(channel.history(), author__name='Dave')

  Parameters:

    - iterable (Union[`collections.abc.Iterable`, `collections.abc.AsyncIterable`]) – The iterable to search through. Using a `collections.abc.AsyncIterable`, makes this function return a coroutine.

    - **attrs – Keyword arguments that denote attributes to search with.

discord.utils.setup_logging(*, handler=..., formatter=..., level=..., root=True)

  A helper function to setup logging.

  This is superficially similar to `logging.basicConfig()` but uses different defaults and a colour formatter if the stream can display colour.

  This is used by the `Client` to set up logging if `log_handler` is not `None`.

  Added in version 2.0.

  Parameters:

    - handler (`logging.Handler`) –

      The log handler to use for the library’s logger.

      The default log handler if not provided is `logging.StreamHandler`.

    - formatter (`logging.Formatter`) – The formatter to use with the given log handler. If not provided then it defaults to a colour based logging formatter (if available). If colour is not available then a simple logging formatter is provided.

    - level (`int`) – The default log level for the library’s logger. Defaults to `logging.INFO`.

    - root (`bool`) – Whether to set up the root logger rather than the library logger. Unlike the default for `Client`, this defaults to `True`.

await discord.utils.maybe_coroutine(f, *args, **kwargs)

  This function is a coroutine.

  A helper function that will await the result of a function if it’s a coroutine or return the result if it’s not.

  This is useful for functions that may or may not be coroutines.

  Added in version 2.2.

  Parameters:

    - f (Callable[..., Any]) – The function or coroutine to call.

    - *args – The arguments to pass to the function.

    - **kwargs – The keyword arguments to pass to the function.

  Returns:

    The result of the function or coroutine.

  Return type:

    Any

discord.utils.snowflake_time(id, /)

  Returns the creation time of the given snowflake.

  Changed in version 2.0: The `id` parameter is now positional-only.

  Parameters:

    id (`int`) – The snowflake ID.

  Returns:

    An aware datetime in UTC representing the creation time of the snowflake.

  Return type:

    `datetime.datetime`

discord.utils.time_snowflake(dt, /, *, high=False)

  Returns a numeric snowflake pretending to be created at the given date.

  When using as the lower end of a range, use `time_snowflake(dt, high=False) - 1` to be inclusive, `high=True` to be exclusive.

  When using as the higher end of a range, use `time_snowflake(dt, high=True) + 1` to be inclusive, `high=False` to be exclusive.

  Changed in version 2.0: The `high` parameter is now keyword-only and the `dt` parameter is now positional-only.

  Parameters:

    - dt (`datetime.datetime`) – A datetime object to convert to a snowflake. If naive, the timezone is assumed to be local time.

    - high (`bool`) – Whether or not to set the lower 22 bit to high or low.

  Returns:

    The snowflake representing the time given.

  Return type:

    `int`

discord.utils.oauth_url(client_id, *, permissions=..., guild=..., redirect_uri=..., scopes=..., disable_guild_select=False, state=...)

  A helper function that returns the OAuth2 URL for inviting the bot into guilds.

  Changed in version 2.0: `permissions`, `guild`, `redirect_uri`, `scopes` and `state` parameters are now keyword-only.

  Parameters:

    - client_id (Union[`int`, `str`]) – The client ID for your bot.

    - permissions (`Permissions`) – The permissions you’re requesting. If not given then you won’t be requesting any permissions.

    - guild (`Snowflake`) – The guild to pre-select in the authorization screen, if available.

    - redirect_uri (`str`) – An optional valid redirect URI.

    - scopes (Iterable[`str`]) –

      An optional valid list of scopes. Defaults to `('bot', 'applications.commands')`.

      Added in version 1.7.

    - disable_guild_select (`bool`) –

      Whether to disallow the user from changing the guild dropdown.

      Added in version 2.0.

    - state (`str`) –

      The state to return after the authorization.

      Added in version 2.0.

  Returns:

    The OAuth2 URL for inviting the bot into guilds.

  Return type:

    `str`

discord.utils.remove_markdown(text, *, ignore_links=True)

  A helper function that removes markdown characters.

  Added in version 1.7.

  Note

  This function is not markdown aware and may remove meaning from the original text. For example, if the input contains `10 * 5` then it will be converted into `10 5`.

  Parameters:

    - text (`str`) – The text to remove markdown from.

    - ignore_links (`bool`) – Whether to leave links alone when removing markdown. For example, if a URL in the text contains characters such as `_` then it will be left alone. Defaults to `True`.

  Returns:

    The text with the markdown special characters removed.

  Return type:

    `str`

discord.utils.escape_markdown(text, *, as_needed=False, ignore_links=True)

  A helper function that escapes Discord’s markdown.

  Parameters:

    - text (`str`) – The text to escape markdown from.

    - as_needed (`bool`) – Whether to escape the markdown characters as needed. This means that it does not escape extraneous characters if it’s not necessary, e.g. `**hello**` is escaped into `\*\*hello**` instead of `\*\*hello\*\*`. Note however that this can open you up to some clever syntax abuse. Defaults to `False`.

    - ignore_links (`bool`) – Whether to leave links alone when escaping markdown. For example, if a URL in the text contains characters such as `_` then it will be left alone. This option is not supported with `as_needed`. Defaults to `True`.

  Returns:

    The text with the markdown special characters escaped with a slash.

  Return type:

    `str`

discord.utils.escape_mentions(text)

  A helper function that escapes everyone, here, role, and user mentions.

  Note

  This does not include channel mentions.

  Note

  For more granular control over what mentions should be escaped within messages, refer to the `AllowedMentions` class.

  Parameters:

    text (`str`) – The text to escape mentions from.

  Returns:

    The text with the mentions removed.

  Return type:

    `str`

class discord.ResolvedInvite

  A data class which represents a resolved invite returned from `discord.utils.resolve_invite()`.

  code

    The invite code.

    Type:

      `str`

  event

    The id of the scheduled event that the invite refers to.

    Type:

      Optional[`int`]

discord.utils.resolve_invite(invite)

  Resolves an invite from a `Invite`, URL or code.

  Changed in version 2.0: Now returns a `ResolvedInvite` instead of a `str`.

  Parameters:

    invite (Union[`Invite`, `str`]) – The invite.

  Raises:

    ValueError – The invite is not a valid Discord invite, e.g. is not a URL or does not contain alphanumeric characters.

  Returns:

    A data class containing the invite code and the event ID.

  Return type:

    `ResolvedInvite`

discord.utils.resolve_template(code)

  Resolves a template code from a `Template`, URL or code.

  Added in version 1.4.

  Parameters:

    code (Union[`Template`, `str`]) – The code.

  Returns:

    The template code.

  Return type:

    `str`

await discord.utils.sleep_until(when, result=None)

  This function is a coroutine.

  Sleep until a specified time.

  If the time supplied is in the past this function will yield instantly.

  Added in version 1.3.

  Parameters:

    - when (`datetime.datetime`) – The timestamp in which to sleep until. If the datetime is naive then it is assumed to be local time.

    - result (Any) – If provided is returned to the caller when the coroutine completes.

discord.utils.utcnow()

  A helper function to return an aware UTC datetime representing the current time.

  This should be preferred to `datetime.datetime.utcnow()` since it is an aware datetime, compared to the naive datetime in the standard library.

  Added in version 2.0.

  Returns:

    The current aware datetime in UTC.

  Return type:

    `datetime.datetime`

discord.utils.format_dt(dt, /, style=None)

  A helper function to format a `datetime.datetime` for presentation within Discord.

  This allows for a locale-independent way of presenting data using Discord specific Markdown.

  Style | Example Output | Description
  --- | --- | ---
  t | 22:57 | Short Time
  T | 22:57:58 | Long Time
  d | 17/05/2016 | Short Date
  D | 17 May 2016 | Long Date
  f (default) | 17 May 2016 22:57 | Short Date Time
  F | Tuesday, 17 May 2016 22:57 | Long Date Time
  R | 5 years ago | Relative Time

  Note that the exact output depends on the user’s locale setting in the client. The example output presented is using the `en-GB` locale.

  Added in version 2.0.

  Parameters:

    - dt (`datetime.datetime`) – The datetime to format.

    - style (`str`) – The style to format the datetime with.

  Returns:

    The formatted string.

  Return type:

    `str`

discord.utils.as_chunks(iterator, max_size)

  A helper function that collects an iterator into chunks of a given size.

  Added in version 2.0.

  Parameters:

    - iterator (Union[`collections.abc.Iterable`, `collections.abc.AsyncIterable`]) – The iterator to chunk, can be sync or async.

    - max_size (`int`) – The maximum chunk size.

  Warning

  The last chunk collected may not be as large as `max_size`.

  Returns:

    A new iterator which yields chunks of a given size.

  Return type:

    Union[`Iterator`, `AsyncIterator`]

discord.utils.MISSING

  A type safe sentinel used in the library to represent something as missing. Used to distinguish from `None` values.

  Added in version 2.0.

## Enumerations

The API provides some enumerations for certain types of strings to avoid the API from being stringly typed in case the strings change in the future.

All enumerations are subclasses of an internal class which mimics the behaviour of `enum.Enum`.

class discord.ChannelType

  Specifies the type of channel.

  text

    A text channel.

  voice

    A voice channel.

  private

    A private text channel. Also called a direct message.

  group

    A private group text channel.

  category

    A category channel.

  news

    A guild news channel.

  stage_voice

    A guild stage voice channel.

    Added in version 1.7.

  news_thread

    A news thread

    Added in version 2.0.

  public_thread

    A public thread

    Added in version 2.0.

  private_thread

    A private thread

    Added in version 2.0.

  forum

    A forum channel.

    Added in version 2.0.

  media

    A media channel.

    Added in version 2.4.

class discord.MessageType

  Specifies the type of `Message`. This is used to denote if a message is to be interpreted as a system message or a regular message.

  x == y

    Checks if two messages are equal.

  x != y

    Checks if two messages are not equal.

  default

    The default message type. This is the same as regular messages.

  recipient_add

    The system message when a user is added to a group private message or a thread.

  recipient_remove

    The system message when a user is removed from a group private message or a thread.

  call

    The system message denoting call state, e.g. missed call, started call, etc.

  channel_name_change

    The system message denoting that a channel’s name has been changed.

  channel_icon_change

    The system message denoting that a channel’s icon has been changed.

  pins_add

    The system message denoting that a pinned message has been added to a channel.

  new_member

    The system message denoting that a new member has joined a Guild.

  premium_guild_subscription

    The system message denoting that a member has “nitro boosted” a guild.

  premium_guild_tier_1

    The system message denoting that a member has “nitro boosted” a guild and it achieved level 1.

  premium_guild_tier_2

    The system message denoting that a member has “nitro boosted” a guild and it achieved level 2.

  premium_guild_tier_3

    The system message denoting that a member has “nitro boosted” a guild and it achieved level 3.

  channel_follow_add

    The system message denoting that an announcement channel has been followed.

    Added in version 1.3.

  guild_stream

    The system message denoting that a member is streaming in the guild.

    Added in version 1.7.

  guild_discovery_disqualified

    The system message denoting that the guild is no longer eligible for Server Discovery.

    Added in version 1.7.

  guild_discovery_requalified

    The system message denoting that the guild has become eligible again for Server Discovery.

    Added in version 1.7.

  guild_discovery_grace_period_initial_warning

    The system message denoting that the guild has failed to meet the Server Discovery requirements for one week.

    Added in version 1.7.

  guild_discovery_grace_period_final_warning

    The system message denoting that the guild has failed to meet the Server Discovery requirements for 3 weeks in a row.

    Added in version 1.7.

  thread_created

    The system message denoting that a thread has been created. This is only sent if the thread has been created from an older message. The period of time required for a message to be considered old cannot be relied upon and is up to Discord.

    Added in version 2.0.

  reply

    The system message denoting that the author is replying to a message.

    Added in version 2.0.

  chat_input_command

    The system message denoting that a slash command was executed.

    Added in version 2.0.

  guild_invite_reminder

    The system message sent as a reminder to invite people to the guild.

    Added in version 2.0.

  thread_starter_message

    The system message denoting the message in the thread that is the one that started the thread’s conversation topic.

    Added in version 2.0.

  context_menu_command

    The system message denoting that a context menu command was executed.

    Added in version 2.0.

  auto_moderation_action

    The system message sent when an AutoMod rule is triggered. This is only sent if the rule is configured to sent an alert when triggered.

    Added in version 2.0.

  role_subscription_purchase

    The system message sent when a user purchases or renews a role subscription.

    Added in version 2.2.

  interaction_premium_upsell

    The system message sent when a user is given an advertisement to purchase a premium tier for an application during an interaction.

    Added in version 2.2.

  stage_start

    The system message sent when the stage starts.

    Added in version 2.2.

  stage_end

    The system message sent when the stage ends.

    Added in version 2.2.

  stage_speaker

    The system message sent when the stage speaker changes.

    Added in version 2.2.

  stage_raise_hand

    The system message sent when a user is requesting to speak by raising their hands.

    Added in version 2.2.

  stage_topic

    The system message sent when the stage topic changes.

    Added in version 2.2.

  guild_application_premium_subscription

    The system message sent when an application’s premium subscription is purchased for the guild.

    Added in version 2.2.

  guild_incident_alert_mode_enabled

    The system message sent when security actions is enabled.

    Added in version 2.4.

  guild_incident_alert_mode_disabled

    The system message sent when security actions is disabled.

    Added in version 2.4.

  guild_incident_report_raid

    The system message sent when a raid is reported.

    Added in version 2.4.

  guild_incident_report_false_alarm

    The system message sent when a false alarm is reported.

    Added in version 2.4.

  purchase_notification

    The system message sent when a purchase is made in the guild.

    Added in version 2.5.

  poll_result

    The system message sent when a poll has closed.

class discord.UserFlags

  Represents Discord User flags.

  staff

    The user is a Discord Employee.

  partner

    The user is a Discord Partner.

  hypesquad

    The user is a HypeSquad Events member.

  bug_hunter

    The user is a Bug Hunter.

  mfa_sms

    The user has SMS recovery for Multi Factor Authentication enabled.

  premium_promo_dismissed

    The user has dismissed the Discord Nitro promotion.

  hypesquad_bravery

    The user is a HypeSquad Bravery member.

  hypesquad_brilliance

    The user is a HypeSquad Brilliance member.

  hypesquad_balance

    The user is a HypeSquad Balance member.

  early_supporter

    The user is an Early Supporter.

  team_user

    The user is a Team User.

  system

    The user is a system user (i.e. represents Discord officially).

  has_unread_urgent_messages

    The user has an unread system message.

  bug_hunter_level_2

    The user is a Bug Hunter Level 2.

  verified_bot

    The user is a Verified Bot.

  verified_bot_developer

    The user is an Early Verified Bot Developer.

  discord_certified_moderator

    The user is a Moderator Programs Alumni.

  bot_http_interactions

    The user is a bot that only uses HTTP interactions and is shown in the online member list.

    Added in version 2.0.

  spammer

    The user is flagged as a spammer by Discord.

    Added in version 2.0.

  active_developer

    The user is an active developer.

    Added in version 2.1.

class discord.ActivityType

  Specifies the type of `Activity`. This is used to check how to interpret the activity itself.

  unknown

    An unknown activity type. This should generally not happen.

  playing

    A “Playing” activity type.

  streaming

    A “Streaming” activity type.

  listening

    A “Listening” activity type.

  watching

    A “Watching” activity type.

  custom

    A custom activity type.

  competing

    A competing activity type.

    Added in version 1.5.

class discord.VerificationLevel

  Specifies a `Guild`'s verification level, which is the criteria in which a member must meet before being able to send messages to the guild.

  Added in version 2.0.

  x == y

    Checks if two verification levels are equal.

  x != y

    Checks if two verification levels are not equal.

  x > y

    Checks if a verification level is higher than another.

  x < y

    Checks if a verification level is lower than another.

  x >= y

    Checks if a verification level is higher or equal to another.

  x <= y

    Checks if a verification level is lower or equal to another.

  none

    No criteria set.

  low

    Member must have a verified email on their Discord account.

  medium

    Member must have a verified email and be registered on Discord for more than five minutes.

  high

    Member must have a verified email, be registered on Discord for more than five minutes, and be a member of the guild itself for more than ten minutes.

  highest

    Member must have a verified phone on their Discord account.

class discord.NotificationLevel

  Specifies whether a `Guild` has notifications on for all messages or mentions only by default.

  Added in version 2.0.

  x == y

    Checks if two notification levels are equal.

  x != y

    Checks if two notification levels are not equal.

  x > y

    Checks if a notification level is higher than another.

  x < y

    Checks if a notification level is lower than another.

  x >= y

    Checks if a notification level is higher or equal to another.

  x <= y

    Checks if a notification level is lower or equal to another.

  all_messages

    Members receive notifications for every message regardless of them being mentioned.

  only_mentions

    Members receive notifications for messages they are mentioned in.

class discord.ContentFilter

  Specifies a `Guild`'s explicit content filter, which is the machine learning algorithms that Discord uses to detect if an image contains pornography or otherwise explicit content.

  Added in version 2.0.

  x == y

    Checks if two content filter levels are equal.

  x != y

    Checks if two content filter levels are not equal.

  x > y

    Checks if a content filter level is higher than another.

  x < y

    Checks if a content filter level is lower than another.

  x >= y

    Checks if a content filter level is higher or equal to another.

  x <= y

    Checks if a content filter level is lower or equal to another.

  disabled

    The guild does not have the content filter enabled.

  no_role

    The guild has the content filter enabled for members without a role.

  all_members

    The guild has the content filter enabled for every member.

class discord.Status

  Specifies a `Member` ‘s status.

  online

    The member is online.

  offline

    The member is offline.

  idle

    The member is idle.

  dnd

    The member is “Do Not Disturb”.

  do_not_disturb

    An alias for `dnd`.

  invisible

    The member is “invisible”. In reality, this is only used when sending a presence a la `Client.change_presence()`. When you receive a user’s presence this will be `offline` instead.

class discord.AuditLogAction

  Represents the type of action being done for a `AuditLogEntry`, which is retrievable via `Guild.audit_logs()`.

  guild_update

    The guild has updated. Things that trigger this include:

    - Changing the guild vanity URL

    - Changing the guild invite splash

    - Changing the guild AFK channel or timeout

    - Changing the guild voice server region

    - Changing the guild icon, banner, or discovery splash

    - Changing the guild moderation settings

    - Changing things related to the guild widget

    When this is the action, the type of `target` is the `Guild`.

    Possible attributes for `AuditLogDiff`:

    - `afk_channel`

    - `system_channel`

    - `afk_timeout`

    - `default_notifications`

    - `explicit_content_filter`

    - `mfa_level`

    - `name`

    - `owner`

    - `splash`

    - `discovery_splash`

    - `icon`

    - `banner`

    - `vanity_url_code`

    - `description`

    - `preferred_locale`

    - `prune_delete_days`

    - `public_updates_channel`

    - `rules_channel`

    - `verification_level`

    - `widget_channel`

    - `widget_enabled`

    - `premium_progress_bar_enabled`

    - `system_channel_flags`

  channel_create

    A new channel was created.

    When this is the action, the type of `target` is either a `abc.GuildChannel` or `Object` with an ID.

    A more filled out object in the `Object` case can be found by using `after`.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `type`

    - `overwrites`

  channel_update

    A channel was updated. Things that trigger this include:

    - The channel name or topic was changed

    - The channel bitrate was changed

    When this is the action, the type of `target` is the `abc.GuildChannel` or `Object` with an ID.

    A more filled out object in the `Object` case can be found by using `after` or `before`.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `type`

    - `position`

    - `overwrites`

    - `topic`

    - `bitrate`

    - `rtc_region`

    - `video_quality_mode`

    - `default_auto_archive_duration`

    - `nsfw`

    - `slowmode_delay`

    - `user_limit`

  channel_delete

    A channel was deleted.

    When this is the action, the type of `target` is an `Object` with an ID.

    A more filled out object can be found by using the `before` object.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `type`

    - `overwrites`

    - `flags`

    - `nsfw`

    - `slowmode_delay`

  overwrite_create

    A channel permission overwrite was created.

    When this is the action, the type of `target` is the `abc.GuildChannel` or `Object` with an ID.

    When this is the action, the type of `extra` is either a `Role` or `Member`. If the object is not found then it is a `Object` with an ID being filled, a name, and a `type` attribute set to either `'role'` or `'member'` to help dictate what type of ID it is.

    Possible attributes for `AuditLogDiff`:

    - `deny`

    - `allow`

    - `id`

    - `type`

  overwrite_update

    A channel permission overwrite was changed, this is typically when the permission values change.

    See `overwrite_create` for more information on how the `target` and `extra` fields are set.

    Possible attributes for `AuditLogDiff`:

    - `deny`

    - `allow`

    - `id`

    - `type`

  overwrite_delete

    A channel permission overwrite was deleted.

    See `overwrite_create` for more information on how the `target` and `extra` fields are set.

    Possible attributes for `AuditLogDiff`:

    - `deny`

    - `allow`

    - `id`

    - `type`

  kick

    A member was kicked.

    When this is the action, the type of `target` is the `User` or `Object` who got kicked.

    When this is the action, the type of `extra` is set to an unspecified proxy object with one attribute:

    - `integration_type`: An optional string that denotes the type of integration that did the action.

    When this is the action, `changes` is empty.

  member_prune

    A member prune was triggered.

    When this is the action, the type of `target` is set to `None`.

    When this is the action, the type of `extra` is set to an unspecified proxy object with two attributes:

    - `delete_member_days`: An integer specifying how far the prune was.

    - `members_removed`: An integer specifying how many members were removed.

    When this is the action, `changes` is empty.

  ban

    A member was banned.

    When this is the action, the type of `target` is the `User` or `Object` who got banned.

    When this is the action, `changes` is empty.

  unban

    A member was unbanned.

    When this is the action, the type of `target` is the `User` or `Object` who got unbanned.

    When this is the action, `changes` is empty.

  member_update

    A member has updated. This triggers in the following situations:

    - A nickname was changed

    - They were server muted or deafened (or it was undo’d)

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` who got updated.

    Possible attributes for `AuditLogDiff`:

    - `nick`

    - `mute`

    - `deaf`

    - `timed_out_until`

  member_role_update

    A member’s role has been updated. This triggers when a member either gains a role or loses a role.

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` who got the role.

    When this is the action, the type of `extra` is set to an unspecified proxy object with one attribute:

    - `integration_type`: An optional string that denotes the type of integration that did the action.

    Possible attributes for `AuditLogDiff`:

    - `roles`

  member_move

    A member’s voice channel has been updated. This triggers when a member is moved to a different voice channel.

    When this is the action, the type of `extra` is set to an unspecified proxy object with two attributes:

    - `channel`: A `TextChannel` or `Object` with the channel ID where the members were moved.

    - `count`: An integer specifying how many members were moved.

    Added in version 1.3.

  member_disconnect

    A member’s voice state has changed. This triggers when a member is force disconnected from voice.

    When this is the action, the type of `extra` is set to an unspecified proxy object with one attribute:

    - `count`: An integer specifying how many members were disconnected.

    Added in version 1.3.

  bot_add

    A bot was added to the guild.

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` which was added to the guild.

    Added in version 1.3.

  role_create

    A new role was created.

    When this is the action, the type of `target` is the `Role` or a `Object` with the ID.

    Possible attributes for `AuditLogDiff`:

    - `colour`

    - `mentionable`

    - `hoist`

    - `icon`

    - `unicode_emoji`

    - `name`

    - `permissions`

  role_update

    A role was updated. This triggers in the following situations:

    - The name has changed

    - The permissions have changed

    - The colour has changed

    - The role icon (or unicode emoji) has changed

    - Its hoist/mentionable state has changed

    When this is the action, the type of `target` is the `Role` or a `Object` with the ID.

    Possible attributes for `AuditLogDiff`:

    - `colour`

    - `mentionable`

    - `hoist`

    - `icon`

    - `unicode_emoji`

    - `name`

    - `permissions`

  role_delete

    A role was deleted.

    When this is the action, the type of `target` is the `Role` or a `Object` with the ID.

    Possible attributes for `AuditLogDiff`:

    - `colour`

    - `mentionable`

    - `hoist`

    - `name`

    - `permissions`

  invite_create

    An invite was created.

    When this is the action, the type of `target` is the `Invite` that was created.

    Possible attributes for `AuditLogDiff`:

    - `max_age`

    - `code`

    - `temporary`

    - `inviter`

    - `channel`

    - `uses`

    - `max_uses`

  invite_update

    An invite was updated.

    When this is the action, the type of `target` is the `Invite` that was updated.

  invite_delete

    An invite was deleted.

    When this is the action, the type of `target` is the `Invite` that was deleted.

    Possible attributes for `AuditLogDiff`:

    - `max_age`

    - `code`

    - `temporary`

    - `inviter`

    - `channel`

    - `uses`

    - `max_uses`

  webhook_create

    A webhook was created.

    When this is the action, the type of `target` is the `Object` with the webhook ID.

    Possible attributes for `AuditLogDiff`:

    - `channel`

    - `name`

    - `type` (always set to `1` if so)

  webhook_update

    A webhook was updated. This trigger in the following situations:

    - The webhook name changed

    - The webhook channel changed

    When this is the action, the type of `target` is the `Object` with the webhook ID.

    Possible attributes for `AuditLogDiff`:

    - `channel`

    - `name`

    - `avatar`

  webhook_delete

    A webhook was deleted.

    When this is the action, the type of `target` is the `Object` with the webhook ID.

    Possible attributes for `AuditLogDiff`:

    - `channel`

    - `name`

    - `type` (always set to `1` if so)

  emoji_create

    An emoji was created.

    When this is the action, the type of `target` is the `Emoji` or `Object` with the emoji ID.

    Possible attributes for `AuditLogDiff`:

    - `name`

  emoji_update

    An emoji was updated. This triggers when the name has changed.

    When this is the action, the type of `target` is the `Emoji` or `Object` with the emoji ID.

    Possible attributes for `AuditLogDiff`:

    - `name`

  emoji_delete

    An emoji was deleted.

    When this is the action, the type of `target` is the `Object` with the emoji ID.

    Possible attributes for `AuditLogDiff`:

    - `name`

  message_delete

    A message was deleted by a moderator. Note that this only triggers if the message was deleted by someone other than the author.

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` who had their message deleted.

    When this is the action, the type of `extra` is set to an unspecified proxy object with two attributes:

    - `count`: An integer specifying how many messages were deleted.

    - `channel`: A `TextChannel` or `Object` with the channel ID where the message got deleted.

  message_bulk_delete

    Messages were bulk deleted by a moderator.

    When this is the action, the type of `target` is the `TextChannel` or `Object` with the ID of the channel that was purged.

    When this is the action, the type of `extra` is set to an unspecified proxy object with one attribute:

    - `count`: An integer specifying how many messages were deleted.

    Added in version 1.3.

  message_pin

    A message was pinned in a channel.

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` who had their message pinned.

    When this is the action, the type of `extra` is set to an unspecified proxy object with two attributes:

    - `channel`: A `TextChannel` or `Object` with the channel ID where the message was pinned.

    - `message_id`: the ID of the message which was pinned.

    Added in version 1.3.

  message_unpin

    A message was unpinned in a channel.

    When this is the action, the type of `target` is the `Member`, `User`, or `Object` who had their message unpinned.

    When this is the action, the type of `extra` is set to an unspecified proxy object with two attributes:

    - `channel`: A `TextChannel` or `Object` with the channel ID where the message was unpinned.

    - `message_id`: the ID of the message which was unpinned.

    Added in version 1.3.

  integration_create

    A guild integration was created.

    When this is the action, the type of `target` is a `PartialIntegration` or `Object` with the integration ID of the integration which was created.

    Added in version 1.3.

  integration_update

    A guild integration was updated.

    When this is the action, the type of `target` is a `PartialIntegration` or `Object` with the integration ID of the integration which was updated.

    Added in version 1.3.

  integration_delete

    A guild integration was deleted.

    When this is the action, the type of `target` is a `PartialIntegration` or `Object` with the integration ID of the integration which was deleted.

    Added in version 1.3.

  stage_instance_create

    A stage instance was started.

    When this is the action, the type of `target` is the `StageInstance` or `Object` with the ID of the stage instance which was created.

    Possible attributes for `AuditLogDiff`:

    - `topic`

    - `privacy_level`

    Added in version 2.0.

  stage_instance_update

    A stage instance was updated.

    When this is the action, the type of `target` is the `StageInstance` or `Object` with the ID of the stage instance which was updated.

    Possible attributes for `AuditLogDiff`:

    - `topic`

    - `privacy_level`

    Added in version 2.0.

  stage_instance_delete

    A stage instance was ended.

    Added in version 2.0.

  sticker_create

    A sticker was created.

    When this is the action, the type of `target` is the `GuildSticker` or `Object` with the ID of the sticker which was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `type`

    - `format_type`

    - `description`

    - `available`

    Added in version 2.0.

  sticker_update

    A sticker was updated.

    When this is the action, the type of `target` is the `GuildSticker` or `Object` with the ID of the sticker which was updated.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `type`

    - `format_type`

    - `description`

    - `available`

    Added in version 2.0.

  sticker_delete

    A sticker was deleted.

    When this is the action, the type of `target` is the `GuildSticker` or `Object` with the ID of the sticker which was updated.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `type`

    - `format_type`

    - `description`

    - `available`

    Added in version 2.0.

  scheduled_event_create

    A scheduled event was created.

    When this is the action, the type of `target` is the `ScheduledEvent` or `Object` with the ID of the event which was created.

    Possible attributes for `AuditLogDiff`: - `name` - `channel` - `description` - `privacy_level` - `status` - `entity_type` - `cover_image`

    Added in version 2.0.

  scheduled_event_update

    A scheduled event was created.

    When this is the action, the type of `target` is the `ScheduledEvent` or `Object` with the ID of the event which was updated.

    Possible attributes for `AuditLogDiff`: - `name` - `channel` - `description` - `privacy_level` - `status` - `entity_type` - `cover_image`

    Added in version 2.0.

  scheduled_event_delete

    A scheduled event was created.

    When this is the action, the type of `target` is the `ScheduledEvent` or `Object` with the ID of the event which was deleted.

    Possible attributes for `AuditLogDiff`: - `name` - `channel` - `description` - `privacy_level` - `status` - `entity_type` - `cover_image`

    Added in version 2.0.

  thread_create

    A thread was created.

    When this is the action, the type of `target` is the `Thread` or `Object` with the ID of the thread which was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `archived`

    - `locked`

    - `auto_archive_duration`

    - `invitable`

    Added in version 2.0.

  thread_update

    A thread was updated.

    When this is the action, the type of `target` is the `Thread` or `Object` with the ID of the thread which was updated.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `archived`

    - `locked`

    - `auto_archive_duration`

    - `invitable`

    Added in version 2.0.

  thread_delete

    A thread was deleted.

    When this is the action, the type of `target` is the `Thread` or `Object` with the ID of the thread which was deleted.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `archived`

    - `locked`

    - `auto_archive_duration`

    - `invitable`

    Added in version 2.0.

  app_command_permission_update

    An application command or integrations application command permissions were updated.

    When this is the action, the type of `target` is a `PartialIntegration` for an integrations general permissions, `AppCommand` for a specific commands permissions, or `Object` with the ID of the command or integration which was updated.

    When this is the action, the type of `extra` is set to an `PartialIntegration` or `Object` with the ID of application that command or integration belongs to.

    Possible attributes for `AuditLogDiff`:

    - `app_command_permissions`

    Added in version 2.0.

  automod_rule_create

    An automod rule was created.

    When this is the action, the type of `target` is a `AutoModRule` or `Object` with the ID of the automod rule that was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `enabled`

    - `event_type`

    - `trigger_type`

    - `trigger`

    - `actions`

    - `exempt_roles`

    - `exempt_channels`

    Added in version 2.0.

  automod_rule_update

    An automod rule was updated.

    When this is the action, the type of `target` is a `AutoModRule` or `Object` with the ID of the automod rule that was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `enabled`

    - `event_type`

    - `trigger_type`

    - `trigger`

    - `actions`

    - `exempt_roles`

    - `exempt_channels`

    Added in version 2.0.

  automod_rule_delete

    An automod rule was deleted.

    When this is the action, the type of `target` is a `AutoModRule` or `Object` with the ID of the automod rule that was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `enabled`

    - `event_type`

    - `trigger_type`

    - `trigger`

    - `actions`

    - `exempt_roles`

    - `exempt_channels`

    Added in version 2.0.

  automod_block_message

    An automod rule blocked a message from being sent.

    When this is the action, the type of `target` is a `Member` with the ID of the person who triggered the automod rule.

    When this is the action, the type of `extra` is set to an unspecified proxy object with 3 attributes:

    - `automod_rule_name`: The name of the automod rule that was triggered.

    - `automod_rule_trigger_type`: A `AutoModRuleTriggerType` representation of the rule type that was triggered.

    - `channel`: The channel in which the automod rule was triggered.

    When this is the action, `AuditLogEntry.changes` is empty.

    Added in version 2.0.

  automod_flag_message

    An automod rule flagged a message.

    When this is the action, the type of `target` is a `Member` with the ID of the person who triggered the automod rule.

    When this is the action, the type of `extra` is set to an unspecified proxy object with 3 attributes:

    - `automod_rule_name`: The name of the automod rule that was triggered.

    - `automod_rule_trigger_type`: A `AutoModRuleTriggerType` representation of the rule type that was triggered.

    - `channel`: The channel in which the automod rule was triggered.

    When this is the action, `AuditLogEntry.changes` is empty.

    Added in version 2.1.

  automod_timeout_member

    An automod rule timed-out a member.

    When this is the action, the type of `target` is a `Member` with the ID of the person who triggered the automod rule.

    When this is the action, the type of `extra` is set to an unspecified proxy object with 3 attributes:

    - `automod_rule_name`: The name of the automod rule that was triggered.

    - `automod_rule_trigger_type`: A `AutoModRuleTriggerType` representation of the rule type that was triggered.

    - `channel`: The channel in which the automod rule was triggered.

    When this is the action, `AuditLogEntry.changes` is empty.

    Added in version 2.1.

  creator_monetization_request_created

    A request to monetize the server was created.

    Added in version 2.4.

  creator_monetization_terms_accepted

    The terms and conditions for creator monetization were accepted.

    Added in version 2.4.

  soundboard_sound_create

    A soundboard sound was created.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `volume`

    Added in version 2.5.

  soundboard_sound_update

    A soundboard sound was updated.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `volume`

    Added in version 2.5.

  soundboard_sound_delete

    A soundboard sound was deleted.

    Possible attributes for `AuditLogDiff`:

    - `name`

    - `emoji`

    - `volume`

    Added in version 2.5.

class discord.AuditLogActionCategory

  Represents the category that the `AuditLogAction` belongs to.

  This can be retrieved via `AuditLogEntry.category`.

  create

    The action is the creation of something.

  delete

    The action is the deletion of something.

  update

    The action is the update of something.

class discord.TeamMembershipState

  Represents the membership state of a team member retrieved through `Client.application_info()`.

  Added in version 1.3.

  invited

    Represents an invited member.

  accepted

    Represents a member currently in the team.

class discord.TeamMemberRole

  Represents the type of role of a team member retrieved through `Client.application_info()`.

  Added in version 2.4.

  admin

    The team member is an admin. This allows them to invite members to the team, access credentials, edit the application, and do most things the owner can do. However they cannot do destructive actions.

  developer

    The team member is a developer. This allows them to access information, like the client secret or public key. They can also configure interaction endpoints or reset the bot token. Developers cannot invite anyone to the team nor can they do destructive actions.

  read_only

    The team member is a read-only member. This allows them to access information, but not edit anything.

class discord.WebhookType

  Represents the type of webhook that can be received.

  Added in version 1.3.

  incoming

    Represents a webhook that can post messages to channels with a token.

  channel_follower

    Represents a webhook that is internally managed by Discord, used for following channels.

  application

    Represents a webhook that is used for interactions or applications.

    Added in version 2.0.

class discord.ExpireBehaviour

  Represents the behaviour the `Integration` should perform when a user’s subscription has finished.

  There is an alias for this called `ExpireBehavior`.

  Added in version 1.4.

  remove_role

    This will remove the `StreamIntegration.role` from the user when their subscription is finished.

  kick

    This will kick the user when their subscription is finished.

class discord.DefaultAvatar

  Represents the default avatar of a Discord `User`

  blurple

    Represents the default avatar with the colour blurple. See also `Colour.blurple`

  grey

    Represents the default avatar with the colour grey. See also `Colour.greyple`

  gray

    An alias for `grey`.

  green

    Represents the default avatar with the colour green. See also `Colour.green`

  orange

    Represents the default avatar with the colour orange. See also `Colour.orange`

  red

    Represents the default avatar with the colour red. See also `Colour.red`

  pink

    Represents the default avatar with the colour pink. See also `Colour.pink`

    Added in version 2.3.

class discord.StickerType

  Represents the type of sticker.

  Added in version 2.0.

  standard

    Represents a standard sticker that all Nitro users can use.

  guild

    Represents a custom sticker created in a guild.

class discord.StickerFormatType

  Represents the type of sticker images.

  Added in version 1.6.

  png

    Represents a sticker with a png image.

  apng

    Represents a sticker with an apng image.

  lottie

    Represents a sticker with a lottie image.

  gif

    Represents a sticker with a gif image.

    Added in version 2.2.

class discord.InviteTarget

  Represents the invite type for voice channel invites.

  Added in version 2.0.

  unknown

    The invite doesn’t target anyone or anything.

  stream

    A stream invite that targets a user.

  embedded_application

    A stream invite that targets an embedded application.

class discord.VideoQualityMode

  Represents the camera video quality mode for voice channel participants.

  Added in version 2.0.

  auto

    Represents auto camera video quality.

  full

    Represents full camera video quality.

class discord.PrivacyLevel

  Represents the privacy level of a stage instance or scheduled event.

  Added in version 2.0.

  guild_only

    The stage instance or scheduled event is only accessible within the guild.

class discord.NSFWLevel

  Represents the NSFW level of a guild.

  Added in version 2.0.

  x == y

    Checks if two NSFW levels are equal.

  x != y

    Checks if two NSFW levels are not equal.

  x > y

    Checks if a NSFW level is higher than another.

  x < y

    Checks if a NSFW level is lower than another.

  x >= y

    Checks if a NSFW level is higher or equal to another.

  x <= y

    Checks if a NSFW level is lower or equal to another.

  default

    The guild has not been categorised yet.

  explicit

    The guild contains NSFW content.

  safe

    The guild does not contain any NSFW content.

  age_restricted

    The guild may contain NSFW content.

class discord.Locale

  Supported locales by Discord. Mainly used for application command localisation.

  Added in version 2.0.

  american_english

    The `en-US` locale.

  british_english

    The `en-GB` locale.

  bulgarian

    The `bg` locale.

  chinese

    The `zh-CN` locale.

  taiwan_chinese

    The `zh-TW` locale.

  croatian

    The `hr` locale.

  czech

    The `cs` locale.

  indonesian

    The `id` locale.

    Added in version 2.2.

  danish

    The `da` locale.

  dutch

    The `nl` locale.

  finnish

    The `fi` locale.

  french

    The `fr` locale.

  german

    The `de` locale.

  greek

    The `el` locale.

  hindi

    The `hi` locale.

  hungarian

    The `hu` locale.

  italian

    The `it` locale.

  japanese

    The `ja` locale.

  korean

    The `ko` locale.

  latin_american_spanish

    The `es-419` locale.

    Added in version 2.4.

  lithuanian

    The `lt` locale.

  norwegian

    The `no` locale.

  polish

    The `pl` locale.

  brazil_portuguese

    The `pt-BR` locale.

  romanian

    The `ro` locale.

  russian

    The `ru` locale.

  spain_spanish

    The `es-ES` locale.

  swedish

    The `sv-SE` locale.

  thai

    The `th` locale.

  turkish

    The `tr` locale.

  ukrainian

    The `uk` locale.

  vietnamese

    The `vi` locale.

class discord.MFALevel

  Represents the Multi-Factor Authentication requirement level of a guild.

  Added in version 2.0.

  x == y

    Checks if two MFA levels are equal.

  x != y

    Checks if two MFA levels are not equal.

  x > y

    Checks if a MFA level is higher than another.

  x < y

    Checks if a MFA level is lower than another.

  x >= y

    Checks if a MFA level is higher or equal to another.

  x <= y

    Checks if a MFA level is lower or equal to another.

  disabled

    The guild has no MFA requirement.

  require_2fa

    The guild requires 2 factor authentication.

class discord.EntityType

  Represents the type of entity that a scheduled event is for.

  Added in version 2.0.

  stage_instance

    The scheduled event will occur in a stage instance.

  voice

    The scheduled event will occur in a voice channel.

  external

    The scheduled event will occur externally.

class discord.EventStatus

  Represents the status of an event.

  Added in version 2.0.

  scheduled

    The event is scheduled.

  active

    The event is active.

  completed

    The event has ended.

  cancelled

    The event has been cancelled.

  canceled

    An alias for `cancelled`.

  ended

    An alias for `completed`.

class discord.AutoModRuleTriggerType

  Represents the trigger type of an automod rule.

  Added in version 2.0.

  keyword

    The rule will trigger when a keyword is mentioned.

  harmful_link

    The rule will trigger when a harmful link is posted.

  spam

    The rule will trigger when a spam message is posted.

  keyword_preset

    The rule will trigger when something triggers based on the set keyword preset types.

  mention_spam

    The rule will trigger when combined number of role and user mentions is greater than the set limit.

  member_profile

    The rule will trigger when a user’s profile contains a keyword.

    Added in version 2.4.

class discord.AutoModRuleEventType

  Represents the event type of an automod rule.

  Added in version 2.0.

  message_send

    The rule will trigger when a message is sent.

  member_update

    The rule will trigger when a member’s profile is updated.

    Added in version 2.4.

class discord.AutoModRuleActionType

  Represents the action type of an automod rule.

  Added in version 2.0.

  block_message

    The rule will block a message from being sent.

  send_alert_message

    The rule will send an alert message to a predefined channel.

  timeout

    The rule will timeout a user.

  block_member_interactions

    Similar to `timeout`, except the user will be timed out indefinitely. This will request the user to edit it’s profile.

    Added in version 2.4.

class discord.ForumLayoutType

  Represents how a forum’s posts are layed out in the client.

  Added in version 2.2.

  not_set

    No default has been set, so it is up to the client to know how to lay it out.

  list_view

    Displays posts as a list.

  gallery_view

    Displays posts as a collection of tiles.

class discord.ForumOrderType

  Represents how a forum’s posts are sorted in the client.

  Added in version 2.3.

  latest_activity

    Sort forum posts by activity.

  creation_date

    Sort forum posts by creation time (from most recent to oldest).

class discord.SelectDefaultValueType

  Represents the default value of a select menu.

  Added in version 2.4.

  user

    The underlying type of the ID is a user.

  role

    The underlying type of the ID is a role.

  channel

    The underlying type of the ID is a channel or thread.

class discord.SKUType

  Represents the type of a SKU.

  Added in version 2.4.

  durable

    The SKU is a durable one-time purchase.

  consumable

    The SKU is a consumable one-time purchase.

  subscription

    The SKU is a recurring subscription.

  subscription_group

    The SKU is a system-generated group which is created for each `SKUType.subscription`.

class discord.EntitlementType

  Represents the type of an entitlement.

  Added in version 2.4.

  purchase

    The entitlement was purchased by the user.

  premium_subscription

    The entitlement is for a nitro subscription.

  developer_gift

    The entitlement was gifted by the developer.

  test_mode_purchase

    The entitlement was purchased by a developer in application test mode.

  free_purchase

    The entitlement was granted, when the SKU was free.

  user_gift

    The entitlement was gifted by a another user.

  premium_purchase

    The entitlement was claimed for free by a nitro subscriber.

  application_subscription

    The entitlement was purchased as an app subscription.

class discord.EntitlementOwnerType

  Represents the type of an entitlement owner.

  Added in version 2.4.

  guild

    The entitlement owner is a guild.

  user

    The entitlement owner is a user.

class discord.PollLayoutType

  Represents how a poll answers are shown.

  Added in version 2.4.

  default

    The default layout.

class discord.InviteType

  Represents the type of an invite.

  Added in version 2.4.

  guild

    The invite is a guild invite.

  group_dm

    The invite is a group DM invite.

  friend

    The invite is a friend invite.

class discord.ReactionType

  Represents the type of a reaction.

  Added in version 2.4.

  normal

    A normal reaction.

  burst

    A burst reaction, also known as a “super reaction”.

class discord.VoiceChannelEffectAnimationType

  Represents the animation type of a voice channel effect.

  Added in version 2.5.

  premium

    A fun animation, sent by a Nitro subscriber.

  basic

    The standard animation.

class discord.SubscriptionStatus

  Represents the status of an subscription.

  Added in version 2.5.

  active

    The subscription is active.

  ending

    The subscription is active but will not renew.

  inactive

    The subscription is inactive and not being charged.

class discord.MessageReferenceType

  Represents the type of a message reference.

  Added in version 2.5.

  reply

    A message reply.

  forward

    A forwarded message.

  default

    An alias for `reply`.

## Audit Log Data

Working with `Guild.audit_logs()` is a complicated process with a lot of machinery involved. The library attempts to make it easy to use and friendly. In order to accomplish this goal, it must make use of a couple of data classes that aid in this goal.

### AuditLogEntry

Attributes

- action
- after
- before
- category
- changes
- created_at
- extra
- guild
- id
- reason
- target
- user
- user_id

class discord.AuditLogEntry(*, users, integrations, app_commands, automod_rules, webhooks, data, guild)

  Represents an Audit Log entry.

  You retrieve these via `Guild.audit_logs()`.

  x == y

    Checks if two entries are equal.

  x != y

    Checks if two entries are not equal.

  hash(x)

    Returns the entry’s hash.

  Changed in version 1.7: Audit log entries are now comparable and hashable.

  action

    The action that was done.

    Type:

      `AuditLogAction`

  user

    The user who initiated this action. Usually a `Member`, unless gone then it’s a `User`.

    Type:

      Optional[`abc.User`]

  user_id

    The user ID who initiated this action.

    Added in version 2.2.

    Type:

      Optional[`int`]

  id

    The entry ID.

    Type:

      `int`

  guild

    The guild that this entry belongs to.

    Type:

      `Guild`

  target

    The target that got changed. The exact type of this depends on the action being done.

    Type:

      Any

  reason

    The reason this action was done.

    Type:

      Optional[`str`]

  extra

    Extra information that this entry has that might be useful. For most actions, this is `None`. However in some cases it contains extra information. See `AuditLogAction` for which actions have this field filled out.

    Type:

      Any

  created_at

    Returns the entry’s creation time in UTC.

    Type:

      `datetime.datetime`

  category

    The category of the action, if applicable.

    Type:

      Optional[`AuditLogActionCategory`]

  changes

    The list of changes this entry has.

    Type:

      `AuditLogChanges`

  before

    The target’s prior state.

    Type:

      `AuditLogDiff`

  after

    The target’s subsequent state.

    Type:

      `AuditLogDiff`

### AuditLogChanges

Attributes

- after
- before

class discord.AuditLogChanges

  An audit log change set.

  before

    The old value. The attribute has the type of `AuditLogDiff`.

    Depending on the `AuditLogActionCategory` retrieved by `category`, the data retrieved by this attribute differs:

    Category | Description
    `create` | All attributes are set to `None`.
    `delete` | All attributes are set the value before deletion.
    `update` | All attributes are set the value before updating.
    `None` | No attributes are set.

  after

    The new value. The attribute has the type of `AuditLogDiff`.

    Depending on the `AuditLogActionCategory` retrieved by `category`, the data retrieved by this attribute differs:

    Category | Description
    `create` | All attributes are set to the created value
    `delete` | All attributes are set to `None`
    `update` | All attributes are set the value after updating.
    `None` | No attributes are set.

### AuditLogDiff

Attributes

- actions
- afk_channel
- afk_timeout
- allow
- app_command_permissions
- applied_tags
- archived
- auto_archive_duration
- available
- available_tags
- avatar
- banner
- bitrate
- channel
- code
- color
- colour
- cover_image
- deaf
- default_auto_archive_duration
- default_notifications
- default_reaction_emoji
- default_thread_slowmode_delay
- deny
- description
- discovery_splash
- emoji
- enable_emoticons
- enabled
- entity_type
- event_type
- exempt_channels
- exempt_roles
- expire_behavior
- expire_behaviour
- expire_grace_period
- explicit_content_filter
- flags
- format_type
- guild
- hoist
- icon
- id
- invitable
- inviter
- locked
- max_age
- max_uses
- mentionable
- mfa_level
- mute
- name
- nick
- nsfw
- overwrites
- owner
- permissions
- position
- preferred_locale
- premium_progress_bar_enabled
- privacy_level
- prune_delete_days
- public_updates_channel
- roles
- rtc_region
- rules_channel
- slowmode_delay
- splash
- status
- system_channel
- system_channel_flags
- temporary
- timed_out_until
- topic
- trigger
- trigger_type
- type
- unicode_emoji
- user
- user_limit
- uses
- vanity_url_code
- verification_level
- video_quality_mode
- volume
- widget_channel
- widget_enabled

class discord.AuditLogDiff

  Represents an audit log “change” object. A change object has dynamic attributes that depend on the type of action being done. Certain actions map to certain attributes being set.

  Note that accessing an attribute that does not match the specified action will lead to an attribute error.

  To get a list of attributes that have been set, you can iterate over them. To see a list of all possible attributes that could be set based on the action being done, check the documentation for `AuditLogAction`, otherwise check the documentation below for all attributes that are possible.

  iter(diff)

    Returns an iterator over (attribute, value) tuple of this diff.

  name

    A name of something.

    Type:

      `str`

  guild

    The guild of something.

    Type:

      `Guild`

  icon

    A guild’s or role’s icon. See also `Guild.icon` or `Role.icon`.

    Type:

      `Asset`

  splash

    The guild’s invite splash. See also `Guild.splash`.

    Type:

      `Asset`

  discovery_splash

    The guild’s discovery splash. See also `Guild.discovery_splash`.

    Type:

      `Asset`

  banner

    The guild’s banner. See also `Guild.banner`.

    Type:

      `Asset`

  owner

    The guild’s owner. See also `Guild.owner`

    Type:

      Union[`Member`, `User`]

  afk_channel

    The guild’s AFK channel.

    If this could not be found, then it falls back to a `Object` with the ID being set.

    See `Guild.afk_channel`.

    Type:

      Union[`VoiceChannel`, `Object`]

  system_channel

    The guild’s system channel.

    If this could not be found, then it falls back to a `Object` with the ID being set.

    See `Guild.system_channel`.

    Type:

      Union[`TextChannel`, `Object`]

  rules_channel

    The guild’s rules channel.

    If this could not be found then it falls back to a `Object` with the ID being set.

    See `Guild.rules_channel`.

    Type:

      Union[`TextChannel`, `Object`]

  public_updates_channel

    The guild’s public updates channel.

    If this could not be found then it falls back to a `Object` with the ID being set.

    See `Guild.public_updates_channel`.

    Type:

      Union[`TextChannel`, `Object`]

  afk_timeout

    The guild’s AFK timeout. See `Guild.afk_timeout`.

    Type:

      `int`

  mfa_level

    The guild’s MFA level. See `Guild.mfa_level`.

    Type:

      `MFALevel`

  widget_enabled

    The guild’s widget has been enabled or disabled.

    Type:

      `bool`

  widget_channel

    The widget’s channel.

    If this could not be found then it falls back to a `Object` with the ID being set.

    Type:

      Union[`TextChannel`, `Object`]

  verification_level

    The guild’s verification level.

    See also `Guild.verification_level`.

    Type:

      `VerificationLevel`

  default_notifications

    The guild’s default notification level.

    See also `Guild.default_notifications`.

    Type:

      `NotificationLevel`

  explicit_content_filter

    The guild’s content filter.

    See also `Guild.explicit_content_filter`.

    Type:

      `ContentFilter`

  vanity_url_code

    The guild’s vanity URL.

    See also `Guild.vanity_invite()` and `Guild.edit()`.

    Type:

      `str`

  position

    The position of a `Role` or `abc.GuildChannel`.

    Type:

      `int`

  type

    The type of channel, sticker, webhook or integration.

    Type:

      Union[`ChannelType`, `StickerType`, `WebhookType`, `str`]

  topic

    The topic of a `TextChannel` or `StageChannel`.

    See also `TextChannel.topic` or `StageChannel.topic`.

    Type:

      `str`

  bitrate

    The bitrate of a `VoiceChannel`.

    See also `VoiceChannel.bitrate`.

    Type:

      `int`

  overwrites

    A list of permission overwrite tuples that represents a target and a `PermissionOverwrite` for said target.

    The first element is the object being targeted, which can either be a `Member` or `User` or `Role`. If this object is not found then it is a `Object` with an ID being filled and a `type` attribute set to either `'role'` or `'member'` to help decide what type of ID it is.

    Type:

      List[Tuple[target, `PermissionOverwrite`]]

  privacy_level

    The privacy level of the stage instance or scheduled event

    Type:

      `PrivacyLevel`

  roles

    A list of roles being added or removed from a member.

    If a role is not found then it is a `Object` with the ID and name being filled in.

    Type:

      List[Union[`Role`, `Object`]]

  nick

    The nickname of a member.

    See also `Member.nick`

    Type:

      Optional[`str`]

  deaf

    Whether the member is being server deafened.

    See also `VoiceState.deaf`.

    Type:

      `bool`

  mute

    Whether the member is being server muted.

    See also `VoiceState.mute`.

    Type:

      `bool`

  permissions

    The permissions of a role.

    See also `Role.permissions`.

    Type:

      `Permissions`

  colour
  color

    The colour of a role.

    See also `Role.colour`

    Type:

      `Colour`

  hoist

    Whether the role is being hoisted or not.

    See also `Role.hoist`

    Type:

      `bool`

  mentionable

    Whether the role is mentionable or not.

    See also `Role.mentionable`

    Type:

      `bool`

  code

    The invite’s code.

    See also `Invite.code`

    Type:

      `str`

  channel

    A guild channel.

    If the channel is not found then it is a `Object` with the ID being set. In some cases the channel name is also set.

    Type:

      Union[`abc.GuildChannel`, `Object`]

  inviter

    The user who created the invite.

    See also `Invite.inviter`.

    Type:

      Optional[`User`]

  max_uses

    The invite’s max uses.

    See also `Invite.max_uses`.

    Type:

      `int`

  uses

    The invite’s current uses.

    See also `Invite.uses`.

    Type:

      `int`

  max_age

    The invite’s max age in seconds.

    See also `Invite.max_age`.

    Type:

      `int`

  temporary

    If the invite is a temporary invite.

    See also `Invite.temporary`.

    Type:

      `bool`

  allow
  deny

    The permissions being allowed or denied.

    Type:

      `Permissions`

  id

    The ID of the object being changed.

    Type:

      `int`

  avatar

    The avatar of a member.

    See also `User.avatar`.

    Type:

      `Asset`

  slowmode_delay

    The number of seconds members have to wait before sending another message in the channel.

    See also `TextChannel.slowmode_delay`.

    Type:

      `int`

  rtc_region

    The region for the voice channel’s voice communication. A value of `None` indicates automatic voice region detection.

    See also `VoiceChannel.rtc_region`.

    Type:

      `str`

  video_quality_mode

    The camera video quality for the voice channel’s participants.

    See also `VoiceChannel.video_quality_mode`.

    Type:

      `VideoQualityMode`

  format_type

    The format type of a sticker being changed.

    See also `GuildSticker.format`

    Type:

      `StickerFormatType`

  emoji

    The emoji which represents one of the following:

    - `GuildSticker.emoji`

    - `SoundboardSound.emoji`

    Type:

      Union[`str`, `PartialEmoji`]

  unicode_emoji

    The unicode emoji that is used as an icon for the role being changed.

    See also `Role.unicode_emoji`.

    Type:

      `str`

  description

    The description of a guild, a sticker, or a scheduled event.

    See also `Guild.description`, `GuildSticker.description`, or `ScheduledEvent.description`.

    Type:

      `str`

  available

    The availability of one of the following being changed:

    - `GuildSticker.available`

    - `SoundboardSound.available`

    Type:

      `bool`

  archived

    The thread is now archived.

    Type:

      `bool`

  locked

    The thread is being locked or unlocked.

    Type:

      `bool`

  auto_archive_duration

    The thread’s auto archive duration being changed.

    See also `Thread.auto_archive_duration`

    Type:

      `int`

  default_auto_archive_duration

    The default auto archive duration for newly created threads being changed.

    Type:

      `int`

  invitable

    Whether non-moderators can add users to this private thread.

    Type:

      `bool`

  timed_out_until

    Whether the user is timed out, and if so until when.

    Type:

      Optional[`datetime.datetime`]

  enable_emoticons

    Integration emoticons were enabled or disabled.

    See also `StreamIntegration.enable_emoticons`

    Type:

      `bool`

  expire_behaviour
  expire_behavior

    The behaviour of expiring subscribers changed.

    See also `StreamIntegration.expire_behaviour`

    Type:

      `ExpireBehaviour`

  expire_grace_period

    The grace period before expiring subscribers changed.

    See also `StreamIntegration.expire_grace_period`

    Type:

      `int`

  preferred_locale

    The preferred locale for the guild changed.

    See also `Guild.preferred_locale`

    Type:

      `Locale`

  prune_delete_days

    The number of days after which inactive and role-unassigned members are kicked has been changed.

    Type:

      `int`

  status

    The status of the scheduled event.

    Type:

      `EventStatus`

  entity_type

    The type of entity this scheduled event is for.

    Type:

      `EntityType`

  cover_image

    The scheduled event’s cover image.

    See also `ScheduledEvent.cover_image`.

    Type:

      `Asset`

  app_command_permissions

    List of permissions for the app command.

    Type:

      List[`AppCommandPermissions`]

  enabled

    Whether the automod rule is active or not.

    Type:

      `bool`

  event_type

    The event type for triggering the automod rule.

    Type:

      `AutoModRuleEventType`

  trigger_type

    The trigger type for the automod rule.

    Type:

      `AutoModRuleTriggerType`

  trigger

    The trigger for the automod rule.

    Note

    The `type` of the trigger may be incorrect. Some attributes such as `keyword_filter`, `regex_patterns`, and `allow_list` will only have the added or removed values.

    Type:

      `AutoModTrigger`

  actions

    The actions to take when an automod rule is triggered.

    Type:

      List[AutoModRuleAction]

  exempt_roles

    The list of roles that are exempt from the automod rule.

    Type:

      List[Union[`Role`, `Object`]]

  exempt_channels

    The list of channels or threads that are exempt from the automod rule.

    Type:

      List[`abc.GuildChannel`, `Thread`, `Object`]

  premium_progress_bar_enabled

    The guild’s display setting to show boost progress bar.

    Type:

      `bool`

  system_channel_flags

    The guild’s system channel settings.

    See also `Guild.system_channel_flags`

    Type:

      `SystemChannelFlags`

  nsfw

    Whether the channel is marked as “not safe for work” or “age restricted”.

    Type:

      `bool`

  user_limit

    The channel’s limit for number of members that can be in a voice or stage channel.

    See also `VoiceChannel.user_limit` and `StageChannel.user_limit`

    Type:

      `int`

  flags

    The channel flags associated with this thread or forum post.

    See also `ForumChannel.flags` and `Thread.flags`

    Type:

      `ChannelFlags`

  default_thread_slowmode_delay

    The default slowmode delay for threads created in this text channel or forum.

    See also `TextChannel.default_thread_slowmode_delay` and `ForumChannel.default_thread_slowmode_delay`

    Type:

      `int`

  applied_tags

    The applied tags of a forum post.

    See also `Thread.applied_tags`

    Type:

      List[Union[`ForumTag`, `Object`]]

  available_tags

    The available tags of a forum.

    See also `ForumChannel.available_tags`

    Type:

      Sequence[`ForumTag`]

  default_reaction_emoji

    The default_reaction_emoji for forum posts.

    See also `ForumChannel.default_reaction_emoji`

    Type:

      Optional[`PartialEmoji`]

  user

    The user that represents the uploader of a soundboard sound.

    See also `SoundboardSound.user`

    Type:

      Union[`Member`, `User`]

  volume

    The volume of a soundboard sound.

    See also `SoundboardSound.volume`

    Type:

      `float`

## Webhook Support

discord.py offers support for creating, editing, and executing webhooks through the `Webhook` class.

### Webhook

Attributes

- avatar
- channel
- channel_id
- created_at
- default_avatar
- display_avatar
- guild
- guild_id
- id
- name
- source_channel
- source_guild
- token
- type
- url
- user

Methods

- cls Webhook.from_url
- cls Webhook.partial
- async delete
- async delete_message
- async edit
- async edit_message
- async fetch
- async fetch_message
- def is_authenticated
- def is_partial
- async send

class discord.Webhook

  Represents an asynchronous Discord webhook.

  Webhooks are a form to send messages to channels in Discord without a bot user or authentication.

  There are two main ways to use Webhooks. The first is through the ones received by the library such as `Guild.webhooks()`, `TextChannel.webhooks()`, `VoiceChannel.webhooks()` and `ForumChannel.webhooks()`. The ones received by the library will automatically be bound using the library’s internal HTTP session.

  The second form involves creating a webhook object manually using the `from_url()` or `partial()` classmethods.

  For example, creating a webhook from a URL and using aiohttp:

      from discord import Webhook
      import aiohttp

      async def foo():
          async with aiohttp.ClientSession() as session:
              webhook = Webhook.from_url('url-here', session=session)
              await webhook.send('Hello World', username='Foo')

  For a synchronous counterpart, see `SyncWebhook`.

  x == y

    Checks if two webhooks are equal.

  x != y

    Checks if two webhooks are not equal.

  hash(x)

    Returns the webhooks’s hash.

  Changed in version 1.4: Webhooks are now comparable and hashable.

  id

    The webhook’s ID

    Type:

      `int`

  type

    The type of the webhook.

    Added in version 1.3.

    Type:

      `WebhookType`

  token

    The authentication token of the webhook. If this is `None` then the webhook cannot be used to make requests.

    Type:

      Optional[`str`]

  guild_id

    The guild ID this webhook is for.

    Type:

      Optional[`int`]

  channel_id

    The channel ID this webhook is for.

    Type:

      Optional[`int`]

  user

    The user this webhook was created by. If the webhook was received without authentication then this will be `None`.

    Type:

      Optional[`abc.User`]

  name

    The default name of the webhook.

    Type:

      Optional[`str`]

  source_guild

    The guild of the channel that this webhook is following. Only given if `type` is `WebhookType.channel_follower`.

    Added in version 2.0.

    Type:

      Optional[`PartialWebhookGuild`]

  source_channel

    The channel that this webhook is following. Only given if `type` is `WebhookType.channel_follower`.

    Added in version 2.0.

    Type:

      Optional[`PartialWebhookChannel`]

  property url

    Returns the webhook’s url.

    Type:

      `str`

  classmethod partial(id, token, *, session=..., client=..., bot_token=None)

    Creates a partial `Webhook`.

    Parameters:

      - id (`int`) – The ID of the webhook.

      - token (`str`) – The authentication token of the webhook.

      - session (`aiohttp.ClientSession`) –

        The session to use to send requests with. Note that the library does not manage the session and will not close it.

        Added in version 2.0.

      - client (`Client`) –

        The client to initialise this webhook with. This allows it to attach the client’s internal state. If `session` is not given while this is given then the client’s internal session will be used.

        Added in version 2.2.

      - bot_token (Optional[`str`]) –

        The bot authentication token for authenticated requests involving the webhook.

        Added in version 2.0.

    Raises:

      TypeError – Neither `session` nor `client` were given.

    Returns:

      A partial `Webhook`. A partial webhook is just a webhook object with an ID and a token.

    Return type:

      `Webhook`

  classmethod from_url(url, *, session=..., client=..., bot_token=None)

    Creates a partial `Webhook` from a webhook URL.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - url (`str`) – The URL of the webhook.

      - session (`aiohttp.ClientSession`) –

        The session to use to send requests with. Note that the library does not manage the session and will not close it.

        Added in version 2.0.

      - client (`Client`) –

        The client to initialise this webhook with. This allows it to attach the client’s internal state. If `session` is not given while this is given then the client’s internal session will be used.

        Added in version 2.2.

      - bot_token (Optional[`str`]) –

        The bot authentication token for authenticated requests involving the webhook.

        Added in version 2.0.

    Raises:

      - ValueError – The URL is invalid.

      - TypeError – Neither `session` nor `client` were given.

    Returns:

      A partial `Webhook`. A partial webhook is just a webhook object with an ID and a token.

    Return type:

      `Webhook`

  await fetch(*, prefer_auth=True)

    This function is a coroutine.

    Fetches the current webhook.

    This could be used to get a full webhook from a partial webhook.

    Added in version 2.0.

    Note

    When fetching with an unauthenticated webhook, i.e. `is_authenticated()` returns `False`, then the returned webhook does not contain any user information.

    Parameters:

      prefer_auth (`bool`) – Whether to use the bot token over the webhook token if available. Defaults to `True`.

    Raises:

      - HTTPException – Could not fetch the webhook

      - NotFound – Could not find the webhook by this ID

      - ValueError – This webhook does not have a token associated with it.

    Returns:

      The fetched webhook.

    Return type:

      `Webhook`

  await delete(*, reason=None, prefer_auth=True)

    This function is a coroutine.

    Deletes this Webhook.

    Parameters:

      - reason (Optional[`str`]) –

        The reason for deleting this webhook. Shows up on the audit log.

        Added in version 1.4.

      - prefer_auth (`bool`) –

        Whether to use the bot token over the webhook token if available. Defaults to `True`.

        Added in version 2.0.

    Raises:

      - HTTPException – Deleting the webhook failed.

      - NotFound – This webhook does not exist.

      - Forbidden – You do not have permissions to delete this webhook.

      - ValueError – This webhook does not have a token associated with it.

  await edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)

    This function is a coroutine.

    Edits this Webhook.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (Optional[`str`]) – The webhook’s new default name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s new default avatar.

      - channel (Optional[`abc.Snowflake`]) –

        The webhook’s new channel. This requires an authenticated webhook.

        Added in version 2.0.

      - reason (Optional[`str`]) –

        The reason for editing this webhook. Shows up on the audit log.

        Added in version 1.4.

      - prefer_auth (`bool`) –

        Whether to use the bot token over the webhook token if available. Defaults to `True`.

        Added in version 2.0.

    Raises:

      - HTTPException – Editing the webhook failed.

      - NotFound – This webhook does not exist.

      - ValueError – This webhook does not have a token associated with it or it tried editing a channel without authentication.

  property avatar

    Returns an `Asset` for the avatar the webhook has.

    If the webhook does not have a traditional avatar, `None` is returned. If you want the avatar that a webhook has displayed, consider `display_avatar`.

    Type:

      Optional[`Asset`]

  property channel

    The channel this webhook belongs to.

    If this is a partial webhook, then this will always return `None`.

    Type:

      Optional[Union[`ForumChannel`, `VoiceChannel`, `TextChannel`]]

  property created_at

    Returns the webhook’s creation time in UTC.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar.

    Added in version 2.0.

    Type:

      `Asset`

  property display_avatar

    Returns the webhook’s display avatar.

    This is either webhook’s default avatar or uploaded avatar.

    Added in version 2.0.

    Type:

      `Asset`

  property guild

    The guild this webhook belongs to.

    If this is a partial webhook, then this will always return `None`.

    Type:

      Optional[`Guild`]

  is_authenticated()

    `bool`: Whether the webhook is authenticated with a bot token.

    Added in version 2.0.

  is_partial()

    `bool`: Whether the webhook is a “partial” webhook.

    Added in version 2.0.

  await send(content=..., *, username=..., avatar_url=..., tts=False, ephemeral=False, file=..., files=..., embed=..., embeds=..., allowed_mentions=..., view=..., thread=..., thread_name=..., wait=False, suppress_embeds=False, silent=False, applied_tags=..., poll=...)

    This function is a coroutine.

    Sends a message using the webhook.

    The content must be a type that can convert to a string through `str(content)`.

    To upload a single file, the `file` parameter should be used with a single `File` object.

    If the `embed` parameter is provided, it must be of type `Embed` and it must be a rich embed type. You cannot mix the `embed` parameter with the `embeds` parameter, which must be a `list` of `Embed` objects to send.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (`str`) – The content of the message to send.

      - wait (`bool`) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from `None` to a `WebhookMessage` if set to `True`. If the type of webhook is `WebhookType.application` then this is always set to `True`.

      - username (`str`) – The username to send with this message. If no username is provided then the default username for the webhook is used.

      - avatar_url (`str`) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using `str`.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - ephemeral (`bool`) –

        Indicates if the message should only be visible to the user. This is only available to `WebhookType.application` webhooks. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

        Added in version 2.0.

      - file (`File`) – The file to upload. This cannot be mixed with `files` parameter.

      - files (List[`File`]) – A list of files to send with the content. This cannot be mixed with the `file` parameter.

      - embed (`Embed`) – The rich embed for the content to send. This cannot be mixed with `embeds` parameter.

      - embeds (List[`Embed`]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the `embed` parameter.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message.

        Added in version 1.4.

      - view (`discord.ui.View`) –

        The view to send with the message. If the webhook is partial or is not managed by the library, then you can only send URL buttons. Otherwise, you can send views with any type of components.

        Added in version 2.0.

      - thread (`Snowflake`) –

        The thread to send this webhook to.

        Added in version 2.0.

      - thread_name (`str`) –

        The thread name to create with this webhook if the webhook belongs to a `ForumChannel`. Note that this is mutually exclusive with the `thread` parameter, as this will create a new thread with the given name.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - applied_tags (List[`ForumTag`]) –

        Tags to apply to the thread if the webhook belongs to a `ForumChannel`.

        Added in version 2.4.

      - poll (`Poll`) –

        The poll to send with this message.

        Warning

        When sending a Poll via webhook, you cannot manually end it.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - NotFound – This webhook was not found.

      - Forbidden – The authorization token for the webhook is incorrect.

      - TypeError – You specified both `embed` and `embeds` or `file` and `files` or `thread` and `thread_name`.

      - ValueError – The length of `embeds` was invalid, there was no token associated with this webhook or `ephemeral` was passed with the improper webhook type or there was no state attached with this webhook when giving it a view that had components other than URL buttons.

    Returns:

      If `wait` is `True` then the message that was sent, otherwise `None`.

    Return type:

      Optional[`WebhookMessage`]

  await fetch_message(id, /, *, thread=...)

    This function is a coroutine.

    Retrieves a single `WebhookMessage` owned by this webhook.

    Added in version 2.0.

    Parameters:

      - id (`int`) – The message ID to look for.

      - thread (`Snowflake`) – The thread to look in.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

      - ValueError – There was no token associated with this webhook.

    Returns:

      The message asked for.

    Return type:

      `WebhookMessage`

  await edit_message(message_id, *, content=..., embeds=..., embed=..., attachments=..., view=..., allowed_mentions=None, thread=...)

    This function is a coroutine.

    Edits a message owned by this webhook.

    This is a lower level interface to `WebhookMessage.edit()` in case you only have an ID.

    Added in version 1.6.

    Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - message_id (`int`) – The message ID to edit.

      - content (Optional[`str`]) – The content to edit the message with or `None` to clear it.

      - embeds (List[`Embed`]) – A list of embeds to edit the message with.

      - embed (Optional[`Embed`]) – The embed to edit the message with. `None` suppresses the embeds. This should not be mixed with the `embeds` parameter.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Added in version 2.0.

      - allowed_mentions (`AllowedMentions`) – Controls the mentions being processed in this message. See `abc.Messageable.send()` for more information.

      - view (Optional[`View`]) –

        The updated view to update this message with. If `None` is passed then the view is removed. The webhook must have state attached, similar to `send()`.

        Added in version 2.0.

      - thread (`Snowflake`) –

        The thread the webhook message belongs to.

        Added in version 2.0.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Edited a message that is not yours.

      - TypeError – You specified both `embed` and `embeds`

      - ValueError – The length of `embeds` was invalid, there was no token associated with this webhook or the webhook had no state.

    Returns:

      The newly edited webhook message.

    Return type:

      `WebhookMessage`

  await delete_message(message_id, /, *, thread=...)

    This function is a coroutine.

    Deletes a message owned by this webhook.

    This is a lower level interface to `WebhookMessage.delete()` in case you only have an ID.

    Added in version 1.6.

    Changed in version 2.0: `message_id` parameter is now positional-only.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - message_id (`int`) – The message ID to delete.

      - thread (`Snowflake`) –

        The thread the webhook message belongs to.

        Added in version 2.0.

    Raises:

      - HTTPException – Deleting the message failed.

      - Forbidden – Deleted a message that is not yours.

      - ValueError – This webhook does not have a token associated with it.

### WebhookMessage

Attributes

- clean_content
- created_at
- edited_at
- interaction
- jump_url
- raw_channel_mentions
- raw_mentions
- raw_role_mentions
- system_content
- thread

Methods

- async add_files
- async add_reaction
- async clear_reaction
- async clear_reactions
- async create_thread
- async delete
- async edit
- async end_poll
- async fetch
- async fetch_thread
- async forward
- def is_system
- async pin
- async publish
- async remove_attachments
- async remove_reaction
- async reply
- def to_reference
- async unpin

class discord.WebhookMessage

  Represents a message sent from your webhook.

  This allows you to edit or delete a message sent by your webhook.

  This inherits from `discord.Message` with changes to `edit()` and `delete()` to work.

  Added in version 1.6.

  await edit(*, content=..., embeds=..., embed=..., attachments=..., view=..., allowed_mentions=None)

    This function is a coroutine.

    Edits the message.

    Added in version 1.6.

    Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content to edit the message with or `None` to clear it.

      - embeds (List[`Embed`]) – A list of embeds to edit the message with.

      - embed (Optional[`Embed`]) – The embed to edit the message with. `None` suppresses the embeds. This should not be mixed with the `embeds` parameter.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Note

        New files will always appear after current attachments.

        Added in version 2.0.

      - allowed_mentions (`AllowedMentions`) – Controls the mentions being processed in this message. See `abc.Messageable.send()` for more information.

      - view (Optional[`View`]) –

        The updated view to update this message with. If `None` is passed then the view is removed.

        Added in version 2.0.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Edited a message that is not yours.

      - TypeError – You specified both `embed` and `embeds`

      - ValueError – The length of `embeds` was invalid or there was no token associated with this webhook.

    Returns:

      The newly edited message.

    Return type:

      `WebhookMessage`

  await add_files(*files)

    This function is a coroutine.

    Adds new files to the end of the message attachments.

    Added in version 2.0.

    Parameters:

      *files (`File`) – New files to add to the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `WebhookMessage`

  await remove_attachments(*attachments)

    This function is a coroutine.

    Removes attachments from the message.

    Added in version 2.0.

    Parameters:

      *attachments (`Attachment`) – Attachments to remove from the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `WebhookMessage`

  await delete(*, delay=None)

    This function is a coroutine.

    Deletes the message.

    Parameters:

      delay (Optional[`float`]) – If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored.

    Raises:

      - Forbidden – You do not have proper permissions to delete the message.

      - NotFound – The message was deleted already.

      - HTTPException – Deleting the message failed.

  await add_reaction(emoji, /)

    This function is a coroutine.

    Adds a reaction to the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `read_message_history` to do this. If nobody else has reacted to the message using this emoji, `add_reactions` is required.

    Changed in version 2.0: `emoji` parameter is now positional-only.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to react with.

    Raises:

      - HTTPException – Adding the reaction failed.

      - Forbidden – You do not have the proper permissions to react to the message.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  clean_content

    A property that returns the content in a “cleaned up” manner. This basically means that mentions are transformed into the way the client shows it. e.g. `<#id>` will transform into `#name`.

    This will also transform @everyone and @here mentions into non-mentions.

    Note

    This does not affect markdown. If you want to escape or remove markdown then use `utils.escape_markdown()` or `utils.remove_markdown()` respectively, along with this function.

    Type:

      `str`

  await clear_reaction(emoji)

    This function is a coroutine.

    Clears a specific reaction from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `manage_messages` to do this.

    Added in version 1.3.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to clear.

    Raises:

      - HTTPException – Clearing the reaction failed.

      - Forbidden – You do not have the proper permissions to clear the reaction.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await clear_reactions()

    This function is a coroutine.

    Removes all the reactions from the message.

    You must have `manage_messages` to do this.

    Raises:

      - HTTPException – Removing the reactions failed.

      - Forbidden – You do not have the proper permissions to remove all the reactions.

  await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)

    This function is a coroutine.

    Creates a public thread from this message.

    You must have `create_public_threads` in order to create a public thread from a message.

    The channel this message belongs in must be a `TextChannel`.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the thread.

      - auto_archive_duration (`int`) –

        The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

        Must be one of `60`, `1440`, `4320`, or `10080`, if provided.

      - slowmode_delay (Optional[`int`]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`. By default no slowmode rate limit if this is `None`.

      - reason (Optional[`str`]) – The reason for creating a new thread. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a thread.

      - HTTPException – Creating the thread failed.

      - ValueError – This message does not have guild info attached.

    Returns:

      The created thread.

    Return type:

      `Thread`

  property created_at

    The message’s creation time in UTC.

    Type:

      `datetime.datetime`

  property edited_at

    An aware UTC datetime object containing the edited time of the message.

    Type:

      Optional[`datetime.datetime`]

  await end_poll()

    This function is a coroutine.

    Ends the `Poll` attached to this message.

    This can only be done if you are the message author.

    If the poll was successfully ended, then it returns the updated `Message`.

    Raises:

      HTTPException – Ending the poll failed.

    Returns:

      The updated message.

    Return type:

      `Message`

  await fetch()

    This function is a coroutine.

    Fetches the partial message to a full `Message`.

    Raises:

      - NotFound – The message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The full message.

    Return type:

      `Message`

  await fetch_thread()

    This function is a coroutine.

    Retrieves the public thread attached to this message.

    Note

    This method is an API call. For general usage, consider `thread` instead.

    Added in version 2.4.

    Raises:

      - InvalidData – An unknown channel type was received from Discord or the guild the thread belongs to is not the same as the one in this object points to.

      - HTTPException – Retrieving the thread failed.

      - NotFound – There is no thread attached to this message.

      - Forbidden – You do not have permission to fetch this channel.

    Returns:

      The public thread attached to this message.

    Return type:

      `Thread`

  await forward(destination, *, fail_if_not_exists=True)

    This function is a coroutine.

    Forwards this message to a channel.

    Added in version 2.5.

    Parameters:

      - destination (`Messageable`) – The channel to forward this message to.

      - fail_if_not_exists (`bool`) – Whether replying using the message reference should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

    Raises:

      HTTPException – Forwarding the message failed.

    Returns:

      The message sent to the channel.

    Return type:

      `Message`

  property interaction

    The interaction that this message is a response to.

    Added in version 2.0.

    Deprecated since version 2.4: This attribute is deprecated and will be removed in a future version. Use `interaction_metadata` instead.

    Type:

      Optional[`MessageInteraction`]

  is_system()

    `bool`: Whether the message is a system message.

    A system message is a message that is constructed entirely by the Discord API in response to something.

    Added in version 1.3.

  property jump_url

    Returns a URL that allows the client to jump to this message.

    Type:

      `str`

  await pin(*, reason=None)

    This function is a coroutine.

    Pins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for pinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to pin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages.

  await publish()

    This function is a coroutine.

    Publishes this message to the channel’s followers.

    The message must have been sent in a news channel. You must have `send_messages` to do this.

    If the message is not your own then `manage_messages` is also needed.

    Raises:

      - Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.

      - HTTPException – Publishing the message failed.

  raw_channel_mentions

    A property that returns an array of channel IDs matched with the syntax of `<#channel_id>` in the message content.

    Type:

      List[`int`]

  raw_mentions

    A property that returns an array of user IDs matched with the syntax of `<@user_id>` in the message content.

    This allows you to receive the user IDs of mentioned users even in a private message context.

    Type:

      List[`int`]

  raw_role_mentions

    A property that returns an array of role IDs matched with the syntax of `<@&role_id>` in the message content.

    Type:

      List[`int`]

  await remove_reaction(emoji, member)

    This function is a coroutine.

    Remove a reaction by the member from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    If the reaction is not your own (i.e. `member` parameter is not you) then `manage_messages` is needed.

    The `member` parameter must represent a member and meet the `abc.Snowflake` abc.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to remove.

      - member (`abc.Snowflake`) – The member for which to remove the reaction.

    Raises:

      - HTTPException – Removing the reaction failed.

      - Forbidden – You do not have the proper permissions to remove the reaction.

      - NotFound – The member or emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await reply(content=None, **kwargs)

    This function is a coroutine.

    A shortcut method to `abc.Messageable.send()` to reply to the `Message`.

    Added in version 1.6.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` list is not of the appropriate size

      - TypeError – You specified both `file` and `files`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  system_content

    A property that returns the content that is rendered regardless of the `Message.type`.

    In the case of `MessageType.default` and `MessageType.reply`, this just returns the regular `Message.content`. Otherwise this returns an English message denoting the contents of the system message.

    Type:

      `str`

  property thread

    The public thread created from this message, if it exists.

    Note

    For messages received via the gateway this does not retrieve archived threads, as they are not retained in the internal cache. Use `fetch_thread()` instead.

    Added in version 2.4.

    Type:

      Optional[`Thread`]

  to_reference(*, fail_if_not_exists=True, type=('default', 0))

    Creates a `MessageReference` from the current message.

    Added in version 1.6.

    Parameters:

      - fail_if_not_exists (`bool`) –

        Whether the referenced message should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

        Added in version 1.7.

      - type (`MessageReferenceType`) –

        The type of message reference.

        Added in version 2.5.

    Returns:

      The reference to this message.

    Return type:

      `MessageReference`

  await unpin(*, reason=None)

    This function is a coroutine.

    Unpins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for unpinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to unpin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Unpinning the message failed.

### SyncWebhook

Attributes

- avatar
- channel
- channel_id
- created_at
- default_avatar
- display_avatar
- guild
- guild_id
- id
- name
- source_channel
- source_guild
- token
- type
- url
- user

Methods

- cls SyncWebhook.from_url
- cls SyncWebhook.partial
- def delete
- def delete_message
- def edit
- def edit_message
- def fetch
- def fetch_message
- def is_authenticated
- def is_partial
- def send

class discord.SyncWebhook

  Represents a synchronous Discord webhook.

  For an asynchronous counterpart, see `Webhook`.

  x == y

    Checks if two webhooks are equal.

  x != y

    Checks if two webhooks are not equal.

  hash(x)

    Returns the webhooks’s hash.

  Changed in version 1.4: Webhooks are now comparable and hashable.

  id

    The webhook’s ID

    Type:

      `int`

  type

    The type of the webhook.

    Added in version 1.3.

    Type:

      `WebhookType`

  token

    The authentication token of the webhook. If this is `None` then the webhook cannot be used to make requests.

    Type:

      Optional[`str`]

  guild_id

    The guild ID this webhook is for.

    Type:

      Optional[`int`]

  channel_id

    The channel ID this webhook is for.

    Type:

      Optional[`int`]

  user

    The user this webhook was created by. If the webhook was received without authentication then this will be `None`.

    Type:

      Optional[`abc.User`]

  name

    The default name of the webhook.

    Type:

      Optional[`str`]

  source_guild

    The guild of the channel that this webhook is following. Only given if `type` is `WebhookType.channel_follower`.

    Added in version 2.0.

    Type:

      Optional[`PartialWebhookGuild`]

  source_channel

    The channel that this webhook is following. Only given if `type` is `WebhookType.channel_follower`.

    Added in version 2.0.

    Type:

      Optional[`PartialWebhookChannel`]

  property url

    Returns the webhook’s url.

    Type:

      `str`

  classmethod partial(id, token, *, session=..., bot_token=None)

    Creates a partial `Webhook`.

    Parameters:

      - id (`int`) – The ID of the webhook.

      - token (`str`) – The authentication token of the webhook.

      - session (`requests.Session`) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the `requests` auto session creation functions are used instead.

      - bot_token (Optional[`str`]) – The bot authentication token for authenticated requests involving the webhook.

    Returns:

      A partial `SyncWebhook`. A partial `SyncWebhook` is just a `SyncWebhook` object with an ID and a token.

    Return type:

      `SyncWebhook`

  classmethod from_url(url, *, session=..., bot_token=None)

    Creates a partial `Webhook` from a webhook URL.

    Parameters:

      - url (`str`) – The URL of the webhook.

      - session (`requests.Session`) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the `requests` auto session creation functions are used instead.

      - bot_token (Optional[`str`]) – The bot authentication token for authenticated requests involving the webhook.

    Raises:

      ValueError – The URL is invalid.

    Returns:

      A partial `SyncWebhook`. A partial `SyncWebhook` is just a `SyncWebhook` object with an ID and a token.

    Return type:

      `SyncWebhook`

  fetch(*, prefer_auth=True)

    Fetches the current webhook.

    This could be used to get a full webhook from a partial webhook.

    Note

    When fetching with an unauthenticated webhook, i.e. `is_authenticated()` returns `False`, then the returned webhook does not contain any user information.

    Parameters:

      prefer_auth (`bool`) – Whether to use the bot token over the webhook token if available. Defaults to `True`.

    Raises:

      - HTTPException – Could not fetch the webhook

      - NotFound – Could not find the webhook by this ID

      - ValueError – This webhook does not have a token associated with it.

    Returns:

      The fetched webhook.

    Return type:

      `SyncWebhook`

  delete(*, reason=None, prefer_auth=True)

    Deletes this Webhook.

    Parameters:

      - reason (Optional[`str`]) –

        The reason for deleting this webhook. Shows up on the audit log.

        Added in version 1.4.

      - prefer_auth (`bool`) – Whether to use the bot token over the webhook token if available. Defaults to `True`.

    Raises:

      - HTTPException – Deleting the webhook failed.

      - NotFound – This webhook does not exist.

      - Forbidden – You do not have permissions to delete this webhook.

      - ValueError – This webhook does not have a token associated with it.

  edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)

    Edits this Webhook.

    Parameters:

      - name (Optional[`str`]) – The webhook’s new default name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s new default avatar.

      - channel (Optional[`abc.Snowflake`]) – The webhook’s new channel. This requires an authenticated webhook.

      - reason (Optional[`str`]) –

        The reason for editing this webhook. Shows up on the audit log.

        Added in version 1.4.

      - prefer_auth (`bool`) – Whether to use the bot token over the webhook token if available. Defaults to `True`.

    Raises:

      - HTTPException – Editing the webhook failed.

      - NotFound – This webhook does not exist.

      - ValueError – This webhook does not have a token associated with it or it tried editing a channel without authentication.

    Returns:

      The newly edited webhook.

    Return type:

      `SyncWebhook`

  send(content=..., *, username=..., avatar_url=..., tts=False, file=..., files=..., embed=..., embeds=..., allowed_mentions=..., thread=..., thread_name=..., wait=False, suppress_embeds=False, silent=False, applied_tags=..., poll=..., view=...)

    Sends a message using the webhook.

    The content must be a type that can convert to a string through `str(content)`.

    To upload a single file, the `file` parameter should be used with a single `File` object.

    If the `embed` parameter is provided, it must be of type `Embed` and it must be a rich embed type. You cannot mix the `embed` parameter with the `embeds` parameter, which must be a `list` of `Embed` objects to send.

    Parameters:

      - content (`str`) – The content of the message to send.

      - wait (`bool`) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from `None` to a `WebhookMessage` if set to `True`.

      - username (`str`) – The username to send with this message. If no username is provided then the default username for the webhook is used.

      - avatar_url (`str`) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using `str`.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - file (`File`) – The file to upload. This cannot be mixed with `files` parameter.

      - files (List[`File`]) – A list of files to send with the content. This cannot be mixed with the `file` parameter.

      - embed (`Embed`) – The rich embed for the content to send. This cannot be mixed with `embeds` parameter.

      - embeds (List[`Embed`]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the `embed` parameter.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message.

        Added in version 1.4.

      - thread (`Snowflake`) –

        The thread to send this message to.

        Added in version 2.0.

      - thread_name (`str`) –

        The thread name to create with this webhook if the webhook belongs to a `ForumChannel`. Note that this is mutually exclusive with the `thread` parameter, as this will create a new thread with the given name.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Warning

        When sending a Poll via webhook, you cannot manually end it.

        Added in version 2.4.

      - view (`View`) –

        The view to send with the message. This can only have URL buttons, which donnot require a state to be attached to it.

        If you want to send a view with any component attached to it, check `Webhook.send()`.

        Added in version 2.5.

    Raises:

      - HTTPException – Sending the message failed.

      - NotFound – This webhook was not found.

      - Forbidden – The authorization token for the webhook is incorrect.

      - TypeError – You specified both `embed` and `embeds` or `file` and `files` or `thread` and `thread_name`.

      - ValueError – The length of `embeds` was invalid, there was no token associated with this webhook or you tried to send a view with components other than URL buttons.

    Returns:

      If `wait` is `True` then the message that was sent, otherwise `None`.

    Return type:

      Optional[`SyncWebhookMessage`]

  fetch_message(id, /, *, thread=...)

    Retrieves a single `SyncWebhookMessage` owned by this webhook.

    Added in version 2.0.

    Parameters:

      - id (`int`) – The message ID to look for.

      - thread (`Snowflake`) – The thread to look in.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

      - ValueError – There was no token associated with this webhook.

    Returns:

      The message asked for.

    Return type:

      `SyncWebhookMessage`

  property avatar

    Returns an `Asset` for the avatar the webhook has.

    If the webhook does not have a traditional avatar, `None` is returned. If you want the avatar that a webhook has displayed, consider `display_avatar`.

    Type:

      Optional[`Asset`]

  property channel

    The channel this webhook belongs to.

    If this is a partial webhook, then this will always return `None`.

    Type:

      Optional[Union[`ForumChannel`, `VoiceChannel`, `TextChannel`]]

  property created_at

    Returns the webhook’s creation time in UTC.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar.

    Added in version 2.0.

    Type:

      `Asset`

  property display_avatar

    Returns the webhook’s display avatar.

    This is either webhook’s default avatar or uploaded avatar.

    Added in version 2.0.

    Type:

      `Asset`

  edit_message(message_id, *, content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None, thread=...)

    Edits a message owned by this webhook.

    This is a lower level interface to `WebhookMessage.edit()` in case you only have an ID.

    Added in version 1.6.

    Parameters:

      - message_id (`int`) – The message ID to edit.

      - content (Optional[`str`]) – The content to edit the message with or `None` to clear it.

      - embeds (List[`Embed`]) – A list of embeds to edit the message with.

      - embed (Optional[`Embed`]) – The embed to edit the message with. `None` suppresses the embeds. This should not be mixed with the `embeds` parameter.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Added in version 2.0.

      - allowed_mentions (`AllowedMentions`) – Controls the mentions being processed in this message. See `abc.Messageable.send()` for more information.

      - thread (`Snowflake`) –

        The thread the webhook message belongs to.

        Added in version 2.0.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Edited a message that is not yours.

      - TypeError – You specified both `embed` and `embeds`

      - ValueError – The length of `embeds` was invalid or there was no token associated with this webhook.

  property guild

    The guild this webhook belongs to.

    If this is a partial webhook, then this will always return `None`.

    Type:

      Optional[`Guild`]

  is_authenticated()

    `bool`: Whether the webhook is authenticated with a bot token.

    Added in version 2.0.

  is_partial()

    `bool`: Whether the webhook is a “partial” webhook.

    Added in version 2.0.

  delete_message(message_id, /, *, thread=...)

    Deletes a message owned by this webhook.

    This is a lower level interface to `WebhookMessage.delete()` in case you only have an ID.

    Added in version 1.6.

    Parameters:

      - message_id (`int`) – The message ID to delete.

      - thread (`Snowflake`) –

        The thread the webhook message belongs to.

        Added in version 2.0.

    Raises:

      - HTTPException – Deleting the message failed.

      - Forbidden – Deleted a message that is not yours.

      - ValueError – This webhook does not have a token associated with it.

### SyncWebhookMessage

Methods

- def add_files
- def delete
- def edit
- def remove_attachments

class discord.SyncWebhookMessage

  Represents a message sent from your webhook.

  This allows you to edit or delete a message sent by your webhook.

  This inherits from `discord.Message` with changes to `edit()` and `delete()` to work.

  Added in version 2.0.

  edit(*, content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None)

    Edits the message.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content to edit the message with or `None` to clear it.

      - embeds (List[`Embed`]) – A list of embeds to edit the message with.

      - embed (Optional[`Embed`]) – The embed to edit the message with. `None` suppresses the embeds. This should not be mixed with the `embeds` parameter.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Note

        New files will always appear after current attachments.

        Added in version 2.0.

      - allowed_mentions (`AllowedMentions`) – Controls the mentions being processed in this message. See `abc.Messageable.send()` for more information.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Edited a message that is not yours.

      - TypeError – You specified both `embed` and `embeds`

      - ValueError – The length of `embeds` was invalid or there was no token associated with this webhook.

    Returns:

      The newly edited message.

    Return type:

      `SyncWebhookMessage`

  add_files(*files)

    Adds new files to the end of the message attachments.

    Added in version 2.0.

    Parameters:

      *files (`File`) – New files to add to the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `SyncWebhookMessage`

  remove_attachments(*attachments)

    Removes attachments from the message.

    Added in version 2.0.

    Parameters:

      *attachments (`Attachment`) – Attachments to remove from the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `SyncWebhookMessage`

  delete(*, delay=None)

    Deletes the message.

    Parameters:

      delay (Optional[`float`]) – If provided, the number of seconds to wait before deleting the message. This blocks the thread.

    Raises:

      - Forbidden – You do not have proper permissions to delete the message.

      - NotFound – The message was deleted already.

      - HTTPException – Deleting the message failed.

## Abstract Base Classes

An abstract base class (also known as an `abc`) is a class that models can inherit to get their behaviour. Abstract base classes should not be instantiated. They are mainly there for usage with `isinstance()` and `issubclass()`.

This library has a module related to abstract base classes, in which all the ABCs are subclasses of `typing.Protocol`.

### Snowflake

Attributes

- id

class discord.abc.Snowflake

  An ABC that details the common operations on a Discord model.

  Almost all Discord models meet this abstract base class.

  If you want to create a snowflake on your own, consider using `Object`.

  id

    The model’s unique ID.

    Type:

      `int`

### User

Attributes

- avatar
- avatar_decoration
- avatar_decoration_sku_id
- bot
- default_avatar
- discriminator
- display_avatar
- display_name
- global_name
- mention
- name
- system

Methods

- def mentioned_in

class discord.abc.User

  An ABC that details the common operations on a Discord user.

  The following implement this ABC:

  - `User`

  - `ClientUser`

  - `Member`

  This ABC must also implement `Snowflake`.

  name

    The user’s username.

    Type:

      `str`

  discriminator

    The user’s discriminator. This is a legacy concept that is no longer used.

    Type:

      `str`

  global_name

    The user’s global nickname.

    Type:

      Optional[`str`]

  bot

    If the user is a bot account.

    Type:

      `bool`

  system

    If the user is a system account.

    Type:

      `bool`

  property display_name

    Returns the user’s display name.

    Type:

      `str`

  property mention

    Returns a string that allows you to mention the given user.

    Type:

      `str`

  property avatar

    Returns an Asset that represents the user’s avatar, if present.

    Type:

      Optional[`Asset`]

  property avatar_decoration

    Returns an Asset that represents the user’s avatar decoration, if present.

    Added in version 2.4.

    Type:

      Optional[`Asset`]

  property avatar_decoration_sku_id

    Returns an integer that represents the user’s avatar decoration SKU ID, if present.

    Added in version 2.4.

    Type:

      Optional[`int`]

  property default_avatar

    Returns the default avatar for a given user.

    Type:

      `Asset`

  property display_avatar

    Returns the user’s display avatar.

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

    Added in version 2.0.

    Type:

      `Asset`

  mentioned_in(message)

    Checks if the user is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the user is mentioned in the message.

    Return type:

      `bool`

### PrivateChannel

Attributes

- me

class discord.abc.PrivateChannel

  An ABC that details the common operations on a private Discord channel.

  The following implement this ABC:

  - `DMChannel`

  - `GroupChannel`

  This ABC must also implement `Snowflake`.

  me

    The user presenting yourself.

    Type:

      `ClientUser`

### GuildChannel

Attributes

- category
- changed_roles
- created_at
- guild
- jump_url
- mention
- name
- overwrites
- permissions_synced
- position

Methods

- async clone
- async create_invite
- async delete
- async invites
- async move
- def overwrites_for
- def permissions_for
- async set_permissions

class discord.abc.GuildChannel

  An ABC that details the common operations on a Discord guild channel.

  The following implement this ABC:

  - `TextChannel`

  - `VoiceChannel`

  - `CategoryChannel`

  - `StageChannel`

  - `ForumChannel`

  This ABC must also implement `Snowflake`.

  name

    The channel name.

    Type:

      `str`

  guild

    The guild the channel belongs to.

    Type:

      `Guild`

  position

    The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

    Type:

      `int`

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

### Messageable

Methods

- async fetch_message
- async for history
- async pins
- async send
- def typing

class discord.abc.Messageable

  An ABC that details the common operations on a model that can send messages.

  The following classes implement this ABC:

  - `TextChannel`

  - `VoiceChannel`

  - `StageChannel`

  - `DMChannel`

  - `GroupChannel`

  - `PartialMessageable`

  - `User`

  - `Member`

  - `Context`

  - `Thread`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

### Connectable

Methods

- async connect

class discord.abc.Connectable

  An ABC that details the common operations on a channel that can connect to a voice server.

  The following implement this ABC:

  - `VoiceChannel`

  - `StageChannel`

  await connect(*, timeout=30.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, self_deaf=False, self_mute=False)

    This function is a coroutine.

    Connects to voice and creates a `VoiceClient` to establish your connection to the voice server.

    This requires `voice_states`.

    Parameters:

      - timeout (`float`) – The timeout in seconds to wait the connection to complete.

      - reconnect (`bool`) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.

      - cls (Type[`VoiceProtocol`]) – A type that subclasses `VoiceProtocol` to connect with. Defaults to `VoiceClient`.

      - self_mute (`bool`) –

        Indicates if the client should be self-muted.

        Added in version 2.0.

      - self_deaf (`bool`) –

        Indicates if the client should be self-deafened.

        Added in version 2.0.

    Raises:

      - asyncio.TimeoutError – Could not connect to the voice channel in time.

      - ClientException – You are already connected to a voice channel.

      - OpusNotLoaded – The opus library has not been loaded.

    Returns:

      A voice client that is fully connected to the voice server.

    Return type:

      `VoiceProtocol`

## Discord Models

Models are classes that are received from Discord and are not meant to be created by the user of the library.

Danger

The classes listed below are not intended to be created by users and are also read-only.

For example, this means that you should not make your own `User` instances nor should you modify the `User` instance yourself.

If you want to get one of these model classes instances they’d have to be through the cache, and a common way of doing so is through the `utils.find()` function or attributes of model classes that you receive from the events specified in the Event Reference.

Note

Nearly all classes here have py:slots defined which means that it is impossible to have dynamic attributes to the data classes.

### ClientUser

Attributes

- accent_color
- accent_colour
- avatar
- avatar_decoration
- avatar_decoration_sku_id
- banner
- bot
- color
- colour
- created_at
- default_avatar
- discriminator
- display_avatar
- display_name
- global_name
- id
- locale
- mention
- mfa_enabled
- mutual_guilds
- name
- public_flags
- system
- verified

Methods

- async edit
- def mentioned_in

class discord.ClientUser

  Represents your Discord user.

  x == y

    Checks if two users are equal.

  x != y

    Checks if two users are not equal.

  hash(x)

    Return the user’s hash.

  str(x)

    Returns the user’s handle (e.g. `name` or `name#discriminator`).

  name

    The user’s username.

    Type:

      `str`

  id

    The user’s unique ID.

    Type:

      `int`

  discriminator

    The user’s discriminator. This is a legacy concept that is no longer used.

    Type:

      `str`

  global_name

    The user’s global nickname, taking precedence over the username in display.

    Added in version 2.3.

    Type:

      Optional[`str`]

  bot

    Specifies if the user is a bot account.

    Type:

      `bool`

  system

    Specifies if the user is a system user (i.e. represents Discord officially).

    Added in version 1.3.

    Type:

      `bool`

  verified

    Specifies if the user’s email is verified.

    Type:

      `bool`

  locale

    The IETF language tag used to identify the language the user is using.

    Type:

      Optional[`str`]

  mfa_enabled

    Specifies if the user has MFA turned on and working.

    Type:

      `bool`

  await edit(*, username=..., avatar=..., banner=...)

    This function is a coroutine.

    Edits the current profile of the client.

    Note

    To upload an avatar, a py:bytes-like object must be passed in that represents the image being uploaded. If this is done through a file then the file must be opened via `open('some_filename', 'rb')` and the py:bytes-like object is given through the use of `fp.read()`.

    Changed in version 2.0: The edit is no longer in-place, instead the newly edited client user is returned.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - username (`str`) – The new username you wish to change to.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the image to upload. Could be `None` to denote no avatar. Only image formats supported for uploading are JPEG, PNG, GIF, and WEBP.

      - banner (Optional[`bytes`]) –

        A py:bytes-like object representing the image to upload. Could be `None` to denote no banner. Only image formats supported for uploading are JPEG, PNG, GIF and WEBP.

        Added in version 2.4.

    Raises:

      - HTTPException – Editing your profile failed.

      - ValueError – Wrong image format passed for `avatar`.

    Returns:

      The newly edited client user.

    Return type:

      `ClientUser`

  property mutual_guilds

    The guilds that the user shares with the client.

    Note

    This will only return mutual guilds within the client’s internal cache.

    Added in version 1.7.

    Type:

      List[`Guild`]

  property accent_color

    Returns the user’s accent color, if applicable.

    A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

    There is an alias for this named `accent_colour`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property accent_colour

    Returns the user’s accent colour, if applicable.

    A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

    There is an alias for this named `accent_color`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property avatar

    Returns an `Asset` for the avatar the user has.

    If the user has not uploaded a global avatar, `None` is returned. If you want the avatar that a user has displayed, consider `display_avatar`.

    Type:

      Optional[`Asset`]

  property avatar_decoration

    Returns an `Asset` for the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`Asset`]

  property avatar_decoration_sku_id

    Returns the SKU ID of the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`int`]

  property banner

    Returns the user’s banner asset, if available.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Asset`]

  property color

    A property that returns a color denoting the rendered color for the user. This always returns `Colour.default()`.

    There is an alias for this named `colour`.

    Type:

      `Colour`

  property colour

    A property that returns a colour denoting the rendered colour for the user. This always returns `Colour.default()`.

    There is an alias for this named `color`.

    Type:

      `Colour`

  property created_at

    Returns the user’s creation time in UTC.

    This is when the user’s Discord account was created.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar for a given user.

    Type:

      `Asset`

  property display_avatar

    Returns the user’s display avatar.

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

    Added in version 2.0.

    Type:

      `Asset`

  property display_name

    Returns the user’s display name.

    For regular users this is just their global name or their username, but if they have a guild specific nickname then that is returned instead.

    Type:

      `str`

  property mention

    Returns a string that allows you to mention the given user.

    Type:

      `str`

  mentioned_in(message)

    Checks if the user is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the user is mentioned in the message.

    Return type:

      `bool`

  property public_flags

    The publicly available flags the user has.

    Type:

      `PublicUserFlags`

### User

Attributes

- accent_color
- accent_colour
- avatar
- avatar_decoration
- avatar_decoration_sku_id
- banner
- bot
- color
- colour
- created_at
- default_avatar
- discriminator
- display_avatar
- display_name
- dm_channel
- global_name
- id
- mention
- mutual_guilds
- name
- public_flags
- system

Methods

- async create_dm
- async fetch_message
- async for history
- def mentioned_in
- async pins
- async send
- def typing

class discord.User

  Represents a Discord user.

  x == y

    Checks if two users are equal.

  x != y

    Checks if two users are not equal.

  hash(x)

    Return the user’s hash.

  str(x)

    Returns the user’s handle (e.g. `name` or `name#discriminator`).

  name

    The user’s username.

    Type:

      `str`

  id

    The user’s unique ID.

    Type:

      `int`

  discriminator

    The user’s discriminator. This is a legacy concept that is no longer used.

    Type:

      `str`

  global_name

    The user’s global nickname, taking precedence over the username in display.

    Added in version 2.3.

    Type:

      Optional[`str`]

  bot

    Specifies if the user is a bot account.

    Type:

      `bool`

  system

    Specifies if the user is a system user (i.e. represents Discord officially).

    Type:

      `bool`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property dm_channel

    Returns the channel associated with this user if it exists.

    If this returns `None`, you can create a DM channel by calling the `create_dm()` coroutine function.

    Type:

      Optional[`DMChannel`]

  property mutual_guilds

    The guilds that the user shares with the client.

    Note

    This will only return mutual guilds within the client’s internal cache.

    Added in version 1.7.

    Type:

      List[`Guild`]

  property accent_color

    Returns the user’s accent color, if applicable.

    A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

    There is an alias for this named `accent_colour`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property accent_colour

    Returns the user’s accent colour, if applicable.

    A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

    There is an alias for this named `accent_color`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property avatar

    Returns an `Asset` for the avatar the user has.

    If the user has not uploaded a global avatar, `None` is returned. If you want the avatar that a user has displayed, consider `display_avatar`.

    Type:

      Optional[`Asset`]

  property avatar_decoration

    Returns an `Asset` for the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`Asset`]

  property avatar_decoration_sku_id

    Returns the SKU ID of the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`int`]

  property banner

    Returns the user’s banner asset, if available.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Asset`]

  property color

    A property that returns a color denoting the rendered color for the user. This always returns `Colour.default()`.

    There is an alias for this named `colour`.

    Type:

      `Colour`

  property colour

    A property that returns a colour denoting the rendered colour for the user. This always returns `Colour.default()`.

    There is an alias for this named `color`.

    Type:

      `Colour`

  await create_dm()

    This function is a coroutine.

    Creates a `DMChannel` with this user.

    This should be rarely called, as this is done transparently for most people.

    Returns:

      The channel that was created.

    Return type:

      `DMChannel`

  property created_at

    Returns the user’s creation time in UTC.

    This is when the user’s Discord account was created.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar for a given user.

    Type:

      `Asset`

  property display_avatar

    Returns the user’s display avatar.

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

    Added in version 2.0.

    Type:

      `Asset`

  property display_name

    Returns the user’s display name.

    For regular users this is just their global name or their username, but if they have a guild specific nickname then that is returned instead.

    Type:

      `str`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  property mention

    Returns a string that allows you to mention the given user.

    Type:

      `str`

  mentioned_in(message)

    Checks if the user is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the user is mentioned in the message.

    Return type:

      `bool`

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  property public_flags

    The publicly available flags the user has.

    Type:

      `PublicUserFlags`

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

### AutoMod

Attributes

- actions
- creator
- creator_id
- enabled
- event_type
- exempt_channel_ids
- exempt_channels
- exempt_role_ids
- exempt_roles
- guild
- id
- name
- trigger

Methods

- async delete
- async edit
- def is_exempt

class discord.AutoModRule

  Represents an auto moderation rule.

  Added in version 2.0.

  id

    The ID of the rule.

    Type:

      `int`

  guild

    The guild the rule is for.

    Type:

      `Guild`

  name

    The name of the rule.

    Type:

      `str`

  creator_id

    The ID of the user that created the rule.

    Type:

      `int`

  trigger

    The rule’s trigger.

    Type:

      `AutoModTrigger`

  enabled

    Whether the rule is enabled.

    Type:

      `bool`

  exempt_role_ids

    The IDs of the roles that are exempt from the rule.

    Type:

      Set[`int`]

  exempt_channel_ids

    The IDs of the channels that are exempt from the rule.

    Type:

      Set[`int`]

  event_type

    The type of event that will trigger the the rule.

    Type:

      `AutoModRuleEventType`

  property creator

    The member that created this rule.

    Type:

      Optional[`Member`]

  exempt_roles

    The roles that are exempt from this rule.

    Type:

      List[`Role`]

  exempt_channels

    The channels that are exempt from this rule.

    Type:

      List[Union[`abc.GuildChannel`, `Thread`]]

  actions

    The actions that are taken when this rule is triggered.

    Type:

      List[`AutoModRuleAction`]

  is_exempt(obj, /)

    Check if an object is exempt from the automod rule.

    Parameters:

      obj (`abc.Snowflake`) – The role, channel, or thread to check.

    Returns:

      Whether the object is exempt from the automod rule.

    Return type:

      `bool`

  await edit(*, name=..., event_type=..., actions=..., trigger=..., enabled=..., exempt_roles=..., exempt_channels=..., reason=...)

    This function is a coroutine.

    Edits this auto moderation rule.

    You must have `Permissions.manage_guild` to edit rules.

    Parameters:

      - name (`str`) – The new name to change to.

      - event_type (`AutoModRuleEventType`) – The new event type to change to.

      - actions (List[`AutoModRuleAction`]) – The new rule actions to update.

      - trigger (`AutoModTrigger`) – The new trigger to update. You can only change the trigger metadata, not the type.

      - enabled (`bool`) – Whether the rule should be enabled or not.

      - exempt_roles (Sequence[`abc.Snowflake`]) – The new roles to exempt from the rule.

      - exempt_channels (Sequence[`abc.Snowflake`]) – The new channels to exempt from the rule.

      - reason (`str`) – The reason for updating this rule. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permission to edit this rule.

      - HTTPException – Editing the rule failed.

    Returns:

      The updated auto moderation rule.

    Return type:

      `AutoModRule`

  await delete(*, reason=...)

    This function is a coroutine.

    Deletes the auto moderation rule.

    You must have `Permissions.manage_guild` to delete rules.

    Parameters:

      reason (`str`) – The reason for deleting this rule. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to delete the rule.

      - HTTPException – Deleting the rule failed.

Attributes

- action
- alert_system_message_id
- channel
- channel_id
- content
- guild
- guild_id
- matched_content
- matched_keyword
- member
- message_id
- rule_id
- rule_trigger_type
- user_id

Methods

- async fetch_rule

class discord.AutoModAction

  Represents an action that was taken as the result of a moderation rule.

  Added in version 2.0.

  action

    The action that was taken.

    Type:

      `AutoModRuleAction`

  message_id

    The message ID that triggered the action. This is only available if the action is done on an edited message.

    Type:

      Optional[`int`]

  rule_id

    The ID of the rule that was triggered.

    Type:

      `int`

  rule_trigger_type

    The trigger type of the rule that was triggered.

    Type:

      `AutoModRuleTriggerType`

  guild_id

    The ID of the guild where the rule was triggered.

    Type:

      `int`

  user_id

    The ID of the user that triggered the rule.

    Type:

      `int`

  channel_id

    The ID of the channel where the rule was triggered.

    Type:

      `int`

  alert_system_message_id

    The ID of the system message that was sent to the predefined alert channel.

    Type:

      Optional[`int`]

  content

    The content of the message that triggered the rule. Requires the `Intents.message_content` or it will always return an empty string.

    Type:

      `str`

  matched_keyword

    The matched keyword from the triggering message.

    Type:

      Optional[`str`]

  matched_content

    The matched content from the triggering message. Requires the `Intents.message_content` or it will always return `None`.

    Type:

      Optional[`str`]

  property guild

    The guild this action was taken in.

    Type:

      `Guild`

  property channel

    The channel this action was taken in.

    Type:

      Optional[Union[`abc.GuildChannel`, `Thread`]]

  property member

    The member this action was taken against /who triggered this rule.

    Type:

      Optional[`Member`]

  await fetch_rule()

    This function is a coroutine.

    Fetch the rule whose action was taken.

    You must have `Permissions.manage_guild` to do this.

    Raises:

      - Forbidden – You do not have permissions to view the rule.

      - HTTPException – Fetching the rule failed.

    Returns:

      The rule that was executed.

    Return type:

      `AutoModRule`

### Attachment

Attributes

- content_type
- description
- duration
- ephemeral
- filename
- flags
- height
- id
- proxy_url
- size
- title
- url
- waveform
- width

Methods

- def is_spoiler
- def is_voice_message
- async read
- async save
- async to_file

class discord.Attachment

  Represents an attachment from Discord.

  str(x)

    Returns the URL of the attachment.

  x == y

    Checks if the attachment is equal to another attachment.

  x != y

    Checks if the attachment is not equal to another attachment.

  hash(x)

    Returns the hash of the attachment.

  Changed in version 1.7: Attachment can now be casted to `str` and is hashable.

  id

    The attachment ID.

    Type:

      `int`

  size

    The attachment size in bytes.

    Type:

      `int`

  height

    The attachment’s height, in pixels. Only applicable to images and videos.

    Type:

      Optional[`int`]

  width

    The attachment’s width, in pixels. Only applicable to images and videos.

    Type:

      Optional[`int`]

  filename

    The attachment’s filename.

    Type:

      `str`

  url

    The attachment URL. If the message this attachment was attached to is deleted, then this will 404.

    Type:

      `str`

  proxy_url

    The proxy URL. This is a cached version of the `url` in the case of images. When the message is deleted, this URL might be valid for a few minutes or not valid at all.

    Type:

      `str`

  content_type

    The attachment’s media type

    Added in version 1.7.

    Type:

      Optional[`str`]

  description

    The attachment’s description. Only applicable to images.

    Added in version 2.0.

    Type:

      Optional[`str`]

  ephemeral

    Whether the attachment is ephemeral.

    Added in version 2.0.

    Type:

      `bool`

  duration

    The duration of the audio file in seconds. Returns `None` if it’s not a voice message.

    Added in version 2.3.

    Type:

      Optional[`float`]

  waveform

    The waveform (amplitudes) of the audio in bytes. Returns `None` if it’s not a voice message.

    Added in version 2.3.

    Type:

      Optional[`bytes`]

  title

    The normalised version of the attachment’s filename.

    Added in version 2.5.

    Type:

      Optional[`str`]

  property flags

    The attachment’s flags.

    Type:

      `AttachmentFlags`

  is_spoiler()

    `bool`: Whether this attachment contains a spoiler.

  is_voice_message()

    `bool`: Whether this attachment is a voice message.

  await save(fp, *, seek_begin=True, use_cached=False)

    This function is a coroutine.

    Saves this attachment into a file-like object.

    Parameters:

      - fp (Union[`io.BufferedIOBase`, `os.PathLike`]) – The file-like object to save this attachment to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

      - seek_begin (`bool`) – Whether to seek to the beginning of the file after saving is successfully done.

      - use_cached (`bool`) – Whether to use `proxy_url` rather than `url` when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

    Raises:

      - HTTPException – Saving the attachment failed.

      - NotFound – The attachment was deleted.

    Returns:

      The number of bytes written.

    Return type:

      `int`

  await read(*, use_cached=False)

    This function is a coroutine.

    Retrieves the content of this attachment as a `bytes` object.

    Added in version 1.1.

    Parameters:

      use_cached (`bool`) – Whether to use `proxy_url` rather than `url` when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

    Raises:

      - HTTPException – Downloading the attachment failed.

      - Forbidden – You do not have permissions to access this attachment

      - NotFound – The attachment was deleted.

    Returns:

      The contents of the attachment.

    Return type:

      `bytes`

  await to_file(*, filename=..., description=..., use_cached=False, spoiler=False)

    This function is a coroutine.

    Converts the attachment into a `File` suitable for sending via `abc.Messageable.send()`.

    Added in version 1.3.

    Parameters:

      - filename (Optional[`str`]) –

        The filename to use for the file. If not specified then the filename of the attachment is used instead.

        Added in version 2.0.

      - description (Optional[`str`]) –

        The description to use for the file. If not specified then the description of the attachment is used instead.

        Added in version 2.0.

      - use_cached (`bool`) –

        Whether to use `proxy_url` rather than `url` when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

        Added in version 1.4.

      - spoiler (`bool`) –

        Whether the file is a spoiler.

        Added in version 1.4.

    Raises:

      - HTTPException – Downloading the attachment failed.

      - Forbidden – You do not have permissions to access this attachment

      - NotFound – The attachment was deleted.

    Returns:

      The attachment as a file suitable for sending.

    Return type:

      `File`

### Asset

Attributes

- key
- url

Methods

- def is_animated
- async read
- def replace
- async save
- async to_file
- def with_format
- def with_size
- def with_static_format

class discord.Asset

  Represents a CDN asset on Discord.

  str(x)

    Returns the URL of the CDN asset.

  len(x)

    Returns the length of the CDN asset’s URL.

  x == y

    Checks if the asset is equal to another asset.

  x != y

    Checks if the asset is not equal to another asset.

  hash(x)

    Returns the hash of the asset.

  property url

    Returns the underlying URL of the asset.

    Type:

      `str`

  property key

    Returns the identifying key of the asset.

    Type:

      `str`

  is_animated()

    `bool`: Returns whether the asset is animated.

  replace(*, size=..., format=..., static_format=...)

    Returns a new asset with the passed components replaced.

    Changed in version 2.0: `static_format` is now preferred over `format` if both are present and the asset is not animated.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - size (`int`) – The new size of the asset.

      - format (`str`) – The new format to change it to. Must be either ‘webp’, ‘jpeg’, ‘jpg’, ‘png’, or ‘gif’ if it’s animated.

      - static_format (`str`) – The new format to change it to if the asset isn’t animated. Must be either ‘webp’, ‘jpeg’, ‘jpg’, or ‘png’.

    Raises:

      ValueError – An invalid size or format was passed.

    Returns:

      The newly updated asset.

    Return type:

      `Asset`

  with_size(size, /)

    Returns a new asset with the specified size.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      size (`int`) – The new size of the asset.

    Raises:

      ValueError – The asset had an invalid size.

    Returns:

      The new updated asset.

    Return type:

      `Asset`

  with_format(format, /)

    Returns a new asset with the specified format.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      format (`str`) – The new format of the asset.

    Raises:

      ValueError – The asset had an invalid format.

    Returns:

      The new updated asset.

    Return type:

      `Asset`

  with_static_format(format, /)

    Returns a new asset with the specified static format.

    This only changes the format if the underlying asset is not animated. Otherwise, the asset is not changed.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      format (`str`) – The new static format of the asset.

    Raises:

      ValueError – The asset had an invalid format.

    Returns:

      The new updated asset.

    Return type:

      `Asset`

  await read()

    This function is a coroutine.

    Retrieves the content of this asset as a `bytes` object.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The content of the asset.

    Return type:

      `bytes`

  await save(fp, *, seek_begin=True)

    This function is a coroutine.

    Saves this asset into a file-like object.

    Parameters:

      - fp (Union[`io.BufferedIOBase`, `os.PathLike`]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

      - seek_begin (`bool`) – Whether to seek to the beginning of the file after saving is successfully done.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The number of bytes written.

    Return type:

      `int`

  await to_file(*, filename=..., description=None, spoiler=False)

    This function is a coroutine.

    Converts the asset into a `File` suitable for sending via `abc.Messageable.send()`.

    Added in version 2.0.

    Parameters:

      - filename (Optional[`str`]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.

      - description (Optional[`str`]) – The description for the file.

      - spoiler (`bool`) – Whether the file is a spoiler.

    Raises:

      - DiscordException – The asset does not have an associated state.

      - ValueError – The asset is a unicode emoji.

      - TypeError – The asset is a sticker with lottie type.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The asset as a file suitable for sending.

    Return type:

      `File`

### Message

Attributes

- activity
- application
- application_id
- attachments
- author
- call
- channel
- channel_mentions
- clean_content
- components
- content
- created_at
- edited_at
- embeds
- flags
- guild
- id
- interaction
- interaction_metadata
- jump_url
- mention_everyone
- mentions
- message_snapshots
- nonce
- pinned
- poll
- position
- purchase_notification
- raw_channel_mentions
- raw_mentions
- raw_role_mentions
- reactions
- reference
- role_mentions
- role_subscription
- stickers
- system_content
- thread
- tts
- type
- webhook_id

Methods

- async add_files
- async add_reaction
- async clear_reaction
- async clear_reactions
- async create_thread
- async delete
- async edit
- async end_poll
- async fetch
- async fetch_thread
- async forward
- def is_system
- async pin
- async publish
- async remove_attachments
- async remove_reaction
- async reply
- def to_reference
- async unpin

class discord.Message

  Represents a message from Discord.

  x == y

    Checks if two messages are equal.

  x != y

    Checks if two messages are not equal.

  hash(x)

    Returns the message’s hash.

  tts

    Specifies if the message was done with text-to-speech. This can only be accurately received in `on_message()` due to a discord limitation.

    Type:

      `bool`

  type

    The type of message. In most cases this should not be checked, but it is helpful in cases where it might be a system message for `system_content`.

    Type:

      `MessageType`

  author

    A `Member` that sent the message. If `channel` is a private channel or the user has the left the guild, then it is a `User` instead.

    Type:

      Union[`Member`, `abc.User`]

  content

    The actual contents of the message. If `Intents.message_content` is not enabled this will always be an empty string unless the bot is mentioned or the message is a direct message.

    Type:

      `str`

  nonce

    The value used by the discord guild and the client to verify that the message is successfully sent. This is not stored long term within Discord’s servers and is only used ephemerally.

    Type:

      Optional[Union[`str`, `int`]]

  embeds

    A list of embeds the message has. If `Intents.message_content` is not enabled this will always be an empty list unless the bot is mentioned or the message is a direct message.

    Type:

      List[`Embed`]

  channel

    The `TextChannel` or `Thread` that the message was sent from. Could be a `DMChannel` or `GroupChannel` if it’s a private message.

    Type:

      Union[`TextChannel`, `StageChannel`, `VoiceChannel`, `Thread`, `DMChannel`, `GroupChannel`, `PartialMessageable`]

  reference

    The message that this message references. This is only applicable to messages of type `MessageType.pins_add`, crossposted messages created by a followed channel integration, or message replies.

    Added in version 1.5.

    Type:

      Optional[`MessageReference`]

  mention_everyone

    Specifies if the message mentions everyone.

    Note

    This does not check if the `@everyone` or the `@here` text is in the message itself. Rather this boolean indicates if either the `@everyone` or the `@here` text is in the message and it did end up mentioning.

    Type:

      `bool`

  mentions

    A list of `Member` that were mentioned. If the message is in a private message then the list will be of `User` instead. For messages that are not of type `MessageType.default`, this array can be used to aid in system messages. For more information, see `system_content`.

    Warning

    The order of the mentions list is not in any particular order so you should not rely on it. This is a Discord limitation, not one with the library.

    Type:

      List[`abc.User`]

  channel_mentions

    A list of `abc.GuildChannel` or `Thread` that were mentioned. If the message is in a private message then the list is always empty.

    Type:

      List[Union[`abc.GuildChannel`, `Thread`]]

  role_mentions

    A list of `Role` that were mentioned. If the message is in a private message then the list is always empty.

    Type:

      List[`Role`]

  id

    The message ID.

    Type:

      `int`

  webhook_id

    If this message was sent by a webhook, then this is the webhook ID’s that sent this message.

    Type:

      Optional[`int`]

  attachments

    A list of attachments given to a message. If `Intents.message_content` is not enabled this will always be an empty list unless the bot is mentioned or the message is a direct message.

    Type:

      List[`Attachment`]

  pinned

    Specifies if the message is currently pinned.

    Type:

      `bool`

  flags

    Extra features of the message.

    Added in version 1.3.

    Type:

      `MessageFlags`

  reactions

    Reactions to a message. Reactions can be either custom emoji or standard unicode emoji.

    Type:

      List[`Reaction`]

  activity

    The activity associated with this message. Sent with Rich-Presence related messages that for example, request joining, spectating, or listening to or with another member.

    It is a dictionary with the following optional keys:

    - `type`: An integer denoting the type of message activity being requested.

    - `party_id`: The party ID associated with the party.

    Type:

      Optional[`dict`]

  application

    The rich presence enabled application associated with this message.

    Changed in version 2.0: Type is now `MessageApplication` instead of `dict`.

    Type:

      Optional[`MessageApplication`]

  stickers

    A list of sticker items given to the message.

    Added in version 1.6.

    Type:

      List[`StickerItem`]

  components

    A list of components in the message. If `Intents.message_content` is not enabled this will always be an empty list unless the bot is mentioned or the message is a direct message.

    Added in version 2.0.

    Type:

      List[Union[`ActionRow`, `Button`, `SelectMenu`]]

  role_subscription

    The data of the role subscription purchase or renewal that prompted this `MessageType.role_subscription_purchase` message.

    Added in version 2.2.

    Type:

      Optional[`RoleSubscriptionInfo`]

  application_id

    The application ID of the application that created this message if this message was sent by an application-owned webhook or an interaction.

    Added in version 2.2.

    Type:

      Optional[`int`]

  position

    A generally increasing integer with potentially gaps or duplicates that represents the approximate position of the message in a thread.

    Added in version 2.2.

    Type:

      Optional[`int`]

  guild

    The guild that the message belongs to, if applicable.

    Type:

      Optional[`Guild`]

  interaction_metadata

    The metadata of the interaction that this message is a response to.

    Added in version 2.4.

    Type:

      Optional[`MessageInteractionMetadata`]

  poll

    The poll attached to this message.

    Added in version 2.4.

    Type:

      Optional[`Poll`]

  call

    The call associated with this message.

    Added in version 2.5.

    Type:

      Optional[`CallMessage`]

  purchase_notification

    The data of the purchase notification that prompted this `MessageType.purchase_notification` message.

    Added in version 2.5.

    Type:

      Optional[`PurchaseNotification`]

  message_snapshots

    The message snapshots attached to this message.

    Added in version 2.5.

    Type:

      List[`MessageSnapshot`]

  await add_reaction(emoji, /)

    This function is a coroutine.

    Adds a reaction to the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `read_message_history` to do this. If nobody else has reacted to the message using this emoji, `add_reactions` is required.

    Changed in version 2.0: `emoji` parameter is now positional-only.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to react with.

    Raises:

      - HTTPException – Adding the reaction failed.

      - Forbidden – You do not have the proper permissions to react to the message.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await clear_reaction(emoji)

    This function is a coroutine.

    Clears a specific reaction from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `manage_messages` to do this.

    Added in version 1.3.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to clear.

    Raises:

      - HTTPException – Clearing the reaction failed.

      - Forbidden – You do not have the proper permissions to clear the reaction.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await clear_reactions()

    This function is a coroutine.

    Removes all the reactions from the message.

    You must have `manage_messages` to do this.

    Raises:

      - HTTPException – Removing the reactions failed.

      - Forbidden – You do not have the proper permissions to remove all the reactions.

  await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)

    This function is a coroutine.

    Creates a public thread from this message.

    You must have `create_public_threads` in order to create a public thread from a message.

    The channel this message belongs in must be a `TextChannel`.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the thread.

      - auto_archive_duration (`int`) –

        The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

        Must be one of `60`, `1440`, `4320`, or `10080`, if provided.

      - slowmode_delay (Optional[`int`]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`. By default no slowmode rate limit if this is `None`.

      - reason (Optional[`str`]) – The reason for creating a new thread. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a thread.

      - HTTPException – Creating the thread failed.

      - ValueError – This message does not have guild info attached.

    Returns:

      The created thread.

    Return type:

      `Thread`

  await delete(*, delay=None)

    This function is a coroutine.

    Deletes the message.

    Your own messages could be deleted without any proper permissions. However to delete other people’s messages, you must have `manage_messages`.

    Changed in version 1.1: Added the new `delay` keyword-only parameter.

    Parameters:

      delay (Optional[`float`]) – If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored.

    Raises:

      - Forbidden – You do not have proper permissions to delete the message.

      - NotFound – The message was deleted already

      - HTTPException – Deleting the message failed.

  await end_poll()

    This function is a coroutine.

    Ends the `Poll` attached to this message.

    This can only be done if you are the message author.

    If the poll was successfully ended, then it returns the updated `Message`.

    Raises:

      HTTPException – Ending the poll failed.

    Returns:

      The updated message.

    Return type:

      `Message`

  await fetch()

    This function is a coroutine.

    Fetches the partial message to a full `Message`.

    Raises:

      - NotFound – The message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The full message.

    Return type:

      `Message`

  await fetch_thread()

    This function is a coroutine.

    Retrieves the public thread attached to this message.

    Note

    This method is an API call. For general usage, consider `thread` instead.

    Added in version 2.4.

    Raises:

      - InvalidData – An unknown channel type was received from Discord or the guild the thread belongs to is not the same as the one in this object points to.

      - HTTPException – Retrieving the thread failed.

      - NotFound – There is no thread attached to this message.

      - Forbidden – You do not have permission to fetch this channel.

    Returns:

      The public thread attached to this message.

    Return type:

      `Thread`

  await forward(destination, *, fail_if_not_exists=True)

    This function is a coroutine.

    Forwards this message to a channel.

    Added in version 2.5.

    Parameters:

      - destination (`Messageable`) – The channel to forward this message to.

      - fail_if_not_exists (`bool`) – Whether replying using the message reference should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

    Raises:

      HTTPException – Forwarding the message failed.

    Returns:

      The message sent to the channel.

    Return type:

      `Message`

  property jump_url

    Returns a URL that allows the client to jump to this message.

    Type:

      `str`

  await pin(*, reason=None)

    This function is a coroutine.

    Pins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for pinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to pin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages.

  await publish()

    This function is a coroutine.

    Publishes this message to the channel’s followers.

    The message must have been sent in a news channel. You must have `send_messages` to do this.

    If the message is not your own then `manage_messages` is also needed.

    Raises:

      - Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.

      - HTTPException – Publishing the message failed.

  await remove_reaction(emoji, member)

    This function is a coroutine.

    Remove a reaction by the member from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    If the reaction is not your own (i.e. `member` parameter is not you) then `manage_messages` is needed.

    The `member` parameter must represent a member and meet the `abc.Snowflake` abc.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to remove.

      - member (`abc.Snowflake`) – The member for which to remove the reaction.

    Raises:

      - HTTPException – Removing the reaction failed.

      - Forbidden – You do not have the proper permissions to remove the reaction.

      - NotFound – The member or emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await reply(content=None, **kwargs)

    This function is a coroutine.

    A shortcut method to `abc.Messageable.send()` to reply to the `Message`.

    Added in version 1.6.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` list is not of the appropriate size

      - TypeError – You specified both `file` and `files`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  to_reference(*, fail_if_not_exists=True, type=('default', 0))

    Creates a `MessageReference` from the current message.

    Added in version 1.6.

    Parameters:

      - fail_if_not_exists (`bool`) –

        Whether the referenced message should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

        Added in version 1.7.

      - type (`MessageReferenceType`) –

        The type of message reference.

        Added in version 2.5.

    Returns:

      The reference to this message.

    Return type:

      `MessageReference`

  await unpin(*, reason=None)

    This function is a coroutine.

    Unpins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for unpinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to unpin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Unpinning the message failed.

  raw_mentions

    A property that returns an array of user IDs matched with the syntax of `<@user_id>` in the message content.

    This allows you to receive the user IDs of mentioned users even in a private message context.

    Type:

      List[`int`]

  raw_channel_mentions

    A property that returns an array of channel IDs matched with the syntax of `<#channel_id>` in the message content.

    Type:

      List[`int`]

  raw_role_mentions

    A property that returns an array of role IDs matched with the syntax of `<@&role_id>` in the message content.

    Type:

      List[`int`]

  clean_content

    A property that returns the content in a “cleaned up” manner. This basically means that mentions are transformed into the way the client shows it. e.g. `<#id>` will transform into `#name`.

    This will also transform @everyone and @here mentions into non-mentions.

    Note

    This does not affect markdown. If you want to escape or remove markdown then use `utils.escape_markdown()` or `utils.remove_markdown()` respectively, along with this function.

    Type:

      `str`

  property created_at

    The message’s creation time in UTC.

    Type:

      `datetime.datetime`

  property edited_at

    An aware UTC datetime object containing the edited time of the message.

    Type:

      Optional[`datetime.datetime`]

  property thread

    The public thread created from this message, if it exists.

    Note

    For messages received via the gateway this does not retrieve archived threads, as they are not retained in the internal cache. Use `fetch_thread()` instead.

    Added in version 2.4.

    Type:

      Optional[`Thread`]

  property interaction

    The interaction that this message is a response to.

    Added in version 2.0.

    Deprecated since version 2.4: This attribute is deprecated and will be removed in a future version. Use `interaction_metadata` instead.

    Type:

      Optional[`MessageInteraction`]

  is_system()

    `bool`: Whether the message is a system message.

    A system message is a message that is constructed entirely by the Discord API in response to something.

    Added in version 1.3.

  system_content

    A property that returns the content that is rendered regardless of the `Message.type`.

    In the case of `MessageType.default` and `MessageType.reply`, this just returns the regular `Message.content`. Otherwise this returns an English message denoting the contents of the system message.

    Type:

      `str`

  await edit(*, content=..., embed=..., embeds=..., attachments=..., suppress=False, delete_after=None, allowed_mentions=..., view=...)

    This function is a coroutine.

    Edits the message.

    The content must be able to be transformed into a string via `str(content)`.

    Changed in version 1.3: The `suppress` keyword-only parameter was added.

    Changed in version 2.0: Edits are no longer in-place, the newly edited message is returned instead.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The new content to replace the message with. Could be `None` to remove the content.

      - embed (Optional[`Embed`]) – The new embed to replace the original with. Could be `None` to remove the embed.

      - embeds (List[`Embed`]) –

        The new embeds to replace the original with. Must be a maximum of 10. To remove all embeds `[]` should be passed.

        Added in version 2.0.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Note

        New files will always appear after current attachments.

        Added in version 2.0.

      - suppress (`bool`) – Whether to suppress embeds for the message. This removes all the embeds if set to `True`. If set to `False` this brings the embeds back if they were suppressed. Using this parameter requires `manage_messages`.

      - delete_after (Optional[`float`]) – If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored.

      - allowed_mentions (Optional[`AllowedMentions`]) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - view (Optional[`View`]) – The updated view to update this message with. If `None` is passed then the view is removed.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to suppress a message without permissions or edited a message’s content or embed that isn’t yours.

      - NotFound – This message does not exist.

      - TypeError – You specified both `embed` and `embeds`

    Returns:

      The newly edited message.

    Return type:

      `Message`

  await add_files(*files)

    This function is a coroutine.

    Adds new files to the end of the message attachments.

    Added in version 2.0.

    Parameters:

      *files (`File`) – New files to add to the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `Message`

  await remove_attachments(*attachments)

    This function is a coroutine.

    Removes attachments from the message.

    Added in version 2.0.

    Parameters:

      *attachments (`Attachment`) – Attachments to remove from the message.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to edit a message that isn’t yours.

    Returns:

      The newly edited message.

    Return type:

      `Message`

### DeletedReferencedMessage

Attributes

- channel_id
- guild_id
- id

class discord.DeletedReferencedMessage

  A special sentinel type given when the resolved message reference points to a deleted message.

  The purpose of this class is to separate referenced messages that could not be fetched and those that were previously fetched but have since been deleted.

  Added in version 1.6.

  property id

    The message ID of the deleted referenced message.

    Type:

      `int`

  property channel_id

    The channel ID of the deleted referenced message.

    Type:

      `int`

  property guild_id

    The guild ID of the deleted referenced message.

    Type:

      Optional[`int`]

### Reaction

Attributes

- burst_count
- count
- emoji
- me
- me_burst
- message
- normal_count

Methods

- async clear
- def is_custom_emoji
- async remove
- async for users

class discord.Reaction

  Represents a reaction to a message.

  Depending on the way this object was created, some of the attributes can have a value of `None`.

  x == y

    Checks if two reactions are equal. This works by checking if the emoji is the same. So two messages with the same reaction will be considered “equal”.

  x != y

    Checks if two reactions are not equal.

  hash(x)

    Returns the reaction’s hash.

  str(x)

    Returns the string form of the reaction’s emoji.

  emoji

    The reaction emoji. May be a custom emoji, or a unicode emoji.

    Type:

      Union[`Emoji`, `PartialEmoji`, `str`]

  count

    Number of times this reaction was made. This is a sum of `normal_count` and `burst_count`.

    Type:

      `int`

  me

    If the user sent this reaction.

    Type:

      `bool`

  message

    Message this reaction is for.

    Type:

      `Message`

  me_burst

    If the user sent this super reaction.

    Added in version 2.4.

    Type:

      `bool`

  normal_count

    The number of times this reaction was made using normal reactions. This is not available in the gateway events such as `on_reaction_add()` or `on_reaction_remove()`.

    Added in version 2.4.

    Type:

      `int`

  burst_count

    The number of times this reaction was made using super reactions. This is not available in the gateway events such as `on_reaction_add()` or `on_reaction_remove()`.

    Added in version 2.4.

    Type:

      `int`

  is_custom_emoji()

    `bool`: If this is a custom emoji.

  await remove(user)

    This function is a coroutine.

    Remove the reaction by the provided `User` from the message.

    If the reaction is not your own (i.e. `user` parameter is not you) then `manage_messages` is needed.

    The `user` parameter must represent a user or member and meet the `abc.Snowflake` abc.

    Parameters:

      user (`abc.Snowflake`) – The user or member from which to remove the reaction.

    Raises:

      - HTTPException – Removing the reaction failed.

      - Forbidden – You do not have the proper permissions to remove the reaction.

      - NotFound – The user you specified, or the reaction’s message was not found.

  await clear()

    This function is a coroutine.

    Clears this reaction from the message.

    You must have `manage_messages` to do this.

    Added in version 1.3.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Raises:

      - HTTPException – Clearing the reaction failed.

      - Forbidden – You do not have the proper permissions to clear the reaction.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  async for ... in users(*, limit=None, after=None, type=None)

    Returns an asynchronous iterator representing the users that have reacted to the message.

    The `after` parameter must represent a member and meet the `abc.Snowflake` abc.

    Changed in version 2.0: `limit` and `after` parameters are now keyword-only.

    Examples

    Usage

        # I do not actually recommend doing this.
        async for user in reaction.users():
            await channel.send(f'{user} has reacted with {reaction.emoji}!')

    Flattening into a list:

        users = [user async for user in reaction.users()]
        # users is now a list of User...
        winner = random.choice(users)
        await channel.send(f'{winner} has won the raffle.')

    Parameters:

      - limit (Optional[`int`]) – The maximum number of results to return. If not provided, returns all the users who reacted to the message.

      - after (Optional[`abc.Snowflake`]) – For pagination, reactions are sorted by member.

      - type (Optional[`ReactionType`]) –

        The type of reaction to return users from. If not provided, Discord only returns users of reactions with type `normal`.

        Added in version 2.4.

    Raises:

      HTTPException – Getting the users for the reaction failed.

    Yields:

      Union[`User`, `Member`] – The member (if retrievable) or the user that has reacted to this message. The case where it can be a `Member` is in a guild message context. Sometimes it can be a `User` if the member has left the guild.

### Guild

Attributes

- afk_channel
- afk_timeout
- approximate_member_count
- approximate_presence_count
- banner
- bitrate_limit
- categories
- channels
- chunked
- created_at
- default_notifications
- default_role
- description
- discovery_splash
- dm_spam_detected_at
- dms_paused_until
- emoji_limit
- emojis
- explicit_content_filter
- features
- filesize_limit
- forums
- icon
- id
- invites_paused_until
- large
- max_members
- max_presences
- max_stage_video_users
- max_video_channel_users
- me
- member_count
- members
- mfa_level
- name
- nsfw_level
- owner
- owner_id
- preferred_locale
- premium_progress_bar_enabled
- premium_subscriber_role
- premium_subscribers
- premium_subscription_count
- premium_tier
- public_updates_channel
- raid_detected_at
- roles
- rules_channel
- safety_alerts_channel
- scheduled_events
- self_role
- shard_id
- soundboard_sounds
- splash
- stage_channels
- stage_instances
- sticker_limit
- stickers
- system_channel
- system_channel_flags
- text_channels
- threads
- unavailable
- vanity_url
- vanity_url_code
- verification_level
- voice_channels
- voice_client
- widget_channel
- widget_enabled

Methods

- async active_threads
- async for audit_logs
- async ban
- async for bans
- async bulk_ban
- def by_category
- async change_voice_state
- async chunk
- async create_automod_rule
- async create_category
- async create_category_channel
- async create_custom_emoji
- async create_forum
- async create_integration
- async create_role
- async create_scheduled_event
- async create_soundboard_sound
- async create_stage_channel
- async create_sticker
- async create_template
- async create_text_channel
- async create_voice_channel
- async delete
- async delete_emoji
- async delete_sticker
- def dms_paused
- async edit
- async edit_role_positions
- async edit_welcome_screen
- async edit_widget
- async estimate_pruned_members
- async fetch_automod_rule
- async fetch_automod_rules
- async fetch_ban
- async fetch_channel
- async fetch_channels
- async fetch_emoji
- async fetch_emojis
- async fetch_member
- async for fetch_members
- async fetch_role
- async fetch_roles
- async fetch_scheduled_event
- async fetch_scheduled_events
- async fetch_soundboard_sound
- async fetch_soundboard_sounds
- async fetch_sticker
- async fetch_stickers
- def get_channel
- def get_channel_or_thread
- def get_emoji
- def get_member
- def get_member_named
- def get_role
- def get_scheduled_event
- def get_soundboard_sound
- def get_stage_instance
- def get_thread
- async integrations
- async invites
- def invites_paused
- def is_dm_spam_detected
- def is_raid_detected
- async kick
- async leave
- async prune_members
- async query_members
- async templates
- async unban
- async vanity_invite
- async webhooks
- async welcome_screen
- async widget

class discord.Guild

  Represents a Discord guild.

  This is referred to as a “server” in the official Discord UI.

  x == y

    Checks if two guilds are equal.

  x != y

    Checks if two guilds are not equal.

  hash(x)

    Returns the guild’s hash.

  str(x)

    Returns the guild’s name.

  name

    The guild name.

    Type:

      `str`

  emojis

    All emojis that the guild owns.

    Type:

      Tuple[`Emoji`, …]

  stickers

    All stickers that the guild owns.

    Added in version 2.0.

    Type:

      Tuple[`GuildSticker`, …]

  afk_timeout

    The number of seconds until someone is moved to the AFK channel.

    Type:

      `int`

  id

    The guild’s ID.

    Type:

      `int`

  owner_id

    The guild owner’s ID. Use `Guild.owner` instead.

    Type:

      `int`

  unavailable

    Indicates if the guild is unavailable. If this is `True` then the reliability of other attributes outside of `Guild.id` is slim and they might all be `None`. It is best to not do anything with the guild if it is unavailable.

    Check the `on_guild_unavailable()` and `on_guild_available()` events.

    Type:

      `bool`

  max_presences

    The maximum amount of presences for the guild.

    Type:

      Optional[`int`]

  max_members

    The maximum amount of members for the guild.

    Note

    This attribute is only available via `Client.fetch_guild()`.

    Type:

      Optional[`int`]

  max_video_channel_users

    The maximum amount of users in a video channel.

    Added in version 1.4.

    Type:

      Optional[`int`]

  description

    The guild’s description.

    Type:

      Optional[`str`]

  verification_level

    The guild’s verification level.

    Type:

      `VerificationLevel`

  vanity_url_code

    The guild’s vanity url code, if any

    Added in version 2.0.

    Type:

      Optional[`str`]

  explicit_content_filter

    The guild’s explicit content filter.

    Type:

      `ContentFilter`

  default_notifications

    The guild’s notification settings.

    Type:

      `NotificationLevel`

  features

    A list of features that the guild has. The features that a guild can have are subject to arbitrary change by Discord. A list of guild features can be found in the Discord documentation.

    Type:

      List[`str`]

  premium_tier

    The premium tier for this guild. Corresponds to “Nitro Server” in the official UI. The number goes from 0 to 3 inclusive.

    Type:

      `int`

  premium_subscription_count

    The number of “boosts” this guild currently has.

    Type:

      `int`

  preferred_locale

    The preferred locale for the guild. Used when filtering Server Discovery results to a specific language.

    Changed in version 2.0: This field is now an enum instead of a `str`.

    Type:

      `Locale`

  nsfw_level

    The guild’s NSFW level.

    Added in version 2.0.

    Type:

      `NSFWLevel`

  mfa_level

    The guild’s Multi-Factor Authentication requirement level.

    Changed in version 2.0: This field is now an enum instead of an `int`.

    Type:

      `MFALevel`

  approximate_member_count

    The approximate number of members in the guild. This is `None` unless the guild is obtained using `Client.fetch_guild()` or `Client.fetch_guilds()` with `with_counts=True`.

    Added in version 2.0.

    Type:

      Optional[`int`]

  approximate_presence_count

    The approximate number of members currently active in the guild. Offline members are excluded. This is `None` unless the guild is obtained using `Client.fetch_guild()` or `Client.fetch_guilds()` with `with_counts=True`.

    Changed in version 2.0.

    Type:

      Optional[`int`]

  premium_progress_bar_enabled

    Indicates if the guild has premium AKA server boost level progress bar enabled.

    Added in version 2.0.

    Type:

      `bool`

  widget_enabled

    Indicates if the guild has widget enabled.

    Added in version 2.0.

    Type:

      `bool`

  max_stage_video_users

    The maximum amount of users in a stage video channel.

    Added in version 2.3.

    Type:

      Optional[`int`]

  property channels

    A list of channels that belongs to this guild.

    Type:

      Sequence[`abc.GuildChannel`]

  property threads

    A list of threads that you have permission to view.

    Added in version 2.0.

    Type:

      Sequence[`Thread`]

  property large

    Indicates if the guild is a ‘large’ guild.

    A large guild is defined as having more than `large_threshold` count members, which for this library is set to the maximum of 250.

    Type:

      `bool`

  property voice_channels

    A list of voice channels that belongs to this guild.

    This is sorted by the position and are in UI order from top to bottom.

    Type:

      List[`VoiceChannel`]

  property stage_channels

    A list of stage channels that belongs to this guild.

    Added in version 1.7.

    This is sorted by the position and are in UI order from top to bottom.

    Type:

      List[`StageChannel`]

  property me

    Similar to `Client.user` except an instance of `Member`. This is essentially used to get the member version of yourself.

    Type:

      `Member`

  property voice_client

    Returns the `VoiceProtocol` associated with this guild, if any.

    Type:

      Optional[`VoiceProtocol`]

  property text_channels

    A list of text channels that belongs to this guild.

    This is sorted by the position and are in UI order from top to bottom.

    Type:

      List[`TextChannel`]

  property categories

    A list of categories that belongs to this guild.

    This is sorted by the position and are in UI order from top to bottom.

    Type:

      List[`CategoryChannel`]

  property forums

    A list of forum channels that belongs to this guild.

    This is sorted by the position and are in UI order from top to bottom.

    Type:

      List[`ForumChannel`]

  by_category()

    Returns every `CategoryChannel` and their associated channels.

    These channels and categories are sorted in the official Discord UI order.

    If the channels do not have a category, then the first element of the tuple is `None`.

    Returns:

      The categories and their associated channels.

    Return type:

      List[Tuple[Optional[`CategoryChannel`], List[`abc.GuildChannel`]]]

  get_channel_or_thread(channel_id, /)

    Returns a channel or thread with the given ID.

    Added in version 2.0.

    Parameters:

      channel_id (`int`) – The ID to search for.

    Returns:

      The returned channel or thread or `None` if not found.

    Return type:

      Optional[Union[`Thread`, `abc.GuildChannel`]]

  get_channel(channel_id, /)

    Returns a channel with the given ID.

    Note

    This does not search for threads.

    Changed in version 2.0: `channel_id` parameter is now positional-only.

    Parameters:

      channel_id (`int`) – The ID to search for.

    Returns:

      The returned channel or `None` if not found.

    Return type:

      Optional[`abc.GuildChannel`]

  get_thread(thread_id, /)

    Returns a thread with the given ID.

    Note

    This does not always retrieve archived threads, as they are not retained in the internal cache. Use `fetch_channel()` instead.

    Added in version 2.0.

    Parameters:

      thread_id (`int`) – The ID to search for.

    Returns:

      The returned thread or `None` if not found.

    Return type:

      Optional[`Thread`]

  get_emoji(emoji_id, /)

    Returns an emoji with the given ID.

    Added in version 2.3.

    Parameters:

      emoji_id (int) – The ID to search for.

    Returns:

      The returned Emoji or `None` if not found.

    Return type:

      Optional[`Emoji`]

  property afk_channel

    The channel that denotes the AFK channel.

    If no channel is set, then this returns `None`.

    Type:

      Optional[Union[`VoiceChannel`, `StageChannel`]]

  property system_channel

    Returns the guild’s channel used for system messages.

    If no channel is set, then this returns `None`.

    Type:

      Optional[`TextChannel`]

  property system_channel_flags

    Returns the guild’s system channel settings.

    Type:

      `SystemChannelFlags`

  property rules_channel

    Return’s the guild’s channel used for the rules. The guild must be a Community guild.

    If no channel is set, then this returns `None`.

    Added in version 1.3.

    Type:

      Optional[`TextChannel`]

  property public_updates_channel

    Return’s the guild’s channel where admins and moderators of the guilds receive notices from Discord. The guild must be a Community guild.

    If no channel is set, then this returns `None`.

    Added in version 1.4.

    Type:

      Optional[`TextChannel`]

  property safety_alerts_channel

    Return’s the guild’s channel used for safety alerts, if set.

    For example, this is used for the raid protection setting. The guild must have the `COMMUNITY` feature.

    Added in version 2.3.

    Type:

      Optional[`TextChannel`]

  property widget_channel

    Returns the widget channel of the guild.

    If no channel is set, then this returns `None`.

    Added in version 2.3.

    Type:

      Optional[Union[`TextChannel`, `ForumChannel`, `VoiceChannel`, `StageChannel`]]

  property emoji_limit

    The maximum number of emoji slots this guild has.

    Type:

      `int`

  property sticker_limit

    The maximum number of sticker slots this guild has.

    Added in version 2.0.

    Type:

      `int`

  property bitrate_limit

    The maximum bitrate for voice channels this guild can have.

    Type:

      `float`

  property filesize_limit

    The maximum number of bytes files can have when uploaded to this guild.

    Type:

      `int`

  property members

    A list of members that belong to this guild.

    Type:

      Sequence[`Member`]

  get_member(user_id, /)

    Returns a member with the given ID.

    Changed in version 2.0: `user_id` parameter is now positional-only.

    Parameters:

      user_id (`int`) – The ID to search for.

    Returns:

      The member or `None` if not found.

    Return type:

      Optional[`Member`]

  property premium_subscribers

    A list of members who have “boosted” this guild.

    Type:

      List[`Member`]

  property roles

    Returns a sequence of the guild’s roles in hierarchy order.

    The first element of this sequence will be the lowest role in the hierarchy.

    Type:

      Sequence[`Role`]

  get_role(role_id, /)

    Returns a role with the given ID.

    Changed in version 2.0: `role_id` parameter is now positional-only.

    Parameters:

      role_id (`int`) – The ID to search for.

    Returns:

      The role or `None` if not found.

    Return type:

      Optional[`Role`]

  property default_role

    Gets the @everyone role that all members have by default.

    Type:

      `Role`

  property premium_subscriber_role

    Gets the premium subscriber role, AKA “boost” role, in this guild.

    Added in version 1.6.

    Type:

      Optional[`Role`]

  property self_role

    Gets the role associated with this client’s user, if any.

    Added in version 1.6.

    Type:

      Optional[`Role`]

  property stage_instances

    Returns a sequence of the guild’s stage instances that are currently running.

    Added in version 2.0.

    Type:

      Sequence[`StageInstance`]

  get_stage_instance(stage_instance_id, /)

    Returns a stage instance with the given ID.

    Added in version 2.0.

    Parameters:

      stage_instance_id (`int`) – The ID to search for.

    Returns:

      The stage instance or `None` if not found.

    Return type:

      Optional[`StageInstance`]

  property scheduled_events

    Returns a sequence of the guild’s scheduled events.

    Added in version 2.0.

    Type:

      Sequence[`ScheduledEvent`]

  get_scheduled_event(scheduled_event_id, /)

    Returns a scheduled event with the given ID.

    Added in version 2.0.

    Parameters:

      scheduled_event_id (`int`) – The ID to search for.

    Returns:

      The scheduled event or `None` if not found.

    Return type:

      Optional[`ScheduledEvent`]

  property soundboard_sounds

    Returns a sequence of the guild’s soundboard sounds.

    Added in version 2.5.

    Type:

      Sequence[`SoundboardSound`]

  get_soundboard_sound(sound_id, /)

    Returns a soundboard sound with the given ID.

    Added in version 2.5.

    Parameters:

      sound_id (`int`) – The ID to search for.

    Returns:

      The soundboard sound or `None` if not found.

    Return type:

      Optional[`SoundboardSound`]

  property owner

    The member that owns the guild.

    Type:

      Optional[`Member`]

  property icon

    Returns the guild’s icon asset, if available.

    Type:

      Optional[`Asset`]

  property banner

    Returns the guild’s banner asset, if available.

    Type:

      Optional[`Asset`]

  property splash

    Returns the guild’s invite splash asset, if available.

    Type:

      Optional[`Asset`]

  property discovery_splash

    Returns the guild’s discovery splash asset, if available.

    Type:

      Optional[`Asset`]

  property member_count

    Returns the member count if available.

    Warning

    Due to a Discord limitation, in order for this attribute to remain up-to-date and accurate, it requires `Intents.members` to be specified.

    Changed in version 2.0: Now returns an `Optional[int]`.

    Type:

      Optional[`int`]

  property chunked

    Returns a boolean indicating if the guild is “chunked”.

    A chunked guild means that `member_count` is equal to the number of members stored in the internal `members` cache.

    If this value returns `False`, then you should request for offline members.

    Type:

      `bool`

  property shard_id

    Returns the shard ID for this guild if applicable.

    Type:

      `int`

  property created_at

    Returns the guild’s creation time in UTC.

    Type:

      `datetime.datetime`

  get_member_named(name, /)

    Returns the first member found that matches the name provided.

    The name is looked up in the following order:

    - Username#Discriminator (deprecated)

    - Username#0 (deprecated, only gets users that migrated from their discriminator)

    - Nickname

    - Global name

    - Username

    If no member is found, `None` is returned.

    Changed in version 2.0: `name` parameter is now positional-only.

    Deprecated since version 2.3: Looking up users via discriminator due to Discord API change.

    Parameters:

      name (`str`) – The name of the member to lookup.

    Returns:

      The member in this guild with the associated name. If not found then `None` is returned.

    Return type:

      Optional[`Member`]

  await create_text_channel(name, *, reason=None, category=None, news=False, position=..., topic=..., slowmode_delay=..., nsfw=..., overwrites=..., default_auto_archive_duration=..., default_thread_slowmode_delay=...)

    This function is a coroutine.

    Creates a `TextChannel` for the guild.

    Note that you must have `manage_channels` to create the channel.

    The `overwrites` parameter can be used to create a ‘secret’ channel upon creation. This parameter expects a `dict` of overwrites with the target (either a `Member` or a `Role`) as the key and a `PermissionOverwrite` as the value.

    Note

    Creating a channel of a specified position will not update the position of other channels to follow suit. A follow-up call to `edit()` will be required to update the position of the channel in the channel list.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Examples

    Creating a basic channel:

        channel = await guild.create_text_channel('cool-channel')

    Creating a “secret” channel:

        overwrites = {
            guild.default_role: discord.PermissionOverwrite(read_messages=False),
            guild.me: discord.PermissionOverwrite(read_messages=True)
        }

        channel = await guild.create_text_channel('secret', overwrites=overwrites)

    Parameters:

      - name (`str`) – The channel’s name.

      - overwrites (Dict[Union[`Role`, `Member`], `PermissionOverwrite`]) – A `dict` of target (either a role or a member) to `PermissionOverwrite` to apply upon creation of a channel. Useful for creating secret channels.

      - category (Optional[`CategoryChannel`]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.

      - position (`int`) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

      - topic (`str`) – The new channel’s topic.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`.

      - nsfw (`bool`) – To mark the channel as NSFW or not.

      - news (`bool`) –

        Whether to create the text channel as a news channel.

        Added in version 2.0.

      - default_auto_archive_duration (`int`) –

        The default auto archive duration for threads created in the text channel (in minutes). Must be one of `60`, `1440`, `4320`, or `10080`.

        Added in version 2.0.

      - default_thread_slowmode_delay (`int`) –

        The default slowmode delay in seconds for threads created in the text channel.

        Added in version 2.3.

      - reason (Optional[`str`]) – The reason for creating this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `TextChannel`

  await create_voice_channel(name, *, reason=None, category=None, position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., overwrites=...)

    This function is a coroutine.

    This is similar to `create_text_channel()` except makes a `VoiceChannel` instead.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The channel’s name.

      - overwrites (Dict[Union[`Role`, `Member`], `PermissionOverwrite`]) – A `dict` of target (either a role or a member) to `PermissionOverwrite` to apply upon creation of a channel. Useful for creating secret channels.

      - category (Optional[`CategoryChannel`]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.

      - position (`int`) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

      - bitrate (`int`) – The channel’s preferred audio bitrate in bits per second.

      - user_limit (`int`) – The channel’s limit for number of members that can be in a voice channel.

      - rtc_region (Optional[`str`]) –

        The region for the voice channel’s voice communication. A value of `None` indicates automatic voice region detection.

        Added in version 1.7.

      - video_quality_mode (`VideoQualityMode`) –

        The camera video quality for the voice channel’s participants.

        Added in version 2.0.

      - reason (Optional[`str`]) – The reason for creating this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `VoiceChannel`

  await create_stage_channel(name, *, reason=None, category=None, position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., overwrites=...)

    This function is a coroutine.

    This is similar to `create_text_channel()` except makes a `StageChannel` instead.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The channel’s name.

      - overwrites (Dict[Union[`Role`, `Member`], `PermissionOverwrite`]) – A `dict` of target (either a role or a member) to `PermissionOverwrite` to apply upon creation of a channel. Useful for creating secret channels.

      - category (Optional[`CategoryChannel`]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.

      - position (`int`) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

      - bitrate (`int`) –

        The channel’s preferred audio bitrate in bits per second.

        Added in version 2.2.

      - user_limit (`int`) –

        The channel’s limit for number of members that can be in a voice channel.

        Added in version 2.2.

      - rtc_region (Optional[`str`]) –

        The region for the voice channel’s voice communication. A value of `None` indicates automatic voice region detection.

        Added in version 2.2.

      - video_quality_mode (`VideoQualityMode`) –

        The camera video quality for the voice channel’s participants.

        Added in version 2.2.

      - reason (Optional[`str`]) – The reason for creating this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `StageChannel`

  await create_category(name, *, overwrites=..., reason=None, position=...)

    This function is a coroutine.

    Same as `create_text_channel()` except makes a `CategoryChannel` instead.

    Note

    The `category` parameter is not supported in this function since categories cannot have categories.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `CategoryChannel`

  await create_category_channel(name, *, overwrites=..., reason=None, position=...)

    This function is a coroutine.

    Same as `create_text_channel()` except makes a `CategoryChannel` instead.

    Note

    The `category` parameter is not supported in this function since categories cannot have categories.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `CategoryChannel`

  await create_forum(name, *, topic=..., position=..., category=None, slowmode_delay=..., nsfw=..., overwrites=..., reason=None, default_auto_archive_duration=..., default_thread_slowmode_delay=..., default_sort_order=..., default_reaction_emoji=..., default_layout=..., available_tags=...)

    This function is a coroutine.

    Similar to `create_text_channel()` except makes a `ForumChannel` instead.

    The `overwrites` parameter can be used to create a ‘secret’ channel upon creation. This parameter expects a `dict` of overwrites with the target (either a `Member` or a `Role`) as the key and a `PermissionOverwrite` as the value.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The channel’s name.

      - overwrites (Dict[Union[`Role`, `Member`], `PermissionOverwrite`]) – A `dict` of target (either a role or a member) to `PermissionOverwrite` to apply upon creation of a channel. Useful for creating secret channels.

      - topic (`str`) – The channel’s topic.

      - category (Optional[`CategoryChannel`]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.

      - position (`int`) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

      - nsfw (`bool`) – To mark the channel as NSFW or not.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for users in this channel, in seconds. The maximum possible value is `21600`.

      - reason (Optional[`str`]) – The reason for creating this channel. Shows up in the audit log.

      - default_auto_archive_duration (`int`) – The default auto archive duration for threads created in the forum channel (in minutes). Must be one of `60`, `1440`, `4320`, or `10080`.

      - default_thread_slowmode_delay (`int`) –

        The default slowmode delay in seconds for threads created in this forum.

        Added in version 2.1.

      - default_sort_order (`ForumOrderType`) –

        The default sort order for posts in this forum channel.

        Added in version 2.3.

      - default_reaction_emoji (Union[`Emoji`, `PartialEmoji`, `str`]) –

        The default reaction emoji for threads created in this forum to show in the add reaction button.

        Added in version 2.3.

      - default_layout (`ForumLayoutType`) –

        The default layout for posts in this forum.

        Added in version 2.3.

      - available_tags (Sequence[`ForumTag`]) –

        The available tags for this forum channel.

        Added in version 2.1.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

      - TypeError – The permission overwrite information is not in proper form.

    Returns:

      The channel that was just created.

    Return type:

      `ForumChannel`

  await leave()

    This function is a coroutine.

    Leaves the guild.

    Note

    You cannot leave the guild that you own, you must delete it instead via `delete()`.

    Raises:

      HTTPException – Leaving the guild failed.

  await delete()

    This function is a coroutine.

    Deletes the guild. You must be the guild owner to delete the guild.

    Raises:

      - HTTPException – Deleting the guild failed.

      - Forbidden – You do not have permissions to delete the guild.

  await edit(*, reason=..., name=..., description=..., icon=..., banner=..., splash=..., discovery_splash=..., community=..., afk_channel=..., owner=..., afk_timeout=..., default_notifications=..., verification_level=..., explicit_content_filter=..., vanity_code=..., system_channel=..., system_channel_flags=..., preferred_locale=..., rules_channel=..., public_updates_channel=..., premium_progress_bar_enabled=..., discoverable=..., invites_disabled=..., widget_enabled=..., widget_channel=..., mfa_level=..., raid_alerts_disabled=..., safety_alerts_channel=..., invites_disabled_until=..., dms_disabled_until=...)

    This function is a coroutine.

    Edits the guild.

    You must have `manage_guild` to edit the guild.

    Changed in version 2.0: The newly updated guild is returned.

    Changed in version 2.0: The `region` keyword parameter has been removed.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new name of the guild.

      - description (Optional[`str`]) – The new description of the guild. Could be `None` for no description. This is only available to guilds that contain `COMMUNITY` in `Guild.features`.

      - icon (`bytes`) – A py:bytes-like object representing the icon. Only PNG/JPEG is supported. GIF is only available to guilds that contain `ANIMATED_ICON` in `Guild.features`. Could be `None` to denote removal of the icon.

      - banner (`bytes`) – A py:bytes-like object representing the banner. Could be `None` to denote removal of the banner. This is only available to guilds that contain `BANNER` in `Guild.features`.

      - splash (`bytes`) – A py:bytes-like object representing the invite splash. Only PNG/JPEG supported. Could be `None` to denote removing the splash. This is only available to guilds that contain `INVITE_SPLASH` in `Guild.features`.

      - discovery_splash (`bytes`) –

        A py:bytes-like object representing the discovery splash. Only PNG/JPEG supported. Could be `None` to denote removing the splash. This is only available to guilds that contain `DISCOVERABLE` in `Guild.features`.

        Added in version 2.0.

      - community (`bool`) –

        Whether the guild should be a Community guild. If set to `True`, both `rules_channel` and `public_updates_channel` parameters are required.

        Added in version 2.0.

      - afk_channel (Optional[`VoiceChannel`]) – The new channel that is the AFK channel. Could be `None` for no AFK channel.

      - afk_timeout (`int`) – The number of seconds until someone is moved to the AFK channel.

      - owner (`Member`) – The new owner of the guild to transfer ownership to. Note that you must be owner of the guild to do this.

      - verification_level (`VerificationLevel`) – The new verification level for the guild.

      - default_notifications (`NotificationLevel`) – The new default notification level for the guild.

      - explicit_content_filter (`ContentFilter`) – The new explicit content filter for the guild.

      - vanity_code (`str`) – The new vanity code for the guild.

      - system_channel (Optional[`TextChannel`]) – The new channel that is used for the system channel. Could be `None` for no system channel.

      - system_channel_flags (`SystemChannelFlags`) – The new system channel settings to use with the new system channel.

      - preferred_locale (`Locale`) –

        The new preferred locale for the guild. Used as the primary language in the guild.

        Changed in version 2.0: Now accepts an enum instead of `str`.

      - rules_channel (Optional[`TextChannel`]) –

        The new channel that is used for rules. This is only available to guilds that contain `COMMUNITY` in `Guild.features`. Could be `None` for no rules channel.

        Added in version 1.4.

      - public_updates_channel (Optional[`TextChannel`]) –

        The new channel that is used for public updates from Discord. This is only available to guilds that contain `COMMUNITY` in `Guild.features`. Could be `None` for no public updates channel.

        Added in version 1.4.

      - premium_progress_bar_enabled (`bool`) –

        Whether the premium AKA server boost level progress bar should be enabled for the guild.

        Added in version 2.0.

      - discoverable (`bool`) –

        Whether server discovery is enabled for this guild.

        Added in version 2.1.

      - invites_disabled (`bool`) –

        Whether joining via invites should be disabled for the guild.

        Added in version 2.1.

      - widget_enabled (`bool`) –

        Whether to enable the widget for the guild.

        Added in version 2.3.

      - widget_channel (Optional[`abc.Snowflake`]) –

        The new widget channel. `None` removes the widget channel.

        Added in version 2.3.

      - mfa_level (`MFALevel`) –

        The new guild’s Multi-Factor Authentication requirement level. Note that you must be owner of the guild to do this.

        Added in version 2.3.

      - reason (Optional[`str`]) – The reason for editing this guild. Shows up on the audit log.

      - raid_alerts_disabled (`bool`) –

        Whether the alerts for raid protection should be disabled for the guild.

        Added in version 2.3.

      - safety_alerts_channel (Optional[`TextChannel`]) –

        The new channel that is used for safety alerts. This is only available to guilds that contain `COMMUNITY` in `Guild.features`. Could be `None` for no safety alerts channel.

        Added in version 2.3.

      - invites_disabled_until (Optional[`datetime.datetime`]) –

        The time when invites should be enabled again, or `None` to disable the action. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

        Added in version 2.4.

      - dms_disabled_until (Optional[`datetime.datetime`]) –

        The time when direct messages should be allowed again, or `None` to disable the action. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

        Added in version 2.4.

    Raises:

      - Forbidden – You do not have permissions to edit the guild.

      - HTTPException – Editing the guild failed.

      - ValueError – The image format passed in to `icon` is invalid. It must be PNG or JPG. This is also raised if you are not the owner of the guild and request an ownership transfer.

      - TypeError – The type passed to the `default_notifications`, `rules_channel`, `public_updates_channel`, `safety_alerts_channel` `verification_level`, `explicit_content_filter`, `system_channel_flags`, or `mfa_level` parameter was of the incorrect type.

    Returns:

      The newly updated guild. Note that this has the same limitations as mentioned in `Client.fetch_guild()` and may not have full data.

    Return type:

      `Guild`

  await fetch_channels()

    This function is a coroutine.

    Retrieves all `abc.GuildChannel` that the guild has.

    Note

    This method is an API call. For general usage, consider `channels` instead.

    Added in version 1.2.

    Raises:

      - InvalidData – An unknown channel type was received from Discord.

      - HTTPException – Retrieving the channels failed.

    Returns:

      All channels in the guild.

    Return type:

      Sequence[`abc.GuildChannel`]

  await active_threads()

    This function is a coroutine.

    Returns a list of active `Thread` that the client can access.

    This includes both private and public threads.

    Added in version 2.0.

    Raises:

      HTTPException – The request to get the active threads failed.

    Returns:

      The active threads

    Return type:

      List[`Thread`]

  async for ... in fetch_members(*, limit=1000, after=...)

    Retrieves an asynchronous iterator that enables receiving the guild’s members. In order to use this, `Intents.members()` must be enabled.

    Note

    This method is an API call. For general usage, consider `members` instead.

    Added in version 1.3.

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of members to retrieve. Defaults to 1000. Pass `None` to fetch all members. Note that this is potentially slow.

      - after (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Retrieve members after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

    Raises:

      - ClientException – The members intent is not enabled.

      - HTTPException – Getting the members failed.

    Yields:

      `Member` – The member with the member data parsed.

    Examples

    Usage

        async for member in guild.fetch_members(limit=150):
            print(member.name)

  await fetch_member(member_id, /)

    This function is a coroutine.

    Retrieves a `Member` from a guild ID, and a member ID.

    Note

    This method is an API call. If you have `Intents.members` and member cache enabled, consider `get_member()` instead.

    Changed in version 2.0: `member_id` parameter is now positional-only.

    Parameters:

      member_id (`int`) – The member’s ID to fetch from.

    Raises:

      - Forbidden – You do not have access to the guild.

      - HTTPException – Fetching the member failed.

      - NotFound – The member could not be found.

    Returns:

      The member from the member ID.

    Return type:

      `Member`

  await fetch_ban(user)

    This function is a coroutine.

    Retrieves the `BanEntry` for a user.

    You must have `ban_members` to get this information.

    Parameters:

      user (`abc.Snowflake`) – The user to get ban information from.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - NotFound – This user is not banned.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The `BanEntry` object for the specified user.

    Return type:

      `BanEntry`

  await fetch_channel(channel_id, /)

    This function is a coroutine.

    Retrieves a `abc.GuildChannel` or `Thread` with the specified ID.

    Note

    This method is an API call. For general usage, consider `get_channel_or_thread()` instead.

    Added in version 2.0.

    Raises:

      - InvalidData – An unknown channel type was received from Discord or the guild the channel belongs to is not the same as the one in this object points to.

      - HTTPException – Retrieving the channel failed.

      - NotFound – Invalid Channel ID.

      - Forbidden – You do not have permission to fetch this channel.

    Returns:

      The channel from the ID.

    Return type:

      Union[`abc.GuildChannel`, `Thread`]

  async for ... in bans(*, limit=1000, before=..., after=...)

    Retrieves an asynchronous iterator of the users that are banned from the guild as a `BanEntry`.

    You must have `ban_members` to get this information.

    Changed in version 2.0: Due to a breaking change in Discord’s API, this now returns a paginated iterator instead of a list.

    Examples

    Usage

        async for entry in guild.bans(limit=150):
            print(entry.user, entry.reason)

    Flattening into a list

        bans = [entry async for entry in guild.bans(limit=2000)]
        # bans is now a list of BanEntry...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of bans to retrieve. If `None`, it retrieves every ban in the guild. Note, however, that this would make it a slow operation. Defaults to `1000`.

      - before (`abc.Snowflake`) – Retrieves bans before this user.

      - after (`abc.Snowflake`) – Retrieve bans after this user.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

      - TypeError – Both `after` and `before` were provided, as Discord does not support this type of pagination.

    Yields:

      `BanEntry` – The ban entry of the banned user.

  await prune_members(*, days, compute_prune_count=True, roles=..., reason=None)

    This function is a coroutine.

    Prunes the guild from its inactive members.

    The inactive members are denoted if they have not logged on in `days` number of days and they have no roles.

    You must have both `kick_members` and `manage_guild` to do this.

    To check how many members you would prune without actually pruning, see the `estimate_pruned_members()` function.

    To prune members that have specific roles see the `roles` parameter.

    Changed in version 1.4: The `roles` keyword-only parameter was added.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - days (`int`) – The number of days before counting as inactive.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

      - compute_prune_count (`bool`) – Whether to compute the prune count. This defaults to `True` which makes it prone to timeouts in very large guilds. In order to prevent timeouts, you must set this to `False`. If this is set to `False`, then this function will always return `None`.

      - roles (List[`abc.Snowflake`]) – A list of `abc.Snowflake` that represent roles to include in the pruning process. If a member has a role that is not specified, they’ll be excluded.

    Raises:

      - Forbidden – You do not have permissions to prune members.

      - HTTPException – An error occurred while pruning members.

      - TypeError – An integer was not passed for `days`.

    Returns:

      The number of members pruned. If `compute_prune_count` is `False` then this returns `None`.

    Return type:

      Optional[`int`]

  await templates()

    This function is a coroutine.

    Gets the list of templates from this guild.

    You must have `manage_guild` to do this.

    Added in version 1.7.

    Raises:

      Forbidden – You don’t have permissions to get the templates.

    Returns:

      The templates for this guild.

    Return type:

      List[`Template`]

  await webhooks()

    This function is a coroutine.

    Gets the list of webhooks from this guild.

    You must have `manage_webhooks` to do this.

    Raises:

      Forbidden – You don’t have permissions to get the webhooks.

    Returns:

      The webhooks for this guild.

    Return type:

      List[`Webhook`]

  await estimate_pruned_members(*, days, roles=...)

    This function is a coroutine.

    Similar to `prune_members()` except instead of actually pruning members, it returns how many members it would prune from the guild had it been called.

    Changed in version 2.0: The returned value can be `None`.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - days (`int`) – The number of days before counting as inactive.

      - roles (List[`abc.Snowflake`]) –

        A list of `abc.Snowflake` that represent roles to include in the estimate. If a member has a role that is not specified, they’ll be excluded.

        Added in version 1.7.

    Raises:

      - Forbidden – You do not have permissions to prune members.

      - HTTPException – An error occurred while fetching the prune members estimate.

      - TypeError – An integer was not passed for `days`.

    Returns:

      The number of members estimated to be pruned.

    Return type:

      Optional[`int`]

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from the guild.

    You must have `manage_guild` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  await create_template(*, name, description=...)

    This function is a coroutine.

    Creates a template for the guild.

    You must have `manage_guild` to do this.

    Added in version 1.7.

    Parameters:

      - name (`str`) – The name of the template.

      - description (`str`) – The description of the template.

  await create_integration(*, type, id)

    This function is a coroutine.

    Attaches an integration to the guild.

    You must have `manage_guild` to do this.

    Added in version 1.4.

    Parameters:

      - type (`str`) – The integration type (e.g. Twitch).

      - id (`int`) – The integration ID.

    Raises:

      - Forbidden – You do not have permission to create the integration.

      - HTTPException – The account could not be found.

  await integrations()

    This function is a coroutine.

    Returns a list of all integrations attached to the guild.

    You must have `manage_guild` to do this.

    Added in version 1.4.

    Raises:

      - Forbidden – You do not have permission to create the integration.

      - HTTPException – Fetching the integrations failed.

    Returns:

      The list of integrations that are attached to the guild.

    Return type:

      List[`Integration`]

  await fetch_stickers()

    This function is a coroutine.

    Retrieves a list of all `Sticker`s for the guild.

    Added in version 2.0.

    Note

    This method is an API call. For general usage, consider `stickers` instead.

    Raises:

      HTTPException – An error occurred fetching the stickers.

    Returns:

      The retrieved stickers.

    Return type:

      List[`GuildSticker`]

  await fetch_sticker(sticker_id, /)

    This function is a coroutine.

    Retrieves a custom `Sticker` from the guild.

    Added in version 2.0.

    Note

    This method is an API call. For general usage, consider iterating over `stickers` instead.

    Parameters:

      sticker_id (`int`) – The sticker’s ID.

    Raises:

      - NotFound – The sticker requested could not be found.

      - HTTPException – An error occurred fetching the sticker.

    Returns:

      The retrieved sticker.

    Return type:

      `GuildSticker`

  await create_sticker(*, name, description, emoji, file, reason=None)

    This function is a coroutine.

    Creates a `Sticker` for the guild.

    You must have `manage_emojis_and_stickers` to do this.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The sticker name. Must be at least 2 characters.

      - description (`str`) – The sticker’s description.

      - emoji (`str`) – The name of a unicode emoji that represents the sticker’s expression.

      - file (`File`) – The file of the sticker to upload.

      - reason (`str`) – The reason for creating this sticker. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to create stickers.

      - HTTPException – An error occurred creating a sticker.

    Returns:

      The created sticker.

    Return type:

      `GuildSticker`

  await delete_sticker(sticker, /, *, reason=None)

    This function is a coroutine.

    Deletes the custom `Sticker` from the guild.

    You must have `manage_emojis_and_stickers` to do this.

    Added in version 2.0.

    Parameters:

      - sticker (`abc.Snowflake`) – The sticker you are deleting.

      - reason (Optional[`str`]) – The reason for deleting this sticker. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to delete stickers.

      - HTTPException – An error occurred deleting the sticker.

  await fetch_scheduled_events(*, with_counts=True)

    This function is a coroutine.

    Retrieves a list of all scheduled events for the guild.

    Added in version 2.0.

    Parameters:

      with_counts (`bool`) – Whether to include the number of users that are subscribed to the event. Defaults to `True`.

    Raises:

      HTTPException – Retrieving the scheduled events failed.

    Returns:

      The scheduled events.

    Return type:

      List[`ScheduledEvent`]

  await fetch_scheduled_event(scheduled_event_id, /, *, with_counts=True)

    This function is a coroutine.

    Retrieves a scheduled event from the guild.

    Added in version 2.0.

    Parameters:

      - scheduled_event_id (`int`) – The scheduled event ID.

      - with_counts (`bool`) – Whether to include the number of users that are subscribed to the event. Defaults to `True`.

    Raises:

      - NotFound – The scheduled event was not found.

      - HTTPException – Retrieving the scheduled event failed.

    Returns:

      The scheduled event.

    Return type:

      `ScheduledEvent`

  await create_scheduled_event(*, name, start_time, entity_type=..., privacy_level=..., channel=..., location=..., end_time=..., description=..., image=..., reason=None)

    This function is a coroutine.

    Creates a scheduled event for the guild.

    You must have `manage_events` to do this.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the scheduled event.

      - description (`str`) – The description of the scheduled event.

      - channel (Optional[`abc.Snowflake`]) –

        The channel to send the scheduled event to. If the channel is a `StageInstance` or `VoiceChannel` then it automatically sets the entity type.

        Required if `entity_type` is either `EntityType.voice` or `EntityType.stage_instance`.

      - start_time (`datetime.datetime`) – The scheduled start time of the scheduled event. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

      - end_time (`datetime.datetime`) –

        The scheduled end time of the scheduled event. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

        Required if the entity type is `EntityType.external`.

      - privacy_level (`PrivacyLevel`) – The privacy level of the scheduled event.

      - entity_type (`EntityType`) – The entity type of the scheduled event. If the channel is a `StageInstance` or `VoiceChannel` then this is automatically set to the appropriate entity type. If no channel is passed then the entity type is assumed to be `EntityType.external`

      - image (`bytes`) – The image of the scheduled event.

      - location (`str`) –

        The location of the scheduled event.

        Required if the `entity_type` is `EntityType.external`.

      - reason (Optional[`str`]) – The reason for creating this scheduled event. Shows up on the audit log.

    Raises:

      - TypeError – `image` was not a py:bytes-like object, or `privacy_level` was not a `PrivacyLevel`, or `entity_type` was not an `EntityType`, `status` was not an `EventStatus`, or an argument was provided that was incompatible with the provided `entity_type`.

      - ValueError – `start_time` or `end_time` was not a timezone-aware datetime object.

      - Forbidden – You are not allowed to create scheduled events.

      - HTTPException – Creating the scheduled event failed.

    Returns:

      The created scheduled event.

    Return type:

      `ScheduledEvent`

  await fetch_emojis()

    This function is a coroutine.

    Retrieves all custom `Emoji`s from the guild.

    Note

    This method is an API call. For general usage, consider `emojis` instead.

    Raises:

      HTTPException – An error occurred fetching the emojis.

    Returns:

      The retrieved emojis.

    Return type:

      List[`Emoji`]

  await fetch_emoji(emoji_id, /)

    This function is a coroutine.

    Retrieves a custom `Emoji` from the guild.

    Note

    This method is an API call. For general usage, consider iterating over `emojis` instead.

    Changed in version 2.0: `emoji_id` parameter is now positional-only.

    Parameters:

      emoji_id (`int`) – The emoji’s ID.

    Raises:

      - NotFound – The emoji requested could not be found.

      - HTTPException – An error occurred fetching the emoji.

    Returns:

      The retrieved emoji.

    Return type:

      `Emoji`

  await create_custom_emoji(*, name, image, roles=..., reason=None)

    This function is a coroutine.

    Creates a custom `Emoji` for the guild.

    There is currently a limit of 50 static and animated emojis respectively per guild, unless the guild has the `MORE_EMOJI` feature which extends the limit to 200.

    You must have `manage_emojis` to do this.

    Parameters:

      - name (`str`) – The emoji name. Must be at least 2 characters.

      - image (`bytes`) – The py:bytes-like object representing the image data to use. Only JPG, PNG and GIF images are supported.

      - roles (List[`Role`]) – A `list` of `Role`s that can use this emoji. Leave empty to make it available to everyone.

      - reason (Optional[`str`]) – The reason for creating this emoji. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to create emojis.

      - HTTPException – An error occurred creating an emoji.

    Returns:

      The created emoji.

    Return type:

      `Emoji`

  await delete_emoji(emoji, /, *, reason=None)

    This function is a coroutine.

    Deletes the custom `Emoji` from the guild.

    You must have `manage_emojis` to do this.

    Changed in version 2.0: `emoji` parameter is now positional-only.

    Parameters:

      - emoji (`abc.Snowflake`) – The emoji you are deleting.

      - reason (Optional[`str`]) – The reason for deleting this emoji. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to delete emojis.

      - HTTPException – An error occurred deleting the emoji.

  await fetch_roles()

    This function is a coroutine.

    Retrieves all `Role` that the guild has.

    Note

    This method is an API call. For general usage, consider `roles` instead.

    Added in version 1.3.

    Raises:

      HTTPException – Retrieving the roles failed.

    Returns:

      All roles in the guild.

    Return type:

      List[`Role`]

  await fetch_role(role_id, /)

    This function is a coroutine.

    Retrieves a `Role` with the specified ID.

    Added in version 2.5.

    Note

    This method is an API call. For general usage, consider `get_role` instead.

    Parameters:

      role_id (`int`) – The role’s ID.

    Raises:

      - NotFound – The role requested could not be found.

      - HTTPException – An error occurred fetching the role.

    Returns:

      The retrieved role.

    Return type:

      `Role`

  await create_role(*, name=..., permissions=..., color=..., colour=..., hoist=..., display_icon=..., mentionable=..., reason=None)

    This function is a coroutine.

    Creates a `Role` for the guild.

    All fields are optional.

    You must have `manage_roles` to do this.

    Changed in version 1.6: Can now pass `int` to `colour` keyword-only parameter.

    Added in version 2.0: The `display_icon` keyword-only parameter was added.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The role name. Defaults to ‘new role’.

      - permissions (`Permissions`) – The permissions to have. Defaults to no permissions.

      - colour (Union[`Colour`, `int`]) – The colour for the role. Defaults to `Colour.default()`. This is aliased to `color` as well.

      - hoist (`bool`) – Indicates if the role should be shown separately in the member list. Defaults to `False`.

      - display_icon (Union[`bytes`, `str`]) – A py:bytes-like object representing the icon or `str` representing unicode emoji that should be used as a role icon. Only PNG/JPEG is supported. This is only available to guilds that contain `ROLE_ICONS` in `features`.

      - mentionable (`bool`) – Indicates if the role should be mentionable by others. Defaults to `False`.

      - reason (Optional[`str`]) – The reason for creating this role. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create the role.

      - HTTPException – Creating the role failed.

      - TypeError – An invalid keyword argument was given.

    Returns:

      The newly created role.

    Return type:

      `Role`

  await edit_role_positions(positions, *, reason=None)

    This function is a coroutine.

    Bulk edits a list of `Role` in the guild.

    You must have `manage_roles` to do this.

    Added in version 1.4.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Example

        positions = {
            bots_role: 1, # penultimate role
            tester_role: 2,
            admin_role: 6
        }

        await guild.edit_role_positions(positions=positions)

    Parameters:

      - positions – A `dict` of `Role` to `int` to change the positions of each given role.

      - reason (Optional[`str`]) – The reason for editing the role positions. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to move the roles.

      - HTTPException – Moving the roles failed.

      - TypeError – An invalid keyword argument was given.

    Returns:

      A list of all the roles in the guild.

    Return type:

      List[`Role`]

  await welcome_screen()

    This function is a coroutine.

    Returns the guild’s welcome screen.

    The guild must have `COMMUNITY` in `features`.

    You must have `manage_guild` to do this.as well.

    Added in version 2.0.

    Raises:

      - Forbidden – You do not have the proper permissions to get this.

      - HTTPException – Retrieving the welcome screen failed.

    Returns:

      The welcome screen.

    Return type:

      `WelcomeScreen`

  await edit_welcome_screen(*, description=..., welcome_channels=..., enabled=..., reason=None)

    This function is a coroutine.

    A shorthand method of `WelcomeScreen.edit` without needing to fetch the welcome screen beforehand.

    The guild must have `COMMUNITY` in `features`.

    You must have `manage_guild` to do this as well.

    Added in version 2.0.

    Returns:

      The edited welcome screen.

    Return type:

      `WelcomeScreen`

  await kick(user, *, reason=None)

    This function is a coroutine.

    Kicks a user from the guild.

    The user must meet the `abc.Snowflake` abc.

    You must have `kick_members` to do this.

    Parameters:

      - user (`abc.Snowflake`) – The user to kick from the guild.

      - reason (Optional[`str`]) – The reason the user got kicked.

    Raises:

      - Forbidden – You do not have the proper permissions to kick.

      - HTTPException – Kicking failed.

  await ban(user, *, reason=None, delete_message_days=..., delete_message_seconds=...)

    This function is a coroutine.

    Bans a user from the guild.

    The user must meet the `abc.Snowflake` abc.

    You must have `ban_members` to do this.

    Parameters:

      - user (`abc.Snowflake`) – The user to ban from the guild.

      - delete_message_days (`int`) –

        The number of days worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 7. Defaults to 1 day if neither `delete_message_days` nor `delete_message_seconds` are passed.

        Deprecated since version 2.1.

      - delete_message_seconds (`int`) –

        The number of seconds worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 604800 (7 days). Defaults to 1 day if neither `delete_message_days` nor `delete_message_seconds` are passed.

        Added in version 2.1.

      - reason (Optional[`str`]) – The reason the user got banned.

    Raises:

      - NotFound – The requested user was not found.

      - Forbidden – You do not have the proper permissions to ban.

      - HTTPException – Banning failed.

      - TypeError – You specified both `delete_message_days` and `delete_message_seconds`.

  await unban(user, *, reason=None)

    This function is a coroutine.

    Unbans a user from the guild.

    The user must meet the `abc.Snowflake` abc.

    You must have `ban_members` to do this.

    Parameters:

      - user (`abc.Snowflake`) – The user to unban.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - NotFound – The requested unban was not found.

      - Forbidden – You do not have the proper permissions to unban.

      - HTTPException – Unbanning failed.

  await bulk_ban(users, *, reason=None, delete_message_seconds=86400)

    This function is a coroutine.

    Bans multiple users from the guild.

    The users must meet the `abc.Snowflake` abc.

    You must have `ban_members` and `manage_guild` to do this.

    Added in version 2.4.

    Parameters:

      - users (Iterable[`abc.Snowflake`]) – The users to ban from the guild, up to 200 users.

      - delete_message_seconds (`int`) – The number of seconds worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 604800 (7 days). Defaults to 1 day.

      - reason (Optional[`str`]) – The reason the users got banned.

    Raises:

      - Forbidden – You do not have the proper permissions to ban.

      - HTTPException – Banning failed.

    Returns:

      The result of the bulk ban operation.

    Return type:

      `BulkBanResult`

  property vanity_url

    The Discord vanity invite URL for this guild, if available.

    Added in version 2.0.

    Type:

      Optional[`str`]

  await vanity_invite()

    This function is a coroutine.

    Returns the guild’s special vanity invite.

    The guild must have `VANITY_URL` in `features`.

    You must have `manage_guild` to do this as well.

    Raises:

      - Forbidden – You do not have the proper permissions to get this.

      - HTTPException – Retrieving the vanity invite failed.

    Returns:

      The special vanity invite. If `None` then the guild does not have a vanity invite set.

    Return type:

      Optional[`Invite`]

  async for ... in audit_logs(*, limit=100, before=..., after=..., oldest_first=..., user=..., action=...)

    Returns an asynchronous iterator that enables receiving the guild’s audit logs.

    You must have `view_audit_log` to do this.

    Examples

    Getting the first 100 entries:

        async for entry in guild.audit_logs(limit=100):
            print(f'{entry.user} did {entry.action} to {entry.target}')

    Getting entries for a specific action:

        async for entry in guild.audit_logs(action=discord.AuditLogAction.ban):
            print(f'{entry.user} banned {entry.target}')

    Getting entries made by a specific user:

        entries = [entry async for entry in guild.audit_logs(limit=None, user=guild.me)]
        await channel.send(f'I made {len(entries)} moderation actions.')

    Parameters:

      - limit (Optional[`int`]) – The number of entries to retrieve. If `None` retrieve all entries.

      - before (Union[`abc.Snowflake`, `datetime.datetime`]) – Retrieve entries before this date or entry. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Union[`abc.Snowflake`, `datetime.datetime`]) – Retrieve entries after this date or entry. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - oldest_first (`bool`) – If set to `True`, return entries in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

      - user (`abc.Snowflake`) – The moderator to filter entries from.

      - action (`AuditLogAction`) – The action to filter with.

    Raises:

      - Forbidden – You are not allowed to fetch audit logs

      - HTTPException – An error occurred while fetching the audit logs.

    Yields:

      `AuditLogEntry` – The audit log entry.

  await widget()

    This function is a coroutine.

    Returns the widget of the guild.

    Note

    The guild must have the widget enabled to get this information.

    Raises:

      - Forbidden – The widget for this guild is disabled.

      - HTTPException – Retrieving the widget failed.

    Returns:

      The guild’s widget.

    Return type:

      `Widget`

  await edit_widget(*, enabled=..., channel=..., reason=None)

    This function is a coroutine.

    Edits the widget of the guild. This can also be done with `edit`.

    You must have `manage_guild` to do this.

    Added in version 2.0.

    Parameters:

      - enabled (`bool`) – Whether to enable the widget for the guild.

      - channel (Optional[`Snowflake`]) – The new widget channel. `None` removes the widget channel.

      - reason (Optional[`str`]) – The reason for editing this widget. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permission to edit the widget.

      - HTTPException – Editing the widget failed.

  await chunk(*, cache=True)

    This function is a coroutine.

    Requests all members that belong to this guild. In order to use this, `Intents.members()` must be enabled.

    This is a websocket operation and can be slow.

    Added in version 1.5.

    Parameters:

      cache (`bool`) – Whether to cache the members as well.

    Raises:

      ClientException – The members intent is not enabled.

    Returns:

      The list of members in the guild.

    Return type:

      List[`Member`]

  await query_members(query=None, *, limit=5, user_ids=None, presences=False, cache=True)

    This function is a coroutine.

    Request members of this guild whose username or nickname starts with the given query. This is a websocket operation.

    Added in version 1.3.

    Parameters:

      - query (Optional[`str`]) – The string that the username or nickname should start with.

      - limit (`int`) – The maximum number of members to send back. This must be a number between 5 and 100.

      - presences (`bool`) –

        Whether to request for presences to be provided. This defaults to `False`.

        Added in version 1.6.

      - cache (`bool`) – Whether to cache the members internally. This makes operations such as `get_member()` work for those that matched.

      - user_ids (Optional[List[`int`]]) –

        List of user IDs to search for. If the user ID is not in the guild then it won’t be returned.

        Added in version 1.4.

    Raises:

      - asyncio.TimeoutError – The query timed out waiting for the members.

      - ValueError – Invalid parameters were passed to the function

      - ClientException – The presences intent is not enabled.

    Returns:

      The list of members that have matched the query.

    Return type:

      List[`Member`]

  await change_voice_state(*, channel, self_mute=False, self_deaf=False)

    This function is a coroutine.

    Changes client’s voice state in the guild.

    Added in version 1.4.

    Parameters:

      - channel (Optional[`abc.Snowflake`]) – Channel the client wants to join. Use `None` to disconnect.

      - self_mute (`bool`) – Indicates if the client should be self-muted.

      - self_deaf (`bool`) – Indicates if the client should be self-deafened.

  await fetch_automod_rule(automod_rule_id, /)

    This function is a coroutine.

    Fetches an active automod rule from the guild.

    You must have `Permissions.manage_guild` to do this.

    Added in version 2.0.

    Parameters:

      automod_rule_id (`int`) – The ID of the automod rule to fetch.

    Raises:

      - Forbidden – You do not have permission to view the automod rule.

      - NotFound – The automod rule does not exist within this guild.

    Returns:

      The automod rule that was fetched.

    Return type:

      `AutoModRule`

  await fetch_automod_rules()

    This function is a coroutine.

    Fetches all automod rules from the guild.

    You must have `Permissions.manage_guild` to do this.

    Added in version 2.0.

    Raises:

      - Forbidden – You do not have permission to view the automod rule.

      - NotFound – There are no automod rules within this guild.

    Returns:

      The automod rules that were fetched.

    Return type:

      List[`AutoModRule`]

  await create_automod_rule(*, name, event_type, trigger, actions, enabled=False, exempt_roles=..., exempt_channels=..., reason=...)

    This function is a coroutine.

    Create an automod rule.

    You must have `Permissions.manage_guild` to do this.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the automod rule.

      - event_type (`AutoModRuleEventType`) – The type of event that the automod rule will trigger on.

      - trigger (`AutoModTrigger`) – The trigger that will trigger the automod rule.

      - actions (List[`AutoModRuleAction`]) – The actions that will be taken when the automod rule is triggered.

      - enabled (`bool`) – Whether the automod rule is enabled. Defaults to `False`.

      - exempt_roles (Sequence[`abc.Snowflake`]) – A list of roles that will be exempt from the automod rule.

      - exempt_channels (Sequence[`abc.Snowflake`]) – A list of channels that will be exempt from the automod rule.

      - reason (`str`) – The reason for creating this automod rule. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create an automod rule.

      - HTTPException – Creating the automod rule failed.

    Returns:

      The automod rule that was created.

    Return type:

      `AutoModRule`

  property invites_paused_until

    If invites are paused, returns when invites will get enabled in UTC, otherwise returns None.

    Added in version 2.4.

    Type:

      Optional[`datetime.datetime`]

  property dms_paused_until

    If DMs are paused, returns when DMs will get enabled in UTC, otherwise returns None.

    Added in version 2.4.

    Type:

      Optional[`datetime.datetime`]

  property dm_spam_detected_at

    Returns the time when DM spam was detected in the guild.

    Added in version 2.5.

    Type:

      `datetime.datetime`

  property raid_detected_at

    Returns the time when a raid was detected in the guild.

    Added in version 2.5.

    Type:

      Optional[`datetime.datetime`]

  invites_paused()

    `bool`: Whether invites are paused in the guild.

    Added in version 2.4.

  dms_paused()

    `bool`: Whether DMs are paused in the guild.

    Added in version 2.4.

  is_dm_spam_detected()

    `bool`: Whether DM spam was detected in the guild.

    Added in version 2.5.

  is_raid_detected()

    `bool`: Whether a raid was detected in the guild.

    Added in version 2.5.

  await fetch_soundboard_sound(sound_id, /)

    This function is a coroutine.

    Retrieves a `SoundboardSound` with the specified ID.

    Added in version 2.5.

    Note

    Using this, in order to receive `SoundboardSound.user`, you must have `create_expressions` or `manage_expressions`.

    Note

    This method is an API call. For general usage, consider `get_soundboard_sound` instead.

    Raises:

      - NotFound – The sound requested could not be found.

      - HTTPException – Retrieving the sound failed.

    Returns:

      The retrieved sound.

    Return type:

      `SoundboardSound`

  await fetch_soundboard_sounds()

    This function is a coroutine.

    Retrieves a list of all soundboard sounds for the guild.

    Added in version 2.5.

    Note

    Using this, in order to receive `SoundboardSound.user`, you must have `create_expressions` or `manage_expressions`.

    Note

    This method is an API call. For general usage, consider `soundboard_sounds` instead.

    Raises:

      HTTPException – Retrieving the sounds failed.

    Returns:

      The retrieved soundboard sounds.

    Return type:

      List[`SoundboardSound`]

  await create_soundboard_sound(*, name, sound, volume=1, emoji=None, reason=None)

    This function is a coroutine.

    Creates a `SoundboardSound` for the guild. You must have `Permissions.create_expressions` to do this.

    Added in version 2.5.

    Parameters:

      - name (`str`) – The name of the sound. Must be between 2 and 32 characters.

      - sound (`bytes`) – The py:bytes-like object representing the sound data. Only MP3 and OGG sound files that don’t exceed the duration of 5.2s are supported.

      - volume (`float`) – The volume of the sound. Must be between 0 and 1. Defaults to `1`.

      - emoji (Optional[Union[`Emoji`, `PartialEmoji`, `str`]]) – The emoji of the sound.

      - reason (Optional[`str`]) – The reason for creating the sound. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a soundboard sound.

      - HTTPException – Creating the soundboard sound failed.

    Returns:

      The newly created soundboard sound.

    Return type:

      `SoundboardSound`

class discord.BanEntry

  A namedtuple which represents a ban returned from `bans()`.

  reason

    The reason this user was banned.

    Type:

      Optional[`str`]

  user

    The `User` that was banned.

    Type:

      `User`

class discord.BulkBanResult

  A namedtuple which represents the result returned from `bulk_ban()`.

  Added in version 2.4.

  banned

    The list of users that were banned. The inner `Object` of the list has the `Object.type` set to `User`.

    Type:

      List[`Object`]

  failed

    The list of users that could not be banned. The inner `Object` of the list has the `Object.type` set to `User`.

    Type:

      List[`Object`]

### GuildPreview

Attributes

- approximate_member_count
- approximate_presence_count
- created_at
- description
- discovery_splash
- emojis
- features
- icon
- id
- name
- splash
- stickers

class discord.GuildPreview(*, data, state)

  Represents a preview of a Discord guild.

  > Added in version 2.5.

  x == y

    Checks if two guild previews are equal.

  x != y

    Checks if two guild previews are not equal.

  hash(x)

    Returns the guild’s hash.

  str(x)

    Returns the guild’s name.

  name

    The guild preview’s name.

    Type:

      `str`

  id

    The guild preview’s ID.

    Type:

      `int`

  features

    A list of features the guild has. See `Guild.features` for more information.

    Type:

      List[`str`]

  description

    The guild preview’s description.

    Type:

      Optional[`str`]

  emojis

    All emojis that the guild owns.

    Type:

      Tuple[`Emoji`, …]

  stickers

    All stickers that the guild owns.

    Type:

      Tuple[`GuildSticker`, …]

  approximate_member_count

    The approximate number of members in the guild.

    Type:

      `int`

  approximate_presence_count

    The approximate number of members currently active in in the guild. Offline members are excluded.

    Type:

      `int`

  property created_at

    Returns the guild’s creation time in UTC.

    Type:

      `datetime.datetime`

  property icon

    Returns the guild’s icon asset, if available.

    Type:

      Optional[`Asset`]

  property splash

    Returns the guild’s invite splash asset, if available.

    Type:

      Optional[`Asset`]

  property discovery_splash

    Returns the guild’s discovery splash asset, if available.

    Type:

      Optional[`Asset`]

### ScheduledEvent

Attributes

- channel
- cover_image
- creator
- creator_id
- description
- end_time
- entity_id
- entity_type
- guild
- id
- location
- name
- privacy_level
- start_time
- status
- url
- user_count

Methods

- async cancel
- async delete
- async edit
- async end
- async start
- async users

class discord.ScheduledEvent

  Represents a scheduled event in a guild.

  Added in version 2.0.

  x == y

    Checks if two scheduled events are equal.

  x != y

    Checks if two scheduled events are not equal.

  hash(x)

    Returns the scheduled event’s hash.

  id

    The scheduled event’s ID.

    Type:

      `int`

  name

    The name of the scheduled event.

    Type:

      `str`

  description

    The description of the scheduled event.

    Type:

      Optional[`str`]

  entity_type

    The type of entity this event is for.

    Type:

      `EntityType`

  entity_id

    The ID of the entity this event is for if available.

    Type:

      Optional[`int`]

  start_time

    The time that the scheduled event will start in UTC.

    Type:

      `datetime.datetime`

  end_time

    The time that the scheduled event will end in UTC.

    Type:

      Optional[`datetime.datetime`]

  privacy_level

    The privacy level of the scheduled event.

    Type:

      `PrivacyLevel`

  status

    The status of the scheduled event.

    Type:

      `EventStatus`

  user_count

    The number of users subscribed to the scheduled event.

    Type:

      `int`

  creator

    The user that created the scheduled event.

    Type:

      Optional[`User`]

  creator_id

    The ID of the user that created the scheduled event.

    Added in version 2.2.

    Type:

      Optional[`int`]

  location

    The location of the scheduled event.

    Type:

      Optional[`str`]

  property cover_image

    The scheduled event’s cover image.

    Type:

      Optional[`Asset`]

  property guild

    The guild this scheduled event is in.

    Type:

      Optional[`Guild`]

  property channel

    The channel this scheduled event is in.

    Type:

      Optional[Union[`VoiceChannel`, `StageChannel`]]

  property url

    The url for the scheduled event.

    Type:

      `str`

  await start(*, reason=None)

    This function is a coroutine.

    Starts the scheduled event.

    Shorthand for:

        await event.edit(status=EventStatus.active)

    Parameters:

      reason (Optional[`str`]) – The reason for starting the scheduled event.

    Raises:

      - ValueError – The scheduled event has already started or has ended.

      - Forbidden – You do not have the proper permissions to start the scheduled event.

      - HTTPException – The scheduled event could not be started.

    Returns:

      The scheduled event that was started.

    Return type:

      `ScheduledEvent`

  await end(*, reason=None)

    This function is a coroutine.

    Ends the scheduled event.

    Shorthand for:

        await event.edit(status=EventStatus.completed)

    Parameters:

      reason (Optional[`str`]) – The reason for ending the scheduled event.

    Raises:

      - ValueError – The scheduled event is not active or has already ended.

      - Forbidden – You do not have the proper permissions to end the scheduled event.

      - HTTPException – The scheduled event could not be ended.

    Returns:

      The scheduled event that was ended.

    Return type:

      `ScheduledEvent`

  await cancel(*, reason=None)

    This function is a coroutine.

    Cancels the scheduled event.

    Shorthand for:

        await event.edit(status=EventStatus.cancelled)

    Parameters:

      reason (Optional[`str`]) – The reason for cancelling the scheduled event.

    Raises:

      - ValueError – The scheduled event is already running.

      - Forbidden – You do not have the proper permissions to cancel the scheduled event.

      - HTTPException – The scheduled event could not be cancelled.

    Returns:

      The scheduled event that was cancelled.

    Return type:

      `ScheduledEvent`

  await edit(*, name=..., description=..., channel=..., start_time=..., end_time=..., privacy_level=..., entity_type=..., status=..., image=..., location=..., reason=None)

    This function is a coroutine.

    Edits the scheduled event.

    You must have `manage_events` to do this.

    Parameters:

      - name (`str`) – The name of the scheduled event.

      - description (`str`) – The description of the scheduled event.

      - channel (Optional[`Snowflake`]) –

        The channel to put the scheduled event in. If the channel is a `StageInstance` or `VoiceChannel` then it automatically sets the entity type.

        Required if the entity type is either `EntityType.voice` or `EntityType.stage_instance`.

      - start_time (`datetime.datetime`) – The time that the scheduled event will start. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

      - end_time (Optional[`datetime.datetime`]) –

        The time that the scheduled event will end. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

        If the entity type is either `EntityType.voice` or `EntityType.stage_instance`, the end_time can be cleared by passing `None`.

        Required if the entity type is `EntityType.external`.

      - privacy_level (`PrivacyLevel`) – The privacy level of the scheduled event.

      - entity_type (`EntityType`) – The new entity type. If the channel is a `StageInstance` or `VoiceChannel` then this is automatically set to the appropriate entity type.

      - status (`EventStatus`) – The new status of the scheduled event.

      - image (Optional[`bytes`]) – The new image of the scheduled event or `None` to remove the image.

      - location (`str`) –

        The new location of the scheduled event.

        Required if the entity type is `EntityType.external`.

      - reason (Optional[`str`]) – The reason for editing the scheduled event. Shows up on the audit log.

    Raises:

      - TypeError – `image` was not a py:bytes-like object, or `privacy_level` was not a `PrivacyLevel`, or `entity_type` was not an `EntityType`, `status` was not an `EventStatus`, or an argument was provided that was incompatible with the scheduled event’s entity type.

      - ValueError – `start_time` or `end_time` was not a timezone-aware datetime object.

      - Forbidden – You do not have permissions to edit the scheduled event.

      - HTTPException – Editing the scheduled event failed.

    Returns:

      The edited scheduled event.

    Return type:

      `ScheduledEvent`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the scheduled event.

    You must have `manage_events` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting the scheduled event. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to delete the scheduled event.

      - HTTPException – Deleting the scheduled event failed.

  async for ... in users(*, limit=None, before=None, after=None, oldest_first=...)

    This function is a coroutine.

    Retrieves all `User` that are subscribed to this event.

    This requires `Intents.members` to get information about members other than yourself.

    Raises:

      HTTPException – Retrieving the members failed.

    Returns:

      All subscribed users of this event.

    Return type:

      List[`User`]

### Integration

Attributes

- account
- enabled
- guild
- id
- name
- type
- user

Methods

- async delete

class discord.Integration

  Represents a guild integration.

  Added in version 1.4.

  id

    The integration ID.

    Type:

      `int`

  name

    The integration name.

    Type:

      `str`

  guild

    The guild of the integration.

    Type:

      `Guild`

  type

    The integration type (i.e. Twitch).

    Type:

      `str`

  enabled

    Whether the integration is currently enabled.

    Type:

      `bool`

  account

    The account linked to this integration.

    Type:

      `IntegrationAccount`

  user

    The user that added this integration.

    Type:

      `User`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the integration.

    You must have `manage_guild` to do this.

    Parameters:

      reason (`str`) –

      The reason the integration was deleted. Shows up on the audit log.

      Added in version 2.0.

    Raises:

      - Forbidden – You do not have permission to delete the integration.

      - HTTPException – Deleting the integration failed.

Attributes

- id
- name

class discord.IntegrationAccount

  Represents an integration account.

  Added in version 1.4.

  id

    The account ID.

    Type:

      `str`

  name

    The account name.

    Type:

      `str`

Attributes

- account
- application
- enabled
- guild
- id
- name
- type
- user

class discord.BotIntegration

  Represents a bot integration on discord.

  Added in version 2.0.

  id

    The integration ID.

    Type:

      `int`

  name

    The integration name.

    Type:

      `str`

  guild

    The guild of the integration.

    Type:

      `Guild`

  type

    The integration type (i.e. Twitch).

    Type:

      `str`

  enabled

    Whether the integration is currently enabled.

    Type:

      `bool`

  user

    The user that added this integration.

    Type:

      `User`

  account

    The integration account information.

    Type:

      `IntegrationAccount`

  application

    The application tied to this integration.

    Type:

      `IntegrationApplication`

Attributes

- description
- icon
- id
- name
- summary
- user

class discord.IntegrationApplication

  Represents an application for a bot integration.

  Added in version 2.0.

  id

    The ID for this application.

    Type:

      `int`

  name

    The application’s name.

    Type:

      `str`

  icon

    The application’s icon hash.

    Type:

      Optional[`str`]

  description

    The application’s description. Can be an empty string.

    Type:

      `str`

  summary

    The summary of the application. Can be an empty string.

    Type:

      `str`

  user

    The bot user on this application.

    Type:

      Optional[`User`]

Attributes

- account
- enable_emoticons
- enabled
- expire_behavior
- expire_behaviour
- expire_grace_period
- guild
- id
- name
- role
- synced_at
- syncing
- type
- user

Methods

- async edit
- async sync

class discord.StreamIntegration

  Represents a stream integration for Twitch or YouTube.

  Added in version 2.0.

  id

    The integration ID.

    Type:

      `int`

  name

    The integration name.

    Type:

      `str`

  guild

    The guild of the integration.

    Type:

      `Guild`

  type

    The integration type (i.e. Twitch).

    Type:

      `str`

  enabled

    Whether the integration is currently enabled.

    Type:

      `bool`

  syncing

    Where the integration is currently syncing.

    Type:

      `bool`

  enable_emoticons

    Whether emoticons should be synced for this integration (currently twitch only).

    Type:

      Optional[`bool`]

  expire_behaviour

    The behaviour of expiring subscribers. Aliased to `expire_behavior` as well.

    Type:

      `ExpireBehaviour`

  expire_grace_period

    The grace period (in days) for expiring subscribers.

    Type:

      `int`

  user

    The user for the integration.

    Type:

      `User`

  account

    The integration account information.

    Type:

      `IntegrationAccount`

  synced_at

    An aware UTC datetime representing when the integration was last synced.

    Type:

      `datetime.datetime`

  property expire_behavior

    An alias for `expire_behaviour`.

    Type:

      `ExpireBehaviour`

  property role

    Optional[`Role`] The role which the integration uses for subscribers.

  await edit(*, expire_behaviour=..., expire_grace_period=..., enable_emoticons=...)

    This function is a coroutine.

    Edits the integration.

    You must have `manage_guild` to do this.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - expire_behaviour (`ExpireBehaviour`) – The behaviour when an integration subscription lapses. Aliased to `expire_behavior` as well.

      - expire_grace_period (`int`) – The period (in days) where the integration will ignore lapsed subscriptions.

      - enable_emoticons (`bool`) – Where emoticons should be synced for this integration (currently twitch only).

    Raises:

      - Forbidden – You do not have permission to edit the integration.

      - HTTPException – Editing the guild failed.

      - TypeError – `expire_behaviour` did not receive a `ExpireBehaviour`.

  await sync()

    This function is a coroutine.

    Syncs the integration.

    You must have `manage_guild` to do this.

    Raises:

      - Forbidden – You do not have permission to sync the integration.

      - HTTPException – Syncing the integration failed.

Attributes

- account
- application_id
- guild
- id
- name
- type

class discord.PartialIntegration

  Represents a partial guild integration.

  Added in version 2.0.

  id

    The integration ID.

    Type:

      `int`

  name

    The integration name.

    Type:

      `str`

  guild

    The guild of the integration.

    Type:

      `Guild`

  type

    The integration type (i.e. Twitch).

    Type:

      `str`

  account

    The account linked to this integration.

    Type:

      `IntegrationAccount`

  application_id

    The id of the application this integration belongs to.

    Type:

      Optional[`int`]

### Member

Attributes

- accent_color
- accent_colour
- activities
- activity
- avatar
- avatar_decoration
- avatar_decoration_sku_id
- banner
- bot
- client_status
- color
- colour
- created_at
- default_avatar
- desktop_status
- discriminator
- display_avatar
- display_banner
- display_icon
- display_name
- dm_channel
- flags
- global_name
- guild
- guild_avatar
- guild_banner
- guild_permissions
- id
- joined_at
- mention
- mobile_status
- mutual_guilds
- name
- nick
- pending
- premium_since
- public_flags
- raw_status
- resolved_permissions
- roles
- status
- system
- timed_out_until
- top_role
- voice
- web_status

Methods

- async add_roles
- async ban
- async create_dm
- async edit
- async fetch_message
- async fetch_voice
- def get_role
- async for history
- def is_on_mobile
- def is_timed_out
- async kick
- def mentioned_in
- async move_to
- async pins
- async remove_roles
- async request_to_speak
- async send
- async timeout
- def typing
- async unban

class discord.Member

  Represents a Discord member to a `Guild`.

  This implements a lot of the functionality of `User`.

  x == y

    Checks if two members are equal. Note that this works with `User` instances too.

  x != y

    Checks if two members are not equal. Note that this works with `User` instances too.

  hash(x)

    Returns the member’s hash.

  str(x)

    Returns the member’s handle (e.g. `name` or `name#discriminator`).

  joined_at

    An aware datetime object that specifies the date and time in UTC that the member joined the guild. If the member left and rejoined the guild, this will be the latest date. In certain cases, this can be `None`.

    Type:

      Optional[`datetime.datetime`]

  activities

    The activities that the user is currently doing.

    Note

    Due to a Discord API limitation, a user’s Spotify activity may not appear if they are listening to a song with a title longer than 128 characters. See GH-1738 for more information.

    Type:

      Tuple[Union[`BaseActivity`, `Spotify`]]

  guild

    The guild that the member belongs to.

    Type:

      `Guild`

  nick

    The guild specific nickname of the user. Takes precedence over the global name.

    Type:

      Optional[`str`]

  pending

    Whether the member is pending member verification.

    Added in version 1.6.

    Type:

      `bool`

  premium_since

    An aware datetime object that specifies the date and time in UTC when the member used their “Nitro boost” on the guild, if available. This could be `None`.

    Type:

      Optional[`datetime.datetime`]

  timed_out_until

    An aware datetime object that specifies the date and time in UTC that the member’s time out will expire. This will be set to `None` or a time in the past if the user is not timed out.

    Added in version 2.0.

    Type:

      Optional[`datetime.datetime`]

  client_status

    Model which holds information about the status of the member on various clients/platforms via presence updates.

    Added in version 2.5.

    Type:

      `ClientStatus`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property name

    Equivalent to `User.name`

  property id

    Equivalent to `User.id`

  property discriminator

    Equivalent to `User.discriminator`

  property global_name

    Equivalent to `User.global_name`

  property bot

    Equivalent to `User.bot`

  property system

    Equivalent to `User.system`

  property created_at

    Equivalent to `User.created_at`

  property default_avatar

    Equivalent to `User.default_avatar`

  property avatar

    Equivalent to `User.avatar`

  property dm_channel

    Equivalent to `User.dm_channel`

  await create_dm()

    This function is a coroutine.

    Creates a `DMChannel` with this user.

    This should be rarely called, as this is done transparently for most people.

    Returns:

      The channel that was created.

    Return type:

      `DMChannel`

  property mutual_guilds

    Equivalent to `User.mutual_guilds`

  property public_flags

    Equivalent to `User.public_flags`

  property banner

    Equivalent to `User.banner`

  property accent_color

    Equivalent to `User.accent_color`

  property accent_colour

    Equivalent to `User.accent_colour`

  property avatar_decoration

    Equivalent to `User.avatar_decoration`

  property avatar_decoration_sku_id

    Equivalent to `User.avatar_decoration_sku_id`

  property raw_status

    The member’s overall status as a string value.

    Added in version 1.5.

    Type:

      `str`

  property status

    The member’s overall status. If the value is unknown, then it will be a `str` instead.

    Type:

      `Status`

  property mobile_status

    The member’s status on a mobile device, if applicable.

    Type:

      `Status`

  property desktop_status

    The member’s status on the desktop client, if applicable.

    Type:

      `Status`

  property web_status

    The member’s status on the web client, if applicable.

    Type:

      `Status`

  is_on_mobile()

    A helper function that determines if a member is active on a mobile device.

    Return type:

      `bool`

  property colour

    A property that returns a colour denoting the rendered colour for the member. If the default colour is the one rendered then an instance of `Colour.default()` is returned.

    There is an alias for this named `color`.

    Type:

      `Colour`

  property color

    A property that returns a color denoting the rendered color for the member. If the default color is the one rendered then an instance of `Colour.default()` is returned.

    There is an alias for this named `colour`.

    Type:

      `Colour`

  property roles

    A `list` of `Role` that the member belongs to. Note that the first element of this list is always the default ‘@everyone’ role.

    These roles are sorted by their position in the role hierarchy.

    Type:

      List[`Role`]

  property display_icon

    A property that returns the role icon that is rendered for this member. If no icon is shown then `None` is returned.

    Added in version 2.0.

    Type:

      Optional[Union[`str`, `Asset`]]

  property mention

    Returns a string that allows you to mention the member.

    Type:

      `str`

  property display_name

    Returns the user’s display name.

    For regular users this is just their global name or their username, but if they have a guild specific nickname then that is returned instead.

    Type:

      `str`

  property display_avatar

    Returns the member’s display avatar.

    For regular members this is just their avatar, but if they have a guild specific avatar then that is returned instead.

    Added in version 2.0.

    Type:

      `Asset`

  property guild_avatar

    Returns an `Asset` for the guild avatar the member has. If unavailable, `None` is returned.

    Added in version 2.0.

    Type:

      Optional[`Asset`]

  property display_banner

    Returns the member’s displayed banner, if any.

    This is the member’s guild banner if available, otherwise it’s their global banner. If the member has no banner set then `None` is returned.

    Added in version 2.5.

    Type:

      Optional[`Asset`]

  property guild_banner

    Returns an `Asset` for the guild banner the member has. If unavailable, `None` is returned.

    Added in version 2.5.

    Type:

      Optional[`Asset`]

  property activity

    Returns the primary activity the user is currently doing. Could be `None` if no activity is being done.

    Note

    Due to a Discord API limitation, this may be `None` if the user is listening to a song on Spotify with a title longer than 128 characters. See GH-1738 for more information.

    Note

    A user may have multiple activities, these can be accessed under `activities`.

    Type:

      Optional[Union[`BaseActivity`, `Spotify`]]

  mentioned_in(message)

    Checks if the member is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the member is mentioned in the message.

    Return type:

      `bool`

  property top_role

    Returns the member’s highest role.

    This is useful for figuring where a member stands in the role hierarchy chain.

    Type:

      `Role`

  property guild_permissions

    Returns the member’s guild permissions.

    This only takes into consideration the guild permissions and not most of the implied permissions or any of the channel permission overwrites. For 100% accurate permission calculation, please use `abc.GuildChannel.permissions_for()`.

    This does take into consideration guild ownership, the administrator implication, and whether the member is timed out.

    Changed in version 2.0: Member timeouts are taken into consideration.

    Type:

      `Permissions`

  property resolved_permissions

    Returns the member’s resolved permissions from an interaction.

    This is only available in interaction contexts and represents the resolved permissions of the member in the channel the interaction was executed in. This is more or less equivalent to calling `abc.GuildChannel.permissions_for()` but stored and returned as an attribute by the Discord API rather than computed.

    Added in version 2.0.

    Type:

      Optional[`Permissions`]

  property voice

    Returns the member’s current voice state.

    Type:

      Optional[`VoiceState`]

  property flags

    Returns the member’s flags.

    Added in version 2.2.

    Type:

      `MemberFlags`

  await ban(*, delete_message_days=..., delete_message_seconds=..., reason=None)

    This function is a coroutine.

    Bans this member. Equivalent to `Guild.ban()`.

  await unban(*, reason=None)

    This function is a coroutine.

    Unbans this member. Equivalent to `Guild.unban()`.

  await kick(*, reason=None)

    This function is a coroutine.

    Kicks this member. Equivalent to `Guild.kick()`.

  await edit(*, nick=..., mute=..., deafen=..., suppress=..., roles=..., voice_channel=..., timed_out_until=..., bypass_verification=..., reason=None)

    This function is a coroutine.

    Edits the member’s data.

    Depending on the parameter passed, this requires different permissions listed below:

    Parameter | Permission
    nick | `Permissions.manage_nicknames`
    mute | `Permissions.mute_members`
    deafen | `Permissions.deafen_members`
    roles | `Permissions.manage_roles`
    voice_channel | `Permissions.move_members`
    timed_out_until | `Permissions.moderate_members`
    bypass_verification | `Permissions.moderate_members`

    All parameters are optional.

    Changed in version 1.1: Can now pass `None` to `voice_channel` to kick a member from voice.

    Changed in version 2.0: The newly updated member is now optionally returned, if applicable.

    Parameters:

      - nick (Optional[`str`]) – The member’s new nickname. Use `None` to remove the nickname.

      - mute (`bool`) – Indicates if the member should be guild muted or un-muted.

      - deafen (`bool`) – Indicates if the member should be guild deafened or un-deafened.

      - suppress (`bool`) –

        Indicates if the member should be suppressed in stage channels.

        Added in version 1.7.

      - roles (List[`Role`]) – The member’s new list of roles. This replaces the roles.

      - voice_channel (Optional[Union[`VoiceChannel`, `StageChannel`]]) – The voice channel to move the member to. Pass `None` to kick them from voice.

      - timed_out_until (Optional[`datetime.datetime`]) –

        The date the member’s timeout should expire, or `None` to remove the timeout. This must be a timezone-aware datetime object. Consider using `utils.utcnow()`.

        Added in version 2.0.

      - bypass_verification (`bool`) –

        Indicates if the member should be allowed to bypass the guild verification requirements.

        Added in version 2.2.

      - reason (Optional[`str`]) – The reason for editing this member. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to do the action requested.

      - HTTPException – The operation failed.

      - TypeError – The datetime object passed to `timed_out_until` was not timezone-aware.

    Returns:

      The newly updated member, if applicable. This is not returned if certain fields are passed, such as `suppress`.

    Return type:

      Optional[`Member`]

  await request_to_speak()

    This function is a coroutine.

    Request to speak in the connected channel.

    Only applies to stage channels.

    Note

    Requesting members that are not the client is equivalent to `edit` providing `suppress` as `False`.

    Added in version 1.7.

    Raises:

      - ClientException – You are not connected to a voice channel.

      - Forbidden – You do not have the proper permissions to do the action requested.

      - HTTPException – The operation failed.

  await move_to(channel, *, reason=None)

    This function is a coroutine.

    Moves a member to a new voice channel (they must be connected first).

    You must have `move_members` to do this.

    This raises the same exceptions as `edit()`.

    Changed in version 1.1: Can now pass `None` to kick a member from voice.

    Parameters:

      - channel (Optional[Union[`VoiceChannel`, `StageChannel`]]) – The new voice channel to move the member to. Pass `None` to kick them from voice.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

  await timeout(until, /, *, reason=None)

    This function is a coroutine.

    Applies a time out to a member until the specified date time or for the given `datetime.timedelta`.

    You must have `moderate_members` to do this.

    This raises the same exceptions as `edit()`.

    Parameters:

      - until (Optional[Union[`datetime.timedelta`, `datetime.datetime`]]) – If this is a `datetime.timedelta` then it represents the amount of time the member should be timed out for. If this is a `datetime.datetime` then it’s when the member’s timeout should expire. If `None` is passed then the timeout is removed. Note that the API only allows for timeouts up to 28 days.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      TypeError – The `until` parameter was the wrong type or the datetime was not timezone-aware.

  await add_roles(*roles, reason=None, atomic=True)

    This function is a coroutine.

    Gives the member a number of `Role`s.

    You must have `manage_roles` to use this, and the added `Role`s must appear lower in the list of roles than the highest role of the client.

    Parameters:

      - *roles (`abc.Snowflake`) – An argument list of `abc.Snowflake` representing a `Role` to give to the member.

      - reason (Optional[`str`]) – The reason for adding these roles. Shows up on the audit log.

      - atomic (`bool`) – Whether to atomically add roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache.

    Raises:

      - Forbidden – You do not have permissions to add these roles.

      - HTTPException – Adding roles failed.

  await remove_roles(*roles, reason=None, atomic=True)

    This function is a coroutine.

    Removes `Role`s from this member.

    You must have `manage_roles` to use this, and the removed `Role`s must appear lower in the list of roles than the highest role of the client.

    Parameters:

      - *roles (`abc.Snowflake`) – An argument list of `abc.Snowflake` representing a `Role` to remove from the member.

      - reason (Optional[`str`]) – The reason for removing these roles. Shows up on the audit log.

      - atomic (`bool`) – Whether to atomically remove roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache.

    Raises:

      - Forbidden – You do not have permissions to remove these roles.

      - HTTPException – Removing the roles failed.

  await fetch_voice()

    This function is a coroutine.

    Retrieves the current voice state from this member.

    Added in version 2.5.

    Raises:

      - NotFound – The member is not in a voice channel.

      - Forbidden – You do not have permissions to get a voice state.

      - HTTPException – Retrieving the voice state failed.

    Returns:

      The current voice state of the member.

    Return type:

      `VoiceState`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  get_role(role_id, /)

    Returns a role with the given ID from roles which the member has.

    Added in version 2.0.

    Parameters:

      role_id (`int`) – The ID to search for.

    Returns:

      The role or `None` if not found in the member’s roles.

    Return type:

      Optional[`Role`]

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  is_timed_out()

    Returns whether this member is timed out.

    Added in version 2.0.

    Returns:

      `True` if the member is timed out. `False` otherwise.

    Return type:

      `bool`

### Spotify

Attributes

- album
- album_cover_url
- artist
- artists
- color
- colour
- created_at
- duration
- end
- name
- party_id
- start
- title
- track_id
- track_url
- type

class discord.Spotify

  Represents a Spotify listening activity from Discord. This is a special case of `Activity` that makes it easier to work with the Spotify integration.

  x == y

    Checks if two activities are equal.

  x != y

    Checks if two activities are not equal.

  hash(x)

    Returns the activity’s hash.

  str(x)

    Returns the string ‘Spotify’.

  property type

    Returns the activity’s type. This is for compatibility with `Activity`.

    It always returns `ActivityType.listening`.

    Type:

      `ActivityType`

  property created_at

    When the user started listening in UTC.

    Added in version 1.3.

    Type:

      Optional[`datetime.datetime`]

  property colour

    Returns the Spotify integration colour, as a `Colour`.

    There is an alias for this named `color`

    Type:

      `Colour`

  property color

    Returns the Spotify integration colour, as a `Colour`.

    There is an alias for this named `colour`

    Type:

      `Colour`

  property name

    The activity’s name. This will always return “Spotify”.

    Type:

      `str`

  property title

    The title of the song being played.

    Type:

      `str`

  property artists

    The artists of the song being played.

    Type:

      List[`str`]

  property artist

    The artist of the song being played.

    This does not attempt to split the artist information into multiple artists. Useful if there’s only a single artist.

    Type:

      `str`

  property album

    The album that the song being played belongs to.

    Type:

      `str`

  property album_cover_url

    The album cover image URL from Spotify’s CDN.

    Type:

      `str`

  property track_id

    The track ID used by Spotify to identify this song.

    Type:

      `str`

  property track_url

    The track URL to listen on Spotify.

    Added in version 2.0.

    Type:

      `str`

  property start

    When the user started playing this song in UTC.

    Type:

      `datetime.datetime`

  property end

    When the user will stop playing this song in UTC.

    Type:

      `datetime.datetime`

  property duration

    The duration of the song being played.

    Type:

      `datetime.timedelta`

  property party_id

    The party ID of the listening party.

    Type:

      `str`

### VoiceState

Attributes

- afk
- channel
- deaf
- mute
- requested_to_speak_at
- self_deaf
- self_mute
- self_stream
- self_video
- suppress

class discord.VoiceState

  Represents a Discord user’s voice state.

  deaf

    Indicates if the user is currently deafened by the guild.

    Type:

      `bool`

  mute

    Indicates if the user is currently muted by the guild.

    Type:

      `bool`

  self_mute

    Indicates if the user is currently muted by their own accord.

    Type:

      `bool`

  self_deaf

    Indicates if the user is currently deafened by their own accord.

    Type:

      `bool`

  self_stream

    Indicates if the user is currently streaming via ‘Go Live’ feature.

    Added in version 1.3.

    Type:

      `bool`

  self_video

    Indicates if the user is currently broadcasting video.

    Type:

      `bool`

  suppress

    Indicates if the user is suppressed from speaking.

    Only applies to stage channels.

    Added in version 1.7.

    Type:

      `bool`

  requested_to_speak_at

    An aware datetime object that specifies the date and time in UTC that the member requested to speak. It will be `None` if they are not requesting to speak anymore or have been accepted to speak.

    Only applicable to stage channels.

    Added in version 1.7.

    Type:

      Optional[`datetime.datetime`]

  afk

    Indicates if the user is currently in the AFK channel in the guild.

    Type:

      `bool`

  channel

    The voice channel that the user is currently connected to. `None` if the user is not currently in a voice channel.

    Type:

      Optional[Union[`VoiceChannel`, `StageChannel`]]

### Emoji

Attributes

- animated
- available
- created_at
- guild
- guild_id
- id
- managed
- name
- require_colons
- roles
- url
- user

Methods

- async delete
- async edit
- def is_application_owned
- def is_usable
- async read
- async save
- async to_file

class discord.Emoji

  Represents a custom emoji.

  Depending on the way this object was created, some of the attributes can have a value of `None`.

  x == y

    Checks if two emoji are the same.

  x != y

    Checks if two emoji are not the same.

  hash(x)

    Return the emoji’s hash.

  iter(x)

    Returns an iterator of `(field, value)` pairs. This allows this class to be used as an iterable in list/dict/etc constructions.

  str(x)

    Returns the emoji rendered for discord.

  name

    The name of the emoji.

    Type:

      `str`

  id

    The emoji’s ID.

    Type:

      `int`

  require_colons

    If colons are required to use this emoji in the client (:PJSalt: vs PJSalt).

    Type:

      `bool`

  animated

    Whether an emoji is animated or not.

    Type:

      `bool`

  managed

    If this emoji is managed by a Twitch integration.

    Type:

      `bool`

  guild_id

    The guild ID the emoji belongs to.

    Type:

      `int`

  available

    Whether the emoji is available for use.

    Type:

      `bool`

  user

    The user that created the emoji. This can only be retrieved using `Guild.fetch_emoji()` and having `manage_emojis`.

    Or if `is_application_owned()` is `True`, this is the team member that uploaded the emoji, or the bot user if it was uploaded using the API and this can only be retrieved using `fetch_application_emoji()` or `fetch_application_emojis()`.

    Type:

      Optional[`User`]

  property created_at

    Returns the emoji’s creation time in UTC.

    Type:

      `datetime.datetime`

  property url

    Returns the URL of the emoji.

    Type:

      `str`

  property roles

    A `list` of roles that is allowed to use this emoji.

    If roles is empty, the emoji is unrestricted.

    Type:

      List[`Role`]

  property guild

    The guild this emoji belongs to.

    Type:

      `Guild`

  is_usable()

    `bool`: Whether the bot can use this emoji.

    Added in version 1.3.

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the custom emoji.

    You must have `manage_emojis` to do this if `is_application_owned()` is `False`.

    Parameters:

      reason (Optional[`str`]) –

      The reason for deleting this emoji. Shows up on the audit log.

      This does not apply if `is_application_owned()` is `True`.

    Raises:

      - Forbidden – You are not allowed to delete emojis.

      - HTTPException – An error occurred deleting the emoji.

      - MissingApplicationID – The emoji is owned by an application but the application ID is missing.

  await edit(*, name=..., roles=..., reason=None)

    This function is a coroutine.

    Edits the custom emoji.

    You must have `manage_emojis` to do this.

    Changed in version 2.0: The newly updated emoji is returned.

    Parameters:

      - name (`str`) – The new emoji name.

      - roles (List[`Snowflake`]) –

        A list of roles that can use this emoji. An empty list can be passed to make it available to everyone.

        This does not apply if `is_application_owned()` is `True`.

      - reason (Optional[`str`]) –

        The reason for editing this emoji. Shows up on the audit log.

        This does not apply if `is_application_owned()` is `True`.

    Raises:

      - Forbidden – You are not allowed to edit emojis.

      - HTTPException – An error occurred editing the emoji.

      - MissingApplicationID – The emoji is owned by an application but the application ID is missing

    Returns:

      The newly updated emoji.

    Return type:

      `Emoji`

  is_application_owned()

    `bool`: Whether the emoji is owned by an application.

    Added in version 2.5.

  await read()

    This function is a coroutine.

    Retrieves the content of this asset as a `bytes` object.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The content of the asset.

    Return type:

      `bytes`

  await save(fp, *, seek_begin=True)

    This function is a coroutine.

    Saves this asset into a file-like object.

    Parameters:

      - fp (Union[`io.BufferedIOBase`, `os.PathLike`]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

      - seek_begin (`bool`) – Whether to seek to the beginning of the file after saving is successfully done.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The number of bytes written.

    Return type:

      `int`

  await to_file(*, filename=..., description=None, spoiler=False)

    This function is a coroutine.

    Converts the asset into a `File` suitable for sending via `abc.Messageable.send()`.

    Added in version 2.0.

    Parameters:

      - filename (Optional[`str`]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.

      - description (Optional[`str`]) – The description for the file.

      - spoiler (`bool`) – Whether the file is a spoiler.

    Raises:

      - DiscordException – The asset does not have an associated state.

      - ValueError – The asset is a unicode emoji.

      - TypeError – The asset is a sticker with lottie type.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The asset as a file suitable for sending.

    Return type:

      `File`

### PartialEmoji

Attributes

- animated
- created_at
- id
- name
- url

Methods

- cls PartialEmoji.from_str
- def is_custom_emoji
- def is_unicode_emoji
- async read
- async save
- async to_file

class discord.PartialEmoji

  Represents a “partial” emoji.

  This model will be given in two scenarios:

  - “Raw” data events such as `on_raw_reaction_add()`

  - Custom emoji that the bot cannot see from e.g. `Message.reactions`

  x == y

    Checks if two emoji are the same.

  x != y

    Checks if two emoji are not the same.

  hash(x)

    Return the emoji’s hash.

  str(x)

    Returns the emoji rendered for discord.

  name

    The custom emoji name, if applicable, or the unicode codepoint of the non-custom emoji. This can be `None` if the emoji got deleted (e.g. removing a reaction with a deleted emoji).

    Type:

      Optional[`str`]

  animated

    Whether the emoji is animated or not.

    Type:

      `bool`

  id

    The ID of the custom emoji, if applicable.

    Type:

      Optional[`int`]

  classmethod from_str(value)

    Converts a Discord string representation of an emoji to a `PartialEmoji`.

    The formats accepted are:

    - `a:name:id`

    - `<a:name:id>`

    - `name:id`

    - `<:name:id>`

    If the format does not match then it is assumed to be a unicode emoji.

    Added in version 2.0.

    Parameters:

      value (`str`) – The string representation of an emoji.

    Returns:

      The partial emoji from this string.

    Return type:

      `PartialEmoji`

  is_custom_emoji()

    `bool`: Checks if this is a custom non-Unicode emoji.

  is_unicode_emoji()

    `bool`: Checks if this is a Unicode emoji.

  property created_at

    Returns the emoji’s creation time in UTC, or None if Unicode emoji.

    Added in version 1.6.

    Type:

      Optional[`datetime.datetime`]

  property url

    Returns the URL of the emoji, if it is custom.

    If this isn’t a custom emoji then an empty string is returned

    Type:

      `str`

  await read()

    This function is a coroutine.

    Retrieves the content of this asset as a `bytes` object.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

      - ValueError – The PartialEmoji is not a custom emoji.

    Returns:

      The content of the asset.

    Return type:

      `bytes`

  await save(fp, *, seek_begin=True)

    This function is a coroutine.

    Saves this asset into a file-like object.

    Parameters:

      - fp (Union[`io.BufferedIOBase`, `os.PathLike`]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

      - seek_begin (`bool`) – Whether to seek to the beginning of the file after saving is successfully done.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The number of bytes written.

    Return type:

      `int`

  await to_file(*, filename=..., description=None, spoiler=False)

    This function is a coroutine.

    Converts the asset into a `File` suitable for sending via `abc.Messageable.send()`.

    Added in version 2.0.

    Parameters:

      - filename (Optional[`str`]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.

      - description (Optional[`str`]) – The description for the file.

      - spoiler (`bool`) – Whether the file is a spoiler.

    Raises:

      - DiscordException – The asset does not have an associated state.

      - ValueError – The asset is a unicode emoji.

      - TypeError – The asset is a sticker with lottie type.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The asset as a file suitable for sending.

    Return type:

      `File`

### Role

Attributes

- color
- colour
- created_at
- display_icon
- flags
- guild
- hoist
- icon
- id
- managed
- members
- mention
- mentionable
- name
- permissions
- position
- tags
- unicode_emoji

Methods

- async delete
- async edit
- def is_assignable
- def is_bot_managed
- def is_default
- def is_integration
- def is_premium_subscriber
- async move

class discord.Role

  Represents a Discord role in a `Guild`.

  x == y

    Checks if two roles are equal.

  x != y

    Checks if two roles are not equal.

  x > y

    Checks if a role is higher than another in the hierarchy.

  x < y

    Checks if a role is lower than another in the hierarchy.

  x >= y

    Checks if a role is higher or equal to another in the hierarchy.

  x <= y

    Checks if a role is lower or equal to another in the hierarchy.

  hash(x)

    Return the role’s hash.

  str(x)

    Returns the role’s name.

  id

    The ID for the role.

    Type:

      `int`

  name

    The name of the role.

    Type:

      `str`

  guild

    The guild the role belongs to.

    Type:

      `Guild`

  hoist

    Indicates if the role will be displayed separately from other members.

    Type:

      `bool`

  position

    The position of the role. This number is usually positive. The bottom role has a position of 0.

    Warning

    Multiple roles can have the same position number. As a consequence of this, comparing via role position is prone to subtle bugs if checking for role hierarchy. The recommended and correct way to compare for roles in the hierarchy is using the comparison operators on the role objects themselves.

    Type:

      `int`

  unicode_emoji

    The role’s unicode emoji, if available.

    Note

    If `icon` is not `None`, it is displayed as role icon instead of the unicode emoji under this attribute.

    If you want the icon that a role has displayed, consider using `display_icon`.

    Added in version 2.0.

    Type:

      Optional[`str`]

  managed

    Indicates if the role is managed by the guild through some form of integrations such as Twitch.

    Type:

      `bool`

  mentionable

    Indicates if the role can be mentioned by users.

    Type:

      `bool`

  tags

    The role tags associated with this role.

    Type:

      Optional[`RoleTags`]

  is_default()

    `bool`: Checks if the role is the default role.

  is_bot_managed()

    `bool`: Whether the role is associated with a bot.

    Added in version 1.6.

  is_premium_subscriber()

    `bool`: Whether the role is the premium subscriber, AKA “boost”, role for the guild.

    Added in version 1.6.

  is_integration()

    `bool`: Whether the role is managed by an integration.

    Added in version 1.6.

  is_assignable()

    `bool`: Whether the role is able to be assigned or removed by the bot.

    Added in version 2.0.

  property permissions

    Returns the role’s permissions.

    Type:

      `Permissions`

  property colour

    Returns the role colour. An alias exists under `color`.

    Type:

      `Colour`

  property color

    Returns the role color. An alias exists under `colour`.

    Type:

      `Colour`

  property icon

    Returns the role’s icon asset, if available.

    Note

    If this is `None`, the role might instead have unicode emoji as its icon if `unicode_emoji` is not `None`.

    If you want the icon that a role has displayed, consider using `display_icon`.

    Added in version 2.0.

    Type:

      Optional[`Asset`]

  property display_icon

    Returns the role’s display icon, if available.

    Added in version 2.0.

    Type:

      Optional[Union[`Asset`, `str`]]

  property created_at

    Returns the role’s creation time in UTC.

    Type:

      `datetime.datetime`

  property mention

    Returns a string that allows you to mention a role.

    Type:

      `str`

  property members

    Returns all the members with this role.

    Type:

      List[`Member`]

  property flags

    Returns the role’s flags.

    Added in version 2.4.

    Type:

      `RoleFlags`

  await edit(*, name=..., permissions=..., colour=..., color=..., hoist=..., display_icon=..., mentionable=..., position=..., reason=...)

    This function is a coroutine.

    Edits the role.

    You must have `manage_roles` to do this.

    All fields are optional.

    Changed in version 1.4: Can now pass `int` to `colour` keyword-only parameter.

    Changed in version 2.0: Edits are no longer in-place, the newly edited role is returned instead.

    Added in version 2.0: The `display_icon` keyword-only parameter was added.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new role name to change to.

      - permissions (`Permissions`) – The new permissions to change to.

      - colour (Union[`Colour`, `int`]) – The new colour to change to. (aliased to color as well)

      - hoist (`bool`) – Indicates if the role should be shown separately in the member list.

      - display_icon (Optional[Union[`bytes`, `str`]]) – A py:bytes-like object representing the icon or `str` representing unicode emoji that should be used as a role icon. Could be `None` to denote removal of the icon. Only PNG/JPEG is supported. This is only available to guilds that contain `ROLE_ICONS` in `Guild.features`.

      - mentionable (`bool`) – Indicates if the role should be mentionable by others.

      - position (`int`) – The new role’s position. This must be below your top role’s position or it will fail.

      - reason (Optional[`str`]) – The reason for editing this role. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to change the role.

      - HTTPException – Editing the role failed.

      - ValueError – An invalid position was given or the default role was asked to be moved.

    Returns:

      The newly edited role.

    Return type:

      `Role`

  await move(*, beginning=..., end=..., above=..., below=..., offset=0, reason=None)

    This function is a coroutine.

    A rich interface to help move a role relative to other roles.

    You must have `manage_roles` to do this, and you cannot move roles above the client’s top role in the guild.

    Added in version 2.5.

    Parameters:

      - beginning (`bool`) – Whether to move this at the beginning of the role list, above the default role. This is mutually exclusive with end, above, and below.

      - end (`bool`) – Whether to move this at the end of the role list. This is mutually exclusive with beginning, above, and below.

      - above (`Role`) – The role that should be above our current role. This mutually exclusive with beginning, end, and below.

      - below (`Role`) – The role that should be below our current role. This mutually exclusive with beginning, end, and above.

      - offset (`int`) – The number of roles to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 above the beginning. A positive number moves it above while a negative number moves it below. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - reason (Optional[`str`]) – The reason for editing this role. Shows up on the audit log.

    Raises:

      - Forbidden – You cannot move the role there, or lack permissions to do so.

      - HTTPException – Moving the role failed.

      - TypeError – A bad mix of arguments were passed.

      - ValueError – An invalid role was passed.

    Returns:

      A list of all the roles in the guild.

    Return type:

      List[`Role`]

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the role.

    You must have `manage_roles` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this role. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to delete the role.

      - HTTPException – Deleting the role failed.

### RoleTags

Attributes

- bot_id
- integration_id
- subscription_listing_id

Methods

- def is_available_for_purchase
- def is_bot_managed
- def is_guild_connection
- def is_integration
- def is_premium_subscriber

class discord.RoleTags

  Represents tags on a role.

  A role tag is a piece of extra information attached to a managed role that gives it context for the reason the role is managed.

  While this can be accessed, a useful interface is also provided in the `Role` and `Guild` classes as well.

  Added in version 1.6.

  bot_id

    The bot’s user ID that manages this role.

    Type:

      Optional[`int`]

  integration_id

    The integration ID that manages the role.

    Type:

      Optional[`int`]

  subscription_listing_id

    The ID of this role’s subscription SKU and listing.

    Added in version 2.2.

    Type:

      Optional[`int`]

  is_bot_managed()

    `bool`: Whether the role is associated with a bot.

  is_premium_subscriber()

    `bool`: Whether the role is the premium subscriber, AKA “boost”, role for the guild.

  is_integration()

    `bool`: Whether the role is managed by an integration.

  is_available_for_purchase()

    `bool`: Whether the role is available for purchase.

    Added in version 2.2.

  is_guild_connection()

    `bool`: Whether the role is a guild’s linked role.

    Added in version 2.2.

### PartialMessageable

Attributes

- created_at
- guild
- guild_id
- id
- jump_url
- mention
- type

Methods

- async fetch_message
- def get_partial_message
- async for history
- def permissions_for
- async pins
- async send
- def typing

class discord.PartialMessageable

  Represents a partial messageable to aid with working messageable channels when only a channel ID is present.

  The only way to construct this class is through `Client.get_partial_messageable()`.

  Note that this class is trimmed down and has no rich attributes.

  Added in version 2.0.

  x == y

    Checks if two partial messageables are equal.

  x != y

    Checks if two partial messageables are not equal.

  hash(x)

    Returns the partial messageable’s hash.

  id

    The channel ID associated with this partial messageable.

    Type:

      `int`

  guild_id

    The guild ID associated with this partial messageable.

    Type:

      Optional[`int`]

  type

    The channel type associated with this partial messageable, if given.

    Type:

      Optional[`ChannelType`]

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property guild

    The guild this partial messageable is in.

    Type:

      Optional[`Guild`]

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Type:

      `str`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  permissions_for(obj=None, /)

    Handles permission resolution for a `User`.

    This function is there for compatibility with other channel types.

    Since partial messageables cannot reasonably have the concept of permissions, this will always return `Permissions.none()`.

    Parameters:

      obj (`User`) – The user to check permissions for. This parameter is ignored but kept for compatibility with other `permissions_for` methods.

    Returns:

      The resolved permissions.

    Return type:

      `Permissions`

  property mention

    Returns a string that allows you to mention the channel.

    Added in version 2.5.

    Type:

      `str`

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

### TextChannel

Attributes

- category
- category_id
- changed_roles
- created_at
- default_auto_archive_duration
- default_thread_slowmode_delay
- guild
- id
- jump_url
- last_message
- last_message_id
- members
- mention
- name
- nsfw
- overwrites
- permissions_synced
- position
- slowmode_delay
- threads
- topic
- type

Methods

- async for archived_threads
- async clone
- async create_invite
- async create_thread
- async create_webhook
- async delete
- async delete_messages
- async edit
- async fetch_message
- async follow
- def get_partial_message
- def get_thread
- async for history
- async invites
- def is_news
- def is_nsfw
- async move
- def overwrites_for
- def permissions_for
- async pins
- async purge
- async send
- async set_permissions
- def typing
- async webhooks

class discord.TextChannel

  Represents a Discord guild text channel.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the channel’s hash.

  str(x)

    Returns the channel’s name.

  name

    The channel name.

    Type:

      `str`

  guild

    The guild the channel belongs to.

    Type:

      `Guild`

  id

    The channel ID.

    Type:

      `int`

  category_id

    The category channel ID this channel belongs to, if applicable.

    Type:

      Optional[`int`]

  topic

    The channel’s topic. `None` if it doesn’t exist.

    Type:

      Optional[`str`]

  position

    The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

    Type:

      `int`

  last_message_id

    The last message ID of the message sent to this channel. It may not point to an existing or valid message.

    Type:

      Optional[`int`]

  slowmode_delay

    The number of seconds a member must wait between sending messages in this channel. A value of `0` denotes that it is disabled. Bots and users with `manage_channels` or `manage_messages` bypass slowmode.

    Type:

      `int`

  nsfw

    If the channel is marked as “not safe for work” or “age restricted”.

    Type:

      `bool`

  default_auto_archive_duration

    The default auto archive duration in minutes for threads created in this channel.

    Added in version 2.0.

    Type:

      `int`

  default_thread_slowmode_delay

    The default slowmode delay in seconds for threads created in this channel.

    Added in version 2.3.

    Type:

      `int`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  property members

    Returns all members that can see this channel.

    Type:

      List[`Member`]

  property threads

    Returns all the threads that you can see.

    Added in version 2.0.

    Type:

      List[`Thread`]

  is_nsfw()

    `bool`: Checks if the channel is NSFW.

  is_news()

    `bool`: Checks if the channel is a news channel.

  property last_message

    Retrieves the last message from this channel in cache.

    The message might not be valid or point to an existing message.

    Reliable Fetching

    For a slightly more reliable method of fetching the last message, consider using either `history()` or `fetch_message()` with the `last_message_id` attribute.

    Returns:

      The last message in this channel or `None` if not found.

    Return type:

      Optional[`Message`]

  await edit(*, reason=None, **options)

    This function is a coroutine.

    Edits the channel.

    You must have `manage_channels` to do this.

    Changed in version 1.3: The `overwrites` keyword-only parameter was added.

    Changed in version 1.4: The `type` keyword-only parameter was added.

    Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new channel name.

      - topic (`str`) – The new channel’s topic.

      - position (`int`) – The new channel’s position.

      - nsfw (`bool`) – To mark the channel as NSFW or not.

      - sync_permissions (`bool`) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to `False`.

      - category (Optional[`CategoryChannel`]) – The new category for this channel. Can be `None` to remove the category.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`.

      - type (`ChannelType`) – Change the type of this text channel. Currently, only conversion between `ChannelType.text` and `ChannelType.news` is supported. This is only available to guilds that contain `NEWS` in `Guild.features`.

      - reason (Optional[`str`]) – The reason for editing this channel. Shows up on the audit log.

      - overwrites (`Mapping`) – A `Mapping` of target (either a role or a member) to `PermissionOverwrite` to apply to the channel.

      - default_auto_archive_duration (`int`) –

        The new default auto archive duration in minutes for threads created in this channel. Must be one of `60`, `1440`, `4320`, or `10080`.

        Added in version 2.0.

      - default_thread_slowmode_delay (`int`) –

        The new default slowmode delay in seconds for threads created in this channel.

        Added in version 2.3.

    Raises:

      - ValueError – The new `position` is less than 0 or greater than the number of channels.

      - TypeError – The permission overwrite information is not in proper form.

      - Forbidden – You do not have permissions to edit the channel.

      - HTTPException – Editing the channel failed.

    Returns:

      The newly edited text channel. If the edit was only positional then `None` is returned instead.

    Return type:

      Optional[`TextChannel`]

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await delete_messages(messages, *, reason=None)

    This function is a coroutine.

    Deletes a list of messages. This is similar to `Message.delete()` except it bulk deletes multiple messages.

    As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

    You cannot bulk delete more than 100 messages or messages that are older than 14 days old.

    You must have `manage_messages` to do this.

    Changed in version 2.0: `messages` parameter is now positional-only.

    The `reason` keyword-only parameter was added.

    Parameters:

      - messages (Iterable[`abc.Snowflake`]) – An iterable of messages denoting which ones to bulk delete.

      - reason (Optional[`str`]) – The reason for deleting the messages. Shows up on the audit log.

    Raises:

      - ClientException – The number of messages to delete was more than 100.

      - Forbidden – You do not have proper permissions to delete the messages.

      - NotFound – If single delete, then the message was already deleted.

      - HTTPException – Deleting the messages failed.

  await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, bulk=True, reason=None)

    This function is a coroutine.

    Purges a list of messages that meet the criteria given by the predicate `check`. If a `check` is not provided then all messages are deleted without discrimination.

    You must have `manage_messages` to delete messages even if they are your own. Having `read_message_history` is also needed to retrieve message history.

    Changed in version 2.0: The `reason` keyword-only parameter was added.

    Examples

    Deleting bot’s messages

        def is_me(m):
            return m.author == client.user

        deleted = await channel.purge(limit=100, check=is_me)
        await channel.send(f'Deleted {len(deleted)} message(s)')

    Parameters:

      - limit (Optional[`int`]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.

      - check (Callable[[`Message`], `bool`]) – The function used to check if a message should be deleted. It must take a `Message` as its sole parameter.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `before` in `history()`.

      - after (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `after` in `history()`.

      - around (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `around` in `history()`.

      - oldest_first (Optional[`bool`]) – Same as `oldest_first` in `history()`.

      - bulk (`bool`) – If `True`, use bulk delete. Setting this to `False` is useful for mass-deleting a bot’s own messages without `Permissions.manage_messages`. When `True`, will fall back to single delete if messages are older than two weeks.

      - reason (Optional[`str`]) – The reason for purging the messages. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to do the actions required.

      - HTTPException – Purging the messages failed.

    Returns:

      The list of messages that were deleted.

    Return type:

      List[`Message`]

  await webhooks()

    This function is a coroutine.

    Gets the list of webhooks from this channel.

    You must have `manage_webhooks` to do this.

    Raises:

      Forbidden – You don’t have permissions to get the webhooks.

    Returns:

      The webhooks for this channel.

    Return type:

      List[`Webhook`]

  await create_webhook(*, name, avatar=None, reason=None)

    This function is a coroutine.

    Creates a webhook for this channel.

    You must have `manage_webhooks` to do this.

    Changed in version 1.1: Added the `reason` keyword-only parameter.

    Parameters:

      - name (`str`) – The webhook’s name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s default avatar. This operates similarly to `edit()`.

      - reason (Optional[`str`]) – The reason for creating this webhook. Shows up in the audit logs.

    Raises:

      - HTTPException – Creating the webhook failed.

      - Forbidden – You do not have permissions to create a webhook.

    Returns:

      The created webhook.

    Return type:

      `Webhook`

  await follow(*, destination, reason=None)

    This function is a coroutine.

    Follows a channel using a webhook.

    Only news channels can be followed.

    Note

    The webhook returned will not provide a token to do webhook actions, as Discord does not provide it.

    Added in version 1.3.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - destination (`TextChannel`) – The channel you would like to follow from.

      - reason (Optional[`str`]) –

        The reason for following the channel. Shows up on the destination guild’s audit log.

        Added in version 1.4.

    Raises:

      - HTTPException – Following the channel failed.

      - Forbidden – You do not have the permissions to create a webhook.

      - ClientException – The channel is not a news channel.

      - TypeError – The destination channel is not a text channel.

    Returns:

      The created webhook.

    Return type:

      `Webhook`

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Added in version 1.6.

    Changed in version 2.0: `message_id` parameter is now positional-only.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

  get_thread(thread_id, /)

    Returns a thread with the given ID.

    Note

    This does not always retrieve archived threads, as they are not retained in the internal cache. Use `Guild.fetch_channel()` instead.

    Added in version 2.0.

    Parameters:

      thread_id (`int`) – The ID to search for.

    Returns:

      The returned thread or `None` if not found.

    Return type:

      Optional[`Thread`]

  await create_thread(*, name, message=None, auto_archive_duration=..., type=None, reason=None, invitable=True, slowmode_delay=None)

    This function is a coroutine.

    Creates a thread in this text channel.

    To create a public thread, you must have `create_public_threads`. For a private thread, `create_private_threads` is needed instead.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the thread.

      - message (Optional[`abc.Snowflake`]) – A snowflake representing the message to create the thread with. If `None` is passed then a private thread is created. Defaults to `None`.

      - auto_archive_duration (`int`) –

        The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

        Must be one of `60`, `1440`, `4320`, or `10080`, if provided.

      - type (Optional[`ChannelType`]) – The type of thread to create. If a `message` is passed then this parameter is ignored, as a thread created with a message is always a public thread. By default this creates a private thread if this is `None`.

      - reason (`str`) – The reason for creating a new thread. Shows up on the audit log.

      - invitable (`bool`) – Whether non-moderators can add users to the thread. Only applicable to private threads. Defaults to `True`.

      - slowmode_delay (Optional[`int`]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`. By default no slowmode rate limit if this is `None`.

    Raises:

      - Forbidden – You do not have permissions to create a thread.

      - HTTPException – Starting the thread failed.

    Returns:

      The created thread

    Return type:

      `Thread`

  async for ... in archived_threads(*, private=False, joined=False, limit=100, before=None)

    Returns an asynchronous iterator that iterates over all archived threads in this text channel, in order of decreasing ID for joined threads, and decreasing `Thread.archive_timestamp` otherwise.

    You must have `read_message_history` to do this. If iterating over private threads then `manage_threads` is also required.

    Added in version 2.0.

    Parameters:

      - limit (Optional[`bool`]) – The number of threads to retrieve. If `None`, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Retrieve archived channels before the given date or ID.

      - private (`bool`) – Whether to retrieve private archived threads.

      - joined (`bool`) – Whether to retrieve private archived threads that you’ve joined. You cannot set `joined` to `True` and `private` to `False`.

    Raises:

      - Forbidden – You do not have permissions to get archived threads.

      - HTTPException – The request to get the archived threads failed.

      - ValueError – `joined` was set to `True` and `private` was set to `False`. You cannot retrieve public archived threads that you have joined.

    Yields:

      `Thread` – The archived threads.

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

### ForumChannel

Attributes

- available_tags
- category
- category_id
- changed_roles
- created_at
- default_auto_archive_duration
- default_layout
- default_reaction_emoji
- default_sort_order
- default_thread_slowmode_delay
- flags
- guild
- id
- jump_url
- last_message_id
- members
- mention
- name
- nsfw
- overwrites
- permissions_synced
- position
- slowmode_delay
- threads
- topic
- type

Methods

- async for archived_threads
- async clone
- async create_invite
- async create_tag
- async create_thread
- async create_webhook
- async delete
- async edit
- def get_tag
- def get_thread
- async invites
- def is_media
- def is_nsfw
- async move
- def overwrites_for
- def permissions_for
- async set_permissions
- async webhooks

class discord.ForumChannel

  Represents a Discord guild forum channel.

  Added in version 2.0.

  x == y

    Checks if two forums are equal.

  x != y

    Checks if two forums are not equal.

  hash(x)

    Returns the forum’s hash.

  str(x)

    Returns the forum’s name.

  name

    The forum name.

    Type:

      `str`

  guild

    The guild the forum belongs to.

    Type:

      `Guild`

  id

    The forum ID.

    Type:

      `int`

  category_id

    The category channel ID this forum belongs to, if applicable.

    Type:

      Optional[`int`]

  topic

    The forum’s topic. `None` if it doesn’t exist. Called “Guidelines” in the UI. Can be up to 4096 characters long.

    Type:

      Optional[`str`]

  position

    The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

    Type:

      `int`

  last_message_id

    The last thread ID that was created on this forum. This technically also coincides with the message ID that started the thread that was created. It may not point to an existing or valid thread or message.

    Type:

      Optional[`int`]

  slowmode_delay

    The number of seconds a member must wait between creating threads in this forum. A value of `0` denotes that it is disabled. Bots and users with `manage_channels` or `manage_messages` bypass slowmode.

    Type:

      `int`

  nsfw

    If the forum is marked as “not safe for work” or “age restricted”.

    Type:

      `bool`

  default_auto_archive_duration

    The default auto archive duration in minutes for threads created in this forum.

    Type:

      `int`

  default_thread_slowmode_delay

    The default slowmode delay in seconds for threads created in this forum.

    Added in version 2.1.

    Type:

      `int`

  default_reaction_emoji

    The default reaction emoji for threads created in this forum to show in the add reaction button.

    Added in version 2.1.

    Type:

      Optional[`PartialEmoji`]

  default_layout

    The default layout for posts in this forum channel. Defaults to `ForumLayoutType.not_set`.

    Added in version 2.2.

    Type:

      `ForumLayoutType`

  default_sort_order

    The default sort order for posts in this forum channel.

    Added in version 2.3.

    Type:

      Optional[`ForumOrderType`]

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  property members

    Returns all members that can see this channel.

    Added in version 2.5.

    Type:

      List[`Member`]

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  get_thread(thread_id, /)

    Returns a thread with the given ID.

    Note

    This does not always retrieve archived threads, as they are not retained in the internal cache. Use `Guild.fetch_channel()` instead.

    Added in version 2.2.

    Parameters:

      thread_id (`int`) – The ID to search for.

    Returns:

      The returned thread or `None` if not found.

    Return type:

      Optional[`Thread`]

  property threads

    Returns all the threads that you can see.

    Type:

      List[`Thread`]

  property flags

    The flags associated with this thread.

    Added in version 2.1.

    Type:

      `ChannelFlags`

  property available_tags

    Returns all the available tags for this forum.

    Added in version 2.1.

    Type:

      Sequence[`ForumTag`]

  get_tag(tag_id, /)

    Returns the tag with the given ID.

    Added in version 2.1.

    Parameters:

      tag_id (`int`) – The ID to search for.

    Returns:

      The tag with the given ID, or `None` if not found.

    Return type:

      Optional[`ForumTag`]

  is_nsfw()

    `bool`: Checks if the forum is NSFW.

  is_media()

    `bool`: Checks if the channel is a media channel.

    Added in version 2.4.

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await edit(*, reason=None, **options)

    This function is a coroutine.

    Edits the forum.

    You must have `manage_channels` to do this.

    Parameters:

      - name (`str`) – The new forum name.

      - topic (`str`) – The new forum’s topic.

      - position (`int`) – The new forum’s position.

      - nsfw (`bool`) – To mark the forum as NSFW or not.

      - sync_permissions (`bool`) – Whether to sync permissions with the forum’s new or pre-existing category. Defaults to `False`.

      - category (Optional[`CategoryChannel`]) – The new category for this forum. Can be `None` to remove the category.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this forum, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`.

      - type (`ChannelType`) – Change the type of this text forum. Currently, only conversion between `ChannelType.text` and `ChannelType.news` is supported. This is only available to guilds that contain `NEWS` in `Guild.features`.

      - reason (Optional[`str`]) – The reason for editing this forum. Shows up on the audit log.

      - overwrites (`Mapping`) – A `Mapping` of target (either a role or a member) to `PermissionOverwrite` to apply to the forum.

      - default_auto_archive_duration (`int`) – The new default auto archive duration in minutes for threads created in this channel. Must be one of `60`, `1440`, `4320`, or `10080`.

      - available_tags (Sequence[`ForumTag`]) –

        The new available tags for this forum.

        Added in version 2.1.

      - default_thread_slowmode_delay (`int`) –

        The new default slowmode delay for threads in this channel.

        Added in version 2.1.

      - default_reaction_emoji (Optional[Union[`Emoji`, `PartialEmoji`, `str`]]) –

        The new default reaction emoji for threads in this channel.

        Added in version 2.1.

      - default_layout (`ForumLayoutType`) –

        The new default layout for posts in this forum.

        Added in version 2.2.

      - default_sort_order (Optional[`ForumOrderType`]) –

        The new default sort order for posts in this forum.

        Added in version 2.3.

      - require_tag (`bool`) –

        Whether to require a tag for threads in this channel or not.

        Added in version 2.1.

    Raises:

      - ValueError – The new `position` is less than 0 or greater than the number of channels.

      - TypeError – The permission overwrite information is not in proper form or a type is not the expected type.

      - Forbidden – You do not have permissions to edit the forum.

      - HTTPException – Editing the forum failed.

    Returns:

      The newly edited forum channel. If the edit was only positional then `None` is returned instead.

    Return type:

      Optional[`ForumChannel`]

  await create_tag(*, name, emoji=None, moderated=False, reason=None)

    This function is a coroutine.

    Creates a new tag in this forum.

    You must have `manage_channels` to do this.

    Parameters:

      - name (`str`) – The name of the tag. Can only be up to 20 characters.

      - emoji (Optional[Union[`str`, `PartialEmoji`]]) – The emoji to use for the tag.

      - moderated (`bool`) – Whether the tag can only be applied by moderators.

      - reason (Optional[`str`]) – The reason for creating this tag. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a tag in this forum.

      - HTTPException – Creating the tag failed.

    Returns:

      The newly created tag.

    Return type:

      `ForumTag`

  await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, content=None, tts=False, embed=..., embeds=..., file=..., files=..., stickers=..., allowed_mentions=..., mention_author=..., applied_tags=..., view=..., suppress_embeds=False, reason=None)

    This function is a coroutine.

    Creates a thread in this forum.

    This thread is a public thread with the initial message given. Currently in order to start a thread in this forum, the user needs `send_messages`.

    You must send at least one of `content`, `embed`, `embeds`, `file`, `files`, or `view` to create a thread in a forum, since forum channels must have a starter message.

    Parameters:

      - name (`str`) – The name of the thread.

      - auto_archive_duration (`int`) –

        The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

        Must be one of `60`, `1440`, `4320`, or `10080`, if provided.

      - slowmode_delay (Optional[`int`]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`. By default no slowmode rate limit if this is `None`.

      - content (Optional[`str`]) – The content of the message to send with the thread.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) – A list of embeds to upload. Must be a maximum of 10.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - allowed_mentions (`AllowedMentions`) – Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

      - mention_author (`bool`) – If set, overrides the `replied_user` attribute of `allowed_mentions`.

      - applied_tags (List[`discord.ForumTag`]) – A list of tags to apply to the thread.

      - view (`discord.ui.View`) – A Discord UI View to add to the message.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) – A list of stickers to upload. Must be a maximum of 3.

      - suppress_embeds (`bool`) – Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

      - reason (`str`) – The reason for creating a new thread. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a thread.

      - HTTPException – Starting the thread failed.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`.

    Returns:

      The created thread with the created message. This is also accessible as a namedtuple with `thread` and `message` fields.

    Return type:

      Tuple[`Thread`, `Message`]

  await webhooks()

    This function is a coroutine.

    Gets the list of webhooks from this channel.

    You must have `manage_webhooks` to do this.

    Raises:

      Forbidden – You don’t have permissions to get the webhooks.

    Returns:

      The webhooks for this channel.

    Return type:

      List[`Webhook`]

  await create_webhook(*, name, avatar=None, reason=None)

    This function is a coroutine.

    Creates a webhook for this channel.

    You must have `manage_webhooks` to do this.

    Parameters:

      - name (`str`) – The webhook’s name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s default avatar. This operates similarly to `edit()`.

      - reason (Optional[`str`]) – The reason for creating this webhook. Shows up in the audit logs.

    Raises:

      - HTTPException – Creating the webhook failed.

      - Forbidden – You do not have permissions to create a webhook.

    Returns:

      The created webhook.

    Return type:

      `Webhook`

  async for ... in archived_threads(*, limit=100, before=None)

    Returns an asynchronous iterator that iterates over all archived threads in this forum in order of decreasing `Thread.archive_timestamp`.

    You must have `read_message_history` to do this.

    Added in version 2.0.

    Parameters:

      - limit (Optional[`bool`]) – The number of threads to retrieve. If `None`, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Retrieve archived channels before the given date or ID.

    Raises:

      - Forbidden – You do not have permissions to get archived threads.

      - HTTPException – The request to get the archived threads failed.

    Yields:

      `Thread` – The archived threads.

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

### Thread

Attributes

- applied_tags
- archive_timestamp
- archived
- archiver_id
- auto_archive_duration
- category
- category_id
- created_at
- flags
- guild
- id
- invitable
- jump_url
- last_message
- last_message_id
- locked
- me
- member_count
- members
- mention
- message_count
- name
- owner
- owner_id
- parent
- parent_id
- slowmode_delay
- starter_message
- type

Methods

- async add_tags
- async add_user
- async delete
- async delete_messages
- async edit
- async fetch_member
- async fetch_members
- async fetch_message
- def get_partial_message
- async for history
- def is_news
- def is_nsfw
- def is_private
- async join
- async leave
- def permissions_for
- async pins
- async purge
- async remove_tags
- async remove_user
- async send
- def typing

class discord.Thread

  Represents a Discord thread.

  x == y

    Checks if two threads are equal.

  x != y

    Checks if two threads are not equal.

  hash(x)

    Returns the thread’s hash.

  str(x)

    Returns the thread’s name.

  Added in version 2.0.

  name

    The thread name.

    Type:

      `str`

  guild

    The guild the thread belongs to.

    Type:

      `Guild`

  id

    The thread ID. This is the same as the thread starter message ID.

    Type:

      `int`

  parent_id

    The parent `TextChannel` or `ForumChannel` ID this thread belongs to.

    Type:

      `int`

  owner_id

    The user’s ID that created this thread.

    Type:

      `int`

  last_message_id

    The last message ID of the message sent to this thread. It may not point to an existing or valid message.

    Type:

      Optional[`int`]

  slowmode_delay

    The number of seconds a member must wait between sending messages in this thread. A value of `0` denotes that it is disabled. Bots and users with `manage_channels` or `manage_messages` bypass slowmode.

    Type:

      `int`

  message_count

    An approximate number of messages in this thread.

    Type:

      `int`

  member_count

    An approximate number of members in this thread. This caps at 50.

    Type:

      `int`

  me

    A thread member representing yourself, if you’ve joined the thread. This could not be available.

    Type:

      Optional[`ThreadMember`]

  archived

    Whether the thread is archived.

    Type:

      `bool`

  locked

    Whether the thread is locked.

    Type:

      `bool`

  invitable

    Whether non-moderators can add other non-moderators to this thread. This is always `True` for public threads.

    Type:

      `bool`

  archiver_id

    The user’s ID that archived this thread.

    Note

    Due to an API change, the `archiver_id` will always be `None` and can only be obtained via the audit log.

    Type:

      Optional[`int`]

  auto_archive_duration

    The duration in minutes until the thread is automatically hidden from the channel list. Usually a value of 60, 1440, 4320 and 10080.

    Type:

      `int`

  archive_timestamp

    An aware timestamp of when the thread’s archived status was last updated in UTC.

    Type:

      `datetime.datetime`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  property parent

    The parent channel this thread belongs to.

    Type:

      Optional[Union[`ForumChannel`, `TextChannel`]]

  property flags

    The flags associated with this thread.

    Type:

      `ChannelFlags`

  property owner

    The member this thread belongs to.

    Type:

      Optional[`Member`]

  property mention

    The string that allows you to mention the thread.

    Type:

      `str`

  property jump_url

    Returns a URL that allows the client to jump to the thread.

    Added in version 2.0.

    Type:

      `str`

  property members

    A list of thread members in this thread.

    This requires `Intents.members` to be properly filled. Most of the time however, this data is not provided by the gateway and a call to `fetch_members()` is needed.

    Type:

      List[`ThreadMember`]

  property applied_tags

    A list of tags applied to this thread.

    Added in version 2.1.

    Type:

      List[`ForumTag`]

  property starter_message

    Returns the thread starter message from the cache.

    The message might not be cached, valid, or point to an existing message.

    Note that the thread starter message ID is the same ID as the thread.

    Returns:

      The thread starter message or `None` if not found.

    Return type:

      Optional[`Message`]

  property last_message

    Returns the last message from this thread from the cache.

    The message might not be valid or point to an existing message.

    Reliable Fetching

    For a slightly more reliable method of fetching the last message, consider using either `history()` or `fetch_message()` with the `last_message_id` attribute.

    Returns:

      The last message in this channel or `None` if not found.

    Return type:

      Optional[`Message`]

  property category

    The category channel the parent channel belongs to, if applicable.

    Raises:

      ClientException – The parent channel was not cached and returned `None`.

    Returns:

      The parent channel’s category.

    Return type:

      Optional[`CategoryChannel`]

  property category_id

    The category channel ID the parent channel belongs to, if applicable.

    Raises:

      ClientException – The parent channel was not cached and returned `None`.

    Returns:

      The parent channel’s category ID.

    Return type:

      Optional[`int`]

  property created_at

    An aware timestamp of when the thread was created in UTC.

    Note

    This timestamp only exists for threads created after 9 January 2022, otherwise returns `None`.

  is_private()

    `bool`: Whether the thread is a private thread.

    A private thread is only viewable by those that have been explicitly invited or have `manage_threads`.

  is_news()

    `bool`: Whether the thread is a news thread.

    A news thread is a thread that has a parent that is a news channel, i.e. `TextChannel.is_news()` is `True`.

  is_nsfw()

    `bool`: Whether the thread is NSFW or not.

    An NSFW thread is a thread that has a parent that is an NSFW channel, i.e. `TextChannel.is_nsfw()` is `True`.

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    Since threads do not have their own permissions, they mostly inherit them from the parent channel with some implicit permissions changed.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Raises:

      ClientException – The parent channel was not cached and returned `None`

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  await delete_messages(messages, /, *, reason=None)

    This function is a coroutine.

    Deletes a list of messages. This is similar to `Message.delete()` except it bulk deletes multiple messages.

    As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

    You cannot bulk delete more than 100 messages or messages that are older than 14 days old.

    You must have `manage_messages` to do this.

    Parameters:

      - messages (Iterable[`abc.Snowflake`]) – An iterable of messages denoting which ones to bulk delete.

      - reason (Optional[`str`]) – The reason for deleting the messages. Shows up on the audit log.

    Raises:

      - ClientException – The number of messages to delete was more than 100.

      - Forbidden – You do not have proper permissions to delete the messages or you’re not using a bot account.

      - NotFound – If single delete, then the message was already deleted.

      - HTTPException – Deleting the messages failed.

  await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, bulk=True, reason=None)

    This function is a coroutine.

    Purges a list of messages that meet the criteria given by the predicate `check`. If a `check` is not provided then all messages are deleted without discrimination.

    You must have `manage_messages` to delete messages even if they are your own. Having `read_message_history` is also needed to retrieve message history.

    Examples

    Deleting bot’s messages

        def is_me(m):
            return m.author == client.user

        deleted = await thread.purge(limit=100, check=is_me)
        await thread.send(f'Deleted {len(deleted)} message(s)')

    Parameters:

      - limit (Optional[`int`]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.

      - check (Callable[[`Message`], `bool`]) – The function used to check if a message should be deleted. It must take a `Message` as its sole parameter.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `before` in `history()`.

      - after (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `after` in `history()`.

      - around (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `around` in `history()`.

      - oldest_first (Optional[`bool`]) – Same as `oldest_first` in `history()`.

      - bulk (`bool`) – If `True`, use bulk delete. Setting this to `False` is useful for mass-deleting a bot’s own messages without `Permissions.manage_messages`. When `True`, will fall back to single delete if messages are older than two weeks.

      - reason (Optional[`str`]) – The reason for purging the messages. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to do the actions required.

      - HTTPException – Purging the messages failed.

    Returns:

      The list of messages that were deleted.

    Return type:

      List[`Message`]

  await edit(*, name=..., archived=..., locked=..., invitable=..., pinned=..., slowmode_delay=..., auto_archive_duration=..., applied_tags=..., reason=None)

    This function is a coroutine.

    Edits the thread.

    Editing the thread requires `Permissions.manage_threads`. The thread creator can also edit `name`, `archived` or `auto_archive_duration`. Note that if the thread is locked then only those with `Permissions.manage_threads` can unarchive a thread.

    The thread must be unarchived to be edited.

    Parameters:

      - name (`str`) – The new name of the thread.

      - archived (`bool`) – Whether to archive the thread or not.

      - locked (`bool`) – Whether to lock the thread or not.

      - pinned (`bool`) – Whether to pin the thread or not. This only works if the thread is part of a forum.

      - invitable (`bool`) – Whether non-moderators can add other non-moderators to this thread. Only available for private threads.

      - auto_archive_duration (`int`) – The new duration in minutes before a thread is automatically hidden from the channel list. Must be one of `60`, `1440`, `4320`, or `10080`.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this thread, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`.

      - applied_tags (Sequence[`ForumTag`]) –

        The new tags to apply to the thread. There can only be up to 5 tags applied to a thread.

        Added in version 2.1.

      - reason (Optional[`str`]) – The reason for editing this thread. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit the thread.

      - HTTPException – Editing the thread failed.

    Returns:

      The newly edited thread.

    Return type:

      `Thread`

  await add_tags(*tags, reason=None)

    This function is a coroutine.

    Adds the given forum tags to a thread.

    You must have `manage_threads` to use this or the thread must be owned by you.

    Tags that have `ForumTag.moderated` set to `True` require `manage_threads` to be added.

    The maximum number of tags that can be added to a thread is 5.

    The parent channel must be a `ForumChannel`.

    Added in version 2.1.

    Parameters:

      - *tags (`abc.Snowflake`) – An argument list of `abc.Snowflake` representing a `ForumTag` to add to the thread.

      - reason (Optional[`str`]) – The reason for adding these tags.

    Raises:

      - Forbidden – You do not have permissions to add these tags.

      - HTTPException – Adding tags failed.

  await remove_tags(*tags, reason=None)

    This function is a coroutine.

    Remove the given forum tags to a thread.

    You must have `manage_threads` to use this or the thread must be owned by you.

    The parent channel must be a `ForumChannel`.

    Added in version 2.1.

    Parameters:

      - *tags (`abc.Snowflake`) – An argument list of `abc.Snowflake` representing a `ForumTag` to remove to the thread.

      - reason (Optional[`str`]) – The reason for removing these tags.

    Raises:

      - Forbidden – You do not have permissions to remove these tags.

      - HTTPException – Removing tags failed.

  await join()

    This function is a coroutine.

    Joins this thread.

    You must have `send_messages_in_threads` to join a thread. If the thread is private, `manage_threads` is also needed.

    Raises:

      - Forbidden – You do not have permissions to join the thread.

      - HTTPException – Joining the thread failed.

  await leave()

    This function is a coroutine.

    Leaves this thread.

    Raises:

      HTTPException – Leaving the thread failed.

  await add_user(user, /)

    This function is a coroutine.

    Adds a user to this thread.

    You must have `send_messages_in_threads` to add a user to a thread. If the thread is private and `invitable` is `False` then `manage_messages` is required to add a user to the thread.

    Parameters:

      user (`abc.Snowflake`) – The user to add to the thread.

    Raises:

      - Forbidden – You do not have permissions to add the user to the thread.

      - HTTPException – Adding the user to the thread failed.

  await remove_user(user, /)

    This function is a coroutine.

    Removes a user from this thread.

    You must have `manage_threads` or be the creator of the thread to remove a user.

    Parameters:

      user (`abc.Snowflake`) – The user to remove from the thread.

    Raises:

      - Forbidden – You do not have permissions to remove the user from the thread.

      - HTTPException – Removing the user from the thread failed.

  await fetch_member(user_id, /)

    This function is a coroutine.

    Retrieves a `ThreadMember` for the given user ID.

    Raises:

      - NotFound – The specified user is not a member of this thread.

      - HTTPException – Retrieving the member failed.

    Returns:

      The thread member from the user ID.

    Return type:

      `ThreadMember`

  await fetch_members()

    This function is a coroutine.

    Retrieves all `ThreadMember` that are in this thread.

    This requires `Intents.members` to get information about members other than yourself.

    Raises:

      HTTPException – Retrieving the members failed.

    Returns:

      All thread members in the thread.

    Return type:

      List[`ThreadMember`]

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes this thread.

    You must have `manage_threads` to delete threads.

    Parameters:

      reason (Optional[`str`]) –

      The reason for deleting this thread. Shows up on the audit log.

      Added in version 2.4.

    Raises:

      - Forbidden – You do not have permissions to delete this thread.

      - HTTPException – Deleting the thread failed.

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Added in version 2.0.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

### ThreadMember

Attributes

- id
- joined_at
- thread
- thread_id

class discord.ThreadMember

  Represents a Discord thread member.

  x == y

    Checks if two thread members are equal.

  x != y

    Checks if two thread members are not equal.

  hash(x)

    Returns the thread member’s hash.

  str(x)

    Returns the thread member’s name.

  Added in version 2.0.

  id

    The thread member’s ID.

    Type:

      `int`

  thread_id

    The thread’s ID.

    Type:

      `int`

  joined_at

    The time the member joined the thread in UTC.

    Type:

      `datetime.datetime`

  property thread

    The thread this member belongs to.

    Type:

      `Thread`

### VoiceChannel

Attributes

- bitrate
- category
- category_id
- changed_roles
- created_at
- guild
- id
- jump_url
- last_message
- last_message_id
- members
- mention
- name
- nsfw
- overwrites
- permissions_synced
- position
- rtc_region
- scheduled_events
- slowmode_delay
- type
- user_limit
- video_quality_mode
- voice_states

Methods

- async clone
- async connect
- async create_invite
- async create_webhook
- async delete
- async delete_messages
- async edit
- async fetch_message
- def get_partial_message
- async for history
- async invites
- def is_nsfw
- async move
- def overwrites_for
- def permissions_for
- async pins
- async purge
- async send
- async send_sound
- async set_permissions
- def typing
- async webhooks

class discord.VoiceChannel

  Represents a Discord guild voice channel.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the channel’s hash.

  str(x)

    Returns the channel’s name.

  name

    The channel name.

    Type:

      `str`

  guild

    The guild the channel belongs to.

    Type:

      `Guild`

  id

    The channel ID.

    Type:

      `int`

  nsfw

    If the channel is marked as “not safe for work” or “age restricted”.

    Added in version 2.0.

    Type:

      `bool`

  category_id

    The category channel ID this channel belongs to, if applicable.

    Type:

      Optional[`int`]

  position

    The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

    Type:

      `int`

  bitrate

    The channel’s preferred audio bitrate in bits per second.

    Type:

      `int`

  user_limit

    The channel’s limit for number of members that can be in a voice channel.

    Type:

      `int`

  rtc_region

    The region for the voice channel’s voice communication. A value of `None` indicates automatic voice region detection.

    Added in version 1.7.

    Changed in version 2.0: The type of this attribute has changed to `str`.

    Type:

      Optional[`str`]

  video_quality_mode

    The camera video quality for the voice channel’s participants.

    Added in version 2.0.

    Type:

      `VideoQualityMode`

  last_message_id

    The last message ID of the message sent to this channel. It may not point to an existing or valid message.

    Added in version 2.0.

    Type:

      Optional[`int`]

  slowmode_delay

    The number of seconds a member must wait between sending messages in this channel. A value of `0` denotes that it is disabled. Bots and users with `manage_channels` or `manage_messages` bypass slowmode.

    Added in version 2.2.

    Type:

      `int`

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  await edit(*, reason=None, **options)

    This function is a coroutine.

    Edits the channel.

    You must have `manage_channels` to do this.

    Changed in version 1.3: The `overwrites` keyword-only parameter was added.

    Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

    Changed in version 2.0: The `region` parameter now accepts `str` instead of an enum.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new channel’s name.

      - bitrate (`int`) – The new channel’s bitrate.

      - nsfw (`bool`) – To mark the channel as NSFW or not.

      - user_limit (`int`) – The new channel’s user limit.

      - position (`int`) – The new channel’s position.

      - sync_permissions (`bool`) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to `False`.

      - category (Optional[`CategoryChannel`]) – The new category for this channel. Can be `None` to remove the category.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`.

      - reason (Optional[`str`]) – The reason for editing this channel. Shows up on the audit log.

      - overwrites (`Mapping`) – A `Mapping` of target (either a role or a member) to `PermissionOverwrite` to apply to the channel.

      - rtc_region (Optional[`str`]) –

        The new region for the voice channel’s voice communication. A value of `None` indicates automatic voice region detection.

        Added in version 1.7.

      - video_quality_mode (`VideoQualityMode`) –

        The camera video quality for the voice channel’s participants.

        Added in version 2.0.

      - status (Optional[`str`]) –

        The new voice channel status. It can be up to 500 characters. Can be `None` to remove the status.

        Added in version 2.4.

    Raises:

      - TypeError – If the permission overwrite information is not in proper form.

      - Forbidden – You do not have permissions to edit the channel.

      - HTTPException – Editing the channel failed.

    Returns:

      The newly edited voice channel. If the edit was only positional then `None` is returned instead.

    Return type:

      Optional[`VoiceChannel`]

  await send_sound(sound, /)

    This function is a coroutine.

    Sends a soundboard sound for this channel.

    You must have `speak` and `use_soundboard` to do this. Additionally, you must have `use_external_sounds` if the sound is from a different guild.

    Added in version 2.5.

    Parameters:

      sound (Union[`SoundboardSound`, `SoundboardDefaultSound`]) – The sound to send for this channel.

    Raises:

      - Forbidden – You do not have permissions to send a sound for this channel.

      - HTTPException – Sending the sound failed.

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await connect(*, timeout=30.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, self_deaf=False, self_mute=False)

    This function is a coroutine.

    Connects to voice and creates a `VoiceClient` to establish your connection to the voice server.

    This requires `voice_states`.

    Parameters:

      - timeout (`float`) – The timeout in seconds to wait the connection to complete.

      - reconnect (`bool`) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.

      - cls (Type[`VoiceProtocol`]) – A type that subclasses `VoiceProtocol` to connect with. Defaults to `VoiceClient`.

      - self_mute (`bool`) –

        Indicates if the client should be self-muted.

        Added in version 2.0.

      - self_deaf (`bool`) –

        Indicates if the client should be self-deafened.

        Added in version 2.0.

    Raises:

      - asyncio.TimeoutError – Could not connect to the voice channel in time.

      - ClientException – You are already connected to a voice channel.

      - OpusNotLoaded – The opus library has not been loaded.

    Returns:

      A voice client that is fully connected to the voice server.

    Return type:

      `VoiceProtocol`

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  await create_webhook(*, name, avatar=None, reason=None)

    This function is a coroutine.

    Creates a webhook for this channel.

    You must have `manage_webhooks` to do this.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The webhook’s name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s default avatar. This operates similarly to `edit()`.

      - reason (Optional[`str`]) – The reason for creating this webhook. Shows up in the audit logs.

    Raises:

      - HTTPException – Creating the webhook failed.

      - Forbidden – You do not have permissions to create a webhook.

    Returns:

      The created webhook.

    Return type:

      `Webhook`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await delete_messages(messages, *, reason=None)

    This function is a coroutine.

    Deletes a list of messages. This is similar to `Message.delete()` except it bulk deletes multiple messages.

    As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

    You cannot bulk delete more than 100 messages or messages that are older than 14 days old.

    You must have `manage_messages` to do this.

    Added in version 2.0.

    Parameters:

      - messages (Iterable[`abc.Snowflake`]) – An iterable of messages denoting which ones to bulk delete.

      - reason (Optional[`str`]) – The reason for deleting the messages. Shows up on the audit log.

    Raises:

      - ClientException – The number of messages to delete was more than 100.

      - Forbidden – You do not have proper permissions to delete the messages.

      - NotFound – If single delete, then the message was already deleted.

      - HTTPException – Deleting the messages failed.

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Added in version 2.0.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  is_nsfw()

    `bool`: Checks if the channel is NSFW.

    Added in version 2.0.

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property last_message

    Retrieves the last message from this channel in cache.

    The message might not be valid or point to an existing message.

    Added in version 2.0.

    Reliable Fetching

    For a slightly more reliable method of fetching the last message, consider using either `history()` or `fetch_message()` with the `last_message_id` attribute.

    Returns:

      The last message in this channel or `None` if not found.

    Return type:

      Optional[`Message`]

  property members

    Returns all members that are currently inside this voice channel.

    Type:

      List[`Member`]

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, bulk=True, reason=None)

    This function is a coroutine.

    Purges a list of messages that meet the criteria given by the predicate `check`. If a `check` is not provided then all messages are deleted without discrimination.

    You must have `manage_messages` to delete messages even if they are your own. Having `read_message_history` is also needed to retrieve message history.

    Added in version 2.0.

    Examples

    Deleting bot’s messages

        def is_me(m):
            return m.author == client.user

        deleted = await channel.purge(limit=100, check=is_me)
        await channel.send(f'Deleted {len(deleted)} message(s)')

    Parameters:

      - limit (Optional[`int`]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.

      - check (Callable[[`Message`], `bool`]) – The function used to check if a message should be deleted. It must take a `Message` as its sole parameter.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `before` in `history()`.

      - after (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `after` in `history()`.

      - around (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `around` in `history()`.

      - oldest_first (Optional[`bool`]) – Same as `oldest_first` in `history()`.

      - bulk (`bool`) – If `True`, use bulk delete. Setting this to `False` is useful for mass-deleting a bot’s own messages without `Permissions.manage_messages`. When `True`, will fall back to single delete if messages are older than two weeks.

      - reason (Optional[`str`]) – The reason for purging the messages. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to do the actions required.

      - HTTPException – Purging the messages failed.

    Returns:

      The list of messages that were deleted.

    Return type:

      List[`Message`]

  property scheduled_events

    Returns all scheduled events for this channel.

    Added in version 2.0.

    Type:

      List[`ScheduledEvent`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

  typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property voice_states

    Returns a mapping of member IDs who have voice states in this channel.

    Added in version 1.3.

    Note

    This function is intentionally low level to replace `members` when the member cache is unavailable.

    Returns:

      The mapping of member ID to a voice state.

    Return type:

      Mapping[`int`, `VoiceState`]

  await webhooks()

    This function is a coroutine.

    Gets the list of webhooks from this channel.

    You must have `manage_webhooks` to do this.

    Added in version 2.0.

    Raises:

      Forbidden – You don’t have permissions to get the webhooks.

    Returns:

      The webhooks for this channel.

    Return type:

      List[`Webhook`]

Attributes

- animation
- channel
- emoji
- sound
- user

Methods

- def is_sound

class discord.VoiceChannelEffect

  Represents a Discord voice channel effect.

  Added in version 2.5.

  channel

    The channel in which the effect is sent.

    Type:

      `VoiceChannel`

  user

    The user who sent the effect. `None` if not found in cache.

    Type:

      Optional[`Member`]

  animation

    The animation the effect has. Returns `None` if the effect has no animation.

    Type:

      Optional[`VoiceChannelEffectAnimation`]

  emoji

    The emoji of the effect.

    Type:

      Optional[`PartialEmoji`]

  sound

    The sound of the effect. Returns `None` if it’s an emoji effect.

    Type:

      Optional[`VoiceChannelSoundEffect`]

  is_sound()

    `bool`: Whether the effect is a sound or not.

class discord.VoiceChannelEffectAnimation

  A namedtuple which represents a voice channel effect animation.

  Added in version 2.5.

  id

    The ID of the animation.

    Type:

      `int`

  type

    The type of the animation.

    Type:

      `VoiceChannelEffectAnimationType`

Attributes

- created_at
- id
- url
- volume

Methods

- def is_default
- async read
- async save
- async to_file

class discord.VoiceChannelSoundEffect

  Represents a Discord voice channel sound effect.

  Added in version 2.5.

  x == y

    Checks if two sound effects are equal.

  x != y

    Checks if two sound effects are not equal.

  hash(x)

    Returns the sound effect’s hash.

  id

    The ID of the sound.

    Type:

      `int`

  volume

    The volume of the sound as floating point percentage (e.g. `1.0` for 100%).

    Type:

      `float`

  property created_at

    Returns the snowflake’s creation time in UTC. Returns `None` if it’s a default sound.

    Type:

      Optional[`datetime.datetime`]

  is_default()

    `bool`: Whether it’s a default sound or not.

  await read()

    This function is a coroutine.

    Retrieves the content of this asset as a `bytes` object.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The content of the asset.

    Return type:

      `bytes`

  await save(fp, *, seek_begin=True)

    This function is a coroutine.

    Saves this asset into a file-like object.

    Parameters:

      - fp (Union[`io.BufferedIOBase`, `os.PathLike`]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

      - seek_begin (`bool`) – Whether to seek to the beginning of the file after saving is successfully done.

    Raises:

      - DiscordException – There was no internal connection state.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The number of bytes written.

    Return type:

      `int`

  await to_file(*, filename=..., description=None, spoiler=False)

    This function is a coroutine.

    Converts the asset into a `File` suitable for sending via `abc.Messageable.send()`.

    Added in version 2.0.

    Parameters:

      - filename (Optional[`str`]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.

      - description (Optional[`str`]) – The description for the file.

      - spoiler (`bool`) – Whether the file is a spoiler.

    Raises:

      - DiscordException – The asset does not have an associated state.

      - ValueError – The asset is a unicode emoji.

      - TypeError – The asset is a sticker with lottie type.

      - HTTPException – Downloading the asset failed.

      - NotFound – The asset was deleted.

    Returns:

      The asset as a file suitable for sending.

    Return type:

      `File`

  property url

    Returns the URL of the sound.

    Type:

      `str`

### StageChannel

Attributes

- bitrate
- category
- category_id
- changed_roles
- created_at
- guild
- id
- instance
- jump_url
- last_message
- last_message_id
- listeners
- members
- mention
- moderators
- name
- nsfw
- overwrites
- permissions_synced
- position
- requesting_to_speak
- rtc_region
- scheduled_events
- slowmode_delay
- speakers
- topic
- type
- user_limit
- video_quality_mode
- voice_states

Methods

- async clone
- async connect
- async create_instance
- async create_invite
- async create_webhook
- async delete
- async delete_messages
- async edit
- async fetch_instance
- async fetch_message
- def get_partial_message
- async for history
- async invites
- def is_nsfw
- async move
- def overwrites_for
- def permissions_for
- async pins
- async purge
- async send
- async set_permissions
- def typing
- async webhooks

class discord.StageChannel

  Represents a Discord guild stage channel.

  Added in version 1.7.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the channel’s hash.

  str(x)

    Returns the channel’s name.

  name

    The channel name.

    Type:

      `str`

  guild

    The guild the channel belongs to.

    Type:

      `Guild`

  id

    The channel ID.

    Type:

      `int`

  nsfw

    If the channel is marked as “not safe for work” or “age restricted”.

    Added in version 2.0.

    Type:

      `bool`

  topic

    The channel’s topic. `None` if it isn’t set.

    Type:

      Optional[`str`]

  category_id

    The category channel ID this channel belongs to, if applicable.

    Type:

      Optional[`int`]

  position

    The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

    Type:

      `int`

  bitrate

    The channel’s preferred audio bitrate in bits per second.

    Type:

      `int`

  user_limit

    The channel’s limit for number of members that can be in a stage channel.

    Type:

      `int`

  rtc_region

    The region for the stage channel’s voice communication. A value of `None` indicates automatic voice region detection.

    Type:

      Optional[`str`]

  video_quality_mode

    The camera video quality for the stage channel’s participants.

    Added in version 2.0.

    Type:

      `VideoQualityMode`

  last_message_id

    The last message ID of the message sent to this channel. It may not point to an existing or valid message.

    Added in version 2.2.

    Type:

      Optional[`int`]

  slowmode_delay

    The number of seconds a member must wait between sending messages in this channel. A value of `0` denotes that it is disabled. Bots and users with `manage_channels` or `manage_messages` bypass slowmode.

    Added in version 2.2.

    Type:

      `int`

  property requesting_to_speak

    A list of members who are requesting to speak in the stage channel.

    Type:

      List[`Member`]

  property speakers

    A list of members who have been permitted to speak in the stage channel.

    Added in version 2.0.

    Type:

      List[`Member`]

  property listeners

    A list of members who are listening in the stage channel.

    Added in version 2.0.

    Type:

      List[`Member`]

  property moderators

    A list of members who are moderating the stage channel.

    Added in version 2.0.

    Type:

      List[`Member`]

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  property instance

    The running stage instance of the stage channel.

    Added in version 2.0.

    Type:

      Optional[`StageInstance`]

  await create_instance(*, topic, privacy_level=..., send_start_notification=False, scheduled_event=..., reason=None)

    This function is a coroutine.

    Create a stage instance.

    You must have `manage_channels` to do this.

    Added in version 2.0.

    Parameters:

      - topic (`str`) – The stage instance’s topic.

      - privacy_level (`PrivacyLevel`) – The stage instance’s privacy level. Defaults to `PrivacyLevel.guild_only`.

      - send_start_notification (`bool`) –

        Whether to send a start notification. This sends a push notification to @everyone if `True`. Defaults to `False`. You must have `mention_everyone` to do this.

        Added in version 2.3.

      - scheduled_event (`Snowflake`) –

        The guild scheduled event associated with the stage instance.

        Added in version 2.4.

      - reason (`str`) – The reason the stage instance was created. Shows up on the audit log.

    Raises:

      - TypeError – If the `privacy_level` parameter is not the proper type.

      - Forbidden – You do not have permissions to create a stage instance.

      - HTTPException – Creating a stage instance failed.

    Returns:

      The newly created stage instance.

    Return type:

      `StageInstance`

  await fetch_instance()

    This function is a coroutine.

    Gets the running `StageInstance`.

    Added in version 2.0.

    Raises:

      - NotFound – The stage instance or channel could not be found.

      - HTTPException – Getting the stage instance failed.

    Returns:

      The stage instance.

    Return type:

      `StageInstance`

  await edit(*, reason=None, **options)

    This function is a coroutine.

    Edits the channel.

    You must have `manage_channels` to do this.

    Changed in version 2.0: The `topic` parameter must now be set via `create_instance`.

    Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

    Changed in version 2.0: The `region` parameter now accepts `str` instead of an enum.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new channel’s name.

      - bitrate (`int`) – The new channel’s bitrate.

      - position (`int`) – The new channel’s position.

      - nsfw (`bool`) – To mark the channel as NSFW or not.

      - user_limit (`int`) – The new channel’s user limit.

      - sync_permissions (`bool`) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to `False`.

      - category (Optional[`CategoryChannel`]) – The new category for this channel. Can be `None` to remove the category.

      - slowmode_delay (`int`) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`.

      - reason (Optional[`str`]) – The reason for editing this channel. Shows up on the audit log.

      - overwrites (`Mapping`) – A `Mapping` of target (either a role or a member) to `PermissionOverwrite` to apply to the channel.

      - rtc_region (Optional[`str`]) – The new region for the stage channel’s voice communication. A value of `None` indicates automatic voice region detection.

      - video_quality_mode (`VideoQualityMode`) –

        The camera video quality for the stage channel’s participants.

        Added in version 2.0.

    Raises:

      - ValueError – If the permission overwrite information is not in proper form.

      - Forbidden – You do not have permissions to edit the channel.

      - HTTPException – Editing the channel failed.

    Returns:

      The newly edited stage channel. If the edit was only positional then `None` is returned instead.

    Return type:

      Optional[`StageChannel`]

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await connect(*, timeout=30.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, self_deaf=False, self_mute=False)

    This function is a coroutine.

    Connects to voice and creates a `VoiceClient` to establish your connection to the voice server.

    This requires `voice_states`.

    Parameters:

      - timeout (`float`) – The timeout in seconds to wait the connection to complete.

      - reconnect (`bool`) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.

      - cls (Type[`VoiceProtocol`]) – A type that subclasses `VoiceProtocol` to connect with. Defaults to `VoiceClient`.

      - self_mute (`bool`) –

        Indicates if the client should be self-muted.

        Added in version 2.0.

      - self_deaf (`bool`) –

        Indicates if the client should be self-deafened.

        Added in version 2.0.

    Raises:

      - asyncio.TimeoutError – Could not connect to the voice channel in time.

      - ClientException – You are already connected to a voice channel.

      - OpusNotLoaded – The opus library has not been loaded.

    Returns:

      A voice client that is fully connected to the voice server.

    Return type:

      `VoiceProtocol`

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  await create_webhook(*, name, avatar=None, reason=None)

    This function is a coroutine.

    Creates a webhook for this channel.

    You must have `manage_webhooks` to do this.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The webhook’s name.

      - avatar (Optional[`bytes`]) – A py:bytes-like object representing the webhook’s default avatar. This operates similarly to `edit()`.

      - reason (Optional[`str`]) – The reason for creating this webhook. Shows up in the audit logs.

    Raises:

      - HTTPException – Creating the webhook failed.

      - Forbidden – You do not have permissions to create a webhook.

    Returns:

      The created webhook.

    Return type:

      `Webhook`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await delete_messages(messages, *, reason=None)

    This function is a coroutine.

    Deletes a list of messages. This is similar to `Message.delete()` except it bulk deletes multiple messages.

    As a special case, if the number of messages is 0, then nothing is done. If the number of messages is 1 then single message delete is done. If it’s more than two, then bulk delete is used.

    You cannot bulk delete more than 100 messages or messages that are older than 14 days old.

    You must have `manage_messages` to do this.

    Added in version 2.0.

    Parameters:

      - messages (Iterable[`abc.Snowflake`]) – An iterable of messages denoting which ones to bulk delete.

      - reason (Optional[`str`]) – The reason for deleting the messages. Shows up on the audit log.

    Raises:

      - ClientException – The number of messages to delete was more than 100.

      - Forbidden – You do not have proper permissions to delete the messages.

      - NotFound – If single delete, then the message was already deleted.

      - HTTPException – Deleting the messages failed.

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Added in version 2.0.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  is_nsfw()

    `bool`: Checks if the channel is NSFW.

    Added in version 2.0.

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property last_message

    Retrieves the last message from this channel in cache.

    The message might not be valid or point to an existing message.

    Added in version 2.0.

    Reliable Fetching

    For a slightly more reliable method of fetching the last message, consider using either `history()` or `fetch_message()` with the `last_message_id` attribute.

    Returns:

      The last message in this channel or `None` if not found.

    Return type:

      Optional[`Message`]

  property members

    Returns all members that are currently inside this voice channel.

    Type:

      List[`Member`]

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, bulk=True, reason=None)

    This function is a coroutine.

    Purges a list of messages that meet the criteria given by the predicate `check`. If a `check` is not provided then all messages are deleted without discrimination.

    You must have `manage_messages` to delete messages even if they are your own. Having `read_message_history` is also needed to retrieve message history.

    Added in version 2.0.

    Examples

    Deleting bot’s messages

        def is_me(m):
            return m.author == client.user

        deleted = await channel.purge(limit=100, check=is_me)
        await channel.send(f'Deleted {len(deleted)} message(s)')

    Parameters:

      - limit (Optional[`int`]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.

      - check (Callable[[`Message`], `bool`]) – The function used to check if a message should be deleted. It must take a `Message` as its sole parameter.

      - before (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `before` in `history()`.

      - after (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `after` in `history()`.

      - around (Optional[Union[`abc.Snowflake`, `datetime.datetime`]]) – Same as `around` in `history()`.

      - oldest_first (Optional[`bool`]) – Same as `oldest_first` in `history()`.

      - bulk (`bool`) – If `True`, use bulk delete. Setting this to `False` is useful for mass-deleting a bot’s own messages without `Permissions.manage_messages`. When `True`, will fall back to single delete if messages are older than two weeks.

      - reason (Optional[`str`]) – The reason for purging the messages. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to do the actions required.

      - HTTPException – Purging the messages failed.

    Returns:

      The list of messages that were deleted.

    Return type:

      List[`Message`]

  property scheduled_events

    Returns all scheduled events for this channel.

    Added in version 2.0.

    Type:

      List[`ScheduledEvent`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

  typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property voice_states

    Returns a mapping of member IDs who have voice states in this channel.

    Added in version 1.3.

    Note

    This function is intentionally low level to replace `members` when the member cache is unavailable.

    Returns:

      The mapping of member ID to a voice state.

    Return type:

      Mapping[`int`, `VoiceState`]

  await webhooks()

    This function is a coroutine.

    Gets the list of webhooks from this channel.

    You must have `manage_webhooks` to do this.

    Added in version 2.0.

    Raises:

      Forbidden – You don’t have permissions to get the webhooks.

    Returns:

      The webhooks for this channel.

    Return type:

      List[`Webhook`]

### StageInstance

Attributes

- channel
- channel_id
- discoverable_disabled
- guild
- id
- privacy_level
- scheduled_event
- scheduled_event_id
- topic

Methods

- async delete
- async edit

class discord.StageInstance

  Represents a stage instance of a stage channel in a guild.

  Added in version 2.0.

  x == y

    Checks if two stage instances are equal.

  x != y

    Checks if two stage instances are not equal.

  hash(x)

    Returns the stage instance’s hash.

  id

    The stage instance’s ID.

    Type:

      `int`

  guild

    The guild that the stage instance is running in.

    Type:

      `Guild`

  channel_id

    The ID of the channel that the stage instance is running in.

    Type:

      `int`

  topic

    The topic of the stage instance.

    Type:

      `str`

  privacy_level

    The privacy level of the stage instance.

    Type:

      `PrivacyLevel`

  discoverable_disabled

    Whether discoverability for the stage instance is disabled.

    Type:

      `bool`

  scheduled_event_id

    The ID of scheduled event that belongs to the stage instance if any.

    Added in version 2.0.

    Type:

      Optional[`int`]

  channel

    The channel that stage instance is running in.

    Type:

      Optional[`StageChannel`]

  scheduled_event

    The scheduled event that belongs to the stage instance.

    Type:

      Optional[`ScheduledEvent`]

  await edit(*, topic=..., privacy_level=..., reason=None)

    This function is a coroutine.

    Edits the stage instance.

    You must have `manage_channels` to do this.

    Parameters:

      - topic (`str`) – The stage instance’s new topic.

      - privacy_level (`PrivacyLevel`) – The stage instance’s new privacy level.

      - reason (`str`) – The reason the stage instance was edited. Shows up on the audit log.

    Raises:

      - TypeError – If the `privacy_level` parameter is not the proper type.

      - Forbidden – You do not have permissions to edit the stage instance.

      - HTTPException – Editing a stage instance failed.

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the stage instance.

    You must have `manage_channels` to do this.

    Parameters:

      reason (`str`) – The reason the stage instance was deleted. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to delete the stage instance.

      - HTTPException – Deleting the stage instance failed.

### CategoryChannel

Attributes

- category
- changed_roles
- channels
- created_at
- forums
- guild
- id
- jump_url
- mention
- name
- nsfw
- overwrites
- permissions_synced
- position
- stage_channels
- text_channels
- type
- voice_channels

Methods

- async clone
- async create_forum
- async create_invite
- async create_stage_channel
- async create_text_channel
- async create_voice_channel
- async delete
- async edit
- async invites
- def is_nsfw
- async move
- def overwrites_for
- def permissions_for
- async set_permissions

class discord.CategoryChannel

  Represents a Discord channel category.

  These are useful to group channels to logical compartments.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the category’s hash.

  str(x)

    Returns the category’s name.

  name

    The category name.

    Type:

      `str`

  guild

    The guild the category belongs to.

    Type:

      `Guild`

  id

    The category channel ID.

    Type:

      `int`

  position

    The position in the category list. This is a number that starts at 0. e.g. the top category is position 0.

    Type:

      `int`

  nsfw

    If the channel is marked as “not safe for work”.

    Note

    To check if the channel or the guild of that channel are marked as NSFW, consider `is_nsfw()` instead.

    Type:

      `bool`

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  is_nsfw()

    `bool`: Checks if the category is NSFW.

  await clone(*, name=None, category=None, reason=None)

    This function is a coroutine.

    Clones this channel. This creates a channel with the same properties as this channel.

    You must have `manage_channels` to do this.

    Added in version 1.1.

    Parameters:

      - name (Optional[`str`]) – The name of the new channel. If not provided, defaults to this channel name.

      - category (Optional[`CategoryChannel`]) –

        The category the new channel belongs to. This parameter is ignored if cloning a category channel.

        Added in version 2.5.

      - reason (Optional[`str`]) – The reason for cloning this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have the proper permissions to create this channel.

      - HTTPException – Creating the channel failed.

    Returns:

      The channel that was created.

    Return type:

      `abc.GuildChannel`

  await edit(*, reason=None, **options)

    This function is a coroutine.

    Edits the channel.

    You must have `manage_channels` to do this.

    Changed in version 1.3: The `overwrites` keyword-only parameter was added.

    Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The new category’s name.

      - position (`int`) – The new category’s position.

      - nsfw (`bool`) – To mark the category as NSFW or not.

      - reason (Optional[`str`]) – The reason for editing this category. Shows up on the audit log.

      - overwrites (`Mapping`) – A `Mapping` of target (either a role or a member) to `PermissionOverwrite` to apply to the channel.

    Raises:

      - ValueError – If position is less than 0 or greater than the number of categories.

      - TypeError – The overwrite information is not in proper form.

      - Forbidden – You do not have permissions to edit the category.

      - HTTPException – Editing the category failed.

    Returns:

      The newly edited category channel. If the edit was only positional then `None` is returned instead.

    Return type:

      Optional[`CategoryChannel`]

  await move(**kwargs)

    This function is a coroutine.

    A rich interface to help move a channel relative to other channels.

    If exact position movement is required, `edit` should be used instead.

    You must have `manage_channels` to do this.

    Note

    Voice channels will always be sorted below text channels. This is a Discord limitation.

    Added in version 1.7.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - beginning (`bool`) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with `end`, `before`, and `after`.

      - end (`bool`) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with `beginning`, `before`, and `after`.

      - before (`Snowflake`) – Whether to move the channel before the given channel. This is mutually exclusive with `beginning`, `end`, and `after`.

      - after (`Snowflake`) – Whether to move the channel after the given channel. This is mutually exclusive with `beginning`, `end`, and `before`.

      - offset (`int`) – The number of channels to offset the move by. For example, an offset of `2` with `beginning=True` would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the `beginning`, `end`, `before`, and `after` parameters.

      - category (Optional[`Snowflake`]) – The category to move this channel under. If `None` is given then it moves it out of the category. This parameter is ignored if moving a category channel.

      - sync_permissions (`bool`) – Whether to sync the permissions with the category (if given).

      - reason (`str`) – The reason for the move.

    Raises:

      - ValueError – An invalid position was given.

      - TypeError – A bad mix of arguments were passed.

      - Forbidden – You do not have permissions to move the channel.

      - HTTPException – Moving the channel failed.

  property channels

    Returns the channels that are under this category.

    These are sorted by the official Discord UI, which places voice channels below the text channels.

    Type:

      List[`abc.GuildChannel`]

  property text_channels

    Returns the text channels that are under this category.

    Type:

      List[`TextChannel`]

  property voice_channels

    Returns the voice channels that are under this category.

    Type:

      List[`VoiceChannel`]

  property stage_channels

    Returns the stage channels that are under this category.

    Added in version 1.7.

    Type:

      List[`StageChannel`]

  property forums

    Returns the forum channels that are under this category.

    Added in version 2.4.

    Type:

      List[`ForumChannel`]

  await create_text_channel(name, **options)

    This function is a coroutine.

    A shortcut method to `Guild.create_text_channel()` to create a `TextChannel` in the category.

    Returns:

      The channel that was just created.

    Return type:

      `TextChannel`

  await create_voice_channel(name, **options)

    This function is a coroutine.

    A shortcut method to `Guild.create_voice_channel()` to create a `VoiceChannel` in the category.

    Returns:

      The channel that was just created.

    Return type:

      `VoiceChannel`

  await create_stage_channel(name, **options)

    This function is a coroutine.

    A shortcut method to `Guild.create_stage_channel()` to create a `StageChannel` in the category.

    Added in version 1.7.

    Returns:

      The channel that was just created.

    Return type:

      `StageChannel`

  await create_forum(name, **options)

    This function is a coroutine.

    A shortcut method to `Guild.create_forum()` to create a `ForumChannel` in the category.

    Added in version 2.0.

    Returns:

      The channel that was just created.

    Return type:

      `ForumChannel`

  property category

    The category this channel belongs to.

    If there is no category then this is `None`.

    Type:

      Optional[`CategoryChannel`]

  property changed_roles

    Returns a list of roles that have been overridden from their default values in the `roles` attribute.

    Type:

      List[`Role`]

  await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, target_type=None, target_user=None, target_application_id=None)

    This function is a coroutine.

    Creates an instant invite from a text or voice channel.

    You must have `create_instant_invite` to do this.

    Parameters:

      - max_age (`int`) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to `0`.

      - max_uses (`int`) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to `0`.

      - temporary (`bool`) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to `False`.

      - unique (`bool`) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to `False` then it will return a previously created invite.

      - reason (Optional[`str`]) – The reason for creating this invite. Shows up on the audit log.

      - target_type (Optional[`InviteTarget`]) –

        The type of target for the voice channel invite, if any.

        Added in version 2.0.

      - target_user (Optional[`User`]) –

        The user whose stream to display for this invite, required if `target_type` is `InviteTarget.stream`. The user must be streaming in the channel.

        Added in version 2.0.

      - target_application_id: –

        Optional[`int`]: The id of the embedded application for the invite, required if `target_type` is `InviteTarget.embedded_application`.

        Added in version 2.0.

    Raises:

      - HTTPException – Invite creation failed.

      - NotFound – The channel that was passed is a category or an invalid channel.

    Returns:

      The invite that was created.

    Return type:

      `Invite`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the channel.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this channel. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have proper permissions to delete the channel.

      - NotFound – The channel was not found or was already deleted.

      - HTTPException – Deleting the channel failed.

  await invites()

    This function is a coroutine.

    Returns a list of all active instant invites from this channel.

    You must have `manage_channels` to get this information.

    Raises:

      - Forbidden – You do not have proper permissions to get the information.

      - HTTPException – An error occurred while fetching the information.

    Returns:

      The list of invites that are currently active.

    Return type:

      List[`Invite`]

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  property overwrites

    Returns all of the channel’s overwrites.

    This is returned as a dictionary where the key contains the target which can be either a `Role` or a `Member` and the value is the overwrite as a `PermissionOverwrite`.

    Changed in version 2.0: Overwrites can now be type-aware `Object` in case of cache lookup failure

    Returns:

      The channel’s permission overwrites.

    Return type:

      Dict[Union[`Role`, `Member`, `Object`], `PermissionOverwrite`]

  overwrites_for(obj)

    Returns the channel-specific overwrites for a member or a role.

    Parameters:

      obj (Union[`Role`, `User`, `Object`]) – The role or user denoting whose overwrite to get.

    Returns:

      The permission overwrites for this object.

    Return type:

      `PermissionOverwrite`

  permissions_for(obj, /)

    Handles permission resolution for the `Member` or `Role`.

    This function takes into consideration the following cases:

    - Guild owner

    - Guild roles

    - Channel overrides

    - Member overrides

    - Implicit permissions

    - Member timeout

    - User installed app

    If a `Role` is passed, then it checks the permissions someone with that role would have, which is essentially:

    - The default role permissions

    - The permissions of the role used as a parameter

    - The default role permission overwrites

    - The permission overwrites of the role used as a parameter

    Changed in version 2.0: The object passed in can now be a role object.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.4: User installed apps are now taken into account. The permissions returned for a user installed app mirrors the permissions Discord returns in `app_permissions`, though it is recommended to use that attribute instead.

    Parameters:

      obj (Union[`Member`, `Role`]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.

    Returns:

      The resolved permissions for the member or role.

    Return type:

      `Permissions`

  property permissions_synced

    Whether or not the permissions for this channel are synced with the category it belongs to.

    If there is no category then this is `False`.

    Added in version 1.3.

    Type:

      `bool`

  await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)

    This function is a coroutine.

    Sets the channel specific permission overwrites for a target in the channel.

    The `target` parameter should either be a `Member` or a `Role` that belongs to guild.

    The `overwrite` parameter, if given, must either be `None` or `PermissionOverwrite`. For convenience, you can pass in keyword arguments denoting `Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the `overwrite` parameter.

    If the `overwrite` parameter is `None`, then the permission overwrites are deleted.

    You must have `manage_roles` to do this.

    Note

    This method replaces the old overwrites with the ones given.

    Examples

    Setting allow and deny:

        await message.channel.set_permissions(message.author, read_messages=True,
                                                              send_messages=False)

    Deleting overwrites

        await channel.set_permissions(member, overwrite=None)

    Using `PermissionOverwrite`

        overwrite = discord.PermissionOverwrite()
        overwrite.send_messages = False
        overwrite.read_messages = True
        await channel.set_permissions(member, overwrite=overwrite)

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - target (Union[`Member`, `Role`]) – The member or role to overwrite permissions for.

      - overwrite (Optional[`PermissionOverwrite`]) – The permissions to allow and deny to the target, or `None` to delete the overwrite.

      - **permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with `overwrite`.

      - reason (Optional[`str`]) – The reason for doing this action. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit channel specific permissions.

      - HTTPException – Editing channel specific permissions failed.

      - NotFound – The role or member being edited is not part of the guild.

      - TypeError – The `overwrite` parameter was invalid or the target type was not `Role` or `Member`.

      - ValueError – The `overwrite` parameter and `positions` parameters were both unset.

### DMChannel

Attributes

- created_at
- guild
- id
- jump_url
- me
- recipient
- recipients
- type

Methods

- async fetch_message
- def get_partial_message
- async for history
- def permissions_for
- async pins
- async send
- def typing

class discord.DMChannel

  Represents a Discord direct message channel.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the channel’s hash.

  str(x)

    Returns a string representation of the channel

  recipient

    The user you are participating with in the direct message channel. If this channel is received through the gateway, the recipient information may not be always available.

    Type:

      Optional[`User`]

  recipients

    The users you are participating with in the DM channel.

    Added in version 2.4.

    Type:

      List[`User`]

  me

    The user presenting yourself.

    Type:

      `ClientUser`

  id

    The direct message channel ID.

    Type:

      `int`

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  property guild

    The guild this DM channel belongs to. Always `None`.

    This is mainly provided for compatibility purposes in duck typing.

    Added in version 2.0.

    Type:

      Optional[`Guild`]

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  property created_at

    Returns the direct message channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  permissions_for(obj=None, /)

    Handles permission resolution for a `User`.

    This function is there for compatibility with other channel types.

    Actual direct messages do not really have the concept of permissions.

    This returns all the Text related permissions set to `True` except:

    - `send_tts_messages`: You cannot send TTS messages in a DM.

    - `manage_messages`: You cannot delete others messages in a DM.

    - `create_private_threads`: There are no threads in a DM.

    - `create_public_threads`: There are no threads in a DM.

    - `manage_threads`: There are no threads in a DM.

    - `send_messages_in_threads`: There are no threads in a DM.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.1: Thread related permissions are now set to `False`.

    Parameters:

      obj (`User`) – The user to check permissions for. This parameter is ignored but kept for compatibility with other `permissions_for` methods.

    Returns:

      The resolved permissions.

    Return type:

      `Permissions`

  get_partial_message(message_id, /)

    Creates a `PartialMessage` from the message ID.

    This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

    Added in version 1.6.

    Changed in version 2.0: `message_id` parameter is now positional-only.

    Parameters:

      message_id (`int`) – The message ID to create a partial message for.

    Returns:

      The partial message.

    Return type:

      `PartialMessage`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

### GroupChannel

Attributes

- created_at
- guild
- icon
- id
- jump_url
- me
- name
- owner
- owner_id
- recipients
- type

Methods

- async fetch_message
- async for history
- async leave
- def permissions_for
- async pins
- async send
- def typing

class discord.GroupChannel

  Represents a Discord group channel.

  x == y

    Checks if two channels are equal.

  x != y

    Checks if two channels are not equal.

  hash(x)

    Returns the channel’s hash.

  str(x)

    Returns a string representation of the channel

  recipients

    The users you are participating with in the group channel.

    Type:

      List[`User`]

  me

    The user presenting yourself.

    Type:

      `ClientUser`

  id

    The group channel ID.

    Type:

      `int`

  owner

    The user that owns the group channel.

    Type:

      Optional[`User`]

  owner_id

    The owner ID that owns the group channel.

    Added in version 2.0.

    Type:

      `int`

  name

    The group channel’s name if provided.

    Type:

      Optional[`str`]

  async with typing()

    Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using `await`.

    Example Usage:

        async with channel.typing():
            # simulate something heavy
            await asyncio.sleep(20)

        await channel.send('Done!')

    Example Usage:

        await channel.typing()
        # Do some computational magic for about 10 seconds
        await channel.send('Done!')

    Changed in version 2.0: This no longer works with the `with` syntax, `async with` must be used instead.

    Changed in version 2.0: Added functionality to `await` the context manager to send a typing indicator for 10 seconds.

  property type

    The channel’s Discord type.

    Type:

      `ChannelType`

  property guild

    The guild this group channel belongs to. Always `None`.

    This is mainly provided for compatibility purposes in duck typing.

    Added in version 2.0.

    Type:

      Optional[`Guild`]

  property icon

    Returns the channel’s icon asset if available.

    Type:

      Optional[`Asset`]

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

  property jump_url

    Returns a URL that allows the client to jump to the channel.

    Added in version 2.0.

    Type:

      `str`

  permissions_for(obj, /)

    Handles permission resolution for a `User`.

    This function is there for compatibility with other channel types.

    Actual direct messages do not really have the concept of permissions.

    This returns all the Text related permissions set to `True` except:

    - `send_tts_messages`: You cannot send TTS messages in a DM.

    - `manage_messages`: You cannot delete others messages in a DM.

    - `create_private_threads`: There are no threads in a DM.

    - `create_public_threads`: There are no threads in a DM.

    - `manage_threads`: There are no threads in a DM.

    - `send_messages_in_threads`: There are no threads in a DM.

    This also checks the kick_members permission if the user is the owner.

    Changed in version 2.0: `obj` parameter is now positional-only.

    Changed in version 2.1: Thread related permissions are now set to `False`.

    Parameters:

      obj (`Snowflake`) – The user to check permissions for.

    Returns:

      The resolved permissions for the user.

    Return type:

      `Permissions`

  await fetch_message(id, /)

    This function is a coroutine.

    Retrieves a single `Message` from the destination.

    Parameters:

      id (`int`) – The message ID to look for.

    Raises:

      - NotFound – The specified message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The message asked for.

    Return type:

      `Message`

  async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)

    Returns an asynchronous iterator that enables receiving the destination’s message history.

    You must have `read_message_history` to do this.

    Examples

    Usage

        counter = 0
        async for message in channel.history(limit=200):
            if message.author == client.user:
                counter += 1

    Flattening into a list:

        messages = [message async for message in channel.history(limit=123)]
        # messages is now a list of Message...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of messages to retrieve. If `None`, retrieves every message in the channel. Note, however, that this would make it a slow operation.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - around (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

      - oldest_first (Optional[`bool`]) – If set to `True`, return messages in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`.

    Raises:

      - Forbidden – You do not have permissions to get channel message history.

      - HTTPException – The request to get message history failed.

    Yields:

      `Message` – The message with the message data parsed.

  await leave()

    This function is a coroutine.

    Leave the group.

    If you are the only one in the group, this deletes it as well.

    Raises:

      HTTPException – Leaving the group failed.

  await pins()

    This function is a coroutine.

    Retrieves all messages that are currently pinned in the channel.

    Note

    Due to a limitation with the Discord API, the `Message` objects returned by this method do not contain complete `Message.reactions` data.

    Raises:

      - Forbidden – You do not have the permission to retrieve pinned messages.

      - HTTPException – Retrieving the pinned messages failed.

    Returns:

      The messages that are currently pinned.

    Return type:

      List[`Message`]

  await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, silent=False, poll=None)

    This function is a coroutine.

    Sends a message to the destination with the content given.

    The content must be a type that can convert to a string through `str(content)`. If the content is set to `None` (the default), then the `embed` parameter must be provided.

    To upload a single file, the `file` parameter should be used with a single `File` object. To upload multiple files, the `files` parameter should be used with a `list` of `File` objects. Specifying both parameters will lead to an exception.

    To upload a single embed, the `embed` parameter should be used with a single `Embed` object. To upload multiple embeds, the `embeds` parameter should be used with a `list` of `Embed` objects. Specifying both parameters will lead to an exception.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The content of the message to send.

      - tts (`bool`) – Indicates if the message should be sent using text-to-speech.

      - embed (`Embed`) – The rich embed for the content.

      - embeds (List[`Embed`]) –

        A list of embeds to upload. Must be a maximum of 10.

        Added in version 2.0.

      - file (`File`) – The file to upload.

      - files (List[`File`]) – A list of files to upload. Must be a maximum of 10.

      - nonce (`int`) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

      - delete_after (`float`) – If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.

      - allowed_mentions (`AllowedMentions`) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - reference (Union[`Message`, `MessageReference`, `PartialMessage`]) –

        A reference to the `Message` to which you are referencing, this can be created using `to_reference()` or passed directly as a `Message`. In the event of a replying reference, you can control whether this mentions the author of the referenced message using the `replied_user` attribute of `allowed_mentions` or by setting `mention_author`.

        Added in version 1.6.

      - mention_author (Optional[`bool`]) –

        If set, overrides the `replied_user` attribute of `allowed_mentions`.

        Added in version 1.6.

      - view (`discord.ui.View`) –

        A Discord UI View to add to the message.

        Added in version 2.0.

      - stickers (Sequence[Union[`GuildSticker`, `StickerItem`]]) –

        A list of stickers to upload. Must be a maximum of 3.

        Added in version 2.0.

      - suppress_embeds (`bool`) –

        Whether to suppress embeds for the message. This sends the message without any embeds if set to `True`.

        Added in version 2.0.

      - silent (`bool`) –

        Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

        Added in version 2.2.

      - poll (`Poll`) –

        The poll to send with this message.

        Added in version 2.4.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` or `embeds` list is not of the appropriate size.

      - TypeError – You specified both `file` and `files`, or you specified both `embed` and `embeds`, or the `reference` object is not a `Message`, `MessageReference` or `PartialMessage`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

### PartialInviteGuild

Attributes

- banner
- created_at
- description
- features
- icon
- id
- name
- nsfw_level
- premium_subscription_count
- splash
- vanity_url
- vanity_url_code
- verification_level

class discord.PartialInviteGuild

  Represents a “partial” invite guild.

  This model will be given when the user is not part of the guild the `Invite` resolves to.

  x == y

    Checks if two partial guilds are the same.

  x != y

    Checks if two partial guilds are not the same.

  hash(x)

    Return the partial guild’s hash.

  str(x)

    Returns the partial guild’s name.

  name

    The partial guild’s name.

    Type:

      `str`

  id

    The partial guild’s ID.

    Type:

      `int`

  verification_level

    The partial guild’s verification level.

    Type:

      `VerificationLevel`

  features

    A list of features the guild has. See `Guild.features` for more information.

    Type:

      List[`str`]

  description

    The partial guild’s description.

    Type:

      Optional[`str`]

  nsfw_level

    The partial guild’s NSFW level.

    Added in version 2.0.

    Type:

      `NSFWLevel`

  vanity_url_code

    The partial guild’s vanity URL code, if available.

    Added in version 2.0.

    Type:

      Optional[`str`]

  premium_subscription_count

    The number of “boosts” the partial guild currently has.

    Added in version 2.0.

    Type:

      `int`

  property created_at

    Returns the guild’s creation time in UTC.

    Type:

      `datetime.datetime`

  property vanity_url

    The Discord vanity invite URL for this partial guild, if available.

    Added in version 2.0.

    Type:

      Optional[`str`]

  property icon

    Returns the guild’s icon asset, if available.

    Type:

      Optional[`Asset`]

  property banner

    Returns the guild’s banner asset, if available.

    Type:

      Optional[`Asset`]

  property splash

    Returns the guild’s invite splash asset, if available.

    Type:

      Optional[`Asset`]

### PartialInviteChannel

Attributes

- created_at
- id
- mention
- name
- type

class discord.PartialInviteChannel

  Represents a “partial” invite channel.

  This model will be given when the user is not part of the guild the `Invite` resolves to.

  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.

  name

    The partial channel’s name.

    Type:

      `str`

  id

    The partial channel’s ID.

    Type:

      `int`

  type

    The partial channel’s type.

    Type:

      `ChannelType`

  property mention

    The string that allows you to mention the channel.

    Type:

      `str`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

### Invite

Attributes

- approximate_member_count
- approximate_presence_count
- channel
- code
- created_at
- expires_at
- guild
- id
- inviter
- max_age
- max_uses
- revoked
- scheduled_event
- scheduled_event_id
- target_application
- target_type
- target_user
- temporary
- type
- url
- uses

Methods

- async delete
- def set_scheduled_event

class discord.Invite

  Represents a Discord `Guild` or `abc.GuildChannel` invite.

  Depending on the way this object was created, some of the attributes can have a value of `None`.

  x == y

    Checks if two invites are equal.

  x != y

    Checks if two invites are not equal.

  hash(x)

    Returns the invite hash.

  str(x)

    Returns the invite URL.

  The following table illustrates what methods will obtain the attributes:

  Attribute | Method
  --- | ---
  `max_age` | `abc.GuildChannel.invites()`, `Guild.invites()`
  `max_uses` | `abc.GuildChannel.invites()`, `Guild.invites()`
  `created_at` | `abc.GuildChannel.invites()`, `Guild.invites()`
  `temporary` | `abc.GuildChannel.invites()`, `Guild.invites()`
  `uses` | `abc.GuildChannel.invites()`, `Guild.invites()`
  `approximate_member_count` | `Client.fetch_invite()` with `with_counts` enabled
  `approximate_presence_count` | `Client.fetch_invite()` with `with_counts` enabled
  `expires_at` | `Client.fetch_invite()` with `with_expiration` enabled

  If it’s not in the table above then it is available by all methods.

  type

    The type of the invite.

    Type:

      `InviteType`

  max_age

    How long before the invite expires in seconds. A value of `0` indicates that it doesn’t expire.

    Type:

      Optional[`int`]

  code

    The URL fragment used for the invite.

    Type:

      `str`

  guild

    The guild the invite is for. Can be `None` if it’s from a group direct message.

    Type:

      Optional[Union[`Guild`, `Object`, `PartialInviteGuild`]]

  revoked

    Indicates if the invite has been revoked.

    Type:

      Optional[`bool`]

  created_at

    An aware UTC datetime object denoting the time the invite was created.

    Type:

      Optional[`datetime.datetime`]

  temporary

    Indicates that the invite grants temporary membership. If `True`, members who joined via this invite will be kicked upon disconnect.

    Type:

      Optional[`bool`]

  uses

    How many times the invite has been used.

    Type:

      Optional[`int`]

  max_uses

    How many times the invite can be used. A value of `0` indicates that it has unlimited uses.

    Type:

      Optional[`int`]

  inviter

    The user who created the invite.

    Type:

      Optional[`User`]

  approximate_member_count

    The approximate number of members in the guild.

    Type:

      Optional[`int`]

  approximate_presence_count

    The approximate number of members currently active in the guild. This includes idle, dnd, online, and invisible members. Offline members are excluded.

    Type:

      Optional[`int`]

  expires_at

    The expiration date of the invite. If the value is `None` when received through `Client.fetch_invite()` with `with_expiration` enabled, the invite will never expire.

    Added in version 2.0.

    Type:

      Optional[`datetime.datetime`]

  channel

    The channel the invite is for.

    Type:

      Optional[Union[`abc.GuildChannel`, `Object`, `PartialInviteChannel`]]

  target_type

    The type of target for the voice channel invite.

    Added in version 2.0.

    Type:

      `InviteTarget`

  target_user

    The user whose stream to display for this invite, if any.

    Added in version 2.0.

    Type:

      Optional[`User`]

  target_application

    The embedded application the invite targets, if any.

    Added in version 2.0.

    Type:

      Optional[`PartialAppInfo`]

  scheduled_event

    The scheduled event associated with this invite, if any.

    Added in version 2.0.

    Type:

      Optional[`ScheduledEvent`]

  scheduled_event_id

    The ID of the scheduled event associated with this invite, if any.

    Added in version 2.0.

    Type:

      Optional[`int`]

  property id

    Returns the proper code portion of the invite.

    Type:

      `str`

  property url

    A property that retrieves the invite URL.

    Type:

      `str`

  set_scheduled_event(scheduled_event, /)

    Sets the scheduled event for this invite.

    Added in version 2.0.

    Parameters:

      scheduled_event (`Snowflake`) – The ID of the scheduled event.

    Returns:

      The invite with the new scheduled event.

    Return type:

      `Invite`

  await delete(*, reason=None)

    This function is a coroutine.

    Revokes the instant invite.

    You must have `manage_channels` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this invite. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to revoke invites.

      - NotFound – The invite is invalid or expired.

      - HTTPException – Revoking the invite failed.

### Template

Attributes

- code
- created_at
- creator
- description
- is_dirty
- name
- source_guild
- updated_at
- url
- uses

Methods

- async create_guild
- async delete
- async edit
- async sync

class discord.Template

  Represents a Discord template.

  Added in version 1.4.

  code

    The template code.

    Type:

      `str`

  uses

    How many times the template has been used.

    Type:

      `int`

  name

    The name of the template.

    Type:

      `str`

  description

    The description of the template.

    Type:

      `str`

  creator

    The creator of the template.

    Type:

      `User`

  created_at

    An aware datetime in UTC representing when the template was created.

    Type:

      `datetime.datetime`

  updated_at

    An aware datetime in UTC representing when the template was last updated. This is referred to as “last synced” in the official Discord client.

    Type:

      `datetime.datetime`

  source_guild

    The guild snapshot that represents the data that this template currently holds.

    Type:

      `Guild`

  is_dirty

    Whether the template has unsynced changes.

    Added in version 2.0.

    Type:

      Optional[`bool`]

  await create_guild(name, icon=...)

    This function is a coroutine.

    Creates a `Guild` using the template.

    Bot accounts in more than 10 guilds are not allowed to create guilds.

    Changed in version 2.0: The `region` parameter has been removed.

    Changed in version 2.0: This function will now raise `ValueError` instead of `InvalidArgument`.

    Parameters:

      - name (`str`) – The name of the guild.

      - icon (`bytes`) – The py:bytes-like object representing the icon. See `ClientUser.edit()` for more details on what is expected.

    Raises:

      - HTTPException – Guild creation failed.

      - ValueError – Invalid icon image format given. Must be PNG or JPG.

    Returns:

      The guild created. This is not the same guild that is added to cache.

    Return type:

      `Guild`

  await sync()

    This function is a coroutine.

    Sync the template to the guild’s current state.

    You must have `manage_guild` in the source guild to do this.

    Added in version 1.7.

    Changed in version 2.0: The template is no longer edited in-place, instead it is returned.

    Raises:

      - HTTPException – Editing the template failed.

      - Forbidden – You don’t have permissions to edit the template.

      - NotFound – This template does not exist.

    Returns:

      The newly edited template.

    Return type:

      `Template`

  await edit(*, name=..., description=...)

    This function is a coroutine.

    Edit the template metadata.

    You must have `manage_guild` in the source guild to do this.

    Added in version 1.7.

    Changed in version 2.0: The template is no longer edited in-place, instead it is returned.

    Parameters:

      - name (`str`) – The template’s new name.

      - description (Optional[`str`]) – The template’s new description.

    Raises:

      - HTTPException – Editing the template failed.

      - Forbidden – You don’t have permissions to edit the template.

      - NotFound – This template does not exist.

    Returns:

      The newly edited template.

    Return type:

      `Template`

  await delete()

    This function is a coroutine.

    Delete the template.

    You must have `manage_guild` in the source guild to do this.

    Added in version 1.7.

    Raises:

      - HTTPException – Editing the template failed.

      - Forbidden – You don’t have permissions to edit the template.

      - NotFound – This template does not exist.

  property url

    The template url.

    Added in version 2.0.

    Type:

      `str`

### WelcomeScreen

Attributes

- description
- enabled
- welcome_channels

Methods

- async edit

class discord.WelcomeScreen

  Represents a `Guild` welcome screen.

  Added in version 2.0.

  description

    The description shown on the welcome screen.

    Type:

      `str`

  welcome_channels

    The channels shown on the welcome screen.

    Type:

      List[`WelcomeChannel`]

  property enabled

    Whether the welcome screen is displayed.

    This is equivalent to checking if `WELCOME_SCREEN_ENABLED` is present in `Guild.features`.

    Type:

      `bool`

  await edit(*, description=..., welcome_channels=..., enabled=..., reason=None)

    This function is a coroutine.

    Edit the welcome screen.

    Welcome channels can only accept custom emojis if `Guild.premium_tier` is level 2 or above.

    You must have `manage_guild` in the guild to do this.

    Usage:

        rules_channel = guild.get_channel(12345678)
        announcements_channel = guild.get_channel(87654321)

        custom_emoji = utils.get(guild.emojis, name='loudspeaker')

        await welcome_screen.edit(
            description='This is a very cool community server!',
            welcome_channels=[
                WelcomeChannel(channel=rules_channel, description='Read the rules!', emoji='👨‍🏫'),
                WelcomeChannel(channel=announcements_channel, description='Watch out for announcements!', emoji=custom_emoji),
            ]
        )

    Parameters:

      - description (Optional[`str`]) – The welcome screen’s description.

      - welcome_channels (Optional[List[`WelcomeChannel`]]) – The welcome channels, in their respective order.

      - enabled (Optional[`bool`]) – Whether the welcome screen should be displayed.

      - reason (Optional[`str`]) – The reason for editing the welcome screen. Shows up on the audit log.

    Raises:

      - HTTPException – Editing the welcome screen failed.

      - Forbidden – You don’t have permissions to edit the welcome screen.

      - NotFound – This welcome screen does not exist.

### WelcomeChannel

Attributes

- channel
- description
- emoji

class discord.WelcomeChannel

  Represents a `WelcomeScreen` welcome channel.

  Added in version 2.0.

  channel

    The guild channel that is being referenced.

    Type:

      `abc.Snowflake`

  description

    The description shown of the channel.

    Type:

      `str`

  emoji

    The emoji used beside the channel description.

    Type:

      Optional[`PartialEmoji`, `Emoji`, `str`]

### WidgetChannel

Attributes

- created_at
- id
- mention
- name
- position

class discord.WidgetChannel

  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

    The string that allows you to mention the channel.

    Type:

      `str`

  property created_at

    Returns the channel’s creation time in UTC.

    Type:

      `datetime.datetime`

### WidgetMember

Attributes

- accent_color
- accent_colour
- activity
- avatar
- avatar_decoration
- avatar_decoration_sku_id
- banner
- bot
- color
- colour
- connected_channel
- created_at
- deafened
- default_avatar
- discriminator
- display_avatar
- display_name
- global_name
- id
- mention
- muted
- name
- nick
- public_flags
- status
- suppress

Methods

- def mentioned_in

class discord.WidgetMember

  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 handle (e.g. `name` or `name#discriminator`).

  id

    The member’s ID.

    Type:

      `int`

  name

    The member’s username.

    Type:

      `str`

  discriminator

    The member’s discriminator. This is a legacy concept that is no longer used.

    Type:

      `str`

  global_name

    The member’s global nickname, taking precedence over the username in display.

    Added in version 2.3.

    Type:

      Optional[`str`]

  bot

    Whether the member is a bot.

    Type:

      `bool`

  status

    The member’s status.

    Type:

      `Status`

  nick

    The member’s guild-specific nickname. Takes precedence over the global name.

    Type:

      Optional[`str`]

  avatar

    The member’s avatar hash.

    Type:

      Optional[`str`]

  activity

    The member’s activity.

    Type:

      Optional[Union[`BaseActivity`, `Spotify`]]

  deafened

    Whether the member is currently deafened.

    Type:

      Optional[`bool`]

  muted

    Whether the member is currently muted.

    Type:

      Optional[`bool`]

  suppress

    Whether the member is currently being suppressed.

    Type:

      Optional[`bool`]

  connected_channel

    Which channel the member is connected to.

    Type:

      Optional[`WidgetChannel`]

  property display_name

    Returns the member’s display name.

    Type:

      `str`

  property accent_color

    Returns the user’s accent color, if applicable.

    A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

    There is an alias for this named `accent_colour`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property accent_colour

    Returns the user’s accent colour, if applicable.

    A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

    There is an alias for this named `accent_color`.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Colour`]

  property avatar_decoration

    Returns an `Asset` for the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`Asset`]

  property avatar_decoration_sku_id

    Returns the SKU ID of the avatar decoration the user has.

    If the user has not set an avatar decoration, `None` is returned.

    Added in version 2.4.

    Type:

      Optional[`int`]

  property banner

    Returns the user’s banner asset, if available.

    Added in version 2.0.

    Note

    This information is only available via `Client.fetch_user()`.

    Type:

      Optional[`Asset`]

  property color

    A property that returns a color denoting the rendered color for the user. This always returns `Colour.default()`.

    There is an alias for this named `colour`.

    Type:

      `Colour`

  property colour

    A property that returns a colour denoting the rendered colour for the user. This always returns `Colour.default()`.

    There is an alias for this named `color`.

    Type:

      `Colour`

  property created_at

    Returns the user’s creation time in UTC.

    This is when the user’s Discord account was created.

    Type:

      `datetime.datetime`

  property default_avatar

    Returns the default avatar for a given user.

    Type:

      `Asset`

  property display_avatar

    Returns the user’s display avatar.

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

    Added in version 2.0.

    Type:

      `Asset`

  property mention

    Returns a string that allows you to mention the given user.

    Type:

      `str`

  mentioned_in(message)

    Checks if the user is mentioned in the specified message.

    Parameters:

      message (`Message`) – The message to check if you’re mentioned in.

    Returns:

      Indicates if the user is mentioned in the message.

    Return type:

      `bool`

  property public_flags

    The publicly available flags the user has.

    Type:

      `PublicUserFlags`

### Widget

Attributes

- channels
- created_at
- id
- invite_url
- json_url
- members
- name
- presence_count

Methods

- async fetch_invite

class discord.Widget

  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 accessible voice channels in the guild.

    Type:

      List[`WidgetChannel`]

  members

    The online members in the guild. 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 and discriminator information being incorrect. Likewise, the number of members retrieved is capped.

    Type:

      List[`WidgetMember`]

  presence_count

    The approximate number of online members in the guild. Offline members are not included in this count.

    Added in version 2.0.

    Type:

      `int`

  property created_at

    Returns the member’s creation time in UTC.

    Type:

      `datetime.datetime`

  property json_url

    The JSON URL of the widget.

    Type:

      `str`

  property invite_url

    The invite URL for the guild, if available.

    Type:

      Optional[`str`]

  await fetch_invite(*, with_counts=True)

    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.

    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:

      Optional[`Invite`]

### StickerPack

Attributes

- banner
- cover_sticker
- cover_sticker_id
- description
- id
- name
- sku_id
- stickers

class discord.StickerPack

  Represents a sticker pack.

  Added in version 2.0.

  str(x)

    Returns the name of the sticker pack.

  x == y

    Checks if the sticker pack is equal to another sticker pack.

  x != y

    Checks if the sticker pack is not equal to another sticker pack.

  name

    The name of the sticker pack.

    Type:

      `str`

  description

    The description of the sticker pack.

    Type:

      `str`

  id

    The id of the sticker pack.

    Type:

      `int`

  stickers

    The stickers of this sticker pack.

    Type:

      List[`StandardSticker`]

  sku_id

    The SKU ID of the sticker pack.

    Type:

      `int`

  cover_sticker_id

    The ID of the sticker used for the cover of the sticker pack.

    Type:

      Optional[`int`]

  cover_sticker

    The sticker used for the cover of the sticker pack.

    Type:

      Optional[`StandardSticker`]

  property banner

    The banner asset of the sticker pack.

    Type:

      `Asset`

### StickerItem

Attributes

- format
- id
- name
- url

Methods

- async fetch

class discord.StickerItem

  Represents a sticker item.

  Added in version 2.0.

  str(x)

    Returns the name of the sticker item.

  x == y

    Checks if the sticker item is equal to another sticker item.

  x != y

    Checks if the sticker item is not equal to another sticker item.

  name

    The sticker’s name.

    Type:

      `str`

  id

    The id of the sticker.

    Type:

      `int`

  format

    The format for the sticker’s image.

    Type:

      `StickerFormatType`

  url

    The URL for the sticker’s image.

    Type:

      `str`

  await fetch()

    This function is a coroutine.

    Attempts to retrieve the full sticker data of the sticker item.

    Raises:

      HTTPException – Retrieving the sticker failed.

    Returns:

      The retrieved sticker.

    Return type:

      Union[`StandardSticker`, `GuildSticker`]

### Sticker

Attributes

- created_at
- description
- format
- id
- name
- url

class discord.Sticker

  Represents a sticker.

  Added in version 1.6.

  str(x)

    Returns the name of the sticker.

  x == y

    Checks if the sticker is equal to another sticker.

  x != y

    Checks if the sticker is not equal to another sticker.

  name

    The sticker’s name.

    Type:

      `str`

  id

    The id of the sticker.

    Type:

      `int`

  description

    The description of the sticker.

    Type:

      `str`

  format

    The format for the sticker’s image.

    Type:

      `StickerFormatType`

  url

    The URL for the sticker’s image.

    Type:

      `str`

  property created_at

    Returns the sticker’s creation time in UTC.

    Type:

      `datetime.datetime`

### StandardSticker

Attributes

- description
- format
- id
- name
- pack_id
- sort_value
- tags

Methods

- async pack

class discord.StandardSticker

  Represents a sticker that is found in a standard sticker pack.

  Added in version 2.0.

  str(x)

    Returns the name of the sticker.

  x == y

    Checks if the sticker is equal to another sticker.

  x != y

    Checks if the sticker is not equal to another sticker.

  name

    The sticker’s name.

    Type:

      `str`

  id

    The id of the sticker.

    Type:

      `int`

  description

    The description of the sticker.

    Type:

      `str`

  pack_id

    The id of the sticker’s pack.

    Type:

      `int`

  format

    The format for the sticker’s image.

    Type:

      `StickerFormatType`

  tags

    A list of tags for the sticker.

    Type:

      List[`str`]

  sort_value

    The sticker’s sort order within its pack.

    Type:

      `int`

  await pack()

    This function is a coroutine.

    Retrieves the sticker pack that this sticker belongs to.

    Changed in version 2.5: Now raises `NotFound` instead of `InvalidData`.

    Raises:

      - NotFound – The corresponding sticker pack was not found.

      - HTTPException – Retrieving the sticker pack failed.

    Returns:

      The retrieved sticker pack.

    Return type:

      `StickerPack`

### GuildSticker

Attributes

- available
- description
- emoji
- format
- guild
- guild_id
- id
- name
- user

Methods

- async delete
- async edit

class discord.GuildSticker

  Represents a sticker that belongs to a guild.

  Added in version 2.0.

  str(x)

    Returns the name of the sticker.

  x == y

    Checks if the sticker is equal to another sticker.

  x != y

    Checks if the sticker is not equal to another sticker.

  name

    The sticker’s name.

    Type:

      `str`

  id

    The id of the sticker.

    Type:

      `int`

  description

    The description of the sticker.

    Type:

      `str`

  format

    The format for the sticker’s image.

    Type:

      `StickerFormatType`

  available

    Whether this sticker is available for use.

    Type:

      `bool`

  guild_id

    The ID of the guild that this sticker is from.

    Type:

      `int`

  user

    The user that created this sticker. This can only be retrieved using `Guild.fetch_sticker()` and having `manage_emojis_and_stickers`.

    Type:

      Optional[`User`]

  emoji

    The name of a unicode emoji that represents this sticker.

    Type:

      `str`

  guild

    The guild that this sticker is from. Could be `None` if the bot is not in the guild.

    Added in version 2.0.

    Type:

      Optional[`Guild`]

  await edit(*, name=..., description=..., emoji=..., reason=None)

    This function is a coroutine.

    Edits a `GuildSticker` for the guild.

    Parameters:

      - name (`str`) – The sticker’s new name. Must be at least 2 characters.

      - description (Optional[`str`]) – The sticker’s new description. Can be `None`.

      - emoji (`str`) – The name of a unicode emoji that represents the sticker’s expression.

      - reason (`str`) – The reason for editing this sticker. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to edit stickers.

      - HTTPException – An error occurred editing the sticker.

    Returns:

      The newly modified sticker.

    Return type:

      `GuildSticker`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the custom `Sticker` from the guild.

    You must have `manage_emojis_and_stickers` to do this.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this sticker. Shows up on the audit log.

    Raises:

      - Forbidden – You are not allowed to delete stickers.

      - HTTPException – An error occurred deleting the sticker.

### BaseSoundboardSound

Attributes

- id
- url
- volume

class discord.BaseSoundboardSound

  Represents a generic Discord soundboard sound.

  Added in version 2.5.

  x == y

    Checks if two sounds are equal.

  x != y

    Checks if two sounds are not equal.

  hash(x)

    Returns the sound’s hash.

  id

    The ID of the sound.

    Type:

      `int`

  volume

    The volume of the sound as floating point percentage (e.g. `1.0` for 100%).

    Type:

      `float`

  property url

    Returns the URL of the sound.

    Type:

      `str`

### SoundboardDefaultSound

Attributes

- emoji
- id
- name
- volume

class discord.SoundboardDefaultSound

  Represents a Discord soundboard default sound.

  Added in version 2.5.

  x == y

    Checks if two sounds are equal.

  x != y

    Checks if two sounds are not equal.

  hash(x)

    Returns the sound’s hash.

  id

    The ID of the sound.

    Type:

      `int`

  volume

    The volume of the sound as floating point percentage (e.g. `1.0` for 100%).

    Type:

      `float`

  name

    The name of the sound.

    Type:

      `str`

  emoji

    The emoji of the sound.

    Type:

      `PartialEmoji`

### SoundboardSound

Attributes

- available
- created_at
- emoji
- guild
- id
- name
- user
- volume

Methods

- async delete
- async edit

class discord.SoundboardSound

  Represents a Discord soundboard sound.

  Added in version 2.5.

  x == y

    Checks if two sounds are equal.

  x != y

    Checks if two sounds are not equal.

  hash(x)

    Returns the sound’s hash.

  id

    The ID of the sound.

    Type:

      `int`

  volume

    The volume of the sound as floating point percentage (e.g. `1.0` for 100%).

    Type:

      `float`

  name

    The name of the sound.

    Type:

      `str`

  emoji

    The emoji of the sound. `None` if no emoji is set.

    Type:

      Optional[`PartialEmoji`]

  guild

    The guild in which the sound is uploaded.

    Type:

      `Guild`

  available

    Whether this sound is available for use.

    Type:

      `bool`

  property created_at

    Returns the snowflake’s creation time in UTC.

    Type:

      `datetime.datetime`

  property user

    The user who uploaded the sound.

    Type:

      Optional[`User`]

  await edit(*, name=..., volume=..., emoji=..., reason=None)

    This function is a coroutine.

    Edits the soundboard sound.

    You must have `manage_expressions` to edit the sound. If the sound was created by the client, you must have either `manage_expressions` or `create_expressions`.

    Parameters:

      - name (`str`) – The new name of the sound. Must be between 2 and 32 characters.

      - volume (Optional[`float`]) – The new volume of the sound. Must be between 0 and 1.

      - emoji (Optional[Union[`Emoji`, `PartialEmoji`, `str`]]) – The new emoji of the sound.

      - reason (Optional[`str`]) – The reason for editing this sound. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to edit the soundboard sound.

      - HTTPException – Editing the soundboard sound failed.

    Returns:

      The newly updated soundboard sound.

    Return type:

      `SoundboardSound`

  await delete(*, reason=None)

    This function is a coroutine.

    Deletes the soundboard sound.

    You must have `manage_expressions` to delete the sound. If the sound was created by the client, you must have either `manage_expressions` or `create_expressions`.

    Parameters:

      reason (Optional[`str`]) – The reason for deleting this sound. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to delete the soundboard sound.

      - HTTPException – Deleting the soundboard sound failed.

### ShardInfo

Attributes

- id
- latency
- shard_count

Methods

- async connect
- async disconnect
- def is_closed
- def is_ws_ratelimited
- async reconnect

class discord.ShardInfo

  A class that gives information and control over a specific shard.

  You can retrieve this object via `AutoShardedClient.get_shard()` or `AutoShardedClient.shards`.

  Added in version 1.4.

  id

    The shard ID for this shard.

    Type:

      `int`

  shard_count

    The shard count for this cluster. If this is `None` then the bot has not started yet.

    Type:

      Optional[`int`]

  is_closed()

    `bool`: Whether the shard connection is currently closed.

  await disconnect()

    This function is a coroutine.

    Disconnects a shard. When this is called, the shard connection will no longer be open.

    If the shard is already disconnected this does nothing.

  await reconnect()

    This function is a coroutine.

    Disconnects and then connects the shard again.

  await connect()

    This function is a coroutine.

    Connects a shard. If the shard is already connected this does nothing.

  property latency

    Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard.

    Type:

      `float`

  is_ws_ratelimited()

    `bool`: Whether the websocket is currently rate limited.

    This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

    Added in version 1.6.

### SessionStartLimits

Attributes

- max_concurrency
- remaining
- reset_after
- total

class discord.SessionStartLimits

  A class that holds info about session start limits

  Added in version 2.5.

  total

    The total number of session starts the current user is allowed

    Type:

      `int`

  remaining

    Remaining remaining number of session starts the current user is allowed

    Type:

      `int`

  reset_after

    The number of milliseconds until the limit resets

    Type:

      `int`

  max_concurrency

    The number of identify requests allowed per 5 seconds

    Type:

      `int`

### SKU

Attributes

- application_id
- created_at
- flags
- id
- name
- slug
- type

Methods

- async fetch_subscription
- async for subscriptions

class discord.SKU

  Represents a premium offering as a stock-keeping unit (SKU).

  Added in version 2.4.

  id

    The SKU’s ID.

    Type:

      `int`

  type

    The type of the SKU.

    Type:

      `SKUType`

  application_id

    The ID of the application that the SKU belongs to.

    Type:

      `int`

  name

    The consumer-facing name of the premium offering.

    Type:

      `str`

  slug

    A system-generated URL slug based on the SKU name.

    Type:

      `str`

  property flags

    Returns the flags of the SKU.

    Type:

      `SKUFlags`

  property created_at

    Returns the sku’s creation time in UTC.

    Type:

      `datetime.datetime`

  await fetch_subscription(subscription_id, /)

    This function is a coroutine.

    Retrieves a `Subscription` with the specified ID.

    Added in version 2.5.

    Parameters:

      subscription_id (`int`) – The subscription’s ID to fetch from.

    Raises:

      - NotFound – An subscription with this ID does not exist.

      - HTTPException – Fetching the subscription failed.

    Returns:

      The subscription you requested.

    Return type:

      `Subscription`

  async for ... in subscriptions(*, limit=50, before=None, after=None, user)

    Retrieves an asynchronous iterator of the `Subscription` that SKU has.

    Added in version 2.5.

    Examples

    Usage

        async for subscription in sku.subscriptions(limit=100, user=user):
            print(subscription.user_id, subscription.current_period_end)

    Flattening into a list

        subscriptions = [subscription async for subscription in sku.subscriptions(limit=100, user=user)]
        # subscriptions is now a list of Subscription...

    All parameters are optional.

    Parameters:

      - limit (Optional[`int`]) – The number of subscriptions to retrieve. If `None`, it retrieves every subscription for this SKU. Note, however, that this would make it a slow operation. Defaults to `100`.

      - before (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve subscriptions before this date or entitlement. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - after (Optional[Union[`Snowflake`, `datetime.datetime`]]) – Retrieve subscriptions after this date or entitlement. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

      - user (`Snowflake`) – The user to filter by.

    Raises:

      - HTTPException – Fetching the subscriptions failed.

      - TypeError – Both `after` and `before` were provided, as Discord does not support this type of pagination.

    Yields:

      `Subscription` – The subscription with the SKU.

### Entitlement

Attributes

- application_id
- consumed
- created_at
- deleted
- ends_at
- guild
- guild_id
- id
- sku_id
- starts_at
- type
- user
- user_id

Methods

- async consume
- async delete
- def is_expired

class discord.Entitlement

  Represents an entitlement from user or guild which has been granted access to a premium offering.

  Added in version 2.4.

  id

    The entitlement’s ID.

    Type:

      `int`

  sku_id

    The ID of the SKU that the entitlement belongs to.

    Type:

      `int`

  application_id

    The ID of the application that the entitlement belongs to.

    Type:

      `int`

  user_id

    The ID of the user that is granted access to the entitlement.

    Type:

      Optional[`int`]

  type

    The type of the entitlement.

    Type:

      `EntitlementType`

  deleted

    Whether the entitlement has been deleted.

    Type:

      `bool`

  starts_at

    A UTC start date which the entitlement is valid. Not present when using test entitlements.

    Type:

      Optional[`datetime.datetime`]

  ends_at

    A UTC date which entitlement is no longer valid. Not present when using test entitlements.

    Type:

      Optional[`datetime.datetime`]

  guild_id

    The ID of the guild that is granted access to the entitlement

    Type:

      Optional[`int`]

  consumed

    For consumable items, whether the entitlement has been consumed.

    Type:

      `bool`

  property user

    The user that is granted access to the entitlement.

    Type:

      Optional[`User`]

  property guild

    The guild that is granted access to the entitlement.

    Type:

      Optional[`Guild`]

  property created_at

    Returns the entitlement’s creation time in UTC.

    Type:

      `datetime.datetime`

  is_expired()

    `bool`: Returns `True` if the entitlement is expired. Will be always False for test entitlements.

  await consume()

    This function is a coroutine.

    Marks a one-time purchase entitlement as consumed.

    Raises:

      - NotFound – The entitlement could not be found.

      - HTTPException – Consuming the entitlement failed.

  await delete()

    This function is a coroutine.

    Deletes the entitlement.

    Raises:

      - NotFound – The entitlement could not be found.

      - HTTPException – Deleting the entitlement failed.

### Subscription

Attributes

- canceled_at
- created_at
- current_period_end
- current_period_start
- entitlement_ids
- id
- renewal_sku_ids
- sku_ids
- status
- user
- user_id

class discord.Subscription

  Represents a Discord subscription.

  Added in version 2.5.

  id

    The subscription’s ID.

    Type:

      `int`

  user_id

    The ID of the user that is subscribed.

    Type:

      `int`

  sku_ids

    The IDs of the SKUs that the user subscribed to.

    Type:

      List[`int`]

  entitlement_ids

    The IDs of the entitlements granted for this subscription.

    Type:

      List[`int`]

  current_period_start

    When the current billing period started.

    Type:

      `datetime.datetime`

  current_period_end

    When the current billing period ends.

    Type:

      `datetime.datetime`

  status

    The status of the subscription.

    Type:

      `SubscriptionStatus`

  canceled_at

    When the subscription was canceled. This is only available for subscriptions with a `status` of `SubscriptionStatus.inactive`.

    Type:

      Optional[`datetime.datetime`]

  renewal_sku_ids

    The IDs of the SKUs that the user is going to be subscribed to when renewing.

    Type:

      List[`int`]

  property created_at

    Returns the subscription’s creation time in UTC.

    Type:

      `datetime.datetime`

  property user

    The user that is subscribed.

    Type:

      Optional[`User`]

### RawMessageDeleteEvent

Attributes

- cached_message
- channel_id
- guild_id
- message_id

class discord.RawMessageDeleteEvent

  Represents the event payload for a `on_raw_message_delete()` event.

  channel_id

    The channel ID where the deletion took place.

    Type:

      `int`

  guild_id

    The guild ID where the deletion took place, if applicable.

    Type:

      Optional[`int`]

  message_id

    The message ID that got deleted.

    Type:

      `int`

  cached_message

    The cached message, if found in the internal message cache.

    Type:

      Optional[`Message`]

### RawBulkMessageDeleteEvent

Attributes

- cached_messages
- channel_id
- guild_id
- message_ids

class discord.RawBulkMessageDeleteEvent

  Represents the event payload for a `on_raw_bulk_message_delete()` event.

  message_ids

    A `set` of the message IDs that were deleted.

    Type:

      Set[`int`]

  channel_id

    The channel ID where the message got deleted.

    Type:

      `int`

  guild_id

    The guild ID where the message got deleted, if applicable.

    Type:

      Optional[`int`]

  cached_messages

    The cached messages, if found in the internal message cache.

    Type:

      List[`Message`]

### RawMessageUpdateEvent

Attributes

- cached_message
- channel_id
- data
- guild_id
- message
- message_id

class discord.RawMessageUpdateEvent

  Represents the payload for a `on_raw_message_edit()` event.

  message_id

    The message ID that got updated.

    Type:

      `int`

  channel_id

    The channel ID where the update took place.

    Added in version 1.3.

    Type:

      `int`

  guild_id

    The guild ID where the message got updated, if applicable.

    Added in version 1.7.

    Type:

      Optional[`int`]

  data

    The raw data given by the gateway

    Type:

      `dict`

  cached_message

    The cached message, if found in the internal message cache. Represents the message before it is modified by the data in `RawMessageUpdateEvent.data`.

    Type:

      Optional[`Message`]

  message

    The updated message.

    Added in version 2.5.

    Type:

      `Message`

### RawReactionActionEvent

Attributes

- burst
- burst_colors
- burst_colours
- channel_id
- emoji
- event_type
- guild_id
- member
- message_author_id
- message_id
- type
- user_id

class discord.RawReactionActionEvent

  Represents the payload for a `on_raw_reaction_add()` or `on_raw_reaction_remove()` event.

  message_id

    The message ID that got or lost a reaction.

    Type:

      `int`

  user_id

    The user ID who added the reaction or whose reaction was removed.

    Type:

      `int`

  channel_id

    The channel ID where the reaction got added or removed.

    Type:

      `int`

  guild_id

    The guild ID where the reaction got added or removed, if applicable.

    Type:

      Optional[`int`]

  emoji

    The custom or unicode emoji being used.

    Type:

      `PartialEmoji`

  member

    The member who added the reaction. Only available if `event_type` is `REACTION_ADD` and the reaction is inside a guild.

    Added in version 1.3.

    Type:

      Optional[`Member`]

  message_author_id

    The author ID of the message being reacted to. Only available if `event_type` is `REACTION_ADD`.

    Added in version 2.4.

    Type:

      Optional[`int`]

  event_type

    The event type that triggered this action. Can be `REACTION_ADD` for reaction addition or `REACTION_REMOVE` for reaction removal.

    Added in version 1.3.

    Type:

      `str`

  burst

    Whether the reaction was a burst reaction, also known as a “super reaction”.

    Added in version 2.4.

    Type:

      `bool`

  burst_colours

    A list of colours used for burst reaction animation. Only available if `burst` is `True` and if `event_type` is `REACTION_ADD`.

    Added in version 2.0.

    Type:

      List[`Colour`]

  type

    The type of the reaction.

    Added in version 2.4.

    Type:

      `ReactionType`

  property burst_colors

    An alias of `burst_colours`.

    Added in version 2.4.

### RawReactionClearEvent

Attributes

- channel_id
- guild_id
- message_id

class discord.RawReactionClearEvent

  Represents the payload for a `on_raw_reaction_clear()` event.

  message_id

    The message ID that got its reactions cleared.

    Type:

      `int`

  channel_id

    The channel ID where the reactions got cleared.

    Type:

      `int`

  guild_id

    The guild ID where the reactions got cleared.

    Type:

      Optional[`int`]

### RawReactionClearEmojiEvent

Attributes

- channel_id
- emoji
- guild_id
- message_id

class discord.RawReactionClearEmojiEvent

  Represents the payload for a `on_raw_reaction_clear_emoji()` event.

  Added in version 1.3.

  message_id

    The message ID that got its reactions cleared.

    Type:

      `int`

  channel_id

    The channel ID where the reactions got cleared.

    Type:

      `int`

  guild_id

    The guild ID where the reactions got cleared.

    Type:

      Optional[`int`]

  emoji

    The custom or unicode emoji being removed.

    Type:

      `PartialEmoji`

### RawIntegrationDeleteEvent

Attributes

- application_id
- guild_id
- integration_id

class discord.RawIntegrationDeleteEvent

  Represents the payload for a `on_raw_integration_delete()` event.

  Added in version 2.0.

  integration_id

    The ID of the integration that got deleted.

    Type:

      `int`

  application_id

    The ID of the bot/OAuth2 application for this deleted integration.

    Type:

      Optional[`int`]

  guild_id

    The guild ID where the integration got deleted.

    Type:

      `int`

### RawThreadUpdateEvent

Attributes

- data
- guild_id
- parent_id
- thread
- thread_id
- thread_type

class discord.RawThreadUpdateEvent

  Represents the payload for a `on_raw_thread_update()` event.

  Added in version 2.0.

  thread_id

    The ID of the thread that was updated.

    Type:

      `int`

  thread_type

    The channel type of the updated thread.

    Type:

      `discord.ChannelType`

  guild_id

    The ID of the guild the thread is in.

    Type:

      `int`

  parent_id

    The ID of the channel the thread belongs to.

    Type:

      `int`

  data

    The raw data given by the gateway

    Type:

      `dict`

  thread

    The thread, if it could be found in the internal cache.

    Type:

      Optional[`discord.Thread`]

### RawThreadMembersUpdate

Attributes

- data
- guild_id
- member_count
- thread_id

class discord.RawThreadMembersUpdate

  Represents the payload for a `on_raw_thread_member_remove()` event.

  Added in version 2.0.

  thread_id

    The ID of the thread that was updated.

    Type:

      `int`

  guild_id

    The ID of the guild the thread is in.

    Type:

      `int`

  member_count

    The approximate number of members in the thread. This caps at 50.

    Type:

      `int`

  data

    The raw data given by the gateway.

    Type:

      `dict`

### RawThreadDeleteEvent

Attributes

- guild_id
- parent_id
- thread
- thread_id
- thread_type

class discord.RawThreadDeleteEvent

  Represents the payload for a `on_raw_thread_delete()` event.

  Added in version 2.0.

  thread_id

    The ID of the thread that was deleted.

    Type:

      `int`

  thread_type

    The channel type of the deleted thread.

    Type:

      `discord.ChannelType`

  guild_id

    The ID of the guild the thread was deleted in.

    Type:

      `int`

  parent_id

    The ID of the channel the thread belonged to.

    Type:

      `int`

  thread

    The thread, if it could be found in the internal cache.

    Type:

      Optional[`discord.Thread`]

### RawTypingEvent

Attributes

- channel_id
- guild_id
- timestamp
- user
- user_id

class discord.RawTypingEvent

  Represents the payload for a `on_raw_typing()` event.

  Added in version 2.0.

  channel_id

    The ID of the channel the user started typing in.

    Type:

      `int`

  user_id

    The ID of the user that started typing.

    Type:

      `int`

  user

    The user that started typing, if they could be found in the internal cache.

    Type:

      Optional[Union[`discord.User`, `discord.Member`]]

  timestamp

    When the typing started as an aware datetime in UTC.

    Type:

      `datetime.datetime`

  guild_id

    The ID of the guild the user started typing in, if applicable.

    Type:

      Optional[`int`]

### RawMemberRemoveEvent

Attributes

- guild_id
- user

class discord.RawMemberRemoveEvent

  Represents the payload for a `on_raw_member_remove()` event.

  Added in version 2.0.

  user

    The user that left the guild.

    Type:

      Union[`discord.User`, `discord.Member`]

  guild_id

    The ID of the guild the user left.

    Type:

      `int`

### RawAppCommandPermissionsUpdateEvent

Attributes

- application_id
- guild
- permissions
- target_id

class discord.RawAppCommandPermissionsUpdateEvent

  Represents the payload for a `on_raw_app_command_permissions_update()` event.

  Added in version 2.0.

  target_id

    The ID of the command or application whose permissions were updated. When this is the application ID instead of a command ID, the permissions apply to all commands that do not contain explicit overwrites.

    Type:

      `int`

  application_id

    The ID of the application that the command belongs to.

    Type:

      `int`

  guild

    The guild where the permissions were updated.

    Type:

      `Guild`

  permissions

    List of new permissions for the app command.

    Type:

      List[`AppCommandPermissions`]

### RawPollVoteActionEvent

Attributes

- answer_id
- channel_id
- guild_id
- message_id
- user_id

class discord.RawPollVoteActionEvent

  Represents the payload for a `on_raw_poll_vote_add()` or `on_raw_poll_vote_remove()` event.

  Added in version 2.4.

  user_id

    The ID of the user that added or removed a vote.

    Type:

      `int`

  channel_id

    The channel ID where the poll vote action took place.

    Type:

      `int`

  message_id

    The message ID that contains the poll the user added or removed their vote on.

    Type:

      `int`

  guild_id

    The guild ID where the vote got added or removed, if applicable..

    Type:

      Optional[`int`]

  answer_id

    The poll answer’s ID the user voted on.

    Type:

      `int`

### RawPresenceUpdateEvent

Attributes

- activities
- client_status
- guild
- guild_id
- user_id

class discord.RawPresenceUpdateEvent

  Represents the payload for a `on_raw_presence_update()` event.

  Added in version 2.5.

  user_id

    The ID of the user that triggered the presence update.

    Type:

      `int`

  guild_id

    The guild ID for the users presence update. Could be `None`.

    Type:

      Optional[`int`]

  guild

    The guild associated with the presence update and user. Could be `None`.

    Type:

      Optional[`Guild`]

  client_status

    The `ClientStatus` model which holds information about the status of the user on various clients.

    Type:

      `ClientStatus`

  activities

    The activities the user is currently doing. Due to a Discord API limitation, a user’s Spotify activity may not appear if they are listening to a song with a title longer than `128` characters. See GH-1738 for more information.

    Type:

      Tuple[Union[`BaseActivity`, `Spotify`]]

### PartialWebhookGuild

Attributes

- icon
- id
- name

class discord.PartialWebhookGuild

  Represents a partial guild for webhooks.

  These are typically given for channel follower webhooks.

  Added in version 2.0.

  id

    The partial guild’s ID.

    Type:

      `int`

  name

    The partial guild’s name.

    Type:

      `str`

  property icon

    Returns the guild’s icon asset, if available.

    Type:

      Optional[`Asset`]

### PartialWebhookChannel

Attributes

- id
- mention
- name

class discord.PartialWebhookChannel

  Represents a partial channel for webhooks.

  These are typically given for channel follower webhooks.

  Added in version 2.0.

  id

    The partial channel’s ID.

    Type:

      `int`

  name

    The partial channel’s name.

    Type:

      `str`

  property mention

    The string that allows you to mention the channel that the webhook is following.

    Type:

      `str`

### PollAnswer

Attributes

- emoji
- id
- media
- poll
- self_voted
- text
- victor
- vote_count

Methods

- async for voters

class discord.PollAnswer

  Represents a poll’s answer.

  str(x)

    Returns this answer’s text, if any.

  Added in version 2.4.

  id

    The ID of this answer.

    Type:

      `int`

  media

    The display data for this answer.

    Type:

      `PollMedia`

  self_voted

    Whether the current user has voted to this answer or not.

    Type:

      `bool`

  property text

    Returns this answer’s displayed text.

    Type:

      `str`

  property emoji

    Returns this answer’s displayed emoji, if any.

    Type:

      Optional[Union[`Emoji`, `PartialEmoji`]]

  property vote_count

    Returns an approximate count of votes for this answer.

    If the poll is finished, the count is exact.

    Type:

      `int`

  property poll

    Returns the parent poll of this answer.

    Type:

      `Poll`

  property victor

    Whether the answer is the one that had the most votes when the poll ended.

    Added in version 2.5.

    Note

    If the poll has not ended, this will always return `False`.

    Type:

      `bool`

  async for ... in voters(*, limit=None, after=None)

    Returns an asynchronous iterator representing the users that have voted on this answer.

    The `after` parameter must represent a user and meet the `abc.Snowflake` abc.

    This can only be called when the parent poll was sent to a message.

    Examples

    Usage

        async for voter in poll_answer.voters():
            print(f'{voter} has voted for {poll_answer}!')

    Flattening into a list:

        voters = [voter async for voter in poll_answer.voters()]
        # voters is now a list of User

    Parameters:

      - limit (Optional[`int`]) – The maximum number of results to return. If not provided, returns all the users who voted on this poll answer.

      - after (Optional[`abc.Snowflake`]) – For pagination, voters are sorted by member.

    Raises:

      HTTPException – Retrieving the users failed.

    Yields:

      Union[`User`, `Member`] – The member (if retrievable) or the user that has voted on this poll answer. The case where it can be a `Member` is in a guild message context. Sometimes it can be a `User` if the member has left the guild or if the member is not cached.

### MessageSnapshot

Attributes

- attachments
- cached_message
- components
- content
- created_at
- edited_at
- embeds
- flags
- raw_channel_mentions
- raw_mentions
- raw_role_mentions
- stickers
- type

class discord.MessageSnapshot(state, data)

  Represents a message snapshot attached to a forwarded message.

  Added in version 2.5.

  type

    The type of the forwarded message.

    Type:

      `MessageType`

  content

    The actual contents of the forwarded message.

    Type:

      `str`

  embeds

    A list of embeds the forwarded message has.

    Type:

      List[`Embed`]

  attachments

    A list of attachments given to the forwarded message.

    Type:

      List[`Attachment`]

  created_at

    The forwarded message’s time of creation.

    Type:

      `datetime.datetime`

  flags

    Extra features of the the message snapshot.

    Type:

      `MessageFlags`

  stickers

    A list of sticker items given to the message.

    Type:

      List[`StickerItem`]

  components

    A list of components in the message.

    Type:

      List[Union[`ActionRow`, `Button`, `SelectMenu`]]

  raw_mentions

    A property that returns an array of user IDs matched with the syntax of `<@user_id>` in the message content.

    This allows you to receive the user IDs of mentioned users even in a private message context.

    Type:

      List[`int`]

  raw_channel_mentions

    A property that returns an array of channel IDs matched with the syntax of `<#channel_id>` in the message content.

    Type:

      List[`int`]

  raw_role_mentions

    A property that returns an array of role IDs matched with the syntax of `<@&role_id>` in the message content.

    Type:

      List[`int`]

  cached_message

    Returns the cached message this snapshot points to, if any.

    Type:

      Optional[`Message`]

  property edited_at

    An aware UTC datetime object containing the edited time of the forwarded message.

    Type:

      Optional[`datetime.datetime`]

### ClientStatus

Attributes

- desktop_status
- mobile_status
- raw_status
- status
- web_status

Methods

- def is_on_mobile

class discord.ClientStatus

  Represents the Client Status Object from Discord, which holds information about the status of the user on various clients/platforms, with additional helpers.

  Added in version 2.5.

  property status

    The user’s overall status. If the value is unknown, then it will be a `str` instead.

    Type:

      `Status`

  property raw_status

    The user’s overall status as a string value.

    Type:

      `str`

  property mobile_status

    The user’s status on a mobile device, if applicable.

    Type:

      `Status`

  property desktop_status

    The user’s status on the desktop client, if applicable.

    Type:

      `Status`

  property web_status

    The user’s status on the web client, if applicable.

    Type:

      `Status`

  is_on_mobile()

    `bool`: A helper function that determines if a user is active on a mobile device.

## Data Classes

Some classes are just there to be data containers, this lists them.

Unlike models you are allowed to create most of these yourself, even if they can also be used to hold attributes.

Nearly all classes here have py:slots defined which means that it is impossible to have dynamic attributes to the data classes.

The only exception to this rule is `Object`, which is made with dynamic attributes in mind.

### Object

Attributes

- created_at
- id
- type

class discord.Object(id, *, type=...)

  Represents a generic Discord object.

  The purpose of this class is to allow you to create ‘miniature’ versions of data classes if you want to pass in just an ID. Most functions that take in a specific data class with an ID can also take in this class as a substitute instead. Note that even though this is the case, not all objects (if any) actually inherit from this class.

  There are also some cases where some websocket events are received in strange order and when such events happened you would receive this class rather than the actual data class. These cases are extremely rare.

  x == y

    Checks if two objects are equal.

  x != y

    Checks if two objects are not equal.

  hash(x)

    Returns the object’s hash.

  id

    The ID of the object.

    Type:

      `int`

  type

    The discord.py model type of the object, if not specified, defaults to this class.

    Note

    In instances where there are multiple applicable types, use a shared base class. for example, both `Member` and `User` are subclasses of `abc.User`.

    Added in version 2.0.

    Type:

      Type[`abc.Snowflake`]

  property created_at

    Returns the snowflake’s creation time in UTC.

    Type:

      `datetime.datetime`

### Embed

Attributes

- author
- colour
- description
- fields
- flags
- footer
- image
- provider
- thumbnail
- timestamp
- title
- type
- url
- video

Methods

- cls Embed.from_dict
- def add_field
- def clear_fields
- def copy
- def insert_field_at
- def remove_author
- def remove_field
- def remove_footer
- def set_author
- def set_field_at
- def set_footer
- def set_image
- def set_thumbnail
- def to_dict

class discord.Embed(*, colour=None, color=None, title=None, type='rich', url=None, description=None, timestamp=None)

  Represents a Discord embed.

  len(x)

    Returns the total size of the embed. Useful for checking if it’s within the 6000 character limit.

  bool(b)

    Returns whether the embed has any data set.

    Added in version 2.0.

  x == y

    Checks if two embeds are equal.

    Added in version 2.0.

  For ease of use, all parameters that expect a `str` are implicitly casted to `str` for you.

  Changed in version 2.0: `Embed.Empty` has been removed in favour of `None`.

  title

    The title of the embed. This can be set during initialisation. Can only be up to 256 characters.

    Type:

      Optional[`str`]

  type

    The type of embed. Usually “rich”. This can be set during initialisation. Possible strings for embed types can be found on discord’s api docs

    Type:

      `str`

  description

    The description of the embed. This can be set during initialisation. Can only be up to 4096 characters.

    Type:

      Optional[`str`]

  url

    The URL of the embed. This can be set during initialisation.

    Type:

      Optional[`str`]

  timestamp

    The timestamp of the embed content. This is an aware datetime. If a naive datetime is passed, it is converted to an aware datetime with the local timezone.

    Type:

      Optional[`datetime.datetime`]

  colour

    The colour code of the embed. Aliased to `color` as well. This can be set during initialisation.

    Type:

      Optional[Union[`Colour`, `int`]]

  flags

    The flags of this embed.

    Added in version 2.5.

    Type:

      Optional[`EmbedFlags`]

  classmethod from_dict(data)

    Converts a `dict` to a `Embed` provided it is in the format that Discord expects it to be in.

    You can find out about this format in the official Discord documentation.

    Parameters:

      data (`dict`) – The dictionary to convert into an embed.

  copy()

    Returns a shallow copy of the embed.

  property footer

    Returns an `EmbedProxy` denoting the footer contents.

    See `set_footer()` for possible values you can access.

    If the attribute has no value then `None` is returned.

  set_footer(*, text=None, icon_url=None)

    Sets the footer for the embed content.

    This function returns the class instance to allow for fluent-style chaining.

    Parameters:

      - text (`str`) – The footer text. Can only be up to 2048 characters.

      - icon_url (`str`) – The URL of the footer icon. Only HTTP(S) is supported. Inline attachment URLs are also supported, see How do I use a local image file for an embed image?.

  remove_footer()

    Clears embed’s footer information.

    This function returns the class instance to allow for fluent-style chaining.

    Added in version 2.0.

  property image

    Returns an `EmbedProxy` denoting the image contents.

    Possible attributes you can access are:

    - `url`

    - `proxy_url`

    - `width`

    - `height`

    - `flags`

    If the attribute has no value then `None` is returned.

  set_image(*, url)

    Sets the image for the embed content.

    This function returns the class instance to allow for fluent-style chaining.

    Parameters:

      url (Optional[`str`]) – The source URL for the image. Only HTTP(S) is supported. If `None` is passed, any existing image is removed. Inline attachment URLs are also supported, see How do I use a local image file for an embed image?.

  property thumbnail

    Returns an `EmbedProxy` denoting the thumbnail contents.

    Possible attributes you can access are:

    - `url`

    - `proxy_url`

    - `width`

    - `height`

    If the attribute has no value then `None` is returned.

  set_thumbnail(*, url)

    Sets the thumbnail for the embed content.

    This function returns the class instance to allow for fluent-style chaining.

    Parameters:

      url (Optional[`str`]) – The source URL for the thumbnail. Only HTTP(S) is supported. If `None` is passed, any existing thumbnail is removed. Inline attachment URLs are also supported, see How do I use a local image file for an embed image?.

  property video

    Returns an `EmbedProxy` denoting the video contents.

    Possible attributes include:

    - `url` for the video URL.

    - `height` for the video height.

    - `width` for the video width.

    If the attribute has no value then `None` is returned.

  property provider

    Returns an `EmbedProxy` denoting the provider contents.

    The only attributes that might be accessed are `name` and `url`.

    If the attribute has no value then `None` is returned.

  property author

    Returns an `EmbedProxy` denoting the author contents.

    See `set_author()` for possible values you can access.

    If the attribute has no value then `None` is returned.

  set_author(*, name, url=None, icon_url=None)

    Sets the author for the embed content.

    This function returns the class instance to allow for fluent-style chaining.

    Parameters:

      - name (`str`) – The name of the author. Can only be up to 256 characters.

      - url (`str`) – The URL for the author.

      - icon_url (`str`) – The URL of the author icon. Only HTTP(S) is supported. Inline attachment URLs are also supported, see How do I use a local image file for an embed image?.

  remove_author()

    Clears embed’s author information.

    This function returns the class instance to allow for fluent-style chaining.

    Added in version 1.4.

  property fields

    Returns a `list` of `EmbedProxy` denoting the field contents.

    See `add_field()` for possible values you can access.

    If the attribute has no value then `None` is returned.

    Type:

      List[`EmbedProxy`]

  add_field(*, name, value, inline=True)

    Adds a field to the embed object.

    This function returns the class instance to allow for fluent-style chaining. Can only be up to 25 fields.

    Parameters:

      - name (`str`) – The name of the field. Can only be up to 256 characters.

      - value (`str`) – The value of the field. Can only be up to 1024 characters.

      - inline (`bool`) – Whether the field should be displayed inline.

  insert_field_at(index, *, name, value, inline=True)

    Inserts a field before a specified index to the embed.

    This function returns the class instance to allow for fluent-style chaining. Can only be up to 25 fields.

    Added in version 1.2.

    Parameters:

      - index (`int`) – The index of where to insert the field.

      - name (`str`) – The name of the field. Can only be up to 256 characters.

      - value (`str`) – The value of the field. Can only be up to 1024 characters.

      - inline (`bool`) – Whether the field should be displayed inline.

  clear_fields()

    Removes all fields from this embed.

    This function returns the class instance to allow for fluent-style chaining.

    Changed in version 2.0: This function now returns the class instance.

  remove_field(index)

    Removes a field at a specified index.

    If the index is invalid or out of bounds then the error is silently swallowed.

    This function returns the class instance to allow for fluent-style chaining.

    Note

    When deleting a field by index, the index of the other fields shift to fill the gap just like a regular list.

    Changed in version 2.0: This function now returns the class instance.

    Parameters:

      index (`int`) – The index of the field to remove.

  set_field_at(index, *, name, value, inline=True)

    Modifies a field to the embed object.

    The index must point to a valid pre-existing field. Can only be up to 25 fields.

    This function returns the class instance to allow for fluent-style chaining.

    Parameters:

      - index (`int`) – The index of the field to modify.

      - name (`str`) – The name of the field. Can only be up to 256 characters.

      - value (`str`) – The value of the field. Can only be up to 1024 characters.

      - inline (`bool`) – Whether the field should be displayed inline.

    Raises:

      IndexError – An invalid index was provided.

  to_dict()

    Converts this embed object into a dict.

### AllowedMentions

Attributes

- everyone
- replied_user
- roles
- users

Methods

- cls AllowedMentions.all
- cls AllowedMentions.none

class discord.AllowedMentions(*, everyone=True, users=True, roles=True, replied_user=True)

  A class that represents what mentions are allowed in a message.

  This class can be set during `Client` initialisation to apply to every message sent. It can also be applied on a per message basis via `abc.Messageable.send()` for more fine-grained control.

  everyone

    Whether to allow everyone and here mentions. Defaults to `True`.

    Type:

      `bool`

  users

    Controls the users being mentioned. If `True` (the default) then users are mentioned based on the message content. If `False` then users are not mentioned at all. If a list of `abc.Snowflake` is given then only the users provided will be mentioned, provided those users are in the message content.

    Type:

      Union[`bool`, Sequence[`abc.Snowflake`]]

  roles

    Controls the roles being mentioned. If `True` (the default) then roles are mentioned based on the message content. If `False` then roles are not mentioned at all. If a list of `abc.Snowflake` is given then only the roles provided will be mentioned, provided those roles are in the message content.

    Type:

      Union[`bool`, Sequence[`abc.Snowflake`]]

  replied_user

    Whether to mention the author of the message being replied to. Defaults to `True`.

    Added in version 1.6.

    Type:

      `bool`

  classmethod all()

    A factory method that returns a `AllowedMentions` with all fields explicitly set to `True`

    Added in version 1.5.

  classmethod none()

    A factory method that returns a `AllowedMentions` with all fields set to `False`

    Added in version 1.5.

### MessageReference

Attributes

- cached_message
- channel_id
- fail_if_not_exists
- guild_id
- jump_url
- message_id
- resolved
- type

Methods

- cls MessageReference.from_message

class discord.MessageReference(*, message_id, channel_id, guild_id=None, fail_if_not_exists=True, type=('default', 0))

  Represents a reference to a `Message`.

  Added in version 1.5.

  Changed in version 1.6: This class can now be constructed by users.

  type

    The type of message reference.

    Added in version 2.5.

    Type:

      `MessageReferenceType`

  message_id

    The id of the message referenced.

    Type:

      Optional[`int`]

  channel_id

    The channel id of the message referenced.

    Type:

      `int`

  guild_id

    The guild id of the message referenced.

    Type:

      Optional[`int`]

  fail_if_not_exists

    Whether the referenced message should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

    Added in version 1.7.

    Type:

      `bool`

  resolved

    The message that this reference resolved to. If this is `None` then the original message was not fetched either due to the Discord API not attempting to resolve it or it not being available at the time of creation. If the message was resolved at a prior point but has since been deleted then this will be of type `DeletedReferencedMessage`.

    Added in version 1.6.

    Type:

      Optional[Union[`Message`, `DeletedReferencedMessage`]]

  classmethod from_message(message, *, fail_if_not_exists=True, type=('default', 0))

    Creates a `MessageReference` from an existing `Message`.

    Added in version 1.6.

    Parameters:

      - message (`Message`) – The message to be converted into a reference.

      - fail_if_not_exists (`bool`) –

        Whether the referenced message should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

        Added in version 1.7.

      - type (`MessageReferenceType`) –

        The type of message reference this is.

        Added in version 2.5.

    Returns:

      A reference to the message.

    Return type:

      `MessageReference`

  property cached_message

    The cached message, if found in the internal message cache.

    Type:

      Optional[`Message`]

  property jump_url

    Returns a URL that allows the client to jump to the referenced message.

    Added in version 1.7.

    Type:

      `str`

### PartialMessage

Attributes

- channel
- created_at
- guild
- id
- jump_url
- thread

Methods

- async add_reaction
- async clear_reaction
- async clear_reactions
- async create_thread
- async delete
- async edit
- async end_poll
- async fetch
- async fetch_thread
- async forward
- async pin
- async publish
- async remove_reaction
- async reply
- def to_reference
- async unpin

class discord.PartialMessage(*, channel, id)

  Represents a partial message to aid with working messages when only a message and channel ID are present.

  There are two ways to construct this class. The first one is through the constructor itself, and the second is via the following:

  - `TextChannel.get_partial_message()`

  - `VoiceChannel.get_partial_message()`

  - `StageChannel.get_partial_message()`

  - `Thread.get_partial_message()`

  - `DMChannel.get_partial_message()`

  Note that this class is trimmed down and has no rich attributes.

  Added in version 1.6.

  x == y

    Checks if two partial messages are equal.

  x != y

    Checks if two partial messages are not equal.

  hash(x)

    Returns the partial message’s hash.

  channel

    The channel associated with this partial message.

    Type:

      Union[`PartialMessageable`, `TextChannel`, `StageChannel`, `VoiceChannel`, `Thread`, `DMChannel`]

  id

    The message ID.

    Type:

      `int`

  guild

    The guild that the partial message belongs to, if applicable.

    Type:

      Optional[`Guild`]

  property created_at

    The partial message’s creation time in UTC.

    Type:

      `datetime.datetime`

  property jump_url

    Returns a URL that allows the client to jump to this message.

    Type:

      `str`

  property thread

    The public thread created from this message, if it exists.

    Note

    This does not retrieve archived threads, as they are not retained in the internal cache. Use `fetch_thread()` instead.

    Added in version 2.4.

    Type:

      Optional[`Thread`]

  await fetch()

    This function is a coroutine.

    Fetches the partial message to a full `Message`.

    Raises:

      - NotFound – The message was not found.

      - Forbidden – You do not have the permissions required to get a message.

      - HTTPException – Retrieving the message failed.

    Returns:

      The full message.

    Return type:

      `Message`

  await delete(*, delay=None)

    This function is a coroutine.

    Deletes the message.

    Your own messages could be deleted without any proper permissions. However to delete other people’s messages, you must have `manage_messages`.

    Changed in version 1.1: Added the new `delay` keyword-only parameter.

    Parameters:

      delay (Optional[`float`]) – If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored.

    Raises:

      - Forbidden – You do not have proper permissions to delete the message.

      - NotFound – The message was deleted already

      - HTTPException – Deleting the message failed.

  await edit(*, content=..., embed=..., embeds=..., attachments=..., delete_after=None, allowed_mentions=..., view=...)

    This function is a coroutine.

    Edits the message.

    The content must be able to be transformed into a string via `str(content)`.

    Changed in version 2.0: Edits are no longer in-place, the newly edited message is returned instead.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - content (Optional[`str`]) – The new content to replace the message with. Could be `None` to remove the content.

      - embed (Optional[`Embed`]) – The new embed to replace the original with. Could be `None` to remove the embed.

      - embeds (List[`Embed`]) –

        The new embeds to replace the original with. Must be a maximum of 10. To remove all embeds `[]` should be passed.

        Added in version 2.0.

      - attachments (List[Union[`Attachment`, `File`]]) –

        A list of attachments to keep in the message as well as new files to upload. If `[]` is passed then all attachments are removed.

        Note

        New files will always appear after current attachments.

        Added in version 2.0.

      - delete_after (Optional[`float`]) – If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored.

      - allowed_mentions (Optional[`AllowedMentions`]) –

        Controls the mentions being processed in this message. If this is passed, then the object is merged with `allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in `allowed_mentions`. If no object is passed at all then the defaults given by `allowed_mentions` are used instead.

        Added in version 1.4.

      - view (Optional[`View`]) – The updated view to update this message with. If `None` is passed then the view is removed.

    Raises:

      - HTTPException – Editing the message failed.

      - Forbidden – Tried to suppress a message without permissions or edited a message’s content or embed that isn’t yours.

      - NotFound – This message does not exist.

      - TypeError – You specified both `embed` and `embeds`

    Returns:

      The newly edited message.

    Return type:

      `Message`

  await publish()

    This function is a coroutine.

    Publishes this message to the channel’s followers.

    The message must have been sent in a news channel. You must have `send_messages` to do this.

    If the message is not your own then `manage_messages` is also needed.

    Raises:

      - Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.

      - HTTPException – Publishing the message failed.

  await pin(*, reason=None)

    This function is a coroutine.

    Pins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for pinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to pin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages.

  await unpin(*, reason=None)

    This function is a coroutine.

    Unpins the message.

    You must have `manage_messages` to do this in a non-private channel context.

    Parameters:

      reason (Optional[`str`]) –

      The reason for unpinning the message. Shows up on the audit log.

      Added in version 1.4.

    Raises:

      - Forbidden – You do not have permissions to unpin the message.

      - NotFound – The message or channel was not found or deleted.

      - HTTPException – Unpinning the message failed.

  await add_reaction(emoji, /)

    This function is a coroutine.

    Adds a reaction to the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `read_message_history` to do this. If nobody else has reacted to the message using this emoji, `add_reactions` is required.

    Changed in version 2.0: `emoji` parameter is now positional-only.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to react with.

    Raises:

      - HTTPException – Adding the reaction failed.

      - Forbidden – You do not have the proper permissions to react to the message.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await remove_reaction(emoji, member)

    This function is a coroutine.

    Remove a reaction by the member from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    If the reaction is not your own (i.e. `member` parameter is not you) then `manage_messages` is needed.

    The `member` parameter must represent a member and meet the `abc.Snowflake` abc.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      - emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to remove.

      - member (`abc.Snowflake`) – The member for which to remove the reaction.

    Raises:

      - HTTPException – Removing the reaction failed.

      - Forbidden – You do not have the proper permissions to remove the reaction.

      - NotFound – The member or emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await clear_reaction(emoji)

    This function is a coroutine.

    Clears a specific reaction from the message.

    The emoji may be a unicode emoji or a custom guild `Emoji`.

    You must have `manage_messages` to do this.

    Added in version 1.3.

    Changed in version 2.0: This function will now raise `TypeError` instead of `InvalidArgument`.

    Parameters:

      emoji (Union[`Emoji`, `Reaction`, `PartialEmoji`, `str`]) – The emoji to clear.

    Raises:

      - HTTPException – Clearing the reaction failed.

      - Forbidden – You do not have the proper permissions to clear the reaction.

      - NotFound – The emoji you specified was not found.

      - TypeError – The emoji parameter is invalid.

  await clear_reactions()

    This function is a coroutine.

    Removes all the reactions from the message.

    You must have `manage_messages` to do this.

    Raises:

      - HTTPException – Removing the reactions failed.

      - Forbidden – You do not have the proper permissions to remove all the reactions.

  await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)

    This function is a coroutine.

    Creates a public thread from this message.

    You must have `create_public_threads` in order to create a public thread from a message.

    The channel this message belongs in must be a `TextChannel`.

    Added in version 2.0.

    Parameters:

      - name (`str`) – The name of the thread.

      - auto_archive_duration (`int`) –

        The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

        Must be one of `60`, `1440`, `4320`, or `10080`, if provided.

      - slowmode_delay (Optional[`int`]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is `21600`. By default no slowmode rate limit if this is `None`.

      - reason (Optional[`str`]) – The reason for creating a new thread. Shows up on the audit log.

    Raises:

      - Forbidden – You do not have permissions to create a thread.

      - HTTPException – Creating the thread failed.

      - ValueError – This message does not have guild info attached.

    Returns:

      The created thread.

    Return type:

      `Thread`

  await fetch_thread()

    This function is a coroutine.

    Retrieves the public thread attached to this message.

    Note

    This method is an API call. For general usage, consider `thread` instead.

    Added in version 2.4.

    Raises:

      - InvalidData – An unknown channel type was received from Discord or the guild the thread belongs to is not the same as the one in this object points to.

      - HTTPException – Retrieving the thread failed.

      - NotFound – There is no thread attached to this message.

      - Forbidden – You do not have permission to fetch this channel.

    Returns:

      The public thread attached to this message.

    Return type:

      `Thread`

  await reply(content=None, **kwargs)

    This function is a coroutine.

    A shortcut method to `abc.Messageable.send()` to reply to the `Message`.

    Added in version 1.6.

    Changed in version 2.0: This function will now raise `TypeError` or `ValueError` instead of `InvalidArgument`.

    Raises:

      - HTTPException – Sending the message failed.

      - Forbidden – You do not have the proper permissions to send the message.

      - ValueError – The `files` list is not of the appropriate size

      - TypeError – You specified both `file` and `files`.

    Returns:

      The message that was sent.

    Return type:

      `Message`

  await end_poll()

    This function is a coroutine.

    Ends the `Poll` attached to this message.

    This can only be done if you are the message author.

    If the poll was successfully ended, then it returns the updated `Message`.

    Raises:

      HTTPException – Ending the poll failed.

    Returns:

      The updated message.

    Return type:

      `Message`

  to_reference(*, fail_if_not_exists=True, type=('default', 0))

    Creates a `MessageReference` from the current message.

    Added in version 1.6.

    Parameters:

      - fail_if_not_exists (`bool`) –

        Whether the referenced message should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

        Added in version 1.7.

      - type (`MessageReferenceType`) –

        The type of message reference.

        Added in version 2.5.

    Returns:

      The reference to this message.

    Return type:

      `MessageReference`

  await forward(destination, *, fail_if_not_exists=True)

    This function is a coroutine.

    Forwards this message to a channel.

    Added in version 2.5.

    Parameters:

      - destination (`Messageable`) – The channel to forward this message to.

      - fail_if_not_exists (`bool`) – Whether replying using the message reference should raise `HTTPException` if the message no longer exists or Discord could not fetch the message.

    Raises:

      HTTPException – Forwarding the message failed.

    Returns:

      The message sent to the channel.

    Return type:

      `Message`

### MessageApplication

Attributes

- cover
- description
- icon
- id
- name

class discord.MessageApplication(*, state, data)

  Represents a message’s application data from a `Message`.

  Added in version 2.0.

  id

    The application ID.

    Type:

      `int`

  description

    The application description.

    Type:

      `str`

  name

    The application’s name.

    Type:

      `str`

  property icon

    The application’s icon, if any.

    Type:

      Optional[`Asset`]

  property cover

    The application’s cover image, if any.

    Type:

      Optional[`Asset`]

### RoleSubscriptionInfo

Attributes

- is_renewal
- role_subscription_listing_id
- tier_name
- total_months_subscribed

class discord.RoleSubscriptionInfo(data)

  Represents a message’s role subscription information.

  This is currently only attached to messages of type `MessageType.role_subscription_purchase`.

  Added in version 2.0.

  role_subscription_listing_id

    The ID of the SKU and listing that the user is subscribed to.

    Type:

      `int`

  tier_name

    The name of the tier that the user is subscribed to.

    Type:

      `str`

  total_months_subscribed

    The cumulative number of months that the user has been subscribed for.

    Type:

      `int`

  is_renewal

    Whether this notification is for a renewal rather than a new purchase.

    Type:

      `bool`

### PurchaseNotification

Attributes

- guild_product_purchase

class discord.PurchaseNotification

  Represents a message’s purchase notification data.

  This is currently only attached to messages of type `MessageType.purchase_notification`.

  Added in version 2.5.

  guild_product_purchase

    The guild product purchase that prompted the message.

    Type:

      Optional[`GuildProductPurchase`]

#### GuildProductPurchase

Attributes

- listing_id
- product_name

class discord.GuildProductPurchase

  Represents a message’s guild product that the user has purchased.

  Added in version 2.5.

  listing_id

    The ID of the listing that the user has purchased.

    Type:

      `int`

  product_name

    The name of the product that the user has purchased.

    Type:

      `str`

### Intents

Attributes

- auto_moderation
- auto_moderation_configuration
- auto_moderation_execution
- bans
- dm_messages
- dm_polls
- dm_reactions
- dm_typing
- emojis
- emojis_and_stickers
- expressions
- guild_messages
- guild_polls
- guild_reactions
- guild_scheduled_events
- guild_typing
- guilds
- integrations
- invites
- members
- message_content
- messages
- moderation
- polls
- presences
- reactions
- typing
- value
- voice_states
- webhooks

Methods

- cls Intents.all
- cls Intents.default
- cls Intents.none

class discord.Intents(value=0, **kwargs)

  Wraps up a Discord gateway intent flag.

  Similar to `Permissions`, the properties provided are two way. You can set and retrieve individual bits using the properties as if they were regular bools.

  To construct an object you can pass keyword arguments denoting the flags to enable or disable.

  This is used to disable certain gateway features that are unnecessary to run your bot. To make use of this, it is passed to the `intents` keyword argument of `Client`.

  Added in version 1.5.

  x == y

    Checks if two flags are equal.

  x != y

    Checks if two flags are not equal.

  x | y, x |= y

    Returns an Intents instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns an Intents instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns an Intents instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns an Intents instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

  bool(b)

    Returns whether any intent is enabled.

    Added in version 2.0.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  classmethod all()

    A factory method that creates a `Intents` with everything enabled.

  classmethod none()

    A factory method that creates a `Intents` with everything disabled.

  classmethod default()

    A factory method that creates a `Intents` with everything enabled except `presences`, `members`, and `message_content`.

  guilds

    Whether guild related events are enabled.

    This corresponds to the following events:

    - `on_guild_join()`

    - `on_guild_remove()`

    - `on_guild_available()`

    - `on_guild_unavailable()`

    - `on_guild_channel_update()`

    - `on_guild_channel_create()`

    - `on_guild_channel_delete()`

    - `on_guild_channel_pins_update()`

    - `on_thread_create()`

    - `on_thread_join()`

    - `on_thread_update()`

    - `on_thread_delete()`

    This also corresponds to the following attributes and classes in terms of cache:

    - `Client.guilds`

    - `Guild` and all its attributes.

    - `Client.get_channel()`

    - `Client.get_all_channels()`

    It is highly advisable to leave this intent enabled for your bot to function.

    Type:

      `bool`

  members

    Whether guild member related events are enabled.

    This corresponds to the following events:

    - `on_member_join()`

    - `on_member_remove()`

    - `on_member_update()`

    - `on_user_update()`

    - `on_thread_member_join()`

    - `on_thread_member_remove()`

    This also corresponds to the following attributes and classes in terms of cache:

    - `Client.get_all_members()`

    - `Client.get_user()`

    - `Guild.chunk()`

    - `Guild.fetch_members()`

    - `Guild.get_member()`

    - `Guild.members`

    - `Member.roles`

    - `Member.nick`

    - `Member.premium_since`

    - `User.name`

    - `User.avatar`

    - `User.discriminator`

    - `User.global_name`

    For more information go to the member intent documentation.

    Note

    Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

    Type:

      `bool`

  moderation

    Whether guild moderation related events are enabled.

    This corresponds to the following events:

    - `on_member_ban()`

    - `on_member_unban()`

    - `on_audit_log_entry_create()`

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  bans

    An alias of `moderation`.

    Changed in version 2.2: Changed to an alias.

    Type:

      `bool`

  emojis

    Alias of `expressions`.

    Changed in version 2.0: Changed to an alias.

    Type:

      `bool`

  emojis_and_stickers

    Alias of `expressions`.

    Added in version 2.0.

    Changed in version 2.5: Changed to an alias.

    Type:

      `bool`

  expressions

    Whether guild emoji, sticker, and soundboard sound related events are enabled.

    Added in version 2.5.

    This corresponds to the following events:

    - `on_guild_emojis_update()`

    - `on_guild_stickers_update()`

    - `on_soundboard_sound_create()`

    - `on_soundboard_sound_update()`

    - `on_soundboard_sound_delete()`

    This also corresponds to the following attributes and classes in terms of cache:

    - `Emoji`

    - `GuildSticker`

    - `SoundboardSound`

    - `Client.get_emoji()`

    - `Client.get_sticker()`

    - `Client.get_soundboard_sound()`

    - `Client.emojis()`

    - `Client.stickers()`

    - `Client.soundboard_sounds()`

    - `Guild.emojis`

    - `Guild.stickers`

    - `Guild.soundboard_sounds`

    Type:

      `bool`

  integrations

    Whether guild integration related events are enabled.

    This corresponds to the following events:

    - `on_guild_integrations_update()`

    - `on_integration_create()`

    - `on_integration_update()`

    - `on_raw_integration_delete()`

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  webhooks

    Whether guild webhook related events are enabled.

    This corresponds to the following events:

    - `on_webhooks_update()`

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  invites

    Whether guild invite related events are enabled.

    This corresponds to the following events:

    - `on_invite_create()`

    - `on_invite_delete()`

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  voice_states

    Whether guild voice state related events are enabled.

    This corresponds to the following events:

    - `on_voice_state_update()`

    This also corresponds to the following attributes and classes in terms of cache:

    - `VoiceChannel.members`

    - `VoiceChannel.voice_states`

    - `Member.voice`

    Note

    This intent is required to connect to voice.

    Type:

      `bool`

  presences

    Whether guild presence related events are enabled.

    This corresponds to the following events:

    - `on_presence_update()`

    This also corresponds to the following attributes and classes in terms of cache:

    - `Member.activities`

    - `Member.status`

    - `Member.raw_status`

    For more information go to the presence intent documentation.

    Note

    Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

    Type:

      `bool`

  messages

    Whether guild and direct message related events are enabled.

    This is a shortcut to set or get both `guild_messages` and `dm_messages`.

    This corresponds to the following events:

    - `on_message()` (both guilds and DMs)

    - `on_message_edit()` (both guilds and DMs)

    - `on_message_delete()` (both guilds and DMs)

    - `on_raw_message_delete()` (both guilds and DMs)

    - `on_raw_message_edit()` (both guilds and DMs)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message`

    - `Client.cached_messages`

    Note that due to an implicit relationship this also corresponds to the following events:

    - `on_reaction_add()` (both guilds and DMs)

    - `on_reaction_remove()` (both guilds and DMs)

    - `on_reaction_clear()` (both guilds and DMs)

    Type:

      `bool`

  guild_messages

    Whether guild message related events are enabled.

    See also `dm_messages` for DMs or `messages` for both.

    This corresponds to the following events:

    - `on_message()` (only for guilds)

    - `on_message_edit()` (only for guilds)

    - `on_message_delete()` (only for guilds)

    - `on_raw_message_delete()` (only for guilds)

    - `on_raw_message_edit()` (only for guilds)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message`

    - `Client.cached_messages` (only for guilds)

    Note that due to an implicit relationship this also corresponds to the following events:

    - `on_reaction_add()` (only for guilds)

    - `on_reaction_remove()` (only for guilds)

    - `on_reaction_clear()` (only for guilds)

    Type:

      `bool`

  dm_messages

    Whether direct message related events are enabled.

    See also `guild_messages` for guilds or `messages` for both.

    This corresponds to the following events:

    - `on_message()` (only for DMs)

    - `on_message_edit()` (only for DMs)

    - `on_message_delete()` (only for DMs)

    - `on_raw_message_delete()` (only for DMs)

    - `on_raw_message_edit()` (only for DMs)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message`

    - `Client.cached_messages` (only for DMs)

    Note that due to an implicit relationship this also corresponds to the following events:

    - `on_reaction_add()` (only for DMs)

    - `on_reaction_remove()` (only for DMs)

    - `on_reaction_clear()` (only for DMs)

    Type:

      `bool`

  reactions

    Whether guild and direct message reaction related events are enabled.

    This is a shortcut to set or get both `guild_reactions` and `dm_reactions`.

    This corresponds to the following events:

    - `on_reaction_add()` (both guilds and DMs)

    - `on_reaction_remove()` (both guilds and DMs)

    - `on_reaction_clear()` (both guilds and DMs)

    - `on_raw_reaction_add()` (both guilds and DMs)

    - `on_raw_reaction_remove()` (both guilds and DMs)

    - `on_raw_reaction_clear()` (both guilds and DMs)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message.reactions` (both guild and DM messages)

    Type:

      `bool`

  guild_reactions

    Whether guild message reaction related events are enabled.

    See also `dm_reactions` for DMs or `reactions` for both.

    This corresponds to the following events:

    - `on_reaction_add()` (only for guilds)

    - `on_reaction_remove()` (only for guilds)

    - `on_reaction_clear()` (only for guilds)

    - `on_raw_reaction_add()` (only for guilds)

    - `on_raw_reaction_remove()` (only for guilds)

    - `on_raw_reaction_clear()` (only for guilds)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message.reactions` (only for guild messages)

    Type:

      `bool`

  dm_reactions

    Whether direct message reaction related events are enabled.

    See also `guild_reactions` for guilds or `reactions` for both.

    This corresponds to the following events:

    - `on_reaction_add()` (only for DMs)

    - `on_reaction_remove()` (only for DMs)

    - `on_reaction_clear()` (only for DMs)

    - `on_raw_reaction_add()` (only for DMs)

    - `on_raw_reaction_remove()` (only for DMs)

    - `on_raw_reaction_clear()` (only for DMs)

    This also corresponds to the following attributes and classes in terms of cache:

    - `Message.reactions` (only for DM messages)

    Type:

      `bool`

  typing

    Whether guild and direct message typing related events are enabled.

    This is a shortcut to set or get both `guild_typing` and `dm_typing`.

    This corresponds to the following events:

    - `on_typing()` (both guilds and DMs)

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  guild_typing

    Whether guild and direct message typing related events are enabled.

    See also `dm_typing` for DMs or `typing` for both.

    This corresponds to the following events:

    - `on_typing()` (only for guilds)

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  dm_typing

    Whether guild and direct message typing related events are enabled.

    See also `guild_typing` for guilds or `typing` for both.

    This corresponds to the following events:

    - `on_typing()` (only for DMs)

    This does not correspond to any attributes or classes in the library in terms of cache.

    Type:

      `bool`

  message_content

    Whether message content, attachments, embeds and components will be available in messages which do not meet the following criteria:

    - The message was sent by the client

    - The message was sent in direct messages

    - The message mentions the client

    This applies to the following events:

    - `on_message()`

    - `on_message_edit()`

    - `on_message_delete()`

    - `on_raw_message_edit()`

    For more information go to the message content intent documentation.

    Note

    Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

    Added in version 2.0.

    Type:

      `bool`

  guild_scheduled_events

    Whether guild scheduled event related events are enabled.

    This corresponds to the following events:

    - `on_scheduled_event_create()`

    - `on_scheduled_event_update()`

    - `on_scheduled_event_delete()`

    - `on_scheduled_event_user_add()`

    - `on_scheduled_event_user_remove()`

    Added in version 2.0.

    Type:

      `bool`

  auto_moderation

    Whether auto moderation related events are enabled.

    This is a shortcut to set or get both `auto_moderation_configuration` and `auto_moderation_execution`.

    This corresponds to the following events:

    - `on_automod_rule_create()`

    - `on_automod_rule_update()`

    - `on_automod_rule_delete()`

    - `on_automod_action()`

    Added in version 2.0.

    Type:

      `bool`

  auto_moderation_configuration

    Whether auto moderation configuration related events are enabled.

    This corresponds to the following events:

    - `on_automod_rule_create()`

    - `on_automod_rule_update()`

    - `on_automod_rule_delete()`

    Added in version 2.0.

    Type:

      `bool`

  auto_moderation_execution

    Whether auto moderation execution related events are enabled.

    This corresponds to the following events: - `on_automod_action()`

    Added in version 2.0.

    Type:

      `bool`

  polls

    Whether guild and direct messages poll related events are enabled.

    This is a shortcut to set or get both `guild_polls` and `dm_polls`.

    This corresponds to the following events:

    - `on_poll_vote_add()` (both guilds and DMs)

    - `on_poll_vote_remove()` (both guilds and DMs)

    - `on_raw_poll_vote_add()` (both guilds and DMs)

    - `on_raw_poll_vote_remove()` (both guilds and DMs)

    Added in version 2.4.

    Type:

      `bool`

  guild_polls

    Whether guild poll related events are enabled.

    See also `dm_polls` and `polls`.

    This corresponds to the following events:

    - `on_poll_vote_add()` (only for guilds)

    - `on_poll_vote_remove()` (only for guilds)

    - `on_raw_poll_vote_add()` (only for guilds)

    - `on_raw_poll_vote_remove()` (only for guilds)

    Added in version 2.4.

    Type:

      `bool`

  dm_polls

    Whether direct messages poll related events are enabled.

    See also `guild_polls` and `polls`.

    This corresponds to the following events:

    - `on_poll_vote_add()` (only for DMs)

    - `on_poll_vote_remove()` (only for DMs)

    - `on_raw_poll_vote_add()` (only for DMs)

    - `on_raw_poll_vote_remove()` (only for DMs)

    Added in version 2.4.

    Type:

      `bool`

### MemberCacheFlags

Attributes

- joined
- value
- voice

Methods

- cls MemberCacheFlags.all
- cls MemberCacheFlags.from_intents
- cls MemberCacheFlags.none

class discord.MemberCacheFlags(**kwargs)

  Controls the library’s cache policy when it comes to members.

  This allows for finer grained control over what members are cached. Note that the bot’s own member is always cached. This class is passed to the `member_cache_flags` parameter in `Client`.

  Due to a quirk in how Discord works, in order to ensure proper cleanup of cache resources it is recommended to have `Intents.members` enabled. Otherwise the library cannot know when a member leaves a guild and is thus unable to cleanup after itself.

  To construct an object you can pass keyword arguments denoting the flags to enable or disable.

  The default value is all flags enabled.

  Added in version 1.5.

  x == y

    Checks if two flags are equal.

  x != y

    Checks if two flags are not equal.

  x | y, x |= y

    Returns a MemberCacheFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a MemberCacheFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a MemberCacheFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a MemberCacheFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

  bool(b)

    Returns whether any flag is set to `True`.

    Added in version 2.0.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  classmethod all()

    A factory method that creates a `MemberCacheFlags` with everything enabled.

  classmethod none()

    A factory method that creates a `MemberCacheFlags` with everything disabled.

  voice

    Whether to cache members that are in voice.

    This requires `Intents.voice_states`.

    Members that leave voice are no longer cached.

    Type:

      `bool`

  joined

    Whether to cache members that joined the guild or are chunked as part of the initial log in flow.

    This requires `Intents.members`.

    Members that leave the guild are no longer cached.

    Type:

      `bool`

  classmethod from_intents(intents)

    A factory method that creates a `MemberCacheFlags` based on the currently selected `Intents`.

    Parameters:

      intents (`Intents`) – The intents to select from.

    Returns:

      The resulting member cache flags.

    Return type:

      `MemberCacheFlags`

### ApplicationFlags

Attributes

- active
- app_commands_badge
- auto_mod_badge
- embedded
- gateway_guild_members
- gateway_guild_members_limited
- gateway_message_content
- gateway_message_content_limited
- gateway_presence
- gateway_presence_limited
- value
- verification_pending_guild_limit

class discord.ApplicationFlags(**kwargs)

  Wraps up the Discord Application flags.

  x == y

    Checks if two ApplicationFlags are equal.

  x != y

    Checks if two ApplicationFlags are not equal.

  x | y, x |= y

    Returns an ApplicationFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns an ApplicationFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns an ApplicationFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns an ApplicationFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  Added in version 2.0.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  auto_mod_badge

    Returns `True` if the application uses at least 100 automod rules across all guilds. This shows up as a badge in the official client.

    Added in version 2.3.

    Type:

      `bool`

  gateway_presence

    Returns `True` if the application is verified and is allowed to receive presence information over the gateway.

    Type:

      `bool`

  gateway_presence_limited

    Returns `True` if the application is allowed to receive limited presence information over the gateway.

    Type:

      `bool`

  gateway_guild_members

    Returns `True` if the application is verified and is allowed to receive guild members information over the gateway.

    Type:

      `bool`

  gateway_guild_members_limited

    Returns `True` if the application is allowed to receive limited guild members information over the gateway.

    Type:

      `bool`

  verification_pending_guild_limit

    Returns `True` if the application is currently pending verification and has hit the guild limit.

    Type:

      `bool`

  embedded

    Returns `True` if the application is embedded within the Discord client.

    Type:

      `bool`

  gateway_message_content

    Returns `True` if the application is verified and is allowed to read message content in guilds.

    Type:

      `bool`

  gateway_message_content_limited

    Returns `True` if the application is unverified and is allowed to read message content in guilds.

    Type:

      `bool`

  app_commands_badge

    Returns `True` if the application has registered a global application command. This shows up as a badge in the official client.

    Type:

      `bool`

  active

    Returns `True` if the application has had at least one global application command used in the last 30 days.

    Added in version 2.1.

    Type:

      `bool`

### ChannelFlags

Attributes

- hide_media_download_options
- pinned
- require_tag
- value

class discord.ChannelFlags(**kwargs)

  Wraps up the Discord `GuildChannel` or `Thread` flags.

  x == y

    Checks if two channel flags are equal.

  x != y

    Checks if two channel flags are not equal.

  x | y, x |= y

    Returns a ChannelFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a ChannelFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a ChannelFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a ChannelFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  Added in version 2.0.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  pinned

    Returns `True` if the thread is pinned to the forum channel.

    Type:

      `bool`

  require_tag

    Returns `True` if a tag is required to be specified when creating a thread in a `ForumChannel`.

    Added in version 2.1.

    Type:

      `bool`

  hide_media_download_options

    Returns `True` if the client hides embedded media download options in a `ForumChannel`. Only available in media channels.

    Added in version 2.4.

    Type:

      `bool`

### AutoModPresets

Attributes

- profanity
- sexual_content
- slurs
- value

class discord.AutoModPresets(**kwargs)

  Wraps up the Discord `AutoModRule` presets.

  Added in version 2.0.

  x == y

    Checks if two AutoMod preset flags are equal.

  x != y

    Checks if two AutoMod preset flags are not equal.

  x | y, x |= y

    Returns an AutoModPresets instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns an AutoModPresets instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns an AutoModPresets instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns an AutoModPresets instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  profanity

    Whether to use the preset profanity filter.

    Type:

      `bool`

  sexual_content

    Whether to use the preset sexual content filter.

    Type:

      `bool`

  slurs

    Whether to use the preset slurs filter.

    Type:

      `bool`

### AutoModRuleAction

Attributes

- channel_id
- custom_message
- duration
- type

class discord.AutoModRuleAction(*, type=None, channel_id=None, duration=None, custom_message=None)

  Represents an auto moderation’s rule action.

  Note

  Only one of `channel_id`, `duration`, or `custom_message` can be used.

  Added in version 2.0.

  type

    The type of action to take. Defaults to `block_message`.

    Type:

      `AutoModRuleActionType`

  channel_id

    The ID of the channel or thread to send the alert message to, if any. Passing this sets `type` to `send_alert_message`.

    Type:

      Optional[`int`]

  duration

    The duration of the timeout to apply, if any. Has a maximum of 28 days. Passing this sets `type` to `timeout`.

    Type:

      Optional[`datetime.timedelta`]

  custom_message

    A custom message which will be shown to a user when their message is blocked. Passing this sets `type` to `block_message`.

    Added in version 2.2.

    Type:

      Optional[`str`]

### AutoModTrigger

Attributes

- allow_list
- keyword_filter
- mention_limit
- mention_raid_protection
- presets
- regex_patterns
- type

class discord.AutoModTrigger(*, type=None, keyword_filter=None, presets=None, allow_list=None, mention_limit=None, regex_patterns=None, mention_raid_protection=None)

  Represents a trigger for an auto moderation rule.

  The following table illustrates relevant attributes for each `AutoModRuleTriggerType`:

  Type | Attributes
  --- | ---
  `AutoModRuleTriggerType.keyword` | `keyword_filter`, `regex_patterns`, `allow_list`
  `AutoModRuleTriggerType.spam` |
  `AutoModRuleTriggerType.keyword_preset` | `presets`, `allow_list`
  `AutoModRuleTriggerType.mention_spam` | `mention_limit`, `mention_raid_protection`
  `AutoModRuleTriggerType.member_profile` | `keyword_filter`, `regex_patterns`, `allow_list`

  Added in version 2.0.

  type

    The type of trigger.

    Type:

      `AutoModRuleTriggerType`

  keyword_filter

    The list of strings that will trigger the filter. Maximum of 1000. Keywords can only be up to 60 characters in length.

    This could be combined with `regex_patterns`.

    Type:

      List[`str`]

  regex_patterns

    The regex pattern that will trigger the filter. The syntax is based off of Rust’s regex syntax. Maximum of 10. Regex strings can only be up to 260 characters in length.

    This could be combined with `keyword_filter` and/or `allow_list`

    Added in version 2.1.

    Type:

      List[`str`]

  presets

    The presets used with the preset keyword filter.

    Type:

      `AutoModPresets`

  allow_list

    The list of words that are exempt from the commonly flagged words. Maximum of 100. Keywords can only be up to 60 characters in length.

    Type:

      List[`str`]

  mention_limit

    The total number of user and role mentions a message can contain. Has a maximum of 50.

    Type:

      `int`

  mention_raid_protection

    Whether mention raid protection is enabled or not.

    Added in version 2.4.

    Type:

      `bool`

### File

Attributes

- description
- filename
- fp
- spoiler

class discord.File(fp, filename=None, *, spoiler=..., description=None)

  A parameter object used for `abc.Messageable.send()` for sending file objects.

  Note

  File objects are single use and are not meant to be reused in multiple `abc.Messageable.send()`s.

  fp

    A file-like object opened in binary mode and read mode or a filename representing a file in the hard drive to open.

    Note

    If the file-like object passed is opened via `open` then the modes ‘rb’ should be used.

    To pass binary data, consider usage of `io.BytesIO`.

    Type:

      Union[`os.PathLike`, `io.BufferedIOBase`]

  spoiler

    Whether the attachment is a spoiler. If left unspecified, the `filename` is used to determine if the file is a spoiler.

    Type:

      `bool`

  description

    The file description to display, currently only supported for images.

    Added in version 2.0.

    Type:

      Optional[`str`]

  property filename

    The filename to display when uploading to Discord. If this is not given then it defaults to `fp.name` or if `fp` is a string then the `filename` will default to the string given.

    Type:

      `str`

### Colour

Attributes

- b
- g
- r
- value

Methods

- cls Colour.blue
- cls Colour.blurple
- cls Colour.brand_green
- cls Colour.brand_red
- cls Colour.dark_blue
- cls Colour.dark_embed
- cls Colour.dark_gold
- cls Colour.dark_gray
- cls Colour.dark_green
- cls Colour.dark_grey
- cls Colour.dark_magenta
- cls Colour.dark_orange
- cls Colour.dark_purple
- cls Colour.dark_red
- cls Colour.dark_teal
- cls Colour.dark_theme
- cls Colour.darker_gray
- cls Colour.darker_grey
- cls Colour.default
- cls Colour.from_hsv
- cls Colour.from_rgb
- cls Colour.from_str
- cls Colour.fuchsia
- cls Colour.gold
- cls Colour.green
- cls Colour.greyple
- cls Colour.light_embed
- cls Colour.light_gray
- cls Colour.light_grey
- cls Colour.lighter_gray
- cls Colour.lighter_grey
- cls Colour.magenta
- cls Colour.og_blurple
- cls Colour.orange
- cls Colour.pink
- cls Colour.purple
- cls Colour.random
- cls Colour.red
- cls Colour.teal
- cls Colour.yellow
- def to_rgb

class discord.Colour(value)

  Represents a Discord role colour. This class is similar to a (red, green, blue) `tuple`.

  There is an alias for this called Color.

  x == y

    Checks if two colours are equal.

  x != y

    Checks if two colours are not equal.

  hash(x)

    Return the colour’s hash.

  str(x)

    Returns the hex format for the colour.

  int(x)

    Returns the raw colour value.

  Note

  The colour values in the classmethods are mostly provided as-is and can change between versions should the Discord client’s representation of that colour also change.

  value

    The raw integer colour value.

    Type:

      `int`

  property r

    Returns the red component of the colour.

    Type:

      `int`

  property g

    Returns the green component of the colour.

    Type:

      `int`

  property b

    Returns the blue component of the colour.

    Type:

      `int`

  to_rgb()

    Tuple[`int`, `int`, `int`]: Returns an (r, g, b) tuple representing the colour.

  classmethod from_rgb(r, g, b)

    Constructs a `Colour` from an RGB tuple.

  classmethod from_hsv(h, s, v)

    Constructs a `Colour` from an HSV tuple.

  classmethod from_str(value)

    Constructs a `Colour` from a string.

    The following formats are accepted:

    - `0x<hex>`

    - `#<hex>`

    - `0x#<hex>`

    - `rgb(<number>, <number>, <number>)`

    Like CSS, `<number>` can be either 0-255 or 0-100% and `<hex>` can be either a 6 digit hex number or a 3 digit hex shortcut (e.g. #FFF).

    Added in version 2.0.

    Raises:

      ValueError – The string could not be converted into a colour.

  classmethod default()

    A factory method that returns a `Colour` with a value of `0`.

  classmethod random(*, seed=None)

    A factory method that returns a `Colour` with a random hue.

    Note

    The random algorithm works by choosing a colour with a random hue but with maxed out saturation and value.

    Added in version 1.6.

    Parameters:

      seed (Optional[Union[`int`, `str`, `float`, `bytes`, `bytearray`]]) –

      The seed to initialize the RNG with. If `None` is passed the default RNG is used.

      Added in version 1.7.

  classmethod teal()

    A factory method that returns a `Colour` with a value of `0x1ABC9C`.

  classmethod dark_teal()

    A factory method that returns a `Colour` with a value of `0x11806A`.

  classmethod brand_green()

    A factory method that returns a `Colour` with a value of `0x57F287`.

    Added in version 2.0.

  classmethod green()

    A factory method that returns a `Colour` with a value of `0x2ECC71`.

  classmethod dark_green()

    A factory method that returns a `Colour` with a value of `0x1F8B4C`.

  classmethod blue()

    A factory method that returns a `Colour` with a value of `0x3498DB`.

  classmethod dark_blue()

    A factory method that returns a `Colour` with a value of `0x206694`.

  classmethod purple()

    A factory method that returns a `Colour` with a value of `0x9B59B6`.

  classmethod dark_purple()

    A factory method that returns a `Colour` with a value of `0x71368A`.

  classmethod magenta()

    A factory method that returns a `Colour` with a value of `0xE91E63`.

  classmethod dark_magenta()

    A factory method that returns a `Colour` with a value of `0xAD1457`.

  classmethod gold()

    A factory method that returns a `Colour` with a value of `0xF1C40F`.

  classmethod dark_gold()

    A factory method that returns a `Colour` with a value of `0xC27C0E`.

  classmethod orange()

    A factory method that returns a `Colour` with a value of `0xE67E22`.

  classmethod dark_orange()

    A factory method that returns a `Colour` with a value of `0xA84300`.

  classmethod brand_red()

    A factory method that returns a `Colour` with a value of `0xED4245`.

    Added in version 2.0.

  classmethod red()

    A factory method that returns a `Colour` with a value of `0xE74C3C`.

  classmethod dark_red()

    A factory method that returns a `Colour` with a value of `0x992D22`.

  classmethod lighter_grey()

    A factory method that returns a `Colour` with a value of `0x95A5A6`.

  classmethod lighter_gray()

    A factory method that returns a `Colour` with a value of `0x95A5A6`.

  classmethod dark_grey()

    A factory method that returns a `Colour` with a value of `0x607d8b`.

  classmethod dark_gray()

    A factory method that returns a `Colour` with a value of `0x607d8b`.

  classmethod light_grey()

    A factory method that returns a `Colour` with a value of `0x979C9F`.

  classmethod light_gray()

    A factory method that returns a `Colour` with a value of `0x979C9F`.

  classmethod darker_grey()

    A factory method that returns a `Colour` with a value of `0x546E7A`.

  classmethod darker_gray()

    A factory method that returns a `Colour` with a value of `0x546E7A`.

  classmethod og_blurple()

    A factory method that returns a `Colour` with a value of `0x7289DA`.

  classmethod blurple()

    A factory method that returns a `Colour` with a value of `0x5865F2`.

  classmethod greyple()

    A factory method that returns a `Colour` with a value of `0x99AAB5`.

  classmethod dark_theme()

    A factory method that returns a `Colour` with a value of `0x313338`.

    This will appear transparent on Discord’s dark theme.

    Added in version 1.5.

    Changed in version 2.2: Updated colour from previous `0x36393F` to reflect discord theme changes.

  classmethod fuchsia()

    A factory method that returns a `Colour` with a value of `0xEB459E`.

    Added in version 2.0.

  classmethod yellow()

    A factory method that returns a `Colour` with a value of `0xFEE75C`.

    Added in version 2.0.

  classmethod dark_embed()

    A factory method that returns a `Colour` with a value of `0x2B2D31`.

    Added in version 2.2.

  classmethod light_embed()

    A factory method that returns a `Colour` with a value of `0xEEEFF1`.

    Added in version 2.2.

  classmethod pink()

    A factory method that returns a `Colour` with a value of `0xEB459F`.

    Added in version 2.3.

### BaseActivity

Attributes

- created_at

class discord.BaseActivity(**kwargs)

  The base activity that all user-settable activities inherit from. A user-settable activity is one that can be used in `Client.change_presence()`.

  The following types currently count as user-settable:

  - `Activity`

  - `Game`

  - `Streaming`

  - `CustomActivity`

  Note that although these types are considered user-settable by the library, Discord typically ignores certain combinations of activity depending on what is currently set. This behaviour may change in the future so there are no guarantees on whether Discord will actually let you set these types.

  Added in version 1.3.

  property created_at

    When the user started doing this activity in UTC.

    Added in version 1.3.

    Type:

      Optional[`datetime.datetime`]

### Activity

Attributes

- application_id
- assets
- buttons
- details
- emoji
- end
- large_image_text
- large_image_url
- name
- party
- platform
- small_image_text
- small_image_url
- start
- state
- timestamps
- type
- url

class discord.Activity(**kwargs)

  Represents an activity in Discord.

  This could be an activity such as streaming, playing, listening or watching.

  For memory optimisation purposes, some activities are offered in slimmed down versions:

  - `Game`

  - `Streaming`

  application_id

    The application ID of the game.

    Type:

      Optional[`int`]

  name

    The name of the activity.

    Type:

      Optional[`str`]

  url

    A stream URL that the activity could be doing.

    Type:

      Optional[`str`]

  type

    The type of activity currently being done.

    Type:

      `ActivityType`

  state

    The user’s current state. For example, “In Game”.

    Type:

      Optional[`str`]

  details

    The detail of the user’s current activity.

    Type:

      Optional[`str`]

  platform

    The user’s current platform.

    Added in version 2.4.

    Type:

      Optional[`str`]

  timestamps

    A dictionary of timestamps. It contains the following optional keys:

    - `start`: Corresponds to when the user started doing the activity in milliseconds since Unix epoch.

    - `end`: Corresponds to when the user will finish doing the activity in milliseconds since Unix epoch.

    Type:

      `dict`

  assets

    A dictionary representing the images and their hover text of an activity. It contains the following optional keys:

    - `large_image`: A string representing the ID for the large image asset.

    - `large_text`: A string representing the text when hovering over the large image asset.

    - `small_image`: A string representing the ID for the small image asset.

    - `small_text`: A string representing the text when hovering over the small image asset.

    Type:

      `dict`

  party

    A dictionary representing the activity party. It contains the following optional keys:

    - `id`: A string representing the party ID.

    - `size`: A list of up to two integer elements denoting (current_size, maximum_size).

    Type:

      `dict`

  buttons

    A list of strings representing the labels of custom buttons shown in a rich presence.

    Added in version 2.0.

    Type:

      List[`str`]

  emoji

    The emoji that belongs to this activity.

    Type:

      Optional[`PartialEmoji`]

  property start

    When the user started doing this activity in UTC, if applicable.

    Type:

      Optional[`datetime.datetime`]

  property end

    When the user will stop doing this activity in UTC, if applicable.

    Type:

      Optional[`datetime.datetime`]

  property large_image_url

    Returns a URL pointing to the large image asset of this activity, if applicable.

    Type:

      Optional[`str`]

  property small_image_url

    Returns a URL pointing to the small image asset of this activity, if applicable.

    Type:

      Optional[`str`]

  property large_image_text

    Returns the large image asset hover text of this activity, if applicable.

    Type:

      Optional[`str`]

  property small_image_text

    Returns the small image asset hover text of this activity, if applicable.

    Type:

      Optional[`str`]

### Game

Attributes

- assets
- end
- name
- platform
- start
- type

class discord.Game(name, **extra)

  A slimmed down version of `Activity` that represents a Discord game.

  This is typically displayed via Playing on the official Discord client.

  x == y

    Checks if two games are equal.

  x != y

    Checks if two games are not equal.

  hash(x)

    Returns the game’s hash.

  str(x)

    Returns the game’s name.

  Parameters:

    name (`str`) – The game’s name.

  name

    The game’s name.

    Type:

      `str`

  platform

    Where the user is playing from (ie. PS5, Xbox).

    Added in version 2.4.

    Type:

      Optional[`str`]

  assets

    A dictionary representing the images and their hover text of a game. It contains the following optional keys:

    - `large_image`: A string representing the ID for the large image asset.

    - `large_text`: A string representing the text when hovering over the large image asset.

    - `small_image`: A string representing the ID for the small image asset.

    - `small_text`: A string representing the text when hovering over the small image asset.

    Added in version 2.4.

    Type:

      `dict`

  property type

    Returns the game’s type. This is for compatibility with `Activity`.

    It always returns `ActivityType.playing`.

    Type:

      `ActivityType`

  property start

    When the user started playing this game in UTC, if applicable.

    Type:

      Optional[`datetime.datetime`]

  property end

    When the user will stop playing this game in UTC, if applicable.

    Type:

      Optional[`datetime.datetime`]

### Streaming

Attributes

- assets
- details
- game
- name
- platform
- twitch_name
- type
- url

class discord.Streaming(*, name, url, **extra)

  A slimmed down version of `Activity` that represents a Discord streaming status.

  This is typically displayed via Streaming on the official Discord client.

  x == y

    Checks if two streams are equal.

  x != y

    Checks if two streams are not equal.

  hash(x)

    Returns the stream’s hash.

  str(x)

    Returns the stream’s name.

  platform

    Where the user is streaming from (ie. YouTube, Twitch).

    Added in version 1.3.

    Type:

      Optional[`str`]

  name

    The stream’s name.

    Type:

      Optional[`str`]

  details

    An alias for `name`

    Type:

      Optional[`str`]

  game

    The game being streamed.

    Added in version 1.3.

    Type:

      Optional[`str`]

  url

    The stream’s URL.

    Type:

      `str`

  assets

    A dictionary comprising of similar keys than those in `Activity.assets`.

    Type:

      `dict`

  property type

    Returns the game’s type. This is for compatibility with `Activity`.

    It always returns `ActivityType.streaming`.

    Type:

      `ActivityType`

  property twitch_name

    If provided, the twitch name of the user streaming.

    This corresponds to the `large_image` key of the `Streaming.assets` dictionary if it starts with `twitch:`. Typically set by the Discord client.

    Type:

      Optional[`str`]

### CustomActivity

Attributes

- emoji
- name
- type

class discord.CustomActivity(name, *, emoji=None, **extra)

  Represents a custom activity from Discord.

  x == y

    Checks if two activities are equal.

  x != y

    Checks if two activities are not equal.

  hash(x)

    Returns the activity’s hash.

  str(x)

    Returns the custom status text.

  Added in version 1.3.

  name

    The custom activity’s name.

    Type:

      Optional[`str`]

  emoji

    The emoji to pass to the activity, if any.

    Type:

      Optional[`PartialEmoji`]

  property type

    Returns the activity’s type. This is for compatibility with `Activity`.

    It always returns `ActivityType.custom`.

    Type:

      `ActivityType`

### Permissions

Attributes

- add_reactions
- administrator
- attach_files
- ban_members
- change_nickname
- connect
- create_events
- create_expressions
- create_instant_invite
- create_polls
- create_private_threads
- create_public_threads
- deafen_members
- embed_links
- external_emojis
- external_stickers
- kick_members
- manage_channels
- manage_emojis
- manage_emojis_and_stickers
- manage_events
- manage_expressions
- manage_guild
- manage_messages
- manage_nicknames
- manage_permissions
- manage_roles
- manage_threads
- manage_webhooks
- mention_everyone
- moderate_members
- move_members
- mute_members
- priority_speaker
- read_message_history
- read_messages
- request_to_speak
- send_messages
- send_messages_in_threads
- send_polls
- send_tts_messages
- send_voice_messages
- speak
- stream
- use_application_commands
- use_embedded_activities
- use_external_apps
- use_external_emojis
- use_external_sounds
- use_external_stickers
- use_soundboard
- use_voice_activation
- value
- view_audit_log
- view_channel
- view_creator_monetization_analytics
- view_guild_insights

Methods

- cls Permissions.advanced
- cls Permissions.all
- cls Permissions.all_channel
- cls Permissions.elevated
- cls Permissions.events
- cls Permissions.general
- cls Permissions.membership
- cls Permissions.none
- cls Permissions.stage
- cls Permissions.stage_moderator
- cls Permissions.text
- cls Permissions.voice
- def is_strict_subset
- def is_strict_superset
- def is_subset
- def is_superset
- def update

class discord.Permissions(permissions=0, **kwargs)

  Wraps up the Discord permission value.

  The properties provided are two way. You can set and retrieve individual bits using the properties as if they were regular bools. This allows you to edit permissions.

  Changed in version 1.3: You can now use keyword arguments to initialize `Permissions` similar to `update()`.

  x == y

    Checks if two permissions are equal.

  x != y

    Checks if two permissions are not equal.

  x <= y

    Checks if a permission is a subset of another permission.

  x >= y

    Checks if a permission is a superset of another permission.

  x < y

    Checks if a permission is a strict subset of another permission.

  x > y

    Checks if a permission is a strict superset of another permission.

  x | y, x |= y

    Returns a Permissions instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a Permissions instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a Permissions instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a Permissions instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the permission’s hash.

  iter(x)

    Returns an iterator of `(perm, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether the permissions object has any permissions set to `True`.

    Added in version 2.0.

  value

    The raw value. This value is a bit array field of a 53-bit integer representing the currently available permissions. You should query permissions via the properties rather than using this raw value.

    Type:

      `int`

  is_subset(other)

    Returns `True` if self has the same or fewer permissions as other.

  is_superset(other)

    Returns `True` if self has the same or more permissions as other.

  is_strict_subset(other)

    Returns `True` if the permissions on other are a strict subset of those on self.

  is_strict_superset(other)

    Returns `True` if the permissions on other are a strict superset of those on self.

  classmethod none()

    A factory method that creates a `Permissions` with all permissions set to `False`.

  classmethod all()

    A factory method that creates a `Permissions` with all permissions set to `True`.

  classmethod all_channel()

    A `Permissions` with all channel-specific permissions set to `True` and the guild-specific ones set to `False`. The guild-specific permissions are currently:

    - `manage_expressions`

    - `view_audit_log`

    - `view_guild_insights`

    - `manage_guild`

    - `change_nickname`

    - `manage_nicknames`

    - `kick_members`

    - `ban_members`

    - `administrator`

    - `create_expressions`

    - `moderate_members`

    - `create_events`

    - `manage_events`

    - `view_creator_monetization_analytics`

    Changed in version 1.7: Added `stream`, `priority_speaker` and `use_application_commands` permissions.

    Changed in version 2.0: Added `create_public_threads`, `create_private_threads`, `manage_threads`, `use_external_stickers`, `send_messages_in_threads` and `request_to_speak` permissions.

    Changed in version 2.3: Added `use_soundboard`, `create_expressions` permissions.

    Changed in version 2.4: Added `send_polls`, `send_voice_messages`, attr:use_external_sounds, `use_embedded_activities`, and `use_external_apps` permissions.

  classmethod general()

    A factory method that creates a `Permissions` with all “General” permissions from the official Discord UI set to `True`.

    Changed in version 1.7: Permission `read_messages` is now included in the general permissions, but permissions `administrator`, `create_instant_invite`, `kick_members`, `ban_members`, `change_nickname` and `manage_nicknames` are no longer part of the general permissions.

    Changed in version 2.3: Added `create_expressions` permission.

    Changed in version 2.4: Added `view_creator_monetization_analytics` permission.

  classmethod membership()

    A factory method that creates a `Permissions` with all “Membership” permissions from the official Discord UI set to `True`.

    Added in version 1.7.

  classmethod text()

    A factory method that creates a `Permissions` with all “Text” permissions from the official Discord UI set to `True`.

    Changed in version 1.7: Permission `read_messages` is no longer part of the text permissions. Added `use_application_commands` permission.

    Changed in version 2.0: Added `create_public_threads`, `create_private_threads`, `manage_threads`, `send_messages_in_threads` and `use_external_stickers` permissions.

    Changed in version 2.3: Added `send_voice_messages` permission.

    Changed in version 2.4: Added `send_polls` and `use_external_apps` permissions.

  classmethod voice()

    A factory method that creates a `Permissions` with all “Voice” permissions from the official Discord UI set to `True`.

  classmethod stage()

    A factory method that creates a `Permissions` with all “Stage Channel” permissions from the official Discord UI set to `True`.

    Added in version 1.7.

  classmethod stage_moderator()

    A factory method that creates a `Permissions` with all permissions for stage moderators set to `True`. These permissions are currently:

    - `manage_channels`

    - `mute_members`

    - `move_members`

    Added in version 1.7.

    Changed in version 2.0: Added `manage_channels` permission and removed `request_to_speak` permission.

  classmethod elevated()

    A factory method that creates a `Permissions` with all permissions that require 2FA set to `True`. These permissions are currently:

    - `kick_members`

    - `ban_members`

    - `administrator`

    - `manage_channels`

    - `manage_guild`

    - `manage_messages`

    - `manage_roles`

    - `manage_webhooks`

    - `manage_expressions`

    - `manage_threads`

    - `moderate_members`

    Added in version 2.0.

  classmethod events()

    A factory method that creates a `Permissions` with all “Events” permissions from the official Discord UI set to `True`.

    Added in version 2.4.

  classmethod advanced()

    A factory method that creates a `Permissions` with all “Advanced” permissions from the official Discord UI set to `True`.

    Added in version 1.7.

  update(**kwargs)

    Bulk updates this permission object.

    Allows you to set multiple attributes by using keyword arguments. The names must be equivalent to the properties listed. Extraneous key/value pairs will be silently ignored.

    Parameters:

      **kwargs – A list of key/value pairs to bulk update permissions with.

  create_instant_invite

    Returns `True` if the user can create instant invites.

    Type:

      `bool`

  kick_members

    Returns `True` if the user can kick users from the guild.

    Type:

      `bool`

  ban_members

    Returns `True` if a user can ban users from the guild.

    Type:

      `bool`

  administrator

    Returns `True` if a user is an administrator. This role overrides all other permissions.

    This also bypasses all channel-specific overrides.

    Type:

      `bool`

  manage_channels

    Returns `True` if a user can edit, delete, or create channels in the guild.

    This also corresponds to the “Manage Channel” channel-specific override.

    Type:

      `bool`

  manage_guild

    Returns `True` if a user can edit guild properties.

    Type:

      `bool`

  add_reactions

    Returns `True` if a user can add reactions to messages.

    Type:

      `bool`

  view_audit_log

    Returns `True` if a user can view the guild’s audit log.

    Type:

      `bool`

  priority_speaker

    Returns `True` if a user can be more easily heard while talking.

    Type:

      `bool`

  stream

    Returns `True` if a user can stream in a voice channel.

    Type:

      `bool`

  read_messages

    Returns `True` if a user can read messages from all or specific text channels.

    Type:

      `bool`

  view_channel

    An alias for `read_messages`.

    Added in version 1.3.

    Type:

      `bool`

  send_messages

    Returns `True` if a user can send messages from all or specific text channels.

    Type:

      `bool`

  send_tts_messages

    Returns `True` if a user can send TTS messages from all or specific text channels.

    Type:

      `bool`

  manage_messages

    Returns `True` if a user can delete or pin messages in a text channel.

    Note

    Note that there are currently no ways to edit other people’s messages.

    Type:

      `bool`

  embed_links

    Returns `True` if a user’s messages will automatically be embedded by Discord.

    Type:

      `bool`

  attach_files

    Returns `True` if a user can send files in their messages.

    Type:

      `bool`

  read_message_history

    Returns `True` if a user can read a text channel’s previous messages.

    Type:

      `bool`

  mention_everyone

    Returns `True` if a user’s @everyone or @here will mention everyone in the text channel.

    Type:

      `bool`

  external_emojis

    Returns `True` if a user can use emojis from other guilds.

    Type:

      `bool`

  use_external_emojis

    An alias for `external_emojis`.

    Added in version 1.3.

    Type:

      `bool`

  view_guild_insights

    Returns `True` if a user can view the guild’s insights.

    Added in version 1.3.

    Type:

      `bool`

  connect

    Returns `True` if a user can connect to a voice channel.

    Type:

      `bool`

  speak

    Returns `True` if a user can speak in a voice channel.

    Type:

      `bool`

  mute_members

    Returns `True` if a user can mute other users.

    Type:

      `bool`

  deafen_members

    Returns `True` if a user can deafen other users.

    Type:

      `bool`

  move_members

    Returns `True` if a user can move users between other voice channels.

    Type:

      `bool`

  use_voice_activation

    Returns `True` if a user can use voice activation in voice channels.

    Type:

      `bool`

  change_nickname

    Returns `True` if a user can change their nickname in the guild.

    Type:

      `bool`

  manage_nicknames

    Returns `True` if a user can change other user’s nickname in the guild.

    Type:

      `bool`

  manage_roles

    Returns `True` if a user can create or edit roles less than their role’s position.

    This also corresponds to the “Manage Permissions” channel-specific override.

    Type:

      `bool`

  manage_permissions

    An alias for `manage_roles`.

    Added in version 1.3.

    Type:

      `bool`

  manage_webhooks

    Returns `True` if a user can create, edit, or delete webhooks.

    Type:

      `bool`

  manage_expressions

    Returns `True` if a user can edit or delete emojis, stickers, and soundboard sounds.

    Added in version 2.3.

    Type:

      `bool`

  manage_emojis

    An alias for `manage_expressions`.

    Type:

      `bool`

  manage_emojis_and_stickers

    An alias for `manage_expressions`.

    Added in version 2.0.

    Type:

      `bool`

  use_application_commands

    Returns `True` if a user can use slash commands.

    Added in version 1.7.

    Type:

      `bool`

  request_to_speak

    Returns `True` if a user can request to speak in a stage channel.

    Added in version 1.7.

    Type:

      `bool`

  manage_events

    Returns `True` if a user can manage guild events.

    Added in version 2.0.

    Type:

      `bool`

  manage_threads

    Returns `True` if a user can manage threads.

    Added in version 2.0.

    Type:

      `bool`

  create_public_threads

    Returns `True` if a user can create public threads.

    Added in version 2.0.

    Type:

      `bool`

  create_private_threads

    Returns `True` if a user can create private threads.

    Added in version 2.0.

    Type:

      `bool`

  external_stickers

    Returns `True` if a user can use stickers from other guilds.

    Added in version 2.0.

    Type:

      `bool`

  use_external_stickers

    An alias for `external_stickers`.

    Added in version 2.0.

    Type:

      `bool`

  send_messages_in_threads

    Returns `True` if a user can send messages in threads.

    Added in version 2.0.

    Type:

      `bool`

  use_embedded_activities

    Returns `True` if a user can launch an embedded application in a Voice channel.

    Added in version 2.0.

    Type:

      `bool`

  moderate_members

    Returns `True` if a user can time out other members.

    Added in version 2.0.

    Type:

      `bool`

  view_creator_monetization_analytics

    Returns `True` if a user can view role subscription insights.

    Added in version 2.4.

    Type:

      `bool`

  use_soundboard

    Returns `True` if a user can use the soundboard.

    Added in version 2.3.

    Type:

      `bool`

  create_expressions

    Returns `True` if a user can create emojis, stickers, and soundboard sounds.

    Added in version 2.3.

    Type:

      `bool`

  create_events

    Returns `True` if a user can create guild events.

    Added in version 2.4.

    Type:

      `bool`

  use_external_sounds

    Returns `True` if a user can use sounds from other guilds.

    Added in version 2.3.

    Type:

      `bool`

  send_voice_messages

    Returns `True` if a user can send voice messages.

    Added in version 2.3.

    Type:

      `bool`

  send_polls

    Returns `True` if a user can send poll messages.

    Added in version 2.4.

    Type:

      `bool`

  create_polls

    An alias for `send_polls`.

    Added in version 2.4.

    Type:

      `bool`

  use_external_apps

    Returns `True` if a user can use external apps.

    Added in version 2.4.

    Type:

      `bool`

### PermissionOverwrite

Methods

- cls PermissionOverwrite.from_pair
- def is_empty
- def pair
- def update

class discord.PermissionOverwrite(**kwargs)

  A type that is used to represent a channel specific permission.

  Unlike a regular `Permissions`, the default value of a permission is equivalent to `None` and not `False`. Setting a value to `False` is explicitly denying that permission, while setting a value to `True` is explicitly allowing that permission.

  The values supported by this are the same as `Permissions` with the added possibility of it being set to `None`.

  x == y

    Checks if two overwrites are equal.

  x != y

    Checks if two overwrites are not equal.

  iter(x)

    Returns an iterator of `(perm, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  Parameters:

    **kwargs – Set the value of permissions by their name.

  pair()

    Tuple[`Permissions`, `Permissions`]: Returns the (allow, deny) pair from this overwrite.

  classmethod from_pair(allow, deny)

    Creates an overwrite from an allow/deny pair of `Permissions`.

  is_empty()

    Checks if the permission overwrite is currently empty.

    An empty permission overwrite is one that has no overwrites set to `True` or `False`.

    Returns:

      Indicates if the overwrite is empty.

    Return type:

      `bool`

  update(**kwargs)

    Bulk updates this permission overwrite object.

    Allows you to set multiple attributes by using keyword arguments. The names must be equivalent to the properties listed. Extraneous key/value pairs will be silently ignored.

    Parameters:

      **kwargs – A list of key/value pairs to bulk update with.

### SystemChannelFlags

Attributes

- guild_reminder_notifications
- join_notification_replies
- join_notifications
- premium_subscriptions
- role_subscription_purchase_notification_replies
- role_subscription_purchase_notifications
- value

class discord.SystemChannelFlags(**kwargs)

  Wraps up a Discord system channel flag value.

  Similar to `Permissions`, the properties provided are two way. You can set and retrieve individual bits using the properties as if they were regular bools. This allows you to edit the system flags easily.

  To construct an object you can pass keyword arguments denoting the flags to enable or disable.

  x == y

    Checks if two flags are equal.

  x != y

    Checks if two flags are not equal.

  x | y, x |= y

    Returns a SystemChannelFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a SystemChannelFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a SystemChannelFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a SystemChannelFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

  bool(b)

    Returns whether any flag is set to `True`.

    Added in version 2.0.

  value

    The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  join_notifications

    Returns `True` if the system channel is used for member join notifications.

    Type:

      `bool`

  premium_subscriptions

    Returns `True` if the system channel is used for “Nitro boosting” notifications.

    Type:

      `bool`

  guild_reminder_notifications

    Returns `True` if the system channel is used for server setup helpful tips notifications.

    Added in version 2.0.

    Type:

      `bool`

  join_notification_replies

    Returns `True` if sticker reply button (“Wave to say hi!”) is shown for member join notifications.

    Added in version 2.0.

    Type:

      `bool`

  role_subscription_purchase_notifications

    Returns `True` if role subscription purchase and renewal notifications are enabled.

    Added in version 2.2.

    Type:

      `bool`

  role_subscription_purchase_notification_replies

    Returns `True` if the role subscription notifications have a sticker reply button.

    Added in version 2.2.

    Type:

      `bool`

### MessageFlags

Attributes

- crossposted
- ephemeral
- failed_to_mention_some_roles_in_thread
- forwarded
- has_thread
- is_crossposted
- loading
- silent
- source_message_deleted
- suppress_embeds
- suppress_notifications
- urgent
- value
- voice

class discord.MessageFlags(**kwargs)

  Wraps up a Discord Message flag value.

  See `SystemChannelFlags`.

  x == y

    Checks if two flags are equal.

  x != y

    Checks if two flags are not equal.

  x | y, x |= y

    Returns a MessageFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a MessageFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a MessageFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a MessageFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

  bool(b)

    Returns whether any flag is set to `True`.

    Added in version 2.0.

  Added in version 1.3.

  value

    The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  crossposted

    Returns `True` if the message is the original crossposted message.

    Type:

      `bool`

  is_crossposted

    Returns `True` if the message was crossposted from another channel.

    Type:

      `bool`

  suppress_embeds

    Returns `True` if the message’s embeds have been suppressed.

    Type:

      `bool`

  source_message_deleted

    Returns `True` if the source message for this crosspost has been deleted.

    Type:

      `bool`

  urgent

    Returns `True` if the source message is an urgent message.

    An urgent message is one sent by Discord Trust and Safety.

    Type:

      `bool`

  has_thread

    Returns `True` if the source message is associated with a thread.

    Added in version 2.0.

    Type:

      `bool`

  ephemeral

    Returns `True` if the source message is ephemeral.

    Added in version 2.0.

    Type:

      `bool`

  loading

    Returns `True` if the message is an interaction response and the bot is “thinking”.

    Added in version 2.0.

    Type:

      `bool`

  failed_to_mention_some_roles_in_thread

    Returns `True` if the message failed to mention some roles in a thread and add their members to the thread.

    Added in version 2.0.

    Type:

      `bool`

  suppress_notifications

    Returns `True` if the message will not trigger push and desktop notifications.

    Added in version 2.2.

    Type:

      `bool`

  silent

    Alias for `suppress_notifications`.

    Added in version 2.2.

    Type:

      `bool`

  voice

    Returns `True` if the message is a voice message.

    Added in version 2.3.

    Type:

      `bool`

  forwarded

    Returns `True` if the message is a forwarded message.

    Added in version 2.5.

    Type:

      `bool`

### PublicUserFlags

Attributes

- active_developer
- bot_http_interactions
- bug_hunter
- bug_hunter_level_2
- discord_certified_moderator
- early_supporter
- early_verified_bot_developer
- hypesquad
- hypesquad_balance
- hypesquad_bravery
- hypesquad_brilliance
- partner
- spammer
- staff
- system
- team_user
- value
- verified_bot
- verified_bot_developer

Methods

- def all

class discord.PublicUserFlags(**kwargs)

  Wraps up the Discord User Public flags.

  x == y

    Checks if two PublicUserFlags are equal.

  x != y

    Checks if two PublicUserFlags are not equal.

  x | y, x |= y

    Returns a PublicUserFlags instance with all enabled flags from both x and y.

    Added in version 2.0.

  x & y, x &= y

    Returns a PublicUserFlags instance with only flags enabled on both x and y.

    Added in version 2.0.

  x ^ y, x ^= y

    Returns a PublicUserFlags instance with only flags enabled on only one of x or y, not on both.

    Added in version 2.0.

  ~x

    Returns a PublicUserFlags instance with all flags inverted from x.

    Added in version 2.0.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

    Added in version 2.0.

  Added in version 1.4.

  value

    The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  staff

    Returns `True` if the user is a Discord Employee.

    Type:

      `bool`

  partner

    Returns `True` if the user is a Discord Partner.

    Type:

      `bool`

  hypesquad

    Returns `True` if the user is a HypeSquad Events member.

    Type:

      `bool`

  bug_hunter

    Returns `True` if the user is a Bug Hunter

    Type:

      `bool`

  hypesquad_bravery

    Returns `True` if the user is a HypeSquad Bravery member.

    Type:

      `bool`

  hypesquad_brilliance

    Returns `True` if the user is a HypeSquad Brilliance member.

    Type:

      `bool`

  hypesquad_balance

    Returns `True` if the user is a HypeSquad Balance member.

    Type:

      `bool`

  early_supporter

    Returns `True` if the user is an Early Supporter.

    Type:

      `bool`

  team_user

    Returns `True` if the user is a Team User.

    Type:

      `bool`

  system

    Returns `True` if the user is a system user (i.e. represents Discord officially).

    Type:

      `bool`

  bug_hunter_level_2

    Returns `True` if the user is a Bug Hunter Level 2

    Type:

      `bool`

  verified_bot

    Returns `True` if the user is a Verified Bot.

    Type:

      `bool`

  verified_bot_developer

    Returns `True` if the user is an Early Verified Bot Developer.

    Type:

      `bool`

  early_verified_bot_developer

    An alias for `verified_bot_developer`.

    Added in version 1.5.

    Type:

      `bool`

  discord_certified_moderator

    Returns `True` if the user is a Discord Certified Moderator.

    Added in version 2.0.

    Type:

      `bool`

  bot_http_interactions

    Returns `True` if the user is a bot that only uses HTTP interactions and is shown in the online member list.

    Added in version 2.0.

    Type:

      `bool`

  spammer

    Returns `True` if the user is flagged as a spammer by Discord.

    Added in version 2.0.

    Type:

      `bool`

  active_developer

    Returns `True` if the user is an active developer.

    Added in version 2.1.

    Type:

      `bool`

  all()

    List[`UserFlags`]: Returns all public flags the user has.

### MemberFlags

Attributes

- automod_quarantined_username
- bypasses_verification
- completed_home_actions
- completed_onboarding
- did_rejoin
- dm_settings_upsell_acknowledged
- guest
- started_home_actions
- started_onboarding
- value

class discord.MemberFlags(**kwargs)

  Wraps up the Discord Guild Member flags

  Added in version 2.2.

  x == y

    Checks if two MemberFlags are equal.

  x != y

    Checks if two MemberFlags are not equal.

  x | y, x |= y

    Returns a MemberFlags instance with all enabled flags from both x and y.

  x & y, x &= y

    Returns a MemberFlags instance with only flags enabled on both x and y.

  x ^ y, x ^= y

    Returns a MemberFlags instance with only flags enabled on only one of x or y, not on both.

  ~x

    Returns a MemberFlags instance with all flags inverted from x.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  did_rejoin

    Returns `True` if the member left and rejoined the `guild`.

    Type:

      `bool`

  completed_onboarding

    Returns `True` if the member has completed onboarding.

    Type:

      `bool`

  bypasses_verification

    Returns `True` if the member can bypass the guild verification requirements.

    Type:

      `bool`

  started_onboarding

    Returns `True` if the member has started onboarding.

    Type:

      `bool`

  guest

    Returns `True` if the member is a guest and can only access the voice channel they were invited to.

    Added in version 2.5.

    Type:

      `bool`

  started_home_actions

    Returns `True` if the member has started Server Guide new member actions.

    Added in version 2.5.

    Type:

      `bool`

  completed_home_actions

    Returns `True` if the member has completed Server Guide new member actions.

    Added in version 2.5.

    Type:

      `bool`

  automod_quarantined_username

    Returns `True` if the member’s username, nickname, or global name has been blocked by AutoMod.

    Added in version 2.5.

    Type:

      `bool`

  dm_settings_upsell_acknowledged

    Returns `True` if the member has dismissed the DM settings upsell.

    Added in version 2.5.

    Type:

      `bool`

### AttachmentFlags

Attributes

- animated
- clip
- contains_explicit_media
- remix
- spoiler
- thumbnail
- value

class discord.AttachmentFlags(**kwargs)

  Wraps up the Discord Attachment flags

  Added in version 2.4.

  x == y

    Checks if two AttachmentFlags are equal.

  x != y

    Checks if two AttachmentFlags are not equal.

  x | y, x |= y

    Returns a AttachmentFlags instance with all enabled flags from both x and y.

  x & y, x &= y

    Returns a AttachmentFlags instance with only flags enabled on both x and y.

  x ^ y, x ^= y

    Returns a AttachmentFlags instance with only flags enabled on only one of x or y, not on both.

  ~x

    Returns a AttachmentFlags instance with all flags inverted from x.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  clip

    Returns `True` if the attachment is a clip.

    Type:

      `bool`

  thumbnail

    Returns `True` if the attachment is a thumbnail.

    Type:

      `bool`

  remix

    Returns `True` if the attachment has been edited using the remix feature.

    Type:

      `bool`

  spoiler

    Returns `True` if the attachment was marked as a spoiler.

    Added in version 2.5.

    Type:

      `bool`

  contains_explicit_media

    Returns `True` if the attachment was flagged as sensitive content.

    Added in version 2.5.

    Type:

      `bool`

  animated

    Returns `True` if the attachment is an animated image.

    Added in version 2.5.

    Type:

      `bool`

### RoleFlags

Attributes

- in_prompt
- value

class discord.RoleFlags(**kwargs)

  Wraps up the Discord Role flags

  Added in version 2.4.

  x == y

    Checks if two RoleFlags are equal.

  x != y

    Checks if two RoleFlags are not equal.

  x | y, x |= y

    Returns a RoleFlags instance with all enabled flags from both x and y.

  x & y, x &= y

    Returns a RoleFlags instance with only flags enabled on both x and y.

  x ^ y, x ^= y

    Returns a RoleFlags instance with only flags enabled on only one of x or y, not on both.

  ~x

    Returns a RoleFlags instance with all flags inverted from x.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  in_prompt

    Returns `True` if the role can be selected by members in an onboarding prompt.

    Type:

      `bool`

### SKUFlags

Attributes

- available
- guild_subscription
- user_subscription
- value

class discord.SKUFlags

  Wraps up the Discord SKU flags

  Added in version 2.4.

  x == y

    Checks if two SKUFlags are equal.

  x != y

    Checks if two SKUFlags are not equal.

  x | y, x |= y

    Returns a SKUFlags instance with all enabled flags from both x and y.

  x & y, x &= y

    Returns a SKUFlags instance with only flags enabled on both x and y.

  x ^ y, x ^= y

    Returns a SKUFlags instance with only flags enabled on only one of x or y, not on both.

  ~x

    Returns a SKUFlags instance with all flags inverted from x.

  hash(x)

    Return the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  available

    Returns `True` if the SKU is available for purchase.

    Type:

      `bool`

  guild_subscription

    Returns `True` if the SKU is a guild subscription.

    Type:

      `bool`

  user_subscription

    Returns `True` if the SKU is a user subscription.

    Type:

      `bool`

### EmbedFlags

Attributes

- contains_explicit_media
- content_inventory_entry
- value

class discord.EmbedFlags

  Wraps up the Discord Embed flags

  Added in version 2.5.

  x == y

    Checks if two EmbedFlags are equal.

  x != y

    Checks if two EmbedFlags are not equal.

  x | y, x |= y

    Returns an EmbedFlags instance with all enabled flags from both x and y.

  x ^ y, x ^= y

    Returns an EmbedFlags instance with only flags enabled on only one of x or y, not on both.

  ~x

    Returns an EmbedFlags instance with all flags inverted from x.

  hash(x)

    Returns the flag’s hash.

  iter(x)

    Returns an iterator of `(name, value)` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

  bool(b)

    Returns whether any flag is set to `True`.

  value

    The raw value. You should query flags via the properties rather than using this raw value.

    Type:

      `int`

  contains_explicit_media

    Returns `True` if the embed was flagged as sensitive content.

    Type:

      `bool`

  content_inventory_entry

    Returns `True` if the embed is a reply to an activity card, and is no longer displayed.

    Type:

      `bool`

### ForumTag

Attributes

- emoji
- id
- moderated
- name

class discord.ForumTag(*, name, emoji=None, moderated=False)

  Represents a forum tag that can be applied to a thread within a `ForumChannel`.

  Added in version 2.1.

  x == y

    Checks if two forum tags are equal.

  x != y

    Checks if two forum tags are not equal.

  hash(x)

    Returns the forum tag’s hash.

  str(x)

    Returns the forum tag’s name.

  id

    The ID of the tag. If this was manually created then the ID will be `0`.

    Type:

      `int`

  name

    The name of the tag. Can only be up to 20 characters.

    Type:

      `str`

  moderated

    Whether this tag can only be added or removed by a moderator with the `manage_threads` permission.

    Type:

      `bool`

  emoji

    The emoji that is used to represent this tag. Note that if the emoji is a custom emoji, it will not have name information.

    Type:

      Optional[`PartialEmoji`]

### Poll

Attributes

- answers
- created_at
- duration
- expires_at
- layout_type
- message
- multiple
- question
- total_votes
- victor_answer
- victor_answer_id

Methods

- def add_answer
- def copy
- async end
- def get_answer
- def is_finalised
- def is_finalized

class discord.Poll(question, duration, *, multiple=False, layout_type=('default', 1))

  Represents a message’s Poll.

  Added in version 2.4.

  Parameters:

    - question (Union[`PollMedia`, `str`]) – The poll’s displayed question. The text can be up to 300 characters.

    - duration (`datetime.timedelta`) – The duration of the poll. Duration must be in hours.

    - multiple (`bool`) – Whether users are allowed to select more than one answer. Defaults to `False`.

    - layout_type (`PollLayoutType`) – The layout type of the poll. Defaults to `PollLayoutType.default`.

  duration

    The duration of the poll.

    Type:

      `datetime.timedelta`

  multiple

    Whether users are allowed to select more than one answer.

    Type:

      `bool`

  layout_type

    The layout type of the poll.

    Type:

      `PollLayoutType`

  property question

    Returns this poll’s question string.

    Type:

      `str`

  property answers

    Returns a read-only copy of the answers.

    Type:

      List[`PollAnswer`]

  property victor_answer_id

    The victor answer ID.

    Added in version 2.5.

    Note

    This will always be `None` for polls that have not yet finished.

    Type:

      Optional[`int`]

  property victor_answer

    The victor answer.

    Added in version 2.5.

    Note

    This will always be `None` for polls that have not yet finished.

    Type:

      Optional[`PollAnswer`]

  property expires_at

    A datetime object representing the poll expiry.

    Note

    This will always be `None` for stateless polls.

    Type:

      Optional[`datetime.datetime`]

  property created_at

    Returns the poll’s creation time.

    Note

    This will always be `None` for stateless polls.

    Type:

      Optional[`datetime.datetime`]

  property message

    The message this poll is from.

    Type:

      Optional[`Message`]

  property total_votes

    Returns the sum of all the answer votes.

    If the poll has not yet finished, this is an approximate vote count.

    Changed in version 2.5: This now returns an exact vote count when updated from its poll results message.

    Type:

      `int`

  is_finalised()

    `bool`: Returns whether the poll has finalised.

    This always returns `False` for stateless polls.

  is_finalized()

    `bool`: Returns whether the poll has finalised.

    This always returns `False` for stateless polls.

  copy()

    Returns a stateless copy of this poll.

    This is meant to be used when you want to edit a stateful poll.

    Returns:

      The copy of the poll.

    Return type:

      `Poll`

  add_answer(*, text, emoji=None)

    Appends a new answer to this poll.

    Parameters:

      - text (`str`) – The text label for this poll answer. Can be up to 55 characters.

      - emoji (Union[`PartialEmoji`, `Emoji`, `str`]) – The emoji to display along the text.

    Raises:

      ClientException – Cannot append answers to a poll that is active.

    Returns:

      This poll with the new answer appended. This allows fluent-style chaining.

    Return type:

      `Poll`

  get_answer(id)

    Returns the answer with the provided ID or `None` if not found.

    Parameters:

      id (`int`) – The ID of the answer to get.

    Returns:

      The answer.

    Return type:

      Optional[`PollAnswer`]

  await end()

    This function is a coroutine.

    Ends the poll.

    Raises:

      - ClientException – This poll has no attached message.

      - HTTPException – Ending the poll failed.

    Returns:

      The updated poll.

    Return type:

      `Poll`

### PollMedia

Attributes

- emoji
- text

class discord.PollMedia(text, emoji=None)

  Represents the poll media for a poll item.

  Added in version 2.4.

  text

    The displayed text.

    Type:

      `str`

  emoji

    The attached emoji for this media. This is only valid for poll answers.

    Type:

      Optional[Union[`PartialEmoji`, `Emoji`]]

### CallMessage

Attributes

- duration
- ended_timestamp
- participants

Methods

- def is_ended

class discord.CallMessage

  Represents a message’s call data in a private channel from a `Message`.

  Added in version 2.5.

  ended_timestamp

    The timestamp the call has ended.

    Type:

      Optional[`datetime.datetime`]

  participants

    A list of users that participated in the call.

    Type:

      List[`User`]

  property duration

    The duration the call has lasted or is already ongoing.

    Type:

      `datetime.timedelta`

  is_ended()

    `bool`: Whether the call is ended or not.

## Exceptions

The following exceptions are thrown by the library.

exception discord.DiscordException

  Base exception class for discord.py

  Ideally speaking, this could be caught to handle any exceptions raised from this library.

exception discord.ClientException

  Exception that’s raised when an operation in the `Client` fails.

  These are usually for exceptions that happened due to user input.

exception discord.LoginFailure

  Exception that’s raised when the `Client.login()` function fails to log you in from improper credentials or some other misc. failure.

exception discord.HTTPException(response, message)

  Exception that’s raised when an HTTP request operation fails.

  response

    The response of the failed HTTP request. This is an instance of `aiohttp.ClientResponse`. In some cases this could also be a `requests.Response`.

    Type:

      `aiohttp.ClientResponse`

  text

    The text of the error. Could be an empty string.

    Type:

      `str`

  status

    The status code of the HTTP request.

    Type:

      `int`

  code

    The Discord specific error code for the failure.

    Type:

      `int`

exception discord.RateLimited(retry_after)

  Exception that’s raised for when status code 429 occurs and the timeout is greater than the configured maximum using the `max_ratelimit_timeout` parameter in `Client`.

  This is not raised during global ratelimits.

  Since sometimes requests are halted pre-emptively before they’re even made, this does not subclass `HTTPException`.

  Added in version 2.0.

  retry_after

    The amount of seconds that the client should wait before retrying the request.

    Type:

      `float`

exception discord.Forbidden(response, message)

  Exception that’s raised for when status code 403 occurs.

  Subclass of `HTTPException`

exception discord.NotFound(response, message)

  Exception that’s raised for when status code 404 occurs.

  Subclass of `HTTPException`

exception discord.DiscordServerError(response, message)

  Exception that’s raised for when a 500 range status code occurs.

  Subclass of `HTTPException`.

  Added in version 1.5.

exception discord.InvalidData

  Exception that’s raised when the library encounters unknown or invalid data from Discord.

exception discord.GatewayNotFound

  An exception that is raised when the gateway for Discord could not be found

exception discord.ConnectionClosed(socket, *, shard_id, code=None)

  Exception that’s raised when the gateway connection is closed for reasons that could not be handled internally.

  code

    The close code of the websocket.

    Type:

      `int`

  reason

    The reason provided for the closure.

    Type:

      `str`

  shard_id

    The shard ID that got closed if applicable.

    Type:

      Optional[`int`]

exception discord.PrivilegedIntentsRequired(shard_id)

  Exception that’s raised when the gateway is requesting privileged intents but they’re not ticked in the developer page yet.

  Go to https://discord.com/developers/applications/ and enable the intents that are required. Currently these are as follows:

  - `Intents.members`

  - `Intents.presences`

  - `Intents.message_content`

  shard_id

    The shard ID that got closed if applicable.

    Type:

      Optional[`int`]

exception discord.InteractionResponded(interaction)

  Exception that’s raised when sending another interaction response using `InteractionResponse` when one has already been done before.

  An interaction can only respond once.

  Added in version 2.0.

  interaction

    The interaction that’s already been responded to.

    Type:

      `Interaction`

exception discord.MissingApplicationID(message=None)

  An exception raised when the client does not have an application ID set.

  An application ID is required for syncing application commands and various other application tasks such as SKUs or application emojis.

  This inherits from `AppCommandError` and `ClientException`.

  Added in version 2.0.

  Changed in version 2.5: This is now exported to the `discord` namespace and now inherits from `ClientException`.

exception discord.opus.OpusError(code)

  An exception that is thrown for libopus related errors.

  code

    The error code returned.

    Type:

      `int`

exception discord.opus.OpusNotLoaded

  An exception that is thrown for when libopus is not loaded.

### Exception Hierarchy

- `Exception`
    - `DiscordException`
        - `ClientException`

            - `InvalidData`

            - `LoginFailure`

            - `ConnectionClosed`

            - `PrivilegedIntentsRequired`

            - `InteractionResponded`

            - `MissingApplicationID`

        - `GatewayNotFound`

        - `HTTPException`

            - `Forbidden`

            - `NotFound`

            - `DiscordServerError`

            - `app_commands.CommandSyncFailure`

        - `RateLimited`

close

# Settings

## Font

### Use a serif font:

## Theme

### Automatic

### Light

### Dark

arrow_upwardto top