Themes

Client

Discord client class used to interact with the Discord API.

Attributes

activities : None or list of ActivityBase instances

A list of the client's activities. Defaults to None.

application : Application

The bot account's application. The application data of the client is requested meanwhile it logs in.

avatar_hash : int

The client's avatar's hash in uint128.

avatar_type : IconType

The client's avatar's type.

banner_color : None or Color

The user's banner color if has any.

banner_hash : int

The user's banner's hash in uint128.

banner_type : IconType

The user's banner's type.

discriminator : int

The client's discriminator. Given to avoid overlapping names.

email : None or str

The client's email.

Contains the event handlers of the client. New event handlers can be added through it as well.

flags : UserFlag

The client's user flags.

The gateway of the client towards Discord. If the client uses sharding, then DiscordGatewaySharder is used as gateway.

group_channels : dict of (int, ChannelGroup) items

The group channels of the client. They can be accessed by their id as the key.

guild_profiles : dict of (int, GuildProfile) items

A dictionary, which contains the client's guild profiles. If a client is member of a guild, then it should have a respective guild profile accordingly.

guilds : set of Guild

The guilds, where the client is in.

The http session of the client. Can be used as a normal http session, or for lower level interactions with the Discord API.

id : int

The client's unique identifier number.

intents : IntentFlag

The intent flags of the client.

is_bot : bool

Whether the client is a bot or a user account.

locale : str

The preferred locale by the client.

mfa : bool

Whether the client has two factor authorization enabled on the account.

name : str

The client's username.

partial : bool

Partial clients have only their id set. If any other data is set, it might not be in sync with Discord.

premium_type : PremiumType

The Nitro subscription type of the client.

private_channels : dict of (int, ChannelPrivate) items

Stores the private channels of the client. The channels' other recipient' ids are the keys, meanwhile the channels are the values.

ready_state : ReadyState or None

The client on login fills up it's .ready_state with Guild objects, which will have their members requested.

When receiving a READY dispatch event, the client's .ready_state is set as a ReadyState instance and a ._delay_ready task is started, what delays the handle-able ready event, till every user from the received guilds is cached up. When done, .ready_state is set back to None.

relationships : dict of (int, Relationship) items

Stores the relationships of the client. The relationships' users' ids are the keys and the relationships themselves are the values.

running : bool

Whether the client is running or not. When the client is stopped, this attribute is set as False what causes it's heartbeats to stop and it's gateways to close and not reconnect.

secret : str

The client's secret used when interacting with oauth2 endpoints.

shard_count : int

The client's shard count. Set as 0 if the bot is not using sharding.

status : Status

The client's display status.

statuses : dict of (str, str) items

The client's statuses for each platform.

thread_profiles : None or dict(ChannelThread, ThreadProfile) items

A Dictionary which contains the thread profiles for the user in thread channel - thread profile relation. Defaults to None.

token : str

The client's token.

verified : bool

Whether the email of the client is verified.

voice_clients : dict of (int, VoiceClient) items

Each bot can join a channel at every Guild and meanwhile they do, they have an active voice client for that guild. This attribute stores these voice clients. They keys are the guilds' ids, meanwhile the values are the voice clients.

_activity : ActivityBase instance

The client's preferred activity.

_additional_owner_ids : None or set of int

Additional users' (as id) to be passed by the .is_owner check.

_gateway_max_concurrency : int

The max amount of shards, which can be launched at the same time.

_gateway_requesting : bool

Whether the client already requests it's gateway.

_gateway_time : float

The last timestamp when ._gateway_url was updated.

_gateway_url : str

Cached up gateway url, what is invalidated after 1 minute. Used to avoid unnecessary requests when launching up more shards.

_gateway_waiter : None or Future

When client gateway is being requested multiple times at the same time, this future is set and awaited at the secondary requests.

_status : Status

The client's preferred status.

_user_chunker_nonce : int

The last nonce in int used for requesting guild user chunks. The default value is 0, what means the next request will start at 1.

Nonce 0 is allocated for the case, when all the guild's users are requested.

Class Attributes

loop : EventThread

The event loop of the client. Every client uses the same one.

_next_auto_id : int

Auto id generator for clients without identifier.

Notes

Client supports weakreferencing and dynamic attribute names as well for extension support.

See Also

  • UserBase: The superclass of Client and of other user classes.
  • User: The default type of Discord users.
  • Webhook: Discord webhook entity.
  • WebhookRepr: Discord webhook's user representation.
  • UserOA2: A user class with extended oauth2 attributes.

Properties

activity

Returns the user's top activity if applicable. If not.

Returns

activity : ActivityRich or None

avatar

Returns the respective icon.

Returns

icon : Icon

avatar_url

Returns the user's avatar's url. If the user has no avatar, then returns it's default avatar's url.

Parameters

user : UserBase

The respective user.

Returns

url : None or str

avatar_url_for

Returns the user's guild specific avatar. If the user has no guild specific avatar, returns None.

Parameters

user : UserBase

The Respective user.

guild : Guild

The respective guild.

Returns

url : None or str

banner

Returns the respective icon.

Returns

icon : Icon

banner_url

Returns the user's banner's url. If the user has no banner, then returns None.

Parameters

user : UserBase

The respective user.

Returns

url : None or str

blocked

Returns the client's blocked relationships.

Returns

relationships : list of Relationship objects

created_at

When the entity was created.

Returns

created_at : datetime

custom_activity

Returns the user's custom activity if applicable.

Returns

activity : ActivityCustom or None

default_avatar

Returns the user's default avatar.

Returns

default_avatar : DefaultAvatar

default_avatar_url

Returns the user's default avatar's url.

Returns

default_avatar_url : str

extensions

Returns a list of extensions added to the client. Added by the extension_loader extension.

Returns

extensions : list of Extension

friends

Returns the client's friends.

Returns

relationships : list of Relationship objects

full_name

The user's name with it's discriminator.

Returns

full_name : str

mention

The mention of the user.

Returns

mention : str

mention_nick

The mention to the user's nick.

Returns

mention : str

Notes

It actually has nothing to do with the user's nickname > <.

owner

Returns the client's owner if applicable.

If the client is a user account, or if it's .update_application_info was not called yet, then returns ZEROUSER. If the client is owned by a Team, then returns the team's owner.

Returns

owner : ClientUserBase

owners

Returns the owners of the client.

Returns

owners : set of ClientUserBase

partial

Returns whether the user is partial. Partial users have only their .id set and every other field might not reflect the reality.

Returns

partial : bool

platform

Returns the user's top status's platform. If the user is offline it will return an empty string.

Returns

platform : str

received_requests

Returns the received friend requests of the client.

Returns

relationships : list of Relationship objects

sent_requests

Returns the sent friend requests of the client.

Returns

relationships : list of Relationship objects

_platform

Returns the client's local platform.

Returns

platform : str

The platform's name or empty string if the client's status is offline or invisible.

Notes

Custom client's status is always 'web', so other than '' or 'web' will not be returned.

Methods

__new__

Creates a new Client instance with the given parameters.

Parameters

token : str

A valid Discord token, what the client can use to interact with the Discord API.

secret: str, Optional (Keyword only)

Client secret used when interacting with oauth2 endpoints.

client_id : None, int or str, Optional (Keyword only)

The client's .id. If passed as str will be converted to int. Defaults to None.

When more Client is started up, it is recommended to define their id initially. The wrapper can detect the clients' id-s only when they are logging in, so the wrapper needs to check if a User alter_ego of the client exists anywhere, and if does will replace it.

application_id : None, int or str, Optional (Keyword only)

The client's application id. If passed as str, will be converted to int. Defaults to None.

activity : ActivityBase, Optional (Keyword only)

The client's preferred activity.

status : str or Status, Optional (Keyword only)

The client's preferred status.

is_bot : bool, Optional (Keyword only)

Whether the client is a bot user or a user account. Defaults to False.

shard_count : int, Optional (Keyword only)

The client's shard count. If passed as lower as the recommended one, will reshard itself.

intents : IntentFlag, Optional (Keyword only)

By default the client will launch up using all the intent flags. Negative values will be interpreted as using all the intents, meanwhile if passed as positive, non existing intent flags are removed.

additional_owners : None, int, ClientUserBase, iterable of (int, ClientUserBase)

Additional users to return True if is_owner is called.

extensions : None, str, iterable of str, Optional (Keyword only)

The extension's name to setup on the client.

http_debug_options: None, str, iterable of str, Optional (Keyword only)

Http client debug options for the client.

**kwargs : keyword parameters

Additional predefined attributes for the client.

Other Parameters

name : str, Optional (Keyword only)

The client's .name.

discriminator : int or str instance, Optional (Keyword only)

The client's .discriminator. Is accepted as str instance as well and will be converted to int.

avatar : None, Icon or str, Optional (Keyword only)

The client's avatar.

Mutually exclusive with avatar_type and avatar_hash.

avatar_type : IconType, Optional (Keyword only)

The client's avatar's type.

Mutually exclusive with avatar_type.

avatar_hash : int, Optional (Keyword only)

The client's avatar hash.

Mutually exclusive with avatar.

banner : None, Icon or str, Optional (Keyword only)

The client's banner.

Mutually exclusive with banner_type and banner_hash.

banner_color : None or Color

The user's banner color.

banner_type : IconType, Optional (Keyword only)

The client's banner's type.

Mutually exclusive with banner_type.

banner_hash : int, Optional (Keyword only)

The client's banner hash.

Mutually exclusive with banner.

flags : UserFlag or int instance, Optional (Keyword only)

The client's .flags. If not passed as UserFlag, then will be converted to it.

**kwargs : keyword parameters

Additional parameters to pass to extension setuppers.

If any required parameter by an extension is missing RuntimeError is raised, meanwhile if any extra is given, RuntimeWarning is dropped.

Returns

client : Client

Raises

TypeError

If any parameter's type is bad or if unexpected parameter is passed.

ValueError

If an parameter's type is good, but it's value is unacceptable.

RuntimeError

Creating the same client multiple times is not allowed.

achievement_create

Creates an achievement for the client's application and returns it.

This method is a coroutine.

Parameters

name : str

The achievement's name.

description : str

The achievement's description.

icon : bytes-like

The achievement's icon. Can have 'jpg', 'png', 'webp' or 'gif' format.

secret : bool, Optional (Keyword only)

Secret achievements will *not* be shown to the user until they've unlocked them.

secure : bool, Optional (Keyword only)

Secure achievements can only be set via HTTP calls from your server, not by a game client using the SDK.

Returns

achievement : Achievement

The created achievement entity.

Raises

TypeError

If icon was not passed as bytes-like.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the icon 's format is not any of the expected ones.
  • If name was not given as str instance.
  • If description was not given as str instance.
  • If secret was not given as bool instance.
  • If secure was not given as bool instance.

achievement_delete

Deletes the passed achievement.

This method is a coroutine.

Parameters

achievement : Achievement or int

The achievement to delete.

Raises

TypeError

If achievement was not given neither as Achievement, neither as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

achievement_edit

Edits the passed achievement with the specified parameters. All parameter is optional.

This method is a coroutine.

Parameters

achievement : Achievement or int instance

The achievement, what will be edited.

name : str, Optional (Keyword only)

The new name of the achievement.

description : str, Optional (Keyword only)

The achievement's new description.

secret : bool, Optional (Keyword only)

The achievement's new secret value.

secure : bool, Optional (Keyword only)

The achievement's new secure value.

icon : bytes-like, Optional (Keyword only)

The achievement's new icon.

Returns

achievement : Achievement

After a successful edit, the passed achievement is updated and returned.

Raises

TypeError

  • If icon was not passed as bytes-like.
  • If achievement was not given neither as Achievement, neither as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given as str instance.
  • If description was not given as str instance.
  • If secret was not given as bool instance.
  • If secure was not given as str instance.
  • If icon 's format is not any of the expected ones.

achievement_get

Requests one of the client's achievements by it's id.

This method is a coroutine.

Parameters

achievement_id : int

The achievement's id.

Returns

achievement : Achievement

Raises

TypeError

If achievement_id was not given as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

achievement_get_all

Requests all the achievements of the client's application and returns them.

This method is a coroutine.

Returns

achievements : list of Achievement objects

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

activate_authorization_code

Activates a user's oauth2 code.

This method is a coroutine.

Parameters

redirect_url : str

The url, where the activation page redirected to.

code : str

The code, what is included with the redirect url after a successful activation.

scopes : str or list of str

Scope or a list of oauth2 scopes to request.

Returns

access : OA2Access or None

If the code, the redirect url or the scopes are invalid, the methods returns None.

Raises

TypeError

If Scopes wasn't neither as str not list of str instances.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If redirect_url was not given as str instance.
  • If code was not given as str instance.
  • If scopes is empty.
  • If scopes contains empty string.

See Also

parse_oauth2_redirect_url: Parses redirect_url and the code from a full url.

add_additional_owners

Adds additional users to be passed at the .is_owner check.

Parameters

*users : int or UserBase instances

The .id of the a user or the user itself to be added.

Raises

TypeError

A user was passed with invalid type.

application_command_global_create

Creates a new global application command.

If there is an application command with the given name, will overwrite that instead.

Each day only maximum only 200 global application command can be created.

This method is a coroutine.

Parameters

application_command : ApplicationCommand

The application command to create.

Returns

application_command : ApplicationCommand

The created application command.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If application_command was not given as ApplicationCommand instance.

Notes

The command will be available in all guilds after 1 hour.

application_command_global_delete

Deletes the given application command.

Parameters

application_command : ApplicationCommand or int

The application command delete edit. Can be given as the application command's id as well.

Raises

TypeError

If application_command was not given neither as ApplicationCommand nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_global_edit

Edits a global application command.

This method is a coroutine.

Parameters

old_application_command : ApplicationCommand or int

The application command to edit. Can be given as the application command's id as well.

new_application_command : ApplicationCommand

The application command to edit to.

Returns

application_command : ApplicationCommand

The edited application command.

Raises

TypeError

If old_application_command was not given neither as ApplicationCommand nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If new_application_command was not given as ApplicationCommand instance.

Notes

The updates will be available in all guilds after 1 hour.

application_command_global_get

Requests the given global application command.

Parameters

application_command : ApplicationCommand or int

The application command, or it's id to request.

Returns

application_commands : ApplicationCommand

The received application command.

Raises

TypeError

If application_command was not given neither as ApplicationCommand not as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_global_get_all

Requests the client's global application commands.

This method is a coroutine.

Returns

application_commands : list of ApplicationCommand

The received application commands.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_global_update_multiple

Takes an iterable of application commands, and updates the actual global ones.

If a command exists with the given name, edits it, if not, will creates a new one.

The created application commands count to the daily limit.

This method is a coroutine.

Parameters

application_commands : iterable of ApplicationCommand

The application commands to update the existing ones with.

Returns

application_commands : list of ApplicationCommand

The edited and created application commands.

Raises

ValueError

If more than 100 ApplicationCommand is given.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If an application command was not given as ApplicationCommand instance.
  • If application_commands is not iterable.

Notes

The commands will be available in all guilds after 1 hour.

application_command_guild_create

Creates a new guild application command.

If there is an application command with the given name, will overwrite that instead.

Each day only maximum only 200 guild application command can be created at each guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, where application commands will be created.

application_command : ApplicationCommand

The application command to create.

Returns

application_command : ApplicationCommand

The created application command.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If application_command was not given as ApplicationCommand instance.

application_command_guild_delete

Deletes the given application command.

Parameters

guild : Guild or int

The guild, to what the application command is bound to.

application_command : ApplicationCommand or int

The application command delete edit. Can be given as the application command's id as well.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If application_command was not given neither as ApplicationCommand nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_guild_edit

Edits a guild application command.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, to what the application command is bound to.

old_application_command : ApplicationCommand or int

The application command to edit. Can be given as the application command's id as well.

new_application_command : ApplicationCommand

The application command to edit to.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If old_application_command was not given neither as ApplicationCommand nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If new_application_command was not given as ApplicationCommand instance.

application_command_guild_get

Requests the given guild application command.

Parameters

application_command : ApplicationCommand or int

The application command, or it's id to request.

Returns

application_commands : ApplicationCommand

The received application command.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If application_command was not given neither as ApplicationCommand not as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_guild_get_all

Requests the client's global application commands.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, which application commands will be requested.

Returns

application_commands : list of ApplicationCommand

The received application commands.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_command_guild_update_multiple

Takes an iterable of application commands, and updates the guild's actual ones.

If a command exists with the given name, edits it, if not, will creates a new one.

The created application commands count to the daily limit.

This method is a coroutine.

Parameters

application_commands : iterable of ApplicationCommand

The application commands to update the existing ones with.

Returns

application_commands : list of ApplicationCommand

The edited and created application commands.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ValueError

If more than 100 ApplicationCommand is given.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If an application command was not given as ApplicationCommand instance.
  • If application_commands is not iterable.

application_command_permission_edit

Edits the permissions of the given application_command in the given guild.

The new permissions will permission overwrite the existing permission of an application command.

A command will lose it's permissions on rename.

This method is a coroutine.

Parameters

guild : Guild or int

The respective guild.

application_command : ApplicationCommand or int

The respective application command.

permission_overwrites : None or (tuple, list of set) of ApplicationCommandPermissionOverwrite

The new permission overwrites of the given application command inside of the guild.

Give it as None to remove all existing one.

Returns

permissions : ApplicationCommandPermission

The application command's new permissions.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If an application command was not given neither as ApplicationCommand or int instance.
  • If permission_overwrites was not given as None, tuple, list or set.
  • If permission_overwrites contains a non ApplicationCommandPermissionOverwrite element.
  • If permission_overwrites contains more than 10 elements.

application_command_permission_get

Returns the permissions set for the given application_command in the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The respective guild.

application_command : ApplicationCommand or int

The respective application command.

Returns

permission : ApplicationCommandPermission

The requested permissions.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client's application is not yet synced.
  • If an application command was not given neither as ApplicationCommand or int instance.

Notes

Íf the application command has no permission overwrites in the guild, Discord will drop the following error:

DiscordException Not Found (404), code=10066: Unknown application command permissions

application_command_permission_get_all_guild

Returns the permissions set for application commands in the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to request application command permissions from.

Returns

permission : list of ApplicationCommandPermission

The requested permissions for all the application commands in the guild.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the client's application is not yet synced.

application_get

Requests a specific application by it's id.

This method is a coroutine.

Parameters

application : Application or int

The application or it's identifier to request.

Returns

application : Application

Raises

TypeError

If application was not given neither as Application nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint does not support bot accounts.

application_get_all_detectable

Requests the detectable applications

This method is a coroutine.

Returns

applications : list of Application

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_invite_create

Creates an EMBEDDED_APPLICATION invite to the specified voice channel. The application must have must have embedded flag.

This method is a coroutine.

Parameters

channel : channel : ChannelText, ChannelVoice, ChannelGroup, ChannelStore, ChannelDirectory, int

The target channel of the invite.

application : Application or int

The embedded application to open in the voice channel.

The application must have EMBEDDED_APPLICATION flag.

max_age : int, Optional (Keyword only)

After how much time (in seconds) will the invite expire. Defaults is never.

max_uses : int, Optional (Keyword only)

How much times can the invite be used. Defaults to unlimited.

unique : bool, Optional (Keyword only)

Whether the created invite should be unique. Defaults to True.

temporary : bool, Optional (Keyword only)

Whether the invite should give only temporary membership. Defaults to False.

Returns

invite : Invite

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If guild was not given as Guild instance.
  • If max_age was not given as int instance.
  • If max_uses was not given as int instance.
  • If unique was not given as bool instance.
  • If temporary was not given as bool instance.

audit_log_get_chunk

Request a batch of audit logs of the guild and returns them. The after, around and the before parameters are mutually exclusive and they can be passed as int, or as a DiscordEntity instance or as a datetime object.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's audit logs will be requested.

limit : int, Optional

The amount of audit logs to request. Can b between 1 and 100. Defaults to 100.

before : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp before the audit log entries wer created.

after : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp after the audit log entries wer created.

user : None, ClientUserBase or int instance, Optional (Keyword only)

Whether the audit logs should be filtered only to those, which were created by the given user.

event : None, AuditLogEvent, int, Optional (Keyword only)

Whether the audit logs should be filtered only on the given event.

Returns

audit_log : AuditLog

A container what contains the AuditLogEntry-s.

Raises

TypeError

  • If guild was not given neither as Guild, nor as int instance.
  • If after or before was passed with an unexpected type.
  • If user was not given neither as None, ClientUserBase nor as int instance.
  • If event as not not given neither as None, AuditLogEvent nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If limit was not given as int instance.
  • If limit is out of the expected range [1:100].

audit_log_iterator

Returns an audit log iterator for the given guild.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's audit logs will be requested.

user : None, ClientUserBase or int instance, Optional (Keyword only)

Whether the audit logs should be filtered only to those, which were created by the given user.

event : None, AuditLogEvent or int, Optional (Keyword only)

Whether the audit logs should be filtered only on the given event.

Returns

audit_log_iterator : AuditLogIterator

avatar_url_as

Returns the user's avatar's url. If the user has no avatar, then returns it's default avatar's url.

Parameters

user : UserBase

The respective user.

ext : str, Optional

The extension of the image's url. Can be any of: 'jpg', 'jpeg', 'png', 'webp'. If the user has animated avatar, it can 'gif' as well.

size : int, Optional

The preferred minimal size of the avatar's url.

Returns

url : None or str

Raises

ValueError

If ext or size was not passed as any of the expected values.

avatar_url_at

Returns the user's avatar's url at the guild.

Parameters

user : UserBase

The Respective user.

guild : Guild

The respective guild.

Returns

url : None or str

avatar_url_at_as

Returns the user's avatar's url at the guild. If the user has no avatar, then returns it's default avatar's url.

Parameters

user : UserBase

The Respective user.

guild : Guild

The respective guild.

ext : str, Optional

The extension of the image's url. Can be any of: 'jpg', 'jpeg', 'png', 'webp'. If the user has animated avatar, it can 'gif' as well.

size : int, Optional

The preferred minimal size of the avatar's url.

Returns

url : None or str

Raises

ValueError

If ext or size was not passed as any of the expected values.

avatar_url_for_as

Returns the user's guild specific avatar. If the user has no avatar, then returns it's default avatar's url.

Parameters

user : UserBase

The Respective user.

guild : Guild

The respective guild.

ext : str, Optional

The extension of the image's url. Can be any of: 'jpg', 'jpeg', 'png', 'webp'. If the user has animated avatar, it can 'gif' as well.

size : int, Optional

The preferred minimal size of the avatar's url.

Returns

url : None or str

Raises

ValueError

If ext or size was not passed as any of the expected values.

banner_url_as

Returns the user's banner's url. If the user has no banner, then returns None.

Parameters

user : UserBase

The respective user.

ext : str, Optional

The extension of the image's url. Can be any of: 'jpg', 'jpeg', 'png', 'webp'. If the user has animated banner, it can 'gif' as well.

size : int, Optional

The preferred minimal size of the avatar's url.

Returns

url : None or str

Raises

ValueError

If ext or size was not passed as any of the expected values.

can_use_emoji

Returns whether the user can use the given emoji.

Parameters

emoji : Emoji

The emoji to check.

Returns

can_use_emoji : bool

channel_create

Creates a new channel at the given guild. If the channel is successfully created returns it.

This method is a coroutine.

Parameters

guild : Guild or int

The guild where the channel will be created.

name : str

The created channel's name.

type_ : int or ChannelGuildBase subclass, Optional

The type of the created channel. Defaults to ChannelText.

reason : None or str, Optional (Keyword only)

Shows up at the guild 's audit logs.

**kwargs : Keyword parameters

Additional keyword parameters to describe the created channel.

Other Parameters

permission_overwrites : list of cr_p_permission_overwrite_object returns, Optional (Keyword only)

A list of permission overwrites of the channel. The list should contain json serializable permission overwrites made by the cr_p_permission_overwrite_object function.

topic : str, Optional (Keyword only)

The channel's topic.

nsfw : bool, Optional (Keyword only)

Whether the channel is marked as nsfw.

slowmode : int, Optional (Keyword only)

The channel's slowmode value.

bitrate : int, Optional (Keyword only)

The channel's bitrate.

user_limit : int, Optional (Keyword only)

The channel's user limit.

parent : None, ChannelCategory or int, Optional (Keyword only)

The channel's parent. If the channel is under a guild, leave it empty.

category : None, ChannelCategory, Guild or int, Optional (Keyword only)

Deprecated, please use parent parameter instead.

region : None, VoiceRegion or str, Optional (Keyword only)

The channel's voice region.

video_quality_mode : None, VideoQualityMode or int, Optional (Keyword only)

The channel's video quality mode.

default_auto_archive_after : None or int

The default duration (in seconds) for newly created threads to automatically archive the themselves. Can be one of: 3600, 86400, 259200, 604800.

Returns

channel : None or ChannelGuildBase instance

The created channel. Returns None if the respective guild is not cached.

Raises

TypeError

  • If guild was not given as Guild or int instance.
  • If type_ was not passed as int or as ChannelGuildBase instance.
  • If parent was not given as None, ChannelCategory or int instance.
  • If region was not given either as None, str nor VoiceRegion instance.

AssertionError

  • If type_ was given as int, and is less than 0.
  • If type_ was given as int and exceeds the defined channel type limit.
  • If name was not given as str instance.
  • If name 's length is out of range [1:100].
  • If permission_overwrites was not given as None, neither as list of dict-s.
  • If topic was not given as str instance.
  • If topic 's length is over 1024.
  • If topic was given, but the respective channel type is not ChannelText.
  • If nsfw was given meanwhile the respective channel type is not ChannelText or ChannelStore.
  • If nsfw was not given as bool.
  • If slowmode was given, but the respective channel type is not ChannelText.
  • If slowmode was not given as int instance.
  • If slowmode was given, but it's value is less than 0 or greater than 21600.
  • If bitrate was given, but the respective channel type is not ChannelVoice.
  • If bitrate was not given as int instance.
  • If bitrate 's value is out of the expected range.
  • If user_limit was given, but the respective channel type is not ChannelVoice.
  • If user_limit was not given as int instance.
  • If user_limit was given, but is out of the expected [0:99] range.
  • If parent was given, but the respective channel type cannot be put under other categories.
  • If region was given, but the respective channel type is not ChannelVoice.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_delete

Deletes the specified guild channel.

This method is a coroutine.

Parameters

channel : ChannelGuildBase or int

The channel to delete.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If the given channel is not ChannelGuildBase or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If a category channel is deleted, it's sub-channels will not be removed, instead they will move under the guild.

channel_edit

Edits the given guild channel. Different channel types accept different parameters, so make sure to not pass out of place parameters. Only the passed parameters will be edited of the channel.

This method is a coroutine.

Parameters

channel : ChannelGuildBase or int instance

The channel to edit.

name : str, Optional (Keyword only)

The channel 's new name.

topic : str, Optional (Keyword only)

The new topic of the channel.

nsfw : bool, Optional (Keyword only)

Whether the channel will be nsfw or not.

slowmode : int, Optional (Keyword only)

The new slowmode value of the channel.

user_limit : int, Optional (Keyword only)

The new user limit of the channel.

bitrate : int, Optional (Keyword only)

The new bitrate of the channel.

type_ : int, Optional (Keyword only)

The channel 's new type value.

region : None, VoiceRegion, str, Optional (Keyword only)

The channel's new voice region.

By giving as None, you can remove the old value.

video_quality_mode : VideoQualityMode or int, Optional (Keyword only)

The channel's new video quality mode.

default_auto_archive_after : None or int

The default duration (in seconds) for newly created threads to automatically archive the themselves. Can be one of: 3600, 86400, 259200, 604800.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If the given channel is not ChannelGuildBase or int instance.
  • If region was not given neither as None, str nor VoiceRegion instance.
  • If video_quality_mode was not given neither as VideoQualityMode nor as int instance.

AssertionError

  • If name was not given as str instance.
  • If name 's length is out of range [1:100].
  • If topic was not given as str instance.
  • If topic 's length is over 1024 or 120 depending on channel type.
  • If topic was given, but the given channel is not ChannelText nor ChannelStage instance.
  • If type_ was given, but the given channel is not ChannelText instance.
  • If type_ was not given as int instance.
  • If type_ cannot be interchanged to the given value.
  • If nsfw was given meanwhile the channel is not ChannelText or ChannelStore instance.
  • If nsfw was not given as bool.
  • If slowmode was given, but the channel is not ChannelText instance.
  • If slowmode was not given as int instance.
  • If slowmode was given, but it's value is less than 0 or greater than 21600.
  • If bitrate was given, but the channel is not ChannelVoiceBase instance.
  • If bitrate was not given as int instance.
  • If bitrate 's value is out of the expected range.
  • If user_limit was given, but the channel is not ChannelVoiceBase instance.
  • If user_limit was not given as int instance.
  • If user_limit was given, but is out of the expected [0:99] range.
  • If region was given, but the respective channel type is not ChannelVoiceBase.
  • If video_quality_mode was given,but the respective channel type is not ChannelVoice

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_follow

Follows the source_channel with the target_channel. Returns the webhook, what will crosspost the published messages.

This method is a coroutine.

Parameters

source_channel : ChannelText or int instance

The channel what will be followed. Must be an announcements (type 5) channel.

target_channel : ChannelText or int instance

The target channel where the webhook messages will be sent. Can be any guild text channel type.

Returns

webhook : Webhook

The webhook what will crosspost the published messages. This webhook has no .token set.

Raises

TypeError

  • If the source_channel was not given neither as ChannelText nor int instance.
  • If the target_channel was not given neither as ChannelText nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If source_channel is not announcement channel.

channel_group_create

Creates a group channel with the given users.

This method is a coroutine.

Parameters

*users : ClientUserBase or int instances

The users to create the channel with.

Returns

channel : ChannelGroup

The created group channel.

Raises

TypeError

If users contain not only User, Client or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If the total amount of users is less than 2.

Notes

This endpoint does not support bot accounts.

channel_group_edit

Edits the given group channel. Only the provided parameters will be edited.

This method is a coroutine.

Parameters

channel : ChannelGroup or int instance

The channel to edit.

name : None or str, Optional (Keyword only)

The new name of the channel. By passing None or an empty string you can remove the actual one.

icon : None or bytes-like, Optional (Keyword only)

The new icon of the channel. By passing None your can remove the actual one.

Raises

TypeError

  • If channel was not given neither as ChannelGroup nor int instance.
  • If name is neither None or str instance.
  • If icon is neither None or bytes-like.

ValueError

  • If name is passed as str, but it's length is 1, or over 100.
  • If icon is passed as bytes-like, but it's format is not any of the expected formats.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given neither as None or str instance.
  • If name 's length is out of range [1:100].

Notes

No request is done if no optional parameter is provided.

channel_group_leave

Leaves the client from the specified group channel.

This method is a coroutine.

Parameters

channel : ChannelGroup or int

The channel to leave from.

Raises

TypeError

If channel was not given neither as ChannelGroup nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_group_user_add

Adds the users to the given group channel.

This method is a coroutine.

Parameters

channel : ChannelGroup or int instance

The channel to add the users to.

*users : ClientUserBase or int instances

The users to add to the channel.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_group_user_delete

Removes the users from the given group channel.

This method is a coroutine.

Parameters

channel : ChannelGroup or int instance

The channel from where the users will be removed.

*users : ClientUserBase or int instances

The users to remove from the channel.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_move

Moves a guild channel to the given visual position under it's parent, or guild. If the algorithm can not place the channel exactly on that location, it will place it as close, as it can. If there is nothing to move, then the request is skipped.

This method is a coroutine.

Parameters

channel : ChannelGuildMainBase instance

The channel to be moved.

visual_position : int

The visual position where the channel should go.

parent : None or ChannelGroup, Optional (Keyword only)

If not set, then the channel will keep it's current parent. If the parameter is set Guild instance or to None, then the channel will be moved under the guild itself, Or if passed as ChannelCategory.md, then the channel will be moved under it.

category : None or ChannelGroup or Guild, Optional (Keyword only)

Deprecated, please use parent parameter instead.

lock_permissions : bool, Optional (Keyword only)

If you want to sync the permissions with the new category set it to True. Defaults to False.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

ValueError

  • If the channel would be between guilds.
  • If parent channel would be moved under an other category.

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This method also fixes the messy channel positions of Discord to an intuitive one.

channel_pin_get_all

Returns the pinned messages at the given channel.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance

The channel from were the pinned messages will be requested.

Returns

messages : list of Message objects

The pinned messages at the given channel.

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_private_create

Creates a private channel with the given user. If there is an already cached private channel with the user, returns that.

This method is a coroutine.

Parameters

user : ClientUserBase or int instance

The user to create the private with.

Returns

channel : ChannelPrivate

The created private channel.

Raises

TypeError

If user was not given neither as ClientUserBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_private_get_all

Request the client's private + group channels and returns them in a list. At the case of bot accounts the request returns an empty list, so we skip it.

This method is a coroutine.

Returns

channels : list of (ChannelPrivate or ChannelGroup) objects

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_thread_get_all_active

Requests all the active threads of the given channel.

Parameters

channel : ChannelText, int

The channel to request the thread of, or it's identifier.

Returns

thread_channels : list of ChannelThread

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_thread_get_all_archived_private

Requests all the archived private of the given channel.

Parameters

channel : ChannelText, int

The channel to request the thread of, or it's identifier.

Returns

thread_channels : list of ChannelThread

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_thread_get_all_archived_public

Requests all the archived public threads of the given channel.

Parameters

channel : ChannelText, int

The channel to request the thread of, or it's identifier.

Returns

thread_channels : list of ChannelThread

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_thread_get_all_self_archived

Requests all the archived private threads by the client.

Parameters

channel : ChannelText, int

The channel to request the thread of, or it's identifier.

Returns

thread_channels : list of ChannelThread

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

client_connection_get_all

Requests the client's connections.

This method is a coroutine.

Returns

connections : list of Connection objects

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

For a bot account this request will always return an empty list.

client_edit

Edits the client. Only the provided parameters will be changed. Every parameter what refers to a user account is not tested.

This method is a coroutine.

Parameters

avatar : None or bytes-like, Optional (Keyword only)

An 'jpg', 'png', 'webp' image's raw data. If the client is premium account, then it can be 'gif' as well. By passing None you can remove the client's current avatar.

banner : None or bytes-like, Optional (Keyword only)

An 'jpg', 'png', 'webp', 'gif' image's raw data. By passing None you can remove the client's current avatar.

banner_color : None, Color or int, Optional (Keyword only)

The new banner color of the client. By passing it as None you can remove the client's current one.

bio : None or str, Optional (Keyword only)

The new bio of the client. By passing it as None, you can remove the client's current one.

name : str, Optional (Keyword only)

The client's new name.

password : str, Optional (Keyword only)

The actual password of the client.

new_password : str, Optional (Keyword only)

The client's new password.

email : str, Optional (Keyword only)

The client's new email.

house : int, HypesquadHouse or None, Optional (Keyword only)

Remove or change the client's hypesquad house.

Raises

TypeError

  • If avatar was not given as None, neither as bytes-like.
  • If house was not given as int neither as HypesquadHouse instance.
  • If banner was not given as None, neither as bytes-like.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was given but not as str instance.
  • If name 's length is out of range [2:32].
  • If avatar 's type in unsettable for the client.
  • If password was not given meanwhile the client is not bot.
  • If password was not given as str instance.
  • If email was given, but not as str instance.
  • If new_password was given, but not as str instance.
  • If bio is neither None nor str instance.
  • If bio 's length is out of range [0:190].
  • if banner_color is neither None nor int instance.

Notes

The method's endpoint has long rate limit reset, so consider using timeout and checking rate limits with RateLimitProxy.

The password, new_password, email and the house parameters are only for user accounts.

client_edit_presence

Changes the client's presence (status and activity). If a parameter is not defined, it will not be changed.

This method is a coroutine.

Parameters

activity : ActivityBase instance, Optional (Keyword only)

The new activity of the Client.

status : str or Status, Optional (Keyword only)

The new status of the client.

afk : bool, Optional (Keyword only)

Whether the client is afk or not (?). Defaults to False.

Raises

TypeError:

ValueError:

  • If the status str instance, but not any of the predefined ones.

AssertionError

  • afk was not given as int instance.

client_gateway

Requests the gateway information for the client.

Only 1 request can be done at a time and every other will yield the result of first started one.

This method is a coroutine.

Returns

data : dict of (str, Any) items

Raises

ConnectionError

No internet connection or if the request raised any DiscordException.

InvalidToken

When the client's token is invalid.

DiscordException

If any exception was received from the Discord API.

client_gateway_reshard

Reshards the client. And also updates it's gateway's url as a side note.

Should be called only if every shard is down.

This method is a coroutine.

Parameters

force : bool

Whether the the client should reshard to lower amount of shards if needed.

Raises

ConnectionError

No internet connection or if the request raised any DiscordException.

InvalidToken

When the client's token is invalid.

DiscordException

If any exception was received from the Discord API.

client_gateway_url

Requests the client's gateway url. To avoid unreasoned requests when sharding, if this request was done at the last 60 seconds then returns the last generated url.

This method is a coroutine.

Returns

gateway_url : str

The url to what the gateways' websocket will be connected.

Raises

ConnectionError

No internet connection or if the request raised any DiscordException.

InvalidToken

When the client's token is invalid.

DiscordException

If any exception was received from the Discord API.

client_guild_profile_edit

Edits the client guild profile in the given guild. Nick and guild specific avatars can be edited on this way.

An extra reason is accepted as well, which will show up at the respective guild's audit logs.

This method is a coroutine.

Parameters

guild : None, int or Guild instance

The guild where the client's nickname will be changed. If guild is given as None, then the function returns instantly.

nick : None or str, Optional (Keyword only)

The client's new nickname. Pass it as None to remove it. Empty strings are interpreted as None.

avatar : None or bytes-like, Optional (Keyword only)

The client's new guild specific avatar.

Can be a 'jpg', 'png', 'webp' image's raw data. If the client is premium account, then it can be 'gif' as well. By passing None you can remove the client's current avatar.

timed_out_until : None or datetime, Optional (Keyword only)

Till when the client is timed out. Pass it as None to remove it.

reason : None or str, Optional (Keyword only)

Will show up at the respective guild's audit logs.

Raises

TypeError

  • guild was not given neither as Guild or int instance.
  • If avatar is neither None nor bytes-like.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the nick's length is out of range [1:32].
  • If the nick was not given neither as None or str instance.
  • If avatar 's type is incorrect.
  • If timed_out_until is neither None nor datetime instance.

client_login_static

The first step at login in is requesting the client's user data. This method is also used to check whether the token of the client is valid.

This method is a coroutine.

Returns

response_data : dict of (str: Any)

Decoded json data got from Discord.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

InvalidToken

When the token of the client is invalid.

color_at

Returns the user's color at the given guild.

Parameters

guild : None or Guild

The guild, where the user's color will be checked.

Can be given as None.

Returns

color : Color

connect

Starts connecting the client to Discord, fills up the undefined events and creates the task, what will keep receiving the data from Discord (._connect).

If you want to start the connecting process consider using the top-level .start or start_clients instead.

This method is a coroutine.

Returns

success : bool

Whether the client could be started.

Raises

RuntimeError

If the client is already running.

disconnect

Disconnects the client and closes it's websocket(s). Till the client goes offline, it might take even over than 1 minute. Because bot accounts can not logout, so they need to wait for timeout.

This method is a coroutine.

download_attachment

Downloads an attachment object's file. This method always prefers the proxy url of the attachment if applicable.

This method is a coroutine.

Parameters

attachment : Attachment or EmbedImage

The attachment object, which's file will be requested.

Returns

response_data : bytes

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If attachment was not given as Attachment nor EmbedImage instance.

emoji_create

Creates an emoji at the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, where the emoji will be created.

name : str

The emoji's name. It's length can be between 2 and 32.

image : bytes-like

The emoji's icon.

roles : None or ( list , set , tuple ) of ( Role or int), Optional (Keyword only)

Whether the created emoji should be limited only to users with any of the specified roles.

reason : None or str, Optional (Keyword only)

Will show up at the guild's audit logs.

Returns

emoji : Emoji

The created emoji.

Raises

TypeError

If guild was not given neither as Guild nor as int instance. If roles contains a non Role or int element.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given as str instance.
  • If name length is out of the expected range [1:32].
  • If roles was not given neither as None, list, tuple or set instance.

Notes

Only some characters can be in the emoji's name, so every other character is filtered out.

emoji_delete

Deletes the given emoji.

This method is a coroutine.

Parameters

emoji : Emoji

The emoji to delete.

reason : None or str, Optional (Keyword only)

Will show up at the respective guild's audit logs.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If emoji was not given as Emoji instance.

emoji_edit

Edits the given emoji.

This method is a coroutine.

Parameters

emoji : Emoji

The emoji to edit.

name : str, Optional (Keyword only)

The emoji's new name. It's length can be in range [2:32].

roles : None or (list, set, tuple) of (Role, int), Optional (Keyword only)

The roles to what is the role limited. By passing it as None, or as an empty list you can remove the current ones.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If roles contains a non Role or int element.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If emoji was not given as Emoji instance.
  • If name was not given as str instance.
  • If name length is out of the expected range [1:32].
  • If roles was not given neither as None, list, tuple or set instance.

emoji_get

Requests the emoji by it's id at the given guild. If the client's logging in is finished, then it should have it's every emoji loaded already.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, where the emoji is.

emoji : Emoji or int

The emoji to get.

Returns

emoji : Emoji

Raises

TypeError

  • If guild was not given neither as Guild nor as int instance.
  • If emoji was not given neither as Emoji nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

eula_get

Requests the eula with the given id.

This method is a coroutine.

Parameters

eula : int

The id of the eula to request.

Returns

eula : EULA

Raises

TypeError

If eula was not given neither as EULA not as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

gateway_for

Returns the corresponding gateway of the client to the passed guild.

Parameters

guild_id : int

The respective guild's identifier, what's gateway will be returned.

Pass it as 0 to get the default gateway.

Returns

gateway : DiscordGateway

get_guild

Tries to find a guild by it's name. If there is no guild with the given name, then returns the passed default value.

Parameters

name : str

The guild's name to search.

default : Any, Optional

The default value, what will be returned if the guild was not found.

Returns

guild : Guild or default

Raises

AssertionError

  • If name was not given as str instance.
  • If name length is out of the expected range [2:100].

get_guild_profile_for

Returns the user's guild profile for the given guild.

Parameters

guild : Guild

The guild to get guild profile for.

Returns

guild_profile : None or Guild

guild_ban_add

Bans the given user from the guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild from where the user will be banned.

user : ClientUserBase or int instance

The user to ban from the guild.

delete_message_days : int, Optional (Keyword only)

How much days back the user's messages should be deleted. Can be in range [0:7].

reason : None or str, Optional (Keyword only)

Shows up at the guild's audit logs.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If user was not given neither as ClientUserBase, nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • delete_message_days was not given as int instance.
  • delete_message_days is out of range [0:delete_message_days].

guild_ban_delete

Unbans the user from the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild from where the user will be unbanned.

user : ClientUserBase or int instance

The user to unban at the guild.

reason : None or str, Optional (Keyword only)

Shows up at the guild's audit logs.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If user was not given neither as ClientUserBase, nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_ban_get

Returns the guild's ban entry for the given user id.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild where the user banned.

user : ClientUserBase or int instance

The user's id, who's entry is requested.

Returns

ban_entry : BanEntry

The ban entry.

Raises

TypeError

  • If guild was not passed neither as Guild or int instance.
  • If user was not given neither as ClientUserBase or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_ban_get_all

Returns the guild's bans.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's bans will be requested

Returns

bans : list of BanEntry elements

User, reason pairs for each ban entry.

Raises

TypeError

If guild was not given neither as Guild or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_create

Creates a guild with the given parameter. Bot accounts can create guilds only when they have less than 10. User account guild limit is 100, meanwhile staff guild limit is 200.

This method is a coroutine.

Parameters

name : str

The name of the new guild.

icon : None or bytes-like, Optional (Keyword only)

The icon of the new guild.

roles : None or list of cr_p_role_object returns, Optional (Keyword only)

A list of roles of the new guild. It should contain json serializable roles made by the cr_p_role_object function.

channels : None or list of cr_pg_channel_object returns, Optional (Keyword only)

A list of channels of the new guild. It should contain json serializable channels made by the cr_p_role_object function.

afk_channel_id : int, Optional (Keyword only)

The id of the guild's afk channel. The id should be one of the channel's id from channels.

system_channel_id: int, Optional (Keyword only)

The id of the guild's system channel. The id should be one of the channel's id from channels.

afk_timeout : int, Optional (Keyword only)

The afk timeout for the users at the guild's afk channel.

region : VoiceRegion or str, Optional (Keyword only)

The voice region of the new guild.

verification_level : VerificationLevel or int instance, Optional (Keyword only)

The verification level of the new guild.

message_notification : MessageNotificationLevel or int, Optional (Keyword only)

The message notification level of the new guild.

content_filter : ContentFilterLevel or int, Optional (Keyword only)

The content filter level of the guild.

boost_progress_bar_enabled : bool, Optional (Keyword only)

Whether the guild has the boost progress bar should be enabled.

Returns

guild : Guild object

A partial guild made from the received data.

Raises

TypeError

  • If icon is neither None or bytes-like.
  • If region was not given neither as VoiceRegion nor str instance.
  • If verification_level was not given neither as VerificationLevel not int instance.
  • If content_filter was not given neither as ContentFilterLevel not int instance.
  • If message_notification was not given neither as MessageNotificationLevel nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If the client cannot create more guilds.
  • If name was not given as str instance.
  • If the name 's length is out of range [2:100].
  • If icon is passed as bytes-like, but it's format is not a valid image format.
  • If afk-timeout was not given as int instance.
  • If afk_timeout was passed and not as one of: 60, 300, 900, 1800, 3600.
  • If boost_progress_bar_enabled was not given as bool instance.

guild_delete

Deletes the given guild. The client must be the owner of the guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to delete.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_discovery_add_subcategory

Adds a discovery subcategory to the guild.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

Parameters

guild : Guild, GuildDiscovery or int instance

The guild to what the discovery subcategory will be added.

category : DiscoveryCategory or int

The discovery category or it's id what will be added as a subcategory.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

A guild can have maximum 5 discovery subcategories.

If guild was given as GuildDiscovery, then it will be updated.

guild_discovery_delete_subcategory

Removes a discovery subcategory of the guild.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

Parameters

guild : Guild, GuildDiscovery or int instance

The guild to what the discovery subcategory will be removed from.

category : DiscoveryCategory or int

The discovery category or it's id what will be removed from the subcategories.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

A guild can have maximum 5 discovery subcategories.

If guild was given as GuildDiscovery, then it will be updated.

guild_discovery_edit

Edits the guild's discovery metadata.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

Parameters

guild : Guild or GuildDiscovery

The guild what's discovery metadata will be edited or an existing discovery metadata object.

primary_category : None or DiscoveryCategory or int, Optional (Keyword only)

The guild discovery's new primary category's id. Can be given as a DiscoveryCategory object as well. If given as None, then resets the guild discovery's primary category id to it's default, what is 0.

keywords : None or (iterable of str), Optional (Keyword only)

The guild discovery's new keywords. Can be given as None to reset to the default value, what is None, or as an iterable of strings.

emoji_discovery : None, bool or int(0, 1), Optional (Keyword only)

Whether the guild info should be shown when the respective guild's emojis are clicked. If passed as None then will reset the guild discovery's emoji_discovery value to it's default, what is True.

Returns

guild_discovery : GuildDiscovery

Updated guild discovery object.

Raises

ConnectionError

No internet connection.

TypeError

  • If guild was neither passed as type Guild or GuildDiscovery.
  • If primary_category_id was not given neither as None, int or as DiscoveryCategory instance.
  • If keywords was not passed neither as None or iterable of str.
  • If emoji_discovery was not passed neither as None, bool or int(0, 1).

ValueError

  • If primary_category_id was given as not primary DiscoveryCategory object.
  • If emoji_discovery was given as int instance, but not as 0 or 1.

DiscordException

If any exception was received from the Discord API.

guild_discovery_get

Requests and returns the guild's discovery metadata.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

Parameters

guild : Guild

The guild what's discovery will be requested.

Returns

guild_discovery : GuildDiscovery

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_edit

Edits the guild with the given parameters.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to edit.

name : str, Optional (Keyword only)

The guild's new name.

icon : None or bytes-like, Optional (Keyword only)

The new icon of the guild. Can be 'jpg', 'png', 'webp' image's raw data. If the guild has ANIMATED_ICON feature, it can be 'gif' as well. By passing None you can remove the current one.

invite_splash : None or bytes-like, Optional (Keyword only)

The new invite splash of the guild. Can be 'jpg', 'png', 'webp' image's raw data. The guild must have INVITE_SPLASH feature. By passing it as None you can remove the current one.

discovery_splash : None or bytes-like, Optional (Keyword only)

The new splash of the guild. Can be 'jpg', 'png', 'webp' image's raw data. The guild must have DISCOVERABLE feature. By passing it as None you can remove the current one.

banner : None or bytes-like, Optional (Keyword only)

The new splash of the guild. Can be 'jpg', 'png', 'webp' image's raw data. The guild must have BANNER feature. By passing it as None you can remove the current one.

afk_channel : None, ChannelVoice or int, Optional (Keyword only)

The new afk channel of the guild. You can remove the current one by passing is as None.

system_channel : None, ChannelText or int, Optional (Keyword only)

The new system channel of the guild. You can remove the current one by passing is as None.

rules_channel : None, ChannelText or int, Optional (Keyword only)

The new rules channel of the guild. The guild must be a Community guild. You can remove the current one by passing is as None.

public_updates_channel : None, ChannelText or int, Optional (Keyword only)

The new public updates channel of the guild. The guild must be a Community guild. You can remove the current one by passing is as None.

owner : ClientUserBase or int, Optional (Keyword only)

The new owner of the guild. You must be the owner of the guild to transfer ownership.

region : VoiceRegion, Optional (Keyword only)

The new voice region of the guild.

afk_timeout : int, Optional (Keyword only)

The new afk timeout for the users at the guild's afk channel.

Can be one of: 60, 300, 900, 1800, 3600.

verification_level : VerificationLevel or int, Optional (Keyword only)

The new verification level of the guild.

content_filter : ContentFilterLevel or int, Optional (Keyword only)

The new content filter level of the guild.

message_notification : MessageNotificationLevel, Optional (Keyword only)

The new message notification level of the guild.

description : None or str instance, Optional (Keyword only)

The new description of the guild. By passing None, or an empty string you can remove the current one. The guild must be a Community guild.

preferred_locale : str, Optional (Keyword only)

The guild's preferred locale. The guild must be a Community guild.

system_channel_flags : SystemChannelFlag, Optional (Keyword only)

The guild's system channel's new flags.

add_feature : (str, GuildFeature) or (iterable of (str, GuildFeature)), Optional (Keyword only)

Guild feature(s) to add to the guild.

If guild is given as an id, then add_feature should contain all the features of the guild to set.

remove_feature : (str, GuildFeature) or (iterable of (str, GuildFeature)), Optional (Keyword only)

Guild feature(s) to remove from the guild's.

boost_progress_bar_enabled : bool, Optional (Keyword only)

Whether the guild has the boost progress bar should be enabled.

reason : None or str, Optional (Keyword only)

Shows up at the guild's audit logs.

Raises

TypeError

  • If guild was not given neither as Guild or str instance.
  • If icon, invite_splash, discovery_splash, banner is neither None or bytes-like.
  • If add_feature or remove_feature was not given neither as str, as GuildFeature or as as iterable of str or GuildFeature instances.
  • If afk_channel was given, but not as None, ChannelVoice, neither as int instance.
  • If system_channel, rules_channel or public_updates_channel was given, but not as None, ChannelText, neither as int instance.
  • If owner was not given neither as ClientUserBase or int instance.
  • If region was given neither as VoiceRegion or str instance.
  • If verification_level was not given neither as VerificationLevel or int instance.
  • If content_filter was not given neither as ContentFilterLevel or int instance.
  • If description was not given either as None or str instance.

AssertionError

  • If icon, invite_splash, discovery_splash or banner was passed as bytes-like, but it's format is not any of the expected formats.
  • If banner was given meanwhile the guild has no BANNER feature.
  • If rules_channel, description, preferred_locale or public_updates_channel was passed meanwhile the guild is not Community guild.
  • If owner was passed meanwhile the client is not the owner of the guild.
  • If afk_timeout was passed and not as one of: 60, 300, 900, 1800, 3600.
  • If name is shorter than 2 or longer than 100 characters.
  • If discovery_splash was given meanwhile the guild is not discoverable.
  • If invite_splash was passed meanwhile the guild has no INVITE_SPLASH feature.
  • If name was not given as str instance.
  • If afk_timeout was not given as int instance.
  • If system_channel_flags was not given as SystemChannelFlag or as other int instance.
  • If preferred_locale was not given as str instance.
  • If boost_progress_bar_enabled was not given as bool instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_get

Gets or updates the guild.

The client must be in the guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to request.

Returns

guild : Guild

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

guild_get_all

Requests all the guilds of the client.

This method is a coroutine.

Returns

guilds : list of Guild

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If the client finished starting up, all the guilds should be already loaded.

guild_leave

The client leaves the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild from where the client will leave.

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_preview_get

Requests the preview of a public guild.

This method is a coroutine.

Parameters

guild : Guild or int

The id of the guild, what's preview will be requested

Returns

preview : GuildPreview

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_prune

Kicks the members of the guild which were inactive since x days.

This method is a coroutine.

Parameters

guild : Guild or int instance

Where the pruning will be executed.

days : int

The amount of days since at least the users need to inactive. Can be in range [1:30].

roles : None or list of (Role or int instances), Optional (Keyword only)

By default pruning will kick only the users without any roles, but it can defined which roles to include.

count : bool, Optional (Keyword only)

Whether the method should return how much user were pruned, but if the guild is large it will be set to False anyways. Defaults to False.

reason : None or str, Optional (Keyword only)

Will show up at the guild's audit logs.

Returns

count : None or int

The number of pruned users or None if count is set to False.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If roles contain not Role, neither int element.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If roles was given neither as None or as list.
  • If count was not given as bool instance.
  • If days was not given as int instance.
  • If days is out of range [1:30].

See Also

.guild_prune_estimate: Returns how much user would be pruned if .guild_prune would be called.

guild_prune_estimate

Returns the amount users, who would been pruned, if .guild_prune would be called.

This method is a coroutine.

Parameters

guild : Guild or int instance.

Where the counting of prunable users will be done.

days : int

The amount of days since at least the users need to inactive. Can be in range [1:30].

roles : None or list of Role objects, Optional (Keyword only)

By default pruning would kick only the users without any roles, but it can be defined which roles to include.

Returns

count : int

The amount of users who would be pruned.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If roles contain not Role, neither int element.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If roles was given neither as None or as list.
  • If days was not given as int instance.
  • If days is out of range [1:30].

guild_sync

Syncs a guild by it's id with the wrapper. Used internally if de-sync is detected when parsing dispatch events.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to sync.

Returns

guild : Guild

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_sync_channels

Requests the given guild's channels and if there any de-sync between the wrapper and Discord, applies the changes.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's channels will be requested.

Raises

TypeError

If guild was not given neither as Guild, nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_sync_emojis

Syncs the given guild's emojis with the wrapper.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, what's emojis will be synced.

Raises

TypeError

If guild was not given neither as Guild nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_sync_roles

Requests the given guild's roles and if there any de-sync between the wrapper and Discord, applies the changes.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's roles will be requested.

Raises

TypeError

If guild was not given neither as Guild, nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_sync_stickers

Syncs the given guild's stickers with the wrapper.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, what's stickers will be synced.

Raises

TypeError

If guild was not given neither as Guild nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_thread_get_all_active

Gets all the active threads of the given guild.

This method is a coroutine.

Parameters

guild : Guild, int

The guild to get it's threads of.

Returns

threads : list of ChannelThread

Raises

TypeError

If guild is neither Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_add

Adds the passed to the guild. The user must have granted you the 'guilds.join' oauth2 scope.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, where the user is going to be added.

access: OA2Access, UserOA2 or str instance

The access of the user, who will be added.

user : ClientUserBase or int, Optional

Defines which user will be added to the guild. The access must refer to this specified user.

This field is optional if access is passed as an UserOA2 object.

nick : str, Optional (Keyword only)

The nickname, which with the user will be added.

roles : None or list of (Role or int, Optional (Keyword only)

The roles to add the user with.

mute : bool, Optional (Keyword only)

Whether the user should be added as muted.

deaf : bool, Optional (Keyword only)

Whether the user should be added as deafen.

Raises

TypeError:

  • If user was not given neither as None, ClientUserBase or int instance.
  • If user was passed as None and access was passed as OA2Access or as str instance.
  • If access was not given as OA2Access, UserOA2, nether as str instance.
  • If the given access not grants 'guilds.join' scope.
  • If guild was not given neither as Guild, not int instance.
  • If roles contain not Role, nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If user and access refers to a different user.
  • If the nick's length is over 32.
  • If the nick was not given neither as None or str instance.
  • If mute was not given as bool instance.
  • If deaf was not given as bool instance.
  • If roles was not given neither as None or list.

guild_user_delete

Removes the given user from the guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild from where the user will be removed.

user : ClientUserBase or int instance

The user to delete from the guild.

reason : None or str, Optional (Keyword only)

Shows up at the guild's audit logs.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If user was not given neither as ClientUserBase, nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_get

Gets an user and it's profile at a guild. The user must be the member of the guild. If the user is already loaded updates it.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, where the user is.

user : ClientUserBase or int

The user's id, who will be requested.

Returns

user : ClientUserBase

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int instance.
  • If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_get_all

Requests all the users of the guild and returns them.

This method is a coroutine.

Parameters

guild : Guild or int

The guild what's users will be requested.

Returns

users : list of ClientUserBase objects

Raises

TypeError

If guild was not given neither as Guild, nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If user caching is allowed, these users should be already loaded if the client finished starting up. This method takes a long time to finish for huge guilds.

When using it with user account, the client's token will be invalidated.

guild_user_search

Gets an user and it's profile at a guild by it's name. If the users are already loaded updates it.

This method is a coroutine.

Parameters

guild : Guild

The guild, where the user is.

query : name

The query string with what the user's name or nick should start.

limit : int, Optional

The maximal amount of users to return. Can be in range [1:1000], defaults to 1.

Returns

users : list of ClientUserBase

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If query was not given as str instance.
  • If query 's length is out of the expected range [1:32].
  • If limit was not given as str instance.
  • If limit is out fo expected range [1:1000].

guild_voice_region_get_all

Requests the available voice regions for the given guild and returns them and the optional ones.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild, what's regions will be requested.

Returns

voice_regions : list of VoiceRegion objects

The available voice regions for the guild.

optimals : list of VoiceRegion objects

The optimal voice regions for the guild.

Raises

TypeError

If guild was not given neither as Guild, nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_widget_get

Returns the guild's widget.

This method is a coroutine.

Parameters

guild : Guild or int instance

The guild or the guild's id, what's widget will be requested.

Returns

guild_widget : None or GuildWidget

If the guild has it's widget disabled returns None instead.

Raises

TypeError

If guild was not passed neither as Guild or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

has_higher_role_than

Returns whether the user has higher role than the given role at it's respective guild.

If the user is the owner of the guild, then returns True even if it has lower role.

Parameters

role : Role

The role to check.

Returns

has_higher_role_than : bool

has_higher_role_than_at

Returns whether the user has higher role as the other one at the given guild.

Parameters

user : User

The other user to check.

guild : Guild or None

The guild where the users' top roles will be checked.

Can be given as None.

Returns

has_higher_role_than_at : bool

has_role

Returns whether the user has the given role.

Parameters

role : Role

The role what will be checked.

Returns

has_role : bool

hypesquad_house_change

Changes the client's hypesquad house.

This method is a coroutine.

Parameters

house : int or HypesquadHouse instance

The hypesquad house to join.

Raises

TypeError

house was not given as int neither as HypesquadHouse instance.

Notes

User account only.

hypesquad_house_leave

Leaves the client from it's current hypesquad house.

This method is a coroutine.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

User account only.

integration_create

Creates an integration at the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild to what the integration will be attached to.

integration_id : int

The integration's id.

type_ : str

The integration's type ('twitch', 'youtube', etc.).

Returns

integration : Integration

The created integrated.

Raises

TypeError

  • If guild was not given neither as Guild nor int instance.
  • If integration_id was not given as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If type_ is not given as str instance.

integration_delete

Deletes the given integration.

This method is a coroutine.

Parameters

integration : Integration

The integration what will be deleted.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If integration was not given as Integration instance.

integration_edit

Edits the given integration.

This method is a coroutine.

Parameters

integration : Integration

The integration to edit.

expire_behavior : None or int, Optional (Keyword only)

Can be 0 for kick or 1 for role remove.

expire_grace_period : None or int, Optional (Keyword only)

The time in days, after the subscription will be ignored. Can be any of (1, 3, 7, 14, 30).

enable_emojis : None or bool, Optional (Keyword only)

Whether the users can use the integration's emojis in Discord.

Raises

TypeError

  • If expire_behavior was not passed as int.
  • If expire_grace_period was not passed as int.
  • If enable_emojis was not passed as bool.

ValueError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If integration was not given as Integration instance.
  • If expire_behavior was not given neither as None nor as int instance.
  • If expire_grace_period was not given neither as None nor as int instance.
  • If expire_behavior is not any of: (0, 1).
  • If expire_grace_period is not any of (1, 3, 7, 14, 30).
  • If enable_emojis is neither None or bool instance.

integration_get_all

Requests the integrations of the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, what's integrations will be requested.

Returns

integrations : list of Integration

Raises

TypeError

If guild was not given neither as Guild nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

integration_sync

Sync the given integration's state.

This method is a coroutine.

Parameters

integration : Integration

The integration to sync.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If integration was not given as Integration instance.

interaction_application_command_acknowledge

Acknowledges the given application command interaction.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction to acknowledge

show_for_invoking_user_only : bool, Optional (Keyword only)

Whether the sent message should only be shown to the invoking user. Defaults to False.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If interaction was not given an InteractionEvent.

Notes

If the interaction is already timed or out or was used, you will get:

DiscordException Not Found (404), code=10062: Unknown interaction

interaction_application_command_autocomplete

Forwards auto completion choices for the user.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction to acknowledge

choices : None or iterable of str

Choices to show for the user.

Raises

TypeError

If choice is neither None nor iterable.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If interaction was not given an InteractionEvent.

Notes

If the interaction is already timed or out or was used, you will get:

DiscordException Not Found (404), code=10062: Unknown interaction

interaction_component_acknowledge

Acknowledges the given component interaction.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction to acknowledge

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If interaction was not given an InteractionEvent.

Notes

If the interaction is already timed or out or was used, you will get:

DiscordException Not Found (404), code=10062: Unknown interaction

interaction_component_message_edit

Edits the given component interaction's source message.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction, what's source response message will be edited.

content : str, EmbedBase or Any, Optional

The new content of the message.

If given as EmbedBase instance, then the message's embeds will be edited with it.

embed : None, EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The new embedded content of the message. By passing it as None, you can remove the old.

If embed and content parameters are both given as EmbedBase instance, then AssertionError is raised.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

Raises

TypeError

  • If allowed_mentions contains an element of invalid type.
  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.

ValueError

If allowed_mentions 's elements' type is correct, but one of their value is invalid.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

interaction_followup_message_create

Sends a followup message with the given interaction.

When calling .interaction_followup_message_create before calling .interaction_response_message_create on an interaction, will redirect to .interaction_response_message_create and drop a warning.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction to create followup message with.

content : str, EmbedBase, Any, Optional

The message's content if given. If given as str or empty string, then no content will be sent, meanwhile if any other non str or EmbedBase instance is given, then will be casted to string.

If given as EmbedBase instance, then is sent as the message's embed.

embed : EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The embedded content of the message.

If embed and content parameters are both given as EmbedBase instance, then TypeError is raised.

file : Any, Optional

A file to send. Check create_file_form for details.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of ComponentBase), Optional (Keyword only)

Components attached to the message.

components do not count towards having any content in the message.

tts : bool, Optional (Keyword only)

Whether the message is text-to-speech. Defaults to False.

show_for_invoking_user_only : bool, Optional (Keyword only)

Whether the sent message should only be shown to the invoking user. Defaults to False.

If given as True only the message's content, embeds and components will be processed by Discord.

Returns

message : None or Message

Returns None if there is nothing to send.

Raises

TypeError

  • If allowed_mentions contains an element of invalid type.
  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.
  • If invalid file type would be sent.
  • If components type is incorrect.

ValueError

  • If allowed_mentions 's elements' type is correct, but one of their value is invalid.
  • If more than 10 files would be sent.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.
  • If tts was not given as bool instance.
  • If show_for_invoking_user_only was not given as bool instance.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

interaction_followup_message_delete

Deletes an interaction's followup message.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction with what the followup message was sent with.

message : Message or MessageRepr, int instance

The interaction followup's message to edit.

Raises

TypeError

If message was not given neither as Message, MessageRepr or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.

interaction_followup_message_edit

Edits the given interaction followup message.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction with what the followup message was sent with.

message : Message or MessageRepr, int instance

The interaction followup's message to edit.

content : str, EmbedBase or Any, Optional

The new content of the message.

If given as str then the message's content will be edited with it. If given as any non EmbedBase instance, then it will be cased to string first.

By passing it as empty string, you can remove the message's content.

If given as EmbedBase instance, then the message's embeds will be edited with it.

embed : None, EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The new embedded content of the message. By passing it as None, you can remove the old.

If embed and content parameters are both given as EmbedBase instance, then TypeError is raised.

file : Any, Optional (Keyword only)

A file or files to send. Check create_file_form for details.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of

ComponentBase), Optional (Keyword only)

Components attached to the message.

Pass it as None remove the actual ones.

Raises

TypeError

  • If allowed_mentions contains an element of invalid type.
  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.
  • If message was not given neither as Message, MessageRepr or int instance.

ValueError

If allowed_mentions 's elements' type is correct, but one of their value is invalid.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

Notes

Cannot editing interaction messages, which were created with show_for_invoking_user_only=True:

DiscordException Not Found (404), code=10008: Unknown Message

interaction_followup_message_get

Gets a previously sent message with an interaction.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction with what the followup message was sent with.

message_id : int

The webhook's message's identifier to get.

Returns

message : Message

Raises

TypeError

  • If message_id was not given as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.

interaction_response_message_create

Sends an interaction response. After receiving an InteractionEvent, you should acknowledge it within 3 seconds to perform followup actions.

Not like .message_create, this endpoint can be called without any content to still acknowledge the interaction event. This method also wont return a Message object (thank to Discord), but at least .interaction_followup_message_create will. To edit or delete this message, you can use .interaction_response_message_edit and interaction_response_message_delete.

When calling .interaction_response_message_create multiple time on the same interaction, will redirect to .interaction_followup_message_create or to .interaction_response_message_edit depending whether the interaction event was just deferred, and drop a warning.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction to respond to.

content : str, EmbedBase, Any, Optional

The interaction response's content if given. If given as str or empty string, then no content will be sent, meanwhile if any other non str or EmbedBase instance is given, then will be casted to string.

If given as EmbedBase instance, then is sent as the message's embed.

embed : EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The embedded content of the interaction response.

If embed and content parameters are both given as EmbedBase instance, then AssertionError is raised.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of ComponentBase), Optional (Keyword only)

Components attached to the message.

components do not count towards having any content in the message.

tts : bool, Optional (Keyword only)

Whether the message is text-to-speech.

show_for_invoking_user_only : bool, Optional (Keyword only)

Whether the sent message should only be shown to the invoking user. Defaults to False.

Raises

TypeError

  • If allowed_mentions contains an element of invalid type.
  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.
  • If components type is incorrect.

ValueError

If allowed_mentions 's elements' type is correct, but one of their value is invalid.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given an InteractionEvent.
  • If tts was not given as bool instance.
  • If show_for_invoking_user_only was not given as bool instance.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

Notes

Discord do not returns message data, so the method cannot return a Message either.

If the interaction is already timed or out or was used, you will get:

DiscordException Not Found (404), code=10062: Unknown interaction

interaction_response_message_delete

Deletes the given interaction 's source response message.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction, what's source response message will be deleted.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.

interaction_response_message_edit

Edits the given interaction 's source response. If the source interaction event was only deferred, this call will send the message as well.

When calling .interaction_response_message_edit before interaction_response_message_create will redirect to .interaction_response_message_create and drop a warning.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction, what's source response message will be edited.

content : str, EmbedBase or Any, Optional

The new content of the message.

If given as EmbedBase instance, then the message's embeds will be edited with it.

embed : None, EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The new embedded content of the message. By passing it as None, you can remove the old.

If embed and content parameters are both given as EmbedBase instance, then AssertionError is raised.

file : Any, Optional (Keyword only)

A file or files to send. Check create_file_form for details.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of

ComponentBase), Optional (Keyword only)

Components attached to the message.

Pass it as None remove the actual ones.

Raises

TypeError

  • If allowed_mentions contains an element of invalid type.
  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.

ValueError

If allowed_mentions 's elements' type is correct, but one of their value is invalid.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

Notes

Cannot editing interaction messages, which were created with show_for_invoking_user_only=True:

DiscordException Not Found (404), code=10008: Unknown Message

interaction_response_message_get

Gets the given interaction 's source response message.

This method is a coroutine.

Parameters

interaction : InteractionEvent

Interaction, what's source response message will be deleted.

Returns

message : Message

The created message.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If interaction was not given as InteractionEvent.
  • If the client's application is not yet synced.

invite_create

Creates an invite at the given channel with the given parameters.

This method is a coroutine.

Parameters

channel : ChannelText, ChannelVoice, ChannelGroup, ChannelStore, ChannelDirectory, int

The channel of the created invite.

max_age : int, Optional (Keyword only)

After how much time (in seconds) will the invite expire. Defaults is never.

max_uses : int, Optional (Keyword only)

How much times can the invite be used. Defaults to unlimited.

unique : bool, Optional (Keyword only)

Whether the created invite should be unique. Defaults to True.

temporary : bool, Optional (Keyword only)

Whether the invite should give only temporary membership. Defaults to False.

Returns

invite : Invite

Raises

TypeError

If channel was not given neither as ChannelText, ChannelVoice, ChannelGroup,

ChannelStore, ChannelDirectory, neither as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If max_age was not given as int instance.
  • If max_uses was not given as int instance.
  • If unique was not given as bool instance.
  • If temporary was not given as bool instance.

invite_create_preferred

Creates an invite to the guild's preferred channel.

This method is a coroutine.

Parameters

guild . Guild

The guild to her the invite will be created to.

**kwargs : Keyword parameters

Additional keyword parameters to describe the created invite.

Other Parameters

max_age : int, Optional (Keyword only)

After how much time (in seconds) will the invite expire. Defaults is never.

max_uses : int, Optional (Keyword only)

How much times can the invite be used. Defaults to unlimited.

unique : bool, Optional (Keyword only)

Whether the created invite should be unique. Defaults to True.

temporary : bool, Optional (Keyword only)

Whether the invite should give only temporary membership. Defaults to False.

Returns

invite : Invite

Raises

ValueError

If the guild has no channel to create invite to.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If guild was not given as Guild instance.
  • If max_age was not given as int instance.
  • If max_uses was not given as int instance.
  • If unique was not given as bool instance.
  • If temporary was not given as bool instance.

invite_delete

Deletes the given invite.

This method is a coroutine.

Parameters

invite : Invite

The invite to delete.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If invite was not given neither Invite nor str instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_get

Requests a partial invite with the given code.

This method is a coroutine.

Parameters

invite : Invite, str

The invites code.

with_count : bool, Optional (Keyword only)

Whether the invite should contain the respective guild's user and online user count. Defaults to True.

Returns

invite : Invite

Raises

TypeError

If invite was not given neither Invite nor str instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If invite_code was not given as str instance. If with_count was not given as bool instance.

invite_get_all_channel

Gets the invites of the given channel.

This method is a coroutine.

Parameters

channel : ChannelText, ChannelVoice, ChannelGroup, ChannelStore, ChannelDirectory, int

The channel, what's invites will be requested.

Returns

invites : list of Invite objects

Raises

TypeError

If channel was not given neither as ChannelText, ChannelVoice, ChannelGroup, ChannelStore, ChannelDirectory, neither as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_get_all_guild

Gets the invites of the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild, what's invites will be requested.

Returns

invites : list of Invite objects

Raises

TypeError

If guild was not given neither as Guild nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

is_owner

Returns whether the passed user is one of the client's owners.

Parameters

user : ClientUserBase

The user who will be checked.

Returns

is_owner : bool

iter_guild_profiles

Iterates over the guild profiles of the user.

This method is an iterable generator.

Yields

guild : Guild

The guild profile's guild.

guild_profile : GuildProfile

The user's guild profile in the guild.

join_audience

Moves the client to the audience inside of the stage channel. The client must be in the stage channel.

This method is a coroutine.

Parameters

channel : ChannelStage or tuple(int, int)

The stage channel to join.

Raises

RuntimeError

If channel is partial.

TypeError

If channel was not given neither as ChannelStage nor as tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

join_speakers

Request to speak or joins the client as a speaker inside of a stage channel. The client must be in the stage channel.

This method is a coroutine.

Parameters

channel : ChannelStage

The stage channel to join.

request : bool, Optional (Keyword only)

Whether the client should only request to speak.

Raises

TypeError

If channel was not given neither as ChannelStage nor as tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

join_voice

Joins a voice client to the channel. If there is an already existing voice client at the respective guild, moves it.

If not every library is installed, raises RuntimeError, or if the voice client fails to connect raises TimeoutError.

This method is a coroutine.

Parameters

channel : ChannelVoiceBase or tuple(int, int)

The channel to join to.

Returns

voice_client : VoiceClient

Raises

RuntimeError

If not every library is installed to join voice.

TimeoutError

If voice client fails to connect the given channel.

TypeError

If channel was not given neither as ChannelVoiceBase nor as tuple(int, int).

keep_typing

Returns a context manager which will keep sending typing events at the channel. Can be used to indicate that the bot is working.

Parameters

channel ChannelTextBase or int instance

The channel where typing will be triggered.

timeout : float, Optional

The maximal duration for the Typer to keep typing.

Returns

typer : Typer

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

Examples

with client.keep_typing(channel):
# Do some things
await client.message_create(channel, 'Ayaya')

mentioned_in

Returns whether the user is mentioned at a given message.

Parameters

message : Message

The message, what's mentions will be checked.

Returns

mentioned : bool

message_create

Creates and returns a message at the given channel. If there is nothing to send, then returns None.

This method is a coroutine.

Parameters

channel : ChannelTextBase instance, int instance, Message, MessageRepr, MessageReference, tuple(int, int)

The text channel where the message will be sent, or the message on what you want to reply.

content : str, EmbedBase, Any, Optional

The message's content if given. If given as str or empty string, then no content will be sent, meanwhile if any other non str or EmbedBase instance is given, then will be casted to string.

If given as EmbedBase instance, then is sent as the message's embed.

embed : EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The embedded content of the message.

If embed and content parameters are both given as EmbedBase instance, then TypeError is raised.

If embeds are given as a list, then the first embed is picked up.

file : Any, Optional (Keyword only)

A file or files to send. Check create_file_form for details.

sticker : None, Sticker, int, (list, set, tuple) of (Sticker, int)

Sticker or stickers to send within the message.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of ComponentBase), Optional (Keyword only)

Components attached to the message.

components do not count towards having any content in the message.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

reply_fail_fallback : bool, Optional (Keyword only)

Whether normal message should be sent if the referenced message is deleted. Defaults to False.

tts : bool, Optional (Keyword only)

Whether the message is text-to-speech.

nonce : str, Optional (Keyword only)

Used for optimistic message sending. Will shop up at the message's data.

Returns

message : Message or None

Returns None if there is nothing to send.

Raises

TypeError

  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If allowed_mentions contains an element of invalid type.
  • content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.
  • If invalid file type would be sent.
  • If channel 's type is incorrect.
  • If sticker was not given neither as None, Sticker, int, (list, tuple) of (Sticker, int).
  • If components type is incorrect.

ValueError

  • If allowed_mentions 's elements' type is correct, but one of their value is invalid.
  • If more than 10 files would be sent.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If tts was not given as bool instance.
  • If nonce was not given neither as None nor as str instance.
  • If reply_fail_fallback was not given as bool instance.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

See Also

.webhook_message_create: Sending a message with a Webhook.

message_crosspost

Crossposts the given message. The message's channel must be an announcements (type 5) channel.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message to crosspost.

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference nor as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_delete

Deletes the given message.

This method is a coroutine.

Parameters

message : Message, MessageReference, MessageRepr, tuple(int, int)

The message to delete.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If message was not given neither as Message, MessageReference, MessageRepr, neither as tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

The rate limit group is different for own or for messages newer than 2 weeks than for message's of others, which are older than 2 weeks.

message_delete_multiple

Deletes the given messages. The messages can be from different channels as well.

This method is a coroutine.

Parameters

messages : (list, set, tuple) of (Message, MessageReference, MessageRepr, tuple(int, int))

The messages to delete.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If a message was not given neither as Message, MessageReference, MessageRepr, neither as tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If messages was not given neither as list, set nor as tuple instance.

Notes

This method uses up 3 different rate limit groups parallelly to maximize the deletion speed.

message_delete_sequence

Deletes messages between an interval determined by before and after. They can be passed as int, or as a DiscordEntity instance or as a datetime object.

If the client has no manage_messages permission at the channel, then returns instantly.

This method is a coroutine.

Parameters

channel : ChannelTextBase instance

The channel, where the deletion should take place.

after : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp after the messages were created, which will be deleted.

before : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp before the messages were created, which will be deleted.

limit : int, Optional (Keyword only)

The maximal amount of messages to delete.

filter : callable, Optional (Keyword only)

A callable filter, what should accept a message object as parameter and return either True or False.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If after or before was passed with an unexpected type.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If channel was not given as ChannelTextBase instance.

Notes

This method uses up 4 different rate limit groups parallelly to maximize the request and the deletion speed.

message_edit

Edits the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message to edit.

content : str, EmbedBase or Any, Optional

The new content of the message.

If given as str then the message's content will be edited with it. If given as any non EmbedBase instance, then it will be cased to string first.

If given as EmbedBase instance, then the message's embeds will be edited with it.

embed : None, EmbedBase instance or list of EmbedBase instances, Optional (Keyword only)

The new embedded content of the message. By passing it as None, you can remove the old.

If embed and content parameters are both given as EmbedBase instance, then AssertionError is raised.

If embeds are given as a list, then the first embed is picked up.

file : Any, Optional (Keyword only)

A file or files to send. Check create_file_form for details.

allowed_mentions : None, str, UserBase, Role, list of (str, UserBase, Role) , Optional (Keyword only)

Which user or role can the message ping (or everyone). Check parse_allowed_mentions for details.

components : None, ComponentBase, (tuple, list) of (ComponentBase, (tuple, list) of ComponentBase), Optional (Keyword only)

Components attached to the message.

Pass it as None remove the actual ones.

suppress : bool, Optional (Keyword only)

Whether the message's embeds should be suppressed or unsuppressed.

Raises

TypeError

  • If embed was not given neither as EmbedBase nor as list or tuple of EmbedBase instances.
  • If allowed_mentions contains an element of invalid type.
  • content parameter was given as EmbedBase instance, meanwhile embed parameter was given as well.
  • If message 's type is incorrect.
  • If components type is incorrect.

ValueError

  • If allowed_mentions contains an element of invalid type.
  • If more than 10 files would be sent.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If suppress was not given as bool instance.
  • If embed contains a non EmbedBase element.
  • If both content and embed fields are embeds.

Notes

Do not updates he given message object, so dispatch event events can still calculate differences when received.

See Also

message_get

Requests a specific message by it's id at the given channel.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance

The channel from where we want to request the message.

message_id : int

The message's id.

Returns

message : Message

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance. If message_id was not given as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_get_all_in_range

Returns a list of the message between the start- end area. If the client has no permission to request messages, or there are no messages at the given area returns an empty list.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance

The channel from were the messages will be requested.

start : int, Optional

The first message's index at the channel to be requested. Defaults to 0.

end : int

The last message's index at the channel to be requested. Defaults to 100.

Returns

messages : list of Message objects

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If start was not given as int instance.
  • If start is out of range [0:].
  • If end was not given as int instance.
  • If end is out of range [0:].

message_get_at_index

Returns the message at the given channel at the specific index. Can be used to load index amount of messages at the channel.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance.

The channel from were the messages will be requested.

index : int

The index of the target message.

Returns

message : Message object

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If index was not given as int instance.
  • If index is out of range [0:].

message_get_chunk

Requests messages from the given text channel. The after, around and the before parameters are mutually exclusive and they can be passed as int, or as a DiscordEntity instance or as a datetime object. If there is at least 1 message overlap between the received and the loaded messages, the wrapper will chain the channel's message history up. If this happens the channel will get on a queue to have it's messages again limited to the default one, but requesting old messages more times, will cause it to extend.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance

The channel from where we want to request the messages.

limit : int, Optional

The amount of messages to request. Can be between 1 and 100.

after : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp after the requested messages were created.

around : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp around the requested messages were created.

before : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp before the requested messages were created.

Returns

messages : list of Message objects

Raises

TypeError

  • If channel was not given neither as ChannelTextBase nor int instance.
  • If after, around or before was passed with an unexpected type.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If limit was not given as int instance.
  • If limit is out of range [1:100].

See Also

  • .message_get_chunk_from_zero: Familiar to this method, but it requests only the newest messages of the channel and makes sure they are chained up with the channel's message history.
  • .message_get_at_index: A top-level method to get a message at the specified index at the given channel. Usually used to load the channel's message history to that point.
  • .message_get_all_in_range: A top-level method to get all the messages till the specified index at the given channel.
  • .message_iterator: An iterator over a channel's message history.

message_get_chunk_from_zero

If the channel has 1 or less messages loaded use this method instead of .message_get_chunk to request the newest messages there, because this method makes sure, the returned messages will be chained at the channel's message history.

This method is a coroutine.

Parameters

channel : ChannelTextBase instance

The channel from where we want to request the messages.

limit : int, Optional

The amount of messages to request. Can be between 1 and 100.

Returns

messages : list of Message objects

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If limit was not given as int instance.
  • If limit is out of range [1:100].

message_iterator

Returns an asynchronous message iterator over the given text channel.

This method is a coroutine.

Parameters

channel : ChannelTextBase or int instance

The channel from were the messages will be requested.

chunk_size : int, Optional (Keyword only)

The amount of messages to request when the currently loaded history is exhausted. For message chaining it is preferably 99.

Returns

message_iterator : MessageIterator

Raises

TypeError

If channel was not given neither as ChannelTextBase nor int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If chunk_size was not given as int instance.
  • If chunk_size is out of range [1:].

message_pin

Pins the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message to pin.

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference nor as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_suppress_embeds

Suppresses or unsuppressed the given message's embeds.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message, what's embeds will be (un)suppressed.

suppress : bool, Optional

Whether the message's embeds would be suppressed or unsuppressed.

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If suppress was not given as bool instance.

message_unpin

Unpins the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message to unpin.

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference nor as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

multi_client_message_delete_sequence

Deletes messages between an interval determined by before and after. They can be passed as int, or as a DiscordEntity instance or as a datetime object.

Not like .message_delete_sequence, this method uses up all he clients at the respective channel to delete messages an not only the one from what it was called from.

If non of the clients have manage_messages permission, then returns instantly.

This method is a coroutine.

Parameters

channel : ChannelTextBase instance

The channel, where the deletion should take place.

after : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp after the messages were created, which will be deleted.

before : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp before the messages were created, which will be deleted.

limit : int, Optional (Keyword only)

The maximal amount of messages to delete.

filter : callable, Optional (Keyword only)

A callable filter, what should accept a message object as parameter and return either True or False.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If after or before was passed with an unexpected type.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If channel is not ChannelTextBase instance.

Notes

This method uses up to 4 different endpoint groups too as .message_delete_sequence, but tries to parallelize the them between more clients as well.

name_at

Returns the user's name at the given guild.

Parameters

guild : None or Guild

The guild, where the user's nick will be checked.

Can be given as None.

Returns

name : str

owners_access

Similar to .activate_authorization_code, but it requests the application's owner's access. It does not requires the redirect_url and the code parameter either.

This method is a coroutine.

Parameters

scopes : list of str

A list of oauth2 scopes to request.

Returns

access : OA2Access

The oauth2 access of the client's application's owner.

Raises

TypeError

If Scopes is neither str nor list of str instances.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If redirect_url was not given as str instance.
  • If code was not given as str instance.
  • If scopes is empty.
  • If scopes contains empty string.

Notes

Does not work if the client's application is owned by a team.

permission_overwrite_create

Creates a permission overwrite at the given channel.

This method is a coroutine.

Parameters

channel : ChannelGuildMainBase or int instance

The channel to what the permission overwrite will be added.

target : Role, ClientUserBase instance

The permission overwrite's target.

allow : Permission or int instance

The permission overwrite's allowed permission's value.

deny : Permission or int instance

The permission overwrite's denied permission's value.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Returns

permission_overwrite : PermissionOverwrite

A permission overwrite, what estimatedly is same as the one what Discord will create.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If allow was not given neither as Permission nor as other int instance.
  • If deny was not given neither as Permission not as other int instance.

permission_overwrite_delete

Deletes the given permission overwrite.

This method is a coroutine.

Parameters

channel : ˙˙ChannelGuildMainBase instance

The channel where the permission overwrite is.

permission_overwrite : PermissionOverwrite

The permission overwrite to delete.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If channel was not given neither as ChannelGuildMainBase nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If permission_overwrite was not given as PermissionOverwrite instance.

permission_overwrite_edit

Edits the given permission overwrite.

This method is a coroutine.

Parameters

channel : ˙˙ChannelGuildMainBase or int instance

The channel where the permission overwrite is.

permission_overwrite : PermissionOverwrite

The permission overwrite to edit.

allow : None, Permission or int, Optional (Keyword only)

The permission overwrite's new allowed permission's value.

deny : None, Permission or int, Optional (Keyword only)

The permission overwrite's new denied permission's value.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If channel was not given neither as ChannelGuildMainBase nor as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If permission_overwrite was not given as PermissionOverwrite instance.
  • If allow was not given neither as None, Permission not other int instance.
  • If deny was not given neither as None, Permission not other int instance.

reaction_add

Adds a reaction on the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message on which the reaction will be put on.

emoji : Emoji or str

The emoji to react with.

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference nor as tuple(int, int) instance.
  • If emoji 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_clear

Removes all the reactions from the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message from which the reactions will be cleared.

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete

Removes the specified reaction of the user from the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message from which the reaction will be removed.

emoji : Emoji or str

The emoji to remove.

user : ClientUserBase or int instance

The user, who's reaction will be removed.

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.
  • If user was not given neither as ClientUserBase nor int instance.
  • If emoji was not given as Emoji or str instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete_emoji

Removes all the reaction of the specified emoji from the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message from which the reactions will be removed.

emoji : Emoji or str

The reaction to remove.

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.
  • If emoji 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete_own

Removes the specified reaction of the client from the given message.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message from which the reaction will be removed.

emoji : Emoji or str

The emoji to remove.

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.
  • If emoji 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_get_all

Requests all the reactors for every emoji on the given message.

Like the other reaction getting methods, this method prefers using the internal cache as well over doing a request.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message, what's reactions will be requested.

Returns

message : Message

Raises

TypeError

If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_user_get_all

Requests the all the users, which reacted on the message with the given message.

If the message has no reactors at all or no reactors with that emoji returns an empty list. If the emoji's every reactors are known, then do requests are done.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message, what's reactions will be requested.

emoji : Emoji, str

The emoji, what's reactors will be requested.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.
  • If emoji 's type is incorrect.

ValueError

The given emoji is not a valid reaction.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_user_get_chunk

Requests the users, who reacted on the given message with the given emoji.

If the message has no reactors at all or no reactors with that emoji, returns an empty list. If we know the emoji's every reactors we query the parameters from that.

This method is a coroutine.

Parameters

message : Message, MessageRepr, MessageReference, tuple(int, int)

The message, what's reactions will be requested.

emoji : Emoji, str

The emoji, what's reactors will be requested.

limit : None or int, Optional (Keyword only)

The amount of users to request. Can be in range [1:100]. Defaults to 25 by Discord.

after : int, DiscordEntity or datetime, Optional (Keyword only)

The timestamp after the message's reactors were created.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If message was not given neither as Message, MessageRepr, MessageReference neither as tuple(int, int) instance.
  • If after was passed with an unexpected type.
  • If emoji 's type is incorrect.

ValueError

The given emoji is not a valid reaction.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If limit was not given neither as None or int instance.
  • If limit is out of the expected range [1:100].

Notes

before parameter is not supported by Discord.

relationship_create

Creates a relationship with the given user.

This method is a coroutine.

Parameters

user : ClientUserBase, int

The user with who the relationship will be created.

relationship_type : None, RelationshipType, int, Optional

The type of the relationship. Defaults to None.

Raises

TypeError

  • If user is not given neither as ClientUserBase or int instance.
  • If relationship_type was not given neither as None, RelationshipType neither as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint is available only for user accounts.

relationship_delete

Deletes the given relationship.

This method is a coroutine.

Parameters

relationship : Relationship, ClientUserBase or int

The relationship to delete. Also can be given the respective user with who the client hast he relationship with.

Raises

TypeError

If relationship was not given neither as Relationship, ClientUserBase not as int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint is available only for user accounts.

relationship_friend_request

Sends a friend request to the given user.

This method is a coroutine.

Parameters

user : ClientUserBase, int

The user, who will receive the friend request.

Raises

TypeError

If user was not given neither as ClientUserBase or int instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint is available only for user accounts.

remove_additional_owners

Removes additional owners added by the .add_additional_owners method.

Parameters

*users : int or UserBase instances

The .id of the a user or the user itself to be removed.

Raises

TypeError

A user was passed with invalid type.

renew_access_token

Renews the access token of an OA2Access.

This method is a coroutine.

Parameters

access : OA2Access or UserOA2

Oauth2 access to the respective user.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If access was not given neither as OA2Access or UserOA2 instance.

Notes

By default access tokens expire after one week.

request_members

Requests the members of the given guild by their name.

This method uses the client's gateway to request the users. If any of the parameters do not match their expected value or if timeout occurs, returns an empty list instead of raising.

This method is a coroutine.

Parameters

guild : Guild

The guild, what's members will be requested.

name : str

The received user's name or nick should start with this string.

limit : int

The amount of users to received. Limited to 100.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If guild was not given neither as Guild nor as int instance.

AssertionError

  • If limit is not int instance.
  • If limit is out of the expected range [1:100].
  • If name is not str instance.
  • If name length is out of the expected range [1:32].

role_create

Creates a role at the given guild.

This method is a coroutine.

Parameters

guild : Guild or int

The guild where the role will be created.

name : str, Optional (Keyword only)

The created role's name. It's length can be in range [2:32].

color : Color or int, Optional (Keyword only)

The created role's color.

separated : bool, Optional (Keyword only)

Whether the users with the created role should show up as separated from the others.

mentionable : bool, Optional (Keyword only)

Whether the created role should be mentionable.

permissions : Permission or int, Optional (Keyword only)

The permission value of the created role.

icon : None, Emoji or bytes-like, Optional (Keyword only)

The icon for the role.

reason : None or str, Optional (Keyword only)

Shows up at the guild's audit logs.

Raises

TypeError

  • If guild was not given neither as Guild nor as int instance.
  • If icon is neither None, Emoji, or bytes-like.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given neither as None nor str instance.
  • If name length is out of range [2:32].
  • If color was not given as None, Color nor as other int instance.
  • If separated was not given as None, nor as bool instance.
  • If mentionable was not given as None, nor as bool˛ instance.
  • If permissions was not given as None, Permission, neither as other int instance.
  • If icon is passed as bytes-like, but it's format is not a valid image format.

role_delete

Deletes the given role.

This method is a coroutine.

Parameters

role : Role or tuple(int, int)

The role to delete

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

If role was not given neither as Role nor as tuple of (int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

role_edit

Edits the role with the given parameters.

This method is a coroutine.

Parameters

role : Role or tuple(int, int)

The role to edit.

name : str, Optional (Keyword only)

The role's new name. It's length ca be in range [2:32].

color : None, Color or int, Optional (Keyword only)

The role's new color.

separated : None, bool, Optional (Keyword only)

Whether the users with this role should be shown up as separated from the others.

mentionable : None, bool, Optional (Keyword only)

Whether the role should be mentionable.

permissions : None, Permission or int, Optional (Keyword only)

The new permission value of the role.

position : None, int, Optional (Keyword only)

The role's new position.

icon : None, Emoji or bytes-like, Optional (Keyword only)

The new icon of the role. Can be 'jpg', 'png', 'webp' or 'gif' image's raw data.

Pass it as an Emoji to set role's icon to it.

Pass it as None to remove the role's current icon.

reason : None or str, Optional (Keyword only)

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If role was not given neither as Role nor as tuple of (int, int).
  • If icon is neither None or bytes-like.

ValueError

  • If default role would be moved.
  • If any role would be moved to position 0.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given neither as None nor str instance.
  • If name length is out of range [2:32].
  • If color was not given as None, Color nor as other int instance.
  • If separated was not given as None, nor as bool instance.
  • If mentionable was not given as None, nor as bool˛ instance.
  • If permissions was not given as None, Permission, neither as other int instance.
  • If icon was passed as bytes-like, but