Client

Discord client class used to interact with the Discord API.

Attributes

activities : None, list of Activity

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

Discord api client for lower level interactions with the Discord API.

application : Application

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

avatar_decoration : None, AvatarDecoration

The client's avatar decorations.

avatar_hash : int

The client's avatar's hash in uint128.

avatar_type : IconType

The client's avatar's type.

banner_color : None, 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.

bot : bool

Whether the client is a bot or a user account.

discriminator : int

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

display_name : None, str

The clients' non-unique display name.

email : None, str

The client's email.

email_verified : bool

Whether the email of the client is verified.

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.

group_channels : dict of (int, Channel) 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.

http : HttpClient

The http session of the client.

id : int

The client's unique identifier number.

intents : IntentFlag

The intent flags of the client.

locale : Locale

The preferred locale by the client.

mfa_enabled : bool

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

name : str

The client's username.

premium_type : PremiumType

The Nitro subscription type of the client.

private_channels : dict of (int, Channel) items

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

ready_state : None, ReadyState

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 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 : None, dict of (str, str) items

The client's statuses for each platform.

thread_profiles : None, dict(Channel, 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.

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 : Activity

The client's preferred activity.

_additional_owner_ids : None, set of int

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

_gateway_max_concurrency : int

The maximal amount of shards that 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, Future

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

_should_request_users : bool

Whether the client should try to request the users of it's guilds.

_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 types.
  • User: The default type of Discord users.
  • Webhook: Discord webhook entity.
  • WebhookRepr: Discord webhook's user representation.
  • Oauth2User: A user class with extended oauth2 attributes.

Properties

activity

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

Returns

activity : Activity, None

avatar

Returns the respective icon.

Returns

icon : Icon

avatar_decoration_url

Returns the user's avatar decoration's url. If the user has no avatar decoration returns None.

This function is a property of UserBase.

Returns

url : None, str

avatar_url

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

This function is a shared property of UserBase-s.

Returns

url : None, 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.

This function is a shared property of UserBase-s.

Returns

url : None, 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 : Activity, 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

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 > <.

mfa

Returns whether the user has multi factory authentication enabled.

This property is deprecated and will be removed in 2024 April. Please use mfa_enabled instead.

Returns

mfa_enabled : bool

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

plugins

Returns a list of plugins added to the client. Added by the plugin_loader plugin.

Returns

plugins : list of Plugin

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 '', 'web' will not be returned.

Methods

__new__(token, ...)

Creates a new Client with the given parameters.

ParameterTypeOptionalKeyword onlyDescription
token

str

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

activity

Activity

The client's preferred activity.

additional_owners

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

Additional users to return True for by .is_owner.

api

None | DiscordApiClient

The api client to use.

application_id

None, int, str

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

avatar

None, Icon, str

The client's avatar.

avatar_decoration

None, AvatarDecoration

The client's avatar decoration.

banner

None, Icon, str

The client's banner.

banner_color

None, Color, int

The client's banner color.

bot

bool

Whether the client is a bot user or a user account.

client_id

None, int, str

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.

discriminator

str, int

The client's discriminator.

display_name

None, str

The client's non-unique display name.

email

None, str

The client's email.

email_verified

bool

Whether the email of the client is verified.

extensions

None, str, iterable of str

The extension's name to setup on the client.

flags

int, UserFlag

The user's flags.

http

None | HTTPClient

The http client to use.

http_debug_options

None, str, iterable of str

Http client debug options for the client.

intents

int, IntentFlag

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.

locale

Locale, str

The preferred locale by the client.

mfa_enabled

bool

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

name

str

The user's name.

premium_type

PremiumType, int

The Nitro subscription type of the client.

secret

str

Client secret used when interacting with oauth2 endpoints.

shard_count

int

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

should_request_users

int

Whether the client should try to request the users of it's guilds.

status

None, str, Status

The client's preferred status.

**keyword_parameters

keyword parameters

Additional parameters to pass to extension setup functions.

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(name, description, icon, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
name

str

The achievement's name.

description

str

The achievement's description.

icon

bytes-like

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

description_localizations

None, dict of (str, str) items

None

Localized descriptions of the achievement.

name_localizations

None, dict of (str, object) items

None

Localized names of the achievement.

secret

bool

False

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

secure

bool

False

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.

ValueError

  • If icon 's format is not any of the expected ones.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

achievement_delete(achievement)

Deletes the passed achievement.

This method is a coroutine.

ParameterTypeDescription
achievement

Achievement, int

The achievement to delete.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

achievement_edit(achievement, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
achievement

Achievement, int

The achievement, what will be edited.

description

str

The achievement's new description.

description_localizations

dict of (str, str) items

Localized descriptions of the achievement.

icon

bytes-like

The achievement's new icon.

name

str

The new name of the achievement.

name_localizations

dict of (str, str) items

Localized names of the achievement.

secret

bool

The achievement's new secret value.

secure

bool

The achievement's new secure value.

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.

ValueError

  • If icon 's format is not any of the expected ones.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

achievement_get(achievement)

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

This method is a coroutine.

ParameterTypeDescription
achievement

Achievement, int

The achievement or it's identifier.

Returns

achievement : Achievement

Raises

TypeError

If achievement is not given as Achievement, int.

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(redirect_url, code, scopes)

Activates a user's oauth2 code.

This method is a coroutine.

ParameterTypeDescription
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, list of str

Scope or a list of oauth2 scopes to request.

Returns

access : Oauth2Access, 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 s.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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.

ParameterTypeOptionalDescription
*users

int, UserBase

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(application_command)

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.

ParameterTypeDescription
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.

Notes

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

application_command_global_delete(application_command)

Deletes the given application command.

ParameterTypeDescription
application_command

ApplicationCommand, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_global_edit(old_application_command, new_application_command)

Edits a global application command.

This method is a coroutine.

ParameterTypeDescription
old_application_command

ApplicationCommand, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

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

application_command_global_get(application_command)

Requests the given global application command.

This method is a coroutine.

ParameterTypeDescription
application_command

ApplicationCommand, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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.

application_command_global_update_multiple(application_commands)

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.

ParameterTypeDescription
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 application_commands is not iterable.
  • If an element of application_commands is not ApplicationCommand instance.

ValueError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

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

application_command_guild_create(guild, application_command)

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.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_guild_delete(guild, application_command)

Deletes the given application command.

ParameterTypeDescription
guild

Guild, int

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

application_command

ApplicationCommand, 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.
  • If application_command was not given neither as ApplicationCommand nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_guild_edit(guild, old_application_command, new_application_command)

Edits a guild application command.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

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

old_application_command

ApplicationCommand, 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.
  • If old_application_command was not given neither as ApplicationCommand nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_guild_get(application_command)

Requests the given guild application command.

ParameterTypeDescription
application_command

ApplicationCommand, 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.
  • If application_command was not given neither as ApplicationCommand not as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_guild_get_all(guild)

Requests the client's global application commands.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_guild_update_multiple(application_commands)

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.

ParameterTypeDescription
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.
  • If application_commands is not iterable.
  • If an element of application_commands is not ApplicationCommand instance.

ValueError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_permission_edit(access, guild, application_command, permission_overwrites)

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

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

A command will lose it's permissions on rename.

The endpoint requires oauth access with applications.commands.permissions.update scope.

The user with the scope must have in the guild:

  • Permission to manage guild and roles.
  • Ability to invoke the respective command.
  • Permission to manage the resources that will be affected. The can be roles, users and channels depending on the permission types.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str

A user's access token to use.

guild

Guild, int

The respective guild.

application_command

None, ApplicationCommand, int

The respective application command.

Can be None(or 0) if you want to edit the default overwrites for all guild level application commands.

permission_overwrites

None, (tuple, list, 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

ValueError

  • If permission_overwrites contains more than 100 elements.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_command_permission_get(guild, application_command)

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

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The respective guild.

application_command

ApplicationCommand, int

The respective application command.

Returns

permission : ApplicationCommandPermission

The requested permissions.

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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(guild)

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

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_edit_own(...)

Edits the client's application.

ParameterTypeOptionalKeyword onlyDefaultDescription
application

None, Application

None

Application entity to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the application with.

cover

None, bytes-like

The application's cover.

custom_install_url

None, str

The application's default custom authorization link if enabled.

description

None, str

The description of the application.

flags

int, ApplicationFlag

The application's public flags.

icon

None, bytes-like

The application's icon.

install_parameters

None, ApplicationInstallParameters

Settings for the application's default in-app authorization link, if enabled.

interaction_endpoint_url

None, str

Whether and to which url should interaction events be sent to.

role_connection_verification_url

None, str

The application's role connection verification entry point

tags

None, iterable of str

Up to 5 tags describing the content and functionality of the application.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_get(application)

Requests a specific application by it's id.

This method is a coroutine.

ParameterTypeDescription
application

Application, 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.

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(channel, application, ...)

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

Deprecated and will be removed in 2024 February.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The target channel of the invite.

application

Application, int

The embedded application to open in the voice channel.

The application must have EMBEDDED_APPLICATION flag.

max_age

int

0

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

If given as 0(so by default) then the created invite will never expire.

max_uses

int

0

How much times can the invite be used.

If given as 0(so by default) then the created invite will have no use limit.

unique

bool

True

Whether the created invite should be unique.

temporary

bool

False

Whether the invite should give only temporary membership.

Returns

invite : Invite

Raises

TypeError

  • If channel was not given neither as Channel, neither as int.
  • If application was not given neither as Application nor as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_role_connection_metadata_edit_all(application_role_connection_metadatas)

Edits all the role connection metadatas of the client's application. Basically overwrites the old ones.

ParameterTypeDescription
application_role_connection_metadatas

iterable of ApplicationRoleConnectionMetadata

The new application connection metadatas to replace the old ones.

Returns

application_role_connection_metadatas : list of ApplicationRoleConnectionMetadata

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

application_role_connection_metadata_get_all()

Requests all the role connection metadatas of the client's application.

Returns

application_role_connection_metadatas : list of ApplicationRoleConnectionMetadata

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

audit_log_get_chunk(guild, ...)

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 int, or as a DiscordEntity or as a datetime object.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

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

limit

int

100

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

before

None, int, DiscordEntity, datetime

None

The timestamp before the audit log entries wer created.

after

None, int, DiscordEntity, datetime

None

The timestamp after the audit log entries wer created.

user

None, ClientUserBase, int

None

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

entry_type

None, AuditLogEntryType, int

None

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.
  • If after, before was passed with an unexpected type.
  • If user is neither None, ClientUserBase, int.
  • If entry_type is neither None, AuditLogEntryType, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

audit_log_iterator(guild, ...)

Returns an audit log iterator for the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

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

user

None, ClientUserBase, int

None

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

entry_type

None, AuditLogEntryType, int

None

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

Returns

audit_log_iterator : AuditLogIterator

auto_moderation_rule_create(guild, auto_moderation_rule, ...)

Creates an auto moderation rule at the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild or it's identifier.

auto_moderation_rule

AutoModerationRule

The auto moderation rule to create one like.

reason

None, str

None

Shows up at the respective guild's audit logs.

Returns

auto_moderation_rule : AutoModerationRule

The created auto moderation rule.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

auto_moderation_rule_delete(auto_moderation_rule, ...)

Deletes the specified auto moderation rule.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
auto_moderation_rule

AutoModerationRule, tuple(int, int)

The auto moderation rule to delete, or a guild-id, rule-id pair representing it.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If auto_moderation_rule was not given neither as AutoModerationRule nor tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

auto_moderation_rule_edit(old_auto_moderation_rule, new_auto_moderation_rule, ...)

Edits the specified auto moderation rule

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
old_auto_moderation_rule

AutoModerationRule, tuple(int, int)

The auto moderation rule to edit, or a guild-id, rule-id pair representing it.

new_auto_moderation_rule

AutoModerationRule

The auto moderation rule to edit the current to.

reason

None, str

None

Shows up at the respective guild's audit logs.

Returns

auto_moderation_rule : AutoModerationRule

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

auto_moderation_rule_get(auto_moderation_rule)

Requests the specified auto moderation rule.

This method is a coroutine.

ParameterTypeDescription
auto_moderation_rule

AutoModerationRule, tuple(int, int)

The auto moderation rule to get, or a guild-id, rule-id pair representing it.

Returns

auto_moderation_rule : AutoModerationRule

Raises

TypeError

If auto_moderation_rule was not given neither as AutoModerationRule nor tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

auto_moderation_rule_get_all(guild)

Requests all the auto moderation rules of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild or it's identifier.

Returns

auto_moderation_rules : list of AutoModerationRule

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

avatar_decoration_url_as(...)

Returns the user's avatar decoration's url. If the user has no avatar decoration returns None.

This function is a method of UserBase.

ParameterTypeOptionalDefaultDescription
ext

None, str

None

The extension of the image's url. Can be any of: png.

size

None, int

None

The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

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

avatar_url_as(...)

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

This function is a shared method of UserBase-s.

ParameterTypeOptionalDefaultDescription
ext

None, str

None

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

None, int

None

The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

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

avatar_url_at(guild)

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

This function is a shared method of UserBase-s.

ParameterTypeDescription
guild

Guild, int

The respective guild or it's identifier.

Returns

url : None, str

avatar_url_at_as(guild, ...)

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

This function is a shared method of UserBase-s.

ParameterTypeOptionalDefaultDescription
guild

Guild, int

The respective guild or it's identifier.

ext

None, str

None

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

None, int

None

The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

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

avatar_url_for(guild)

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

This function is a shared method of UserBase-s.

ParameterTypeDescription
guild

Guild, int

The respective guild or it's identifier.

Returns

url : None, str

avatar_url_for_as(guild, ...)

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

This function is a shared method of UserBase-s.

ParameterTypeOptionalDefaultDescription
guild

Guild, int

The respective guild or it's identifier.

ext

None, str

None

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

None, int

None

The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

If ext, 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.

This function is a shared method of UserBase-s.

ParameterTypeOptionalDefaultDescription
ext

None, str

None

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

None, int

None

The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

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

can_use_emoji(emoji)

Returns whether the user can use the given emoji.

ParameterTypeDescription
emoji

Emoji

The emoji to check.

Returns

can_use_emoji : bool

channel_create(guild, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild where the channel will be created.

channel_template

None, Channel

None

Channel entity to use as a template.

reason

None, str

None

Shows up at the guild 's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the channel with.

bitrate

int

The bitrate (in bits) of the voice channel.

default_forum_layout

ForumLayout, int

The default layout used to display threads of the forum.

default_sort_order

SortOrder, int

The default thread ordering of the forum.

default_thread_auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

default_thread_reaction_emoji

None, Emoji

The emoji to show in the add reaction button on a thread of the forum channel.

default_thread_slowmode

int

The default slowmode applied to the channel's threads.

channel_type

ChannelType, int

The type of the created channel.

flags

int, ChannelFlag

The channel's flags.

name

str

The channel's name.

nsfw

bool

Whether the channel is marked as non safe for work.

parent_id

None, int, Channel

The channel's parent's identifier.

permission_overwrites

None, list of PermissionOverwrite

The channel's permission overwrites.

position

int

The channel's position.

region

None, VoiceRegion, str

The channel's voice region.

slowmode

int

The channel's slowmode.

topic

None, str

The channel's topic.

users

iterable of (int, ClientUserBase)

The users in the channel.

video_quality_mode

VideoQualityMode

The video quality of the voice channel.

Returns

channel : Channel

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_delete(channel, ...)

Deletes the specified guild channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If the given channel is not Channel, int.

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(channel, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to edit.

channel_template

None, Channel

None

A channel to use as a template.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

applied_tag_ids

None, tuple of (int, ForumTag)

The tags' identifier which have been applied to the thread. Applicable for threads of a forum.

auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

bitrate

int

The bitrate (in bits) of the voice channel.

default_forum_layout

ForumLayout, int

The default layout used to display threads of the forum.

default_sort_order

SortOrder, int

The default thread ordering of the forum.

default_thread_auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

default_thread_reaction_emoji

None, Emoji

The emoji to show in the add reaction button on a thread of the forum channel.

default_thread_slowmode

int

The default slowmode applied to the channel's threads.

flags

int, ChannelFlag

The channel's flags.

name

str

The channel's name.

nsfw

bool

Whether the channel is marked as non safe for work.

open_

bool

Whether the thread channel is open.

parent_id

None, int, Channel

The channel's parent's identifier.

permission_overwrites

None, list of PermissionOverwrite

The channel's permission overwrites.

position

int

The channel's position.

region

None, VoiceRegion, str

The channel's voice region.

slowmode

int

The channel's slowmode.

topic

None, str

The channel's topic.

users

iterable of (int, ClientUserBase)

The users in the channel.

video_quality_mode

VideoQualityMode

The video quality of the voice channel.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_edit_status(channel, status, ...)

Edits the channel with the given status. Channel should be a guild voice.

this function is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to edit.

status

None, str

The channel's status.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If any parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_follow(source_channel, target_channel, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
source_channel

Channel, int

The channel what will be followed. Must be an announcements channel.

target_channel

Channel, int instance

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

reason

None, str

None

Shows up at the respective guild's audit logs.

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 Channel nor int.
  • If the target_channel was not given neither as Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_group_create(...)

Creates a group channel with the given users.

This method is a coroutine.

ParameterTypeOptionalDescription
*users

ClientUserBase, int

The users to create the channel with.

Returns

channel : Channel

The created group channel.

Raises

TypeError

If users contain not only User, Client, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint does not support bot accounts.

channel_group_edit(channel, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to edit.

channel_template

None, Channel

None

A channel to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to define which fields should be modified.

icon

None, bytes-like

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

name

None, str

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

No request is done if no optional parameter is provided.

channel_group_leave(channel)

Leaves the client from the specified group channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

The channel to leave from.

Raises

TypeError

If channel was not given neither as Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_group_user_add(channel, ...)

Adds the users to the given group channel.

This method is a coroutine.

ParameterTypeOptionalDescription
channel

Channel, int

The channel to add the users to.

*users

ClientUserBase, int

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(channel, ...)

Removes the users from the given group channel.

This method is a coroutine.

ParameterTypeOptionalDescription
channel

Channel, int

The channel from where the users will be removed.

*users

ClientUserBase, int

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(channel, visual_position, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel

The channel to be moved.

visual_position

int

The visual position where the channel should go.

parent

None, Channel

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

lock_permissions

bool

False

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

reason

None, str

None

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

  • If channel was isn ot movable.
  • If parent was not given as None, Channel.

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(channel)

Returns the pinned messages at the given channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

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 Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_private_create(user)

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.

ParameterTypeDescription
user

ClientUserBase, int

The user to create the private with.

Returns

channel : Channel

The created private channel.

Raises

TypeError

If user was not given neither as ClientUserBase nor int.

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 (Channel, Channel) objects

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

channel_thread_get_all_active(channel)

Requests all the active threads of the given channel.

ParameterTypeDescription
channel

Channel, int

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

Returns

thread_channels : list of Channel

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

When using API v10 or later, this endpoint filters from .guild_thread_get_all_active method's return. Consider using that instead.

Active threads can also be extracted from Guild.threads.

channel_thread_get_all_archived_private(channel)

Requests all the archived private of the given channel.

ParameterTypeDescription
channel

Channel, int

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

Returns

thread_channels : list of Channel

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(channel)

Requests all the archived public threads of the given channel.

ParameterTypeDescription
channel

Channel, int

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

Returns

thread_channels : list of Channel

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(channel)

Requests all the archived private threads by the client.

ParameterTypeDescription
channel

Channel, int

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

Returns

thread_channels : list of Channel

Raises

TypeError

If channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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, object) 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(force)

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.

ParameterTypeDescription
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_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: object)

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(guild)

Returns the user's color at the given guild.

ParameterTypeDescription
guild

None, Guild, int

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, 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.

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.

copy()

Copies the user returning a new partial one.

Returns

new : instance<type<self>>

copy_with(...)

Copies the user with the given fields.

ParameterTypeOptionalKeyword onlyDescription
avatar

None, Icon, str, bytes-like

The user's avatar.

avatar_decoration

None, AvatarDecoration

The user's avatar decoration.

banner

None, Icon, str, bytes-like

The user's banner.

banner_color

None, Color, int

The user's banner color.

bot

bool

Whether the user is a bot or a user account.

discriminator

str, int

The user's discriminator.

display_name

None, str

The user's non-unique display name.

flags

int, UserFlag

The user's flags.

name

str

The user's name.

Returns

new : instance<type<self>>

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

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(attachment)

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

This method is a coroutine.

ParameterTypeDescription
attachment

Attachment, EmbedImage

The attachment object what's file will be requested.

Returns

response_data : bytes

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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.

ParameterTypeOptionalKeyword onlyDescription
**keyword_parameters

Keyword parameters

Additional keyword parameters representing which field of the client should be edited.

avatar

None, bytes-like

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, bytes-like

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

banner_color

None, Color, int

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

display_name

None, str

The client's non-unique display name.

name

str

The client's new name.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

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

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
activity

Activity

The new activity of the Client.

status

str, Status

The new status of the client.

afk

bool

False

Whether the client is afk or not (?).

Raises

TypeError:

ValueError:

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

emoji_create(guild, name, image, ...)

Creates an emoji at the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, 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, (list, set, tuple) of (Role, int)

None

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

reason

None, str

None

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. If roles contains a non Role, int element.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

Notes

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

emoji_delete(emoji, ...)

Deletes the given emoji.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
emoji

Emoji

The emoji to delete.

reason

None, str

None

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.

emoji_edit(emoji, ...)

Edits the given emoji.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
emoji

Emoji, tuple(int, int)

The emoji to edit.

name

str

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

roles

None, (list, set, tuple) of (Role, int)

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, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If roles contains a non Role, int element.
  • If emoji is not Emoji, tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

emoji_get(emoji, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
emoji

Emoji, tuple(int, int) items

The emoji, or 2 snowflake representing it.

force_update

bool

False

Whether the emoji should be requested even if it supposed to be up to date.

Returns

emoji : Emoji

Raises

TypeError

If emoji was not given as Emoji, tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

emoji_guild_get_all(guild)

Syncs the given guild's emojis with the wrapper.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's emojis will be synced.

Returns

emojis : list of Emoji

The guild's emojis.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

entitlement_create(...)

Creates a new (test) entitlement.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
entitlement_template

None, Entitlement

None

Entitlement to use as a template

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

owner

None, ClientUserBase, Guild, (int | EntitlementOwnerType, int | str)

The entitlement's owner. owner_id and owner_type combined.

owner_id

int

The entitlement's owner's identifier.

owner_type

EntitlementOwnerType, int

The entitlement's owner's type.

sku

int, SKU

Alternative for sku_id.

sku_id

int, SKU

Stock keeping unit to create the entitlement for.

Returns

entitlement : Entitlement

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

entitlement_delete(entitlement)

Deletes the given (test) entitlement.

This method is a coroutine.

ParameterTypeDescription
entitlement

Entitlement, int

The entitlement to delete.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

entitlement_get_all(...)

Requests all the entitlements of the client's application's entitlements that satisfies the criteria.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
exclude_ended

bool

Whether ended entitlements should be excluded. Defaults to False.

guild_id

int, None, Guild

Guild identifier to filter for.

sku_ids

int, None, SKU, iterable of int, iterable of SKU

Stock keeping units to filter for.

user_id

int, None, ClientUserBase

User identifier to filter for.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

entitlement_get_chunk(...)

Requests a chunk of the client's application's entitlements that satisfies the criteria.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
after

int, DiscordEntity, datetime

The timestamp after the entitlements were created.

before

int, DiscordEntity, datetime

The timestamp before the entitlements were created.

exclude_ended

bool

Whether ended entitlements should be excluded. Defaults to False.

guild_id

int, None, Guild

Guild identifier to filter for.

limit

int

Up to how much entitlements should be requested. Can be in range [1, 100]. Defaults to 100.

sku_ids

int, None, SKU, iterable of int, iterable of SKU

Stock keeping units to filter for.

user_id

int, None, ClientUserBase

User identifier to filter for.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

eula_get(eula)

Requests the eula with the given id.

This method is a coroutine.

ParameterTypeDescription
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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

forum_tag_create(forum_channel, ...)

Creates a new forum tag in the channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
forum_channel

Channel, int

The channel to create the tag in.

forum_tag

ForumTag, None

None

A forum tag which can be used as a template for the newly created tag.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

emoji

None, Emoji

The tag's emoji.

moderated

bool

Whether this tag can only be added or removed by a user with manage_threads permission.

name

str

The tag's name.

Returns

forum_tag : None, ForumTag

The created forum tag.

Raises

TypeError

If a parameter's type is not acceptable.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

A forum channel can have up to 25 tags.

See Also

forum_tag_delete(forum_channel, forum_tag, ...)

Deletes the given forum tag.

ParameterTypeOptionalKeyword onlyDefaultDescription
forum_channel

Channel, int

The channel to edit the tag in.

forum_tag

ForumTag, int

The forum tag to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If a parameter's type is not acceptable.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

forum_tag_edit(forum_channel, forum_tag, ...)

Edits the given forum tag.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
forum_channel

Channel, int

The channel to edit the tag in.

forum_tag

ForumTag, int

The forum tag to edit.

template_forum_tag

ForumTag, None

None

A forum tag which can be used as a template for edition.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

emoji

None, Emoji

The tag's emoji.

moderated

bool

Whether this tag can only be added or removed by a user with manage_threads permission.

name

str

The tag's name.

Raises

TypeError

If a parameter's type is not acceptable.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

forum_thread_create(channel_forum, ...)

Creates and thread at the given channel with the given message fields. If there is nothing to send will return None for channel and None for message as well.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel_forum

Channel, int

The forum channel's identifier where the thread will be started.

channel_template

None, Channel

None

(Thread) channel entity to use as a template.

*positional_parameters

Positional parameters

Additional parameters to create the message with.

**keyword_parameters

Keyword parameters

Additional parameters to create the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

applied_tag_ids

None, (list | tuple)<int | ForumTag>, int, ForumTag

The tags' identifier which have been applied to the thread.

applied_tags

None, (list | tuple)<int | ForumTag>, int, ForumTag

Alternative for applied_tag_ids.

attachments

None, object

Attachments to send.

auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

content

None, str

The message's content if given.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, ChannelFlag

The channel's flags. Due to name collision, message.flags is not directly supported.

invitable

bool

Whether non-moderators can invite other non-moderators to the threads.

name

str

The channel's name.

nonce

None, str

Used for optimistic message sending.

open_

bool

Whether the thread is open.

silent

bool

False

Whether the message should be delivered silently.

slowmode

int

The channel's slowmode.

sticker

None, Sticker

Alternative for sticker_ids.

sticker_ids

None, list<int>

Sticker(s) to send within the message.

stickers

None, list<int | Sticker>

Alternative for sticker_ids.

suppress_embeds

bool

False

Whether the message's embeds should be suppressed initially.

tts

bool

False

Whether the message is text-to-speech.

Returns

thread_channel : None, Channel

The created thread channel. None if there was nothing to send.

message : None, Message

Returns None if there is nothing to send.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

.message_create: Sending a message to a text channel. .thread_create: Create thread in a text channel.

from_data(user_data, ...)

Creates a new user from the given data.

ParameterTypeOptionalKeyword onlyDefaultDescription
user_data

dict of (str, object) items

User data.

guild_profile_data

None, dict of (str, object) items

None

Guild profile data.

guild_id

int

0

The guild's identifier to which the guild profile is bound to.

strong_cache

bool

True

Whether the instance should be put into its strong cache.

Returns

self : instance<cls>

gateway_for(guild_id)

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

ParameterTypeDescription
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 : DiscordGatewayClientBase

get_guild(name, ...)

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

ParameterTypeOptionalDefaultDescription
name

str

The guild's name to search.

default

None, object

None

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

Returns

guild : Guild, default

Raises

AssertionError

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

get_guild_profile_for(guild)

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

ParameterTypeDescription
guild

None, Guild, int

The guild to get guild profile for.

Returns

guild_profile : None, Guild

get_status_by_platform(platform)

Gets the user's status by the given platform.

ParameterTypeDescription
platform

str

The platform to get the status for.

Returns

status : Status

Defaults to status.offline if the user has no specific status for the given platform.

guild_ban_add(guild, user, ...)

Bans the given user from the guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild from where the user will be banned.

user

ClientUserBase, int

The user to ban from the guild.

delete_message_duration

int

0

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

reason

None, str

None

Shows up at the guild's audit logs.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_ban_delete(guild, user, ...)

Unbans the user from the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild from where the user will be unbanned.

user

ClientUserBase, int

The user to unban at the guild.

reason

None, str

None

Shows up at the guild's audit logs.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_ban_get(guild, user)

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

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild where the user banned.

user

ClientUserBase, int

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

Returns

ban_entry : BanEntry

The ban entry.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_ban_get_all(guild)

Returns the guild's ban entries.

This method might need multiple requests to complete it's task

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's bans will be requested

Returns

ban_entries : list of BanEntry elements

User - reason pairs for each ban entry.

Raises

TypeError

If guild was not given neither as Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

.guild_ban_get_chunk: Getting a chunk of ban entries up to 1000 users.

guild_ban_get_chunk(guild, ...)

Returns a chunk of the guild's ban entries.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild, what's bans will be requested

after

None, int, DiscordEntity, datetime

None

The timestamp after the banned users were created.

before

None, int, DiscordEntity, datetime

None

The timestamp before the banned users were created.

limit

int

0

The amount of ban entries to request. Can be in range [0:1000]

When given as non-positive (<= 0) defaults to the maximal amount.

Returns

ban_entries : list of BanEntry elements

User, reason pairs for each ban entry.

Raises

TypeError

  • If guild was not given neither as Guild, int.
  • If after, before was passed with an unexpected type.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

.guild_ban_get_all: Getting all ban entries of a guild.

guild_channel_get_all(guild)

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.

ParameterTypeDescription
guild

Guild, int

The guild, what's channels will be requested.

Returns

channels : list of Channel

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_create(name, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
name

str

The name of the new guild.

**keyword_parameters

Keyword parameters

Additional parameters to create the guild with.

afk_channel_id

None, int

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

afk_timeout

None, int

None

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

channels

None, list of (dict<str, object>, Channel)

A list of channels of the new guild. It should contain channel data objects.

explicit_content_filter_level

ExplicitContentFilterLevel, int

The content filter level of the guild.

icon

None, bytes-like

The icon of the new guild.

roles

None, list of (dict<str, object>, Role)

A list of roles of the new guild. It should contain role data objects.

default_message_notification_level

MessageNotificationLevel, int

The default message notification level of the new guild.

system_channel_flags

SystemChannelFlag, int

Describe which type of messages are sent automatically to the system channel.

system_channel_id

int

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

verification_level

VerificationLevel, int

The verification level of the new guild.

Returns

guild : Guild

A partial guild made from the received data.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_delete(guild)

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

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild to delete.

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_discovery_add_sub_category(guild, category)

Adds a discovery subcategory to the guild.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild to what the discovery subcategory will be added.

category

DiscoveryCategory, 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.

guild_discovery_delete_sub_category(guild, category)

Removes a discovery subcategory of the guild.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

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

category

DiscoveryCategory, 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.

guild_discovery_edit(guild, ...)

Edits the guild's discovery metadata.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

To modify sub-categories use the .guild_discovery_add_sub_category and the .guild_discovery_delete_sub_category methods.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

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

discovery_template

None, GuildDiscovery

None

Guild discovery to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to define which fields should be modified.

emoji_discovery

bool

Whether guild info is shown when the respective guild's emojis are clicked.

keywords

None, iterable of str

The set discovery search keywords for the guild.

primary_category

DiscoveryCategory, int

The primary discovery category of the guild.

Returns

guild_discovery : GuildDiscovery

Raises

TypeError

  • If guild is not Guild, int.
  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_discovery_get(guild)

Requests and returns the guild's discovery metadata.

The client must have manage_guild permission to execute this method.

This method is a coroutine.

ParameterTypeDescription
guild

Guild

The guild what's discovery will be requested.

Returns

guild_discovery : GuildDiscovery

Raises

TypeError

  • If guild is not Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_edit(guild, ...)

Edits the guild with the given parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild to edit.

guild_template

None, Guild

None

Guild entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the guild with.

afk_channel_id

int, Channel

The afk channel or its identifier.

afk_timeout

int

The afk timeout at the afk_channel.

banner

None, Icon, str, bytes-like

The guild's banner.

boost_progress_bar_enabled

bool

Whether the guild has the boost progress bar enabled.

explicit_content_filter_level

ExplicitContentFilterLevel, int

The explicit content filter level of the guild.

description

None, str

Description of the guild. The guild must be a Community guild.

discovery_splash

None, Icon, str, bytes-like

The guild's discovery splash.

features

None, iterable of ( int , GuildFeature)

The guild's features.

hub_type

HubType, int

The guild's hub type.

icon

None, Icon, str, bytes-like

The guild's icon.

invite_splash

None, Icon, str, bytes-like

The guild's invite splash.

locale

Locale, int

The preferred language of the guild.

default_message_notification_level

MessageNotificationLevel, int

The default message notification level of the guild.

mfa_level

MfaLevel, int

The required multi-factor authentication level for the guild.

name

str

The guild's name.

nsfw_level

NsfwLevel, int

The nsfw level of the guild.

owner_id

int, ClientUserBase

The guild's owner or their id.

public_updates_channel_id

int, Channel

The channel's identifier where the guild's public updates should go.

rules_channel_id

int, Channel

The channel or its identifier where the rules of a public guild's should be.

safety_alerts_channel_id

int, Channel

The channel or its identifier where safety alerts are sent by Discord.

system_channel_flags

SystemChannelFlag, int

Describe which type of messages are sent automatically to the system channel.

system_channel_id

int, Channel

The channel or its identifier where the system messages are sent.

vanity_code

None, str

The guild's vanity invite's code if it has.

verification_level

VerificationLevel, int

The minimal verification needed to join or to interact with guild.

widget_channel_id

int, Channel

The channel or its identifier for which the guild's widget is for.

widget_enabled

bool

Whether the guild's widget is enabled.

Raises

TypeError

  • If a parameter's type is invalid.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_get(guild)

Gets or updates the guild.

The client must be in the guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild to request.

Returns

guild : Guild

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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_incidents_edit(guild, ...)

Edits the guild's incidents with the given parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild to edit the incidents of.

incidents_template

None, GuildIncidents

None

Guild incidents to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the guild incidents with.

direct_messages_disabled_duration

int, TimeDelta, float

The duration while the direct messages should be disabled in the guild in seconds or time delta.

direct_messages_disabled_until

None, DateTime

Until when are the direct messages disabled in the guild.

direct_messages_disabled_duration

int, TimeDelta, float

The duration while the invites should be disabled in the guild in seconds or time delta.

invites_disabled_until

None, DateTime

Until when are the invites disabled of the guild.

Raises

TypeError

  • If a parameter's type is invalid.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_inventory_settings_edit(guild, ...)

Edits the guild's inventory settings with the given parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild to edit the inventory settings of.

inventory_settings_template

None, GuildInventorySettings

None

Guild inventory settings to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the guild inventory settings with.

emoji_pack_collectible

bool

Whether you can collect this guild's emojis and use it across all guilds.

Raises

TypeError

  • If a parameter's type is invalid.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_leave(guild)

The client leaves the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild from where the client will leave.

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_preview_get(guild)

Requests the preview of a public guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_profile_edit(guild, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

None, int, Guild

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

**keyword_parameters

Keyword parameters

Additional keyword parameters representing which field of the guild profile should be edited.

reason

None, str

None

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

nick

None, str

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

avatar

None, bytes-like

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.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_prune(guild, days, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

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, list of (Role, int)

None

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

count

bool

False

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, str

None

Will show up at the guild's audit logs.

Returns

count : None, 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.
  • 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, list.
  • If count was not given as bool.
  • If days was not given as int.
  • 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(guild, days, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int.

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, list of (Role, int)

None

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.
  • 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, list.
  • If days was not given as int.
  • If days is out of range [1:30].

guild_role_get_all(guild)

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.

ParameterTypeDescription
guild

Guild, int

The guild, what's roles will be requested.

Returns

roles : list of Role

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_sync(guild)

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.

ParameterTypeDescription
guild

Guild, int

The guild to sync.

Returns

guild : Guild

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_thread_get_all_active(guild)

Gets all the active threads of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild to get it's threads of.

If the guild is given as 0, will return an empty list.

Returns

threads : list of Channel

Raises

TypeError

If guild is neither Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_add(guild, access, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

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

access

Oauth2Access, Oauth2User, str

The access of the user, who will be added.

user

None, ClientUserBase

None , int

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 Oauth2User object.

nick

None, str

None

The nickname, which with the user will be added.

roles

None, list of (Role, int)

None

The roles to add the user with.

mute

bool

False

Whether the user should be added as muted.

deaf

bool

False

Whether the user should be added as deafen.

Raises

TypeError:

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

ValueError

  • If the given access is not providing the required scope.
  • If user and access refers to a different user.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_delete(guild, user, ...)

Removes the given user from the guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild from where the user will be removed.

user

ClientUserBase, int

The user to delete from the guild.

reason

None, str

None

Shows up at the guild's audit logs.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_get(guild, user)

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.

ParameterTypeDescription
guild

Guild, int

The guild, where the user is.

user

ClientUserBase, 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.
  • If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_user_get_all(guild)

Requests all the users of the guild and returns them.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

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(guild, query, ...)

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.

ParameterTypeOptionalDefaultDescription
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

1

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

When passed as non-positive value, will default to the maximal allowed amount.

Returns

users : list of ClientUserBase

Raises

TypeError

If guild was not given neither as Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If limit was not given as str.
  • If limit is out fo expected range [1:1000].

guild_voice_region_get_all(guild)

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

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

guild_widget_get(guild)

Returns the guild's widget.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

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

Returns

guild_widget : None, GuildWidget

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

Raises

TypeError

If guild was not passed neither as Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

has_higher_role_than(role)

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.

ParameterTypeDescription
role

Role

The role to check.

Returns

has_higher_role_than : bool

has_higher_role_than_at(user, guild)

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

ParameterTypeDescription
user

User

The other user to check.

guild

Guild, None, int

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

Can be given as None.

Returns

has_higher_role_than_at : bool

has_name_like(name)

Returns whether the user's name is like the given string.

ParameterTypeDescription
name

str

The name of the user.

Returns

has_name_like : bool

has_name_like_at(name, guild)

Returns whether the user's name is like the given string.

ParameterTypeDescription
name

str

The name of the user.

guild

None, Guild, int

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

Can be given as None.

Returns

has_name_like : bool

has_role(role)

Returns whether the user has the given role.

ParameterTypeDescription
role

Role

The role what will be checked.

Returns

has_role : bool

hypesquad_house_change(house)

Changes the client's hypesquad house.

This method is a coroutine.

ParameterTypeDescription
house

int, HypesquadHouse

The hypesquad house to join.

Raises

TypeError

house was not given as int neither as HypesquadHouse.

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(guild, integration_id, type_)

Creates an integration at the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.
  • If integration_id was not given as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If type_ is not given as str.

integration_delete(integration)

Deletes the given integration.

This method is a coroutine.

ParameterTypeDescription
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.

integration_edit(integration, ...)

Edits the given integration.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
integration

Integration

The integration to edit.

expire_behavior

int

Can be 0 for kick or 1 for role remove.

expire_grace_period

int

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

emojis_enabled

bool

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 emojis_enabled was not passed as bool.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

integration_get_all(guild)

Requests the integrations of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

integration_sync(integration)

Sync the given integration's state.

This method is a coroutine.

ParameterTypeDescription
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.

interaction_application_command_acknowledge(interaction_event, ...)

Acknowledges the given application command interaction.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
interaction_event

InteractionEvent

Interaction to acknowledge

wait

bool

True

Whether the interaction should be ensured asynchronously.

show_for_invoking_user_only

bool

False

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.

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(interaction_event, choices)

Forwards auto completion choices for the user.

This method is a coroutine.

ParameterTypeDescription
interaction_event

InteractionEvent

Interaction to acknowledge

choices

None, 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.

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(interaction_event, ...)

Acknowledges the given component interaction.

This method is a coroutine.

ParameterTypeOptionalDefaultDescription
interaction_event

InteractionEvent

Interaction to acknowledge

wait

bool

True

Whether the interaction should be ensured asynchronously.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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(interaction_event, ...)

Edits the given component interaction's source message.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
interaction_event

InteractionEvent

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

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

Pass it as None remove the actual ones.

content

None, str

The new content of the message.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

By passing it as None, you can remove the old.

flags

int, MessageFlag

The message's new flags.

suppress_embeds

bool

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_followup_message_create(interaction_event, ...)

Sends a followup message with the given interaction.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
interaction_event

InteractionEvent

Interaction to create followup message with.

*positional_parameters

Positional parameters

Additional parameters to create the message with.

**keyword_parameters

Keyword parameters

Additional parameters to create the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

content

None, str

The message's content if given.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's flags.

show_for_invoking_user_only

bool

False

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

silent

bool

False

Whether the message should be delivered silently.

suppress_embeds

bool

False

Whether the message's embeds should be suppressed initially.

tts

bool

False

Whether the message is text-to-speech.

Returns

message : None, Message

Returns None if there is nothing to send.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_followup_message_delete(interaction_event, message)

Deletes an interaction's followup message.

This method is a coroutine.

ParameterTypeDescription
interaction_event

InteractionEvent

Interaction with what the followup message was sent with.

message

Message, int

The interaction followup's message to edit.

Raises

TypeError

If message was not given neither as Message, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_followup_message_edit(interaction_event, message, ...)

Edits the given interaction followup message.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
interaction_event

InteractionEvent

Interaction with what the followup message was sent with.

message

Message, int

The interaction followup's message to edit.

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

Pass it as None remove the actual ones.

content

None, str

The new content of the message.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

By passing it as None, you can remove the old.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's new flags.

suppress_embeds

bool

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_followup_message_get(interaction_event, message_id)

Gets a previously sent message with an interaction.

This method is a coroutine.

ParameterTypeDescription
interaction_event

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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_form_send(interaction_event, form)

Responds on an interaction with a form.

This function is a coroutine.

ParameterTypeDescription
interaction_event

InteractionEvent

Interaction to respond to.

form

InteractionForm

The to respond with.

Raises

RuntimeError

If cannot respond with a form on the given interaction.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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_require_subscription(interaction_event)

Requires the user to subscribe to the application.

This method is a coroutine.

ParameterTypeDescription
interaction_event

InteractionEvent

Interaction to respond to.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_response_message_create(interaction_event, ...)

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.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
interaction_event

InteractionEvent

Interaction to respond to.

*positional_parameters

Positional parameters

Additional parameters to create the message with.

**keyword_parameters

Keyword parameters

Additional parameters to create the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

content

None, str

The message's content if given.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

flags

int, MessageFlag

The message's flags.

show_for_invoking_user_only

bool

False

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

silent

bool

False

Whether the message should be delivered silently.

suppress_embeds

bool

False

Whether the message's embeds should be suppressed initially.

tts

bool

False

Whether the message is text-to-speech.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

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(interaction_event)

Deletes the given interaction 's source response message.

This method is a coroutine.

ParameterTypeDescription
interaction_event

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.

interaction_response_message_edit(interaction_event, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
interaction_event

InteractionEvent

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

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

Pass it as None remove the actual ones.

content

None, str

The new content of the message.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

By passing it as None, you can remove the old.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's new flags.

suppress_embeds

bool

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

interaction_response_message_get(interaction_event)

Gets the given interaction 's source response message.

This method is a coroutine.

ParameterTypeDescription
interaction_event

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.

invite_create(channel, ...)

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

To create stream invite pass the target_type parameter as InviteTargetTypes.stream and use either the target_user or target_user_id to define the streamer.

To create an embedded application invite pass the target_type parameter as InviteTargetTypes.embedded_application and use either the target_application or target_application_id to define the application.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel of the created invite.

invite_template

None, Invite

None

Invite entity to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the invite with.

max_age

int

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

max_uses

int

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

target_application

int, Application

Alternative for target_application_id.

target_application_id

int, Application

The invite's target application.

target_type

InviteTargetType, int

The invite's target type.

target_user

int, ClientUserBase

Alternative for target_user.

target_user_id

int, ClientUserBase

The target of the invite if applicable.

temporary

bool

Whether the invite should give only temporary membership.

unique

bool

Whether the created invite should be unique.

Returns

invite : Invite

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_create_preferred(, ...)

Creates an invite to the guild's preferred channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription

guild . Guild

The guild the invite will be created to.

**keyword_parameters

Keyword parameters

Additional keyword parameters to describe the created invite.

max_age

int

0

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

max_uses

int

0

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

unique

bool

True

Whether the created invite should be unique.

temporary

bool

False

Whether the invite should give only temporary membership.

Returns

invite : Invite

Raises

TypeError

  • if guild is not Guild˛

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.

invite_delete(invite, ...)

Deletes the given invite.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
invite

Invite

The invite to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If invite was not given neither Invite nor str.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_edit_vanity(guild, vanity_code, ...)

Edits the given guild's vanity invite's code.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild

The guild, what's invite will be edited.

vanity_code

str

The new code of the guild's vanity invite.

reason

None, str

None

Shows up at the guild's audit logs.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If vanity_code was not given as str.

invite_get(invite)

Requests a partial invite with the given code.

This method is a coroutine.

ParameterTypeDescription
invite

Invite, str

The invites code.

Returns

invite : Invite

Raises

TypeError

If invite was not given neither Invite nor str.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If invite_code was not given as str.

invite_get_all_channel(channel)

Gets the invites of the given channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

The channel, what's invites will be requested.

Returns

invites : list of Invite objects

Raises

TypeError

If channel was not given neither as Channel, neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_get_all_guild(guild)

Gets the invites of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, 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.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

invite_get_vanity(guild)

Returns the vanity invite of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's invite will be returned.

Returns

invite : None, Invite

The vanity invite of the guild, None if it has no vanity invite.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

is_boosting(guild)

Returns whether the user is boosting the given guild.

ParameterTypeDescription
guild

None, Guild, int

The guild to get whether the user is booster of.

Returns

is_boosting : bool

is_owner(user)

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

ParameterTypeDescription
user

ClientUserBase

The user who will be checked.

Returns

is_owner : bool

iter_activities()

Iterates over the user's activities.

This method is an iterable generator.

Yields

activity : Activity

iter_guilds()

Iterates over the guilds of the user.

This method is an iterable generator.

Yields

guild : Guild

The guild profile's guild.

iter_guilds_and_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(channel)

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

This method is a coroutine.

ParameterTypeDescription
channel

Channel, tuple(int, int)

The stage channel to join.

Raises

RuntimeError

If channel is partial.

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

join_speakers(channel, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel

The stage channel to join.

request

bool

False

Whether the client should only request to speak.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

join_voice(channel)

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.

ParameterTypeDescription
channel

Channel, 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 Channel nor as tuple(int, int).

keep_typing(channel, ...)

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

ParameterTypeOptionalDefaultDescription
channel

Channel, int

The channel where typing will be triggered.

timeout

float

300.0

The maximal duration for the Typer to keep typing.

Returns

typer : Typer

Raises

TypeError

If channel was not given neither as Channel nor int.

Examples

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

mentioned_in(message)

Returns whether the user is mentioned at a given message.

ParameterTypeDescription
message

Message

The message, what's mentions will be checked.

Returns

mentioned : bool

message_create(channel, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int, Message, tuple(int, int)

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

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

content

None, str

The message's content if given.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's flags.

nonce

None, str

Used for optimistic message sending.

reply_fail_fallback

bool

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

reply_message_id

int

Which message should the created message be reply to.

Can also be given by passing channel as a Message.

silent

bool

False

Whether the message should be delivered silently.

sticker

None, Sticker

Alternative for sticker_ids.

sticker_ids

None, list<int>

Sticker(s) to send within the message.

stickers

None, list<int | Sticker>

Alternative for sticker_ids.

suppress_embeds

bool

False

Whether the message's embeds should be suppressed initially.

tts

bool

False

Whether the message is text-to-speech.

Returns

message : None, Message

Returns None if there is nothing to send.

Raises

TypeError

  • If a parameter's 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.

See Also

.webhook_message_create: Sending a message with a Webhook.

message_crosspost(message)

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

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message to crosspost.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_delete(message, ...)

Deletes the given message.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
message

Message, tuple(int, int)

The message to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If message was not given neither as Message, 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(messages, ...)

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
messages

(list, set, tuple) of (Message, tuple(int, int))

The messages to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If a message was not given neither as Message, 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, tuple.

Notes

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

message_delete_sequence(channel, ...)

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

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

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel

The channel, where the deletion should take place.

after

None, int, DiscordEntity, DateTime

None

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

before

None, int, DiscordEntity, DateTime

None

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

limit

None, int

None

The maximal amount of messages to delete.

filter

None, callable

None

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

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If after, 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 Channel.

Notes

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

message_edit(message, ...)

Edits the given message.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
message

Message, tuple(int, int)

The message to edit.

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

Pass it as None remove the actual ones.

content

None, str

The new content of the message.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

By passing it as None, you can remove the old.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's new flags.

suppress_embeds

bool

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

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

See Also

  • .message_suppress_embeds: For suppressing only the embeds of the message.
  • .webhook_message_edit: Editing messages sent by webhooks.

message_get(message, ...)

Requests the specified message.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
message

Message, tuple(int, int)

The message to get, or a channel-id, message-id tuple representing it.

force_update

bool

False

Whether the scheduled event should be requested even if it supposed to be up to date.

Returns

message : Message

Raises

TypeError

  • If message 's type is neither Message, nor tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_get_all_in_range(channel, ...)

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.

ParameterTypeOptionalDefaultDescription
channel

Channel, int

The channel from were the messages will be requested.

start

int

0

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

end

int

100

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 Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

message_get_at_index(channel, 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.

ParameterTypeDescription
channel

Channel, int.

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 Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

message_get_chunk(channel, ...)

Requests messages from the given text channel. The after, around and the before parameters are mutually exclusive and they can be int, or as a DiscordEntity 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.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel from where we want to request the messages.

limit

int

100

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

after

None, int, DiscordEntity, DateTime

None

The timestamp after the requested messages were created.

around

None, int, DiscordEntity, DateTime

None

The timestamp around the requested messages were created.

before

None, int, DiscordEntity, DateTime

None

The timestamp before the requested messages were created.

Returns

messages : list of Message

Raises

TypeError

  • If channel was not given neither as Channel nor int.
  • If after, around, 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.
  • 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(channel, ...)

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.

ParameterTypeOptionalDefaultDescription
channel

Channel

The channel from where we want to request the messages.

limit

int

100

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 Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

message_iterator(channel, ...)

Returns an asynchronous message iterator over the given text channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel or int

The channel from were the messages will be requested.

chunk_size

int

99

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 Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

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

message_pin(message)

Pins the given message.

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message to pin.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_suppress_embeds(message, ...)

Suppresses or unsuppressed the given message's embeds.

This method is a coroutine.

ParameterTypeOptionalDefaultDescription
message

Message, tuple(int, int)

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

suppress_embeds

bool

True

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

Raises

TypeError

  • If message was not given neither as Message, tuple(int, int).
  • If suppress was not given as bool.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

message_unpin(message)

Unpins the given message.

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message to unpin.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

multi_client_message_delete_sequence(channel, ...)

Deletes messages between an interval determined by before and after. They can be int, or as a DiscordEntity 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.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel

The channel, where the deletion should take place.

after

None, int, DiscordEntity, DateTime

None

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

before

None, int, DiscordEntity, DateTime

None

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

limit

None, int

None

The maximal amount of messages to delete.

filter

None, callable

None

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

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If after, 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 Channel.

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(guild)

Returns the user's name at the given guild.

ParameterTypeDescription
guild

None, Guild, int

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

Can be given as None.

Returns

name : str

onboarding_screen_edit(guild, ...)

Edits the guild's onboarding screen.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild to edit its onboarding screen.

onboarding_screen_template

None, OnboardingScreen

None

Onboarding screen to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the onboarding screen with.

default_channel_ids

None, iterable of (int, Channel)

The channels' identifiers that new members get opted into automatically.

enabled

bool

Whether onboarding is enabled.

mode

OnboardingMode, int

Onboarding mode.

prompts

None, iterable of OnboardingPrompt

The prompts shown during onboarding and in customize community.

Returns

onboarding_screen : OnboardingScreen

Raises

TypeError

  • If guild is not Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

onboarding_screen_get(guild)

Requests the given guild's onboarding screen.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild what's onboarding screen will be requested.

Returns

onboarding_screen : OnboardingScreen

Raises

TypeError

  • If guild is not Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

owners_access(scopes)

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.

ParameterTypeDescription
scopes

list of str

A list of oauth2 scopes to request.

Returns

access : Oauth2Access

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

Raises

TypeError

If Scopes is neither str nor list of str s.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If redirect_url was not given as str.
  • If code was not given as str.
  • 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(channel, ...)

Creates a permission overwrite at the given channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to what the permission overwrite will be added.

permission_overwrite_template

None, PermissionOverwrite

None

Permission overwrite to be used as a template for creating the new one.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

allow

None, Permission, int

The permission overwrite's allowed permission's value.

deny

None, Permission, int

The permission overwrite's denied permission's value.

target

int, Role, ClientUserBase

The permission overwrite's target. Shortcut for defining target_id and target_type with 1 parameter.

target_id

int

The permission overwrite's target's identifier.

target_type

None, PermissionOverwriteTargetType

The permission overwrite's target's type. Required if target_id is given as a snowflake.

Returns

permission_overwrite : PermissionOverwrite

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

permission_overwrite_delete(channel, permission_overwrite, ...)

Deletes the given permission overwrite.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

˙˙Channel

The channel where the permission overwrite is.

permission_overwrite

PermissionOverwrite, int

The permission overwrite to delete.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

permission_overwrite_edit(channel, permission_overwrite, ...)

Edits the given permission overwrite.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

˙˙Channel, int

The channel where the permission overwrite is.

permission_overwrite

PermissionOverwrite

The permission overwrite to edit.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

allow

None, Permission, int

The permission overwrite's allowed permission's value.

deny

None, Permission, int

The permission overwrite's denied permission's value.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_add(message, emoji)

Adds a reaction on the given message.

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message on which the reaction will be put on.

emoji

Reaction, Emoji, str

The reaction to react with. if given as Emoji / str will use standard reaction.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_clear(message)

Removes all the reactions from the given message.

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message from which the reactions will be cleared.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete(message, reaction, user)

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

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message from which the reaction will be removed.

reaction

Reaction, Emoji, str

The reaction to remove.

user

ClientUserBase, int

The user, who's reaction will be removed.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete_emoji(message, emoji)

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

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message from which the reactions will be removed.

emoji

Emoji, str

The reaction to remove.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_delete_own(message, emoji)

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

This method is a coroutine.

ParameterTypeDescription
message

Message, tuple(int, int)

The message from which the reaction will be removed.

emoji

Reaction, Emoji, str

The reaction to remove.

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_get_all(message)

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.

ParameterTypeDescription
message

Message, tuple(int, int)

The message, what's reactions will be requested.

Returns

message : Message

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

reaction_user_get_all(message, reaction)

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.

ParameterTypeDescription
message

Message, tuple(int, int)

The message, what's reactions will be requested.

reaction

Reacton, Emoji, str

The reaction, what's reactors will be requested.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If a parameter'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(message, reaction, ...)

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.

ParameterTypeOptionalKeyword onlyDefaultDescription
message

Message, tuple(int, int)

The message, what's reactions will be requested.

reaction

Reaction, Emoji, str

The emoji, what's reactors will be requested.

limit

None, int

None

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

after

None, int, DiscordEntity, datetime

None

The timestamp after the message's reactors were created.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If a parameter'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.

Notes

before parameter is not supported by Discord.

relationship_create(user, ...)

Creates a relationship with the given user.

This method is a coroutine.

ParameterTypeOptionalDefaultDescription
user

ClientUserBase, int

The user with who the relationship will be created.

relationship_type

None, RelationshipType, int

None

The type of the relationship. Defaults to None.

Raises

TypeError

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(relationship)

Deletes the given relationship.

This method is a coroutine.

ParameterTypeDescription
relationship

Relationship, ClientUserBase, int

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

Raises

TypeError

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

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(user)

Sends a friend request to the given user.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user, who will receive the friend request.

Raises

TypeError

If user was not given neither as ClientUserBase, int.

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.

ParameterTypeOptionalDescription
*users

int, UserBase

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(access)

Renews the access token of an Oauth2Access.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User

Oauth2 access to the respective user.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

By default access tokens expire after one week.

request_all_users_of(guild)

Requests all users of the given guild.

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 instead of raising.

If the Client is created with should_request_users parameter given as False, this parameter can be used to request users of specific guilds.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's members will be requested.

Raises

TypeError

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

request_soundboard_sounds(guilds, force_request)

Requests the soundboard sounds of the given guilds.

This function is a coroutine.

ParameterTypeDefaultDescription
guilds

iterable of (Guild, int)

The guilds or their identifiers to request the sounds of.

force_request

bool

False

Whether the sounds should be requested even if they are already cached.

Returns

sounds : None, list of SoundboardSoundsEvent

Might return None if there are no guilds to request sounds from.

request_users(guild, name, ...)

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.

ParameterTypeOptionalDefaultDescription
guild

Guild, int

The guild, what's members will be requested.

name

str

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

limit

int

1

The amount of users to be received. Limited to 100.

Returns

users : list of ClientUserBase

Raises

TypeError

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

role_create(guild, ...)

Creates a role at the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild where the role will be created.

role_template

None, Role

None

Role entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the role with.

color

Color, int

The role's color.

flags

RoleFlag, int

The role's flags.

icon

None, Icon, str, bytes-like

The role's icon.

mentionable

bool

Whether the role can be mentioned.

name

str

The role's name.

permissions

int, Permission

The permissions of the users having the role.

position

int

The role's position.

separated

bool

Users show up in separated groups by their highest separated role.

unicode_emoji

None, Emoji

The role's icon as an unicode emoji.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

role_delete(role, ...)

Deletes the given role.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
role

Role, tuple(int, int)

The role to delete

reason

None, str

None

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(role, ...)

Edits the role with the given parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
role

Role, tuple(int, int)

The role to edit.

role_template

None, Role

None

Role entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the role with.

color

Color, int

The role's color.

flags

RoleFlag, int

The role's flags.

icon

None, Icon, str, bytes-like

The role's icon.

mentionable

bool

Whether the role can be mentioned.

name

str

The role's name.

permissions

int, Permission

The permissions of the users having the role.

position

int

The role's position.

separated

bool

Users show up in separated groups by their highest separated role.

unicode_emoji

None, Emoji

The role's icon as an unicode emoji.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

role_move(role, position, ...)

Moves the given role.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
role

Role, tuple of (int, int)

The role to move.

position

int

The position to move the given role.

reason

None, str

None

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).

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.

role_reorder(roles, ...)

Moves more roles at their guild to the specific positions.

Partial roles are ignored and if passed any, every role's position after it is reduced. If there are roles passed with different guilds, then ValueError will be raised. If there are roles passed with the same position, then their positions will be sorted out.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
roles

(dict like or iterable) of tuple(Role or (tuple(int, int), int) items

A dict, list, set, tuple, which contains role-position items.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If roles 's format is not any of the expected ones.

ValueError

  • If default role would be moved.
  • If any role would be moved to position 0.
  • If roles from more guilds are passed.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_create(guild, ...)

Creates a guild scheduled events.

To define, where the event will take place, use the location, stage, voice parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild, where to create the scheduled event.

scheduled_event_template

None, ScheduledEvent = None

Scheduled event to use as a template.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

description

None, str

None

The event's description. It's length can be in range [0:1000].

end

None, datetime

None

When the event will end.

location

None, str

None

The location, where the event will take place.

name

str

The event's name. It's length can be in range [1:100].

privacy_level

PrivacyLevel, int

None

The privacy level of the event. Whether it is global or guild only.

stage

None, Channel, int

None

The stage channel, where the event will take place.

start

datetime

When the event will start.

voice

None, Channel, int

None

The voice channel, where the event will take place.

Returns

scheduled_event : ScheduledEvent

The created scheduled event.

Raises

TypeError

  • If guild is neither Guild nor int.
  • Parameter of incorrect type given.
  • Extra parameters.

ValueError

  • Parameter of incorrect value given.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_delete(scheduled_event)

Edits the given scheduled event.

This method is a coroutine.

ParameterTypeDescription
scheduled_event

ScheduledEvent, tuple(int, int)

The scheduled event to edit.

Raises

TypeError

If scheduled_event is neither ScheduledEvent, nor tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_edit(scheduled_event, ...)

Edits the given scheduled event.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
scheduled_event

ScheduledEvent, tuple(int, int)

The scheduled event to edit.

scheduled_event_template

None, ScheduledEvent = None

Scheduled event to use as a template.

reason

None, str

None

Shows up at the respective guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

description

None, str

The new description of the scheduled event. It's length can be in range [0:1000].

end

None, datetime

The end of the of the scheduled event.

location

str

The new location, where the event will take place.

name

str

The new name of the scheduled event. It's length can be in range [1:100].

privacy_level

PrivacyLevel, int

The privacy level of the event. Whether it is global or guild only.

stage

Channel, int

The new stage channel, where the event will take place.

start

datetime

The new start of the scheduled event.

status

str, ScheduledEventStatus

Thew new status of the scheduled event.

voice

Channel, int

The new voice channel, where the event will take place.

Raises

TypeError

  • If scheduled_event is neither ScheduledEvent nor tuple(int, int).
  • Parameter of incorrect type given.
  • Extra parameters.

ValueError

  • Parameter of incorrect value given.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_get(scheduled_event, ...)

Gets the given scheduled event.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
scheduled_event

ScheduledEvent, tuple int and int

The scheduled event to get.

force_update

bool

False

Whether the scheduled event should be requested even if it supposed to be up to date.

Returns

scheduled_event : ScheduledEvent

Raises

TypeError

If scheduled_event is neither ScheduledEvent, nor tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_get_all_guild(guild)

Gets the given guild's scheduled event.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild to get it's scheduled of.

Returns

scheduled_events : list of ScheduledEvent

Raises

TypeError

If guild is neither Guild nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_user_get_all(scheduled_event)

Requests a chunk user subscribed to a scheduled event.

This method is a coroutine.

ParameterTypeDescription
scheduled_event

ScheduledEvent, tuple int and int

The scheduled event to get.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If scheduled_event is neither ScheduledEvent, nor tuple(int, int) instance.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

scheduled_event_user_get_chunk(scheduled_event, ...)

Requests a chunk user subscribed to a scheduled event.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
scheduled_event

ScheduledEvent, tuple int and int

The scheduled event to get.

after

None, int, DiscordEntity, datetime

None

The timestamp after the subscribed users were created.

before

None, int, DiscordEntity, datetime

None

The timestamp before the subscribed users were created.

limit

None, int

None

The amount of scheduled event users to request. Can be between 1 and 100.

Returns

users : list of ClientUserBase

Raises

TypeError

  • If scheduled_event is neither ScheduledEvent, nor tuple(int, int) instance.
  • If after, 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.
  • If limit is out of range [1:100].

sku_get_all()

Requests the client's application's stock keeping unit.

This method is a coroutine.

Returns

skus : list of SKU

The received stock keeping units.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

soundboard_sound_create(guild, sound, ...)

Creates a soundboard sound at the given guild.

This function is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild where the soundboard sound will be created.

sound

bytes-like

The sound to add. Expected to be in mp3 format.

soundboard_sound_template

None, SoundboardSound

None

soundboard sound entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the soundboard_sound with.

emoji

None, Emoji

Emoji assigned to the sound.

name

str

The name of the sound.

volume

float

The volume of the sound to play as.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

soundboard_sound_delete(soundboard_sound, ...)

Deletes the given soundboard_sound.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
soundboard_sound

SoundboardSound, tuple(int, int)

The soundboard sound to delete

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

If soundboard_sound was not given neither as SoundboardSound nor as tuple of (int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

soundboard_sound_edit(soundboard_sound, ...)

Edits the soundboard sound with the given parameters.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
soundboard_sound

SoundboardSound, tuple(int, int)

The soundboard sound to edit.

soundboard_sound_template

None, SoundboardSound

None

Soundboard sound entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the soundboard sound with.

emoji

None, Emoji

Emoji assigned to the sound.

name

str

The name of the sound.

volume

float

The volume of the sound to play as.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

soundboard_sound_get_all_default()

Requests the default soundboard sounds.

This method is a coroutine.

Returns

sounds : list of SoundboardSound

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

stage_create(channel, ...)

Edits the given stage channel.

Will trigger a stage_create event.

The endpoint has a long rate limit, so please use .stage_edit to edit just the stage's topic.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel to create the stage at.

stage_template

None, Stage

None

Stage entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the role with.

privacy_level

PrivacyLevel, int

The new privacy level of the stage. Defaults to guild only.

scheduled_event

int, ScheduledEvent

Alternative for scheduled_event_id.

scheduled_event_id

int, ScheduledEvent

The scheduled event's identifier that started the stage.

send_start_notification

bool

Whether @everyone should be notified when the stage is started.

You must have mention everyone permission.

topic

None, str

The topic of the stage.

Returns

stage : Stage

The created stage instance.

Raises

TypeError

  • If channel was not given as Channel neither as int.
  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

stage_delete(stage, ...)

Deletes the given stage channel.

Will trigger a stage_delete event.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
stage

Stage, Channel, int

The stage to delete. Can be given as it's channel's identifier.

reason

None, str

None

Shows up at the guild's audit logs.

Raises

TypeError

If stage was not given as Stage, Channel neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

stage_edit(stage, ...)

Edits the given stage channel.

Will trigger a stage_edit event.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
stage

Stage, Channel, int

The stage to edit. Can be given as it's channel's identifier.

stage_template

None, Stage

None

Stage entity to use as a template.

reason

None, str

None

Shows up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters to create the role with.

privacy_level

PrivacyLevel, int

The new privacy level of the stage.

topic

None, str

The new topic of the stage.

Raises

TypeError

  • If channel was not given as Channel neither as int.
  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

stage_get(channel)

Gets the stage of the given stage channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

The stage's channel's identifier.

Raises

TypeError

If channel was not given as Channel neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

start()

Starts the clients' connecting to Discord. If the client is already running, raises RuntimeError.

The return of the method depends on the thread, from which it was called from.

Returns

task : bool, Task, FutureWrapperAsync

  • If the method was called from the client's thread (KOKORO), then returns a Task. The task will return True, if connecting was successful.
  • If the method was called from an EventThread, but not from the client's, then returns a FutureWrapperAsync. The task will return True, if connecting was successful.
  • If the method was called from any other thread, then waits for the connector task to finish and returns True, if it was successful.

Raises

RuntimeError

If the client is already running.

sticker_create(guild, name, tags, image, ...)

Creates a sticker in the guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

The guild to create the sticker in.

name

str

The sticker's name.

tags

None, str, iterable of str

The tags of the sticker.

image

bytes-like

The sticker's image in bytes.

description

None, str

None

The sticker's representation.

reason

None, str

None

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

Returns

sticker : Sticker

The created sticker.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ValueError

If image s media type is neither image/png nor application/json.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_delete(sticker, ...)

Deletes the sticker.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
sticker

Sticker, int

The sticker to delete.

reason

None, str

None

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

Raises

TypeError

If sticker is neither Sticker, nor int.

ValueError

  • Standard stickers cannot be deleted.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_edit(sticker, ...)

Edits the given guild bound sticker,

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
sticker

Sticker, int

The respective sticker.

name

str

New name of the sticker. It's length can be in range [2:32].

tags

str, Emoji, iterable of str

The new emoji representation of the sticker. Used as a tag for the sticker.

description

None, str

New description for the sticker. It's length can be in range [0:100].

reason

None, str

None

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

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.
  • Standard stickers cannot be edited.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_get(sticker, ...)

Gets an sticker by it's id. If the sticker is already loaded updates it.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
sticker

Sticker, int

The sticker, who will be requested.

force_update

bool

False

Whether the sticker should be requested even if it supposed to be up to date.

Returns

sticker : Sticker

Raises

TypeError

If sticker was not given neither as Sticker, neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

TypeError

If sticker was not given as Sticker, nor as int.

sticker_get_all_guild(guild)

Syncs the given guild's stickers with the wrapper.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's stickers will be synced.

Returns

stickers : list of Sticker

The guild's stickers.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_get_guild(sticker, ...)

Gets the specified sticker from the respective guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
sticker

Sticker, tuple, (int, int)

The sticker to get.

force_update

bool

False

Whether the sticker should be requested even if it supposed to be up to date.

Raises

TypeError

If sticker is not Sticker, tuple(int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_guild_create()

Deprecated and will be removed in 2023 December. Please use .sticker_create instead.

sticker_guild_delete()

Deprecated and will be removed in 2023 December. Please use .sticker_delete instead.

sticker_guild_edit()

Deprecated and will be removed in 2023 December. Please use .sticker_edit instead.

sticker_guild_get()

Deprecated and will be removed in 2023 December. Please use .sticker_get_guild instead.

sticker_guild_get_all()

Deprecated and will be removed in 2023 December. Please use .sticker_get_all_guild instead.

sticker_pack_get(sticker_pack, ...)

Gets the sticker packs. If the sticker-packs are already loaded, updates them.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
sticker_pack

StickerPack, int

The sticker pack' identifier.

force_update

bool

False

Whether the sticker-pack should be requested even if it supposed to be up to date.

Returns

sticker_packs : list of StickerPack

Raises

TypeError ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

sticker_pack_get_all(...)

Gets the sticker packs. If the sticker-packs are already loaded, updates them.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
force_update

bool

False

Whether the sticker-packs should be requested even if it supposed to be up to date.

Returns

sticker_packs : list of StickerPack

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

stop()

Starts disconnecting the client.

The return of the method depends on the thread, from which it was called from.

Returns

task : None, Task, FutureWrapperAsync

  • If the method was called from the client's thread (KOKORO), then returns a Task.
  • If the method was called from an EventThread, but not from the client's, then returns a FutureWrapperAsync.
  • If the method was called from any other thread, returns None when disconnecting finished.

stream_invite_create(guild, user, ...)

Creates an STREAM invite at the given guild for the specific user. The user must be streaming at the guild, when the invite is created.

Deprecated and will be removed in 2024 February.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild

The guild where the user streams.

user

ClientUserBase, int

The streaming user.

max_age

int

0

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

max_uses

int

0

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

unique

bool

True

Whether the created invite should be unique.

temporary

bool

False

Whether the invite should give only temporary membership.

Returns

invite : Invite

Raises

TypeError

ValueError

  • If the user is not streaming at the guild.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_create(message_or_channel, ...)

Creates a new thread derived from the given message or channel.

For private thread channels the guild needs to have level 2 boost level.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
message_or_channel

Channel, Message, int, tuple(int, int)

The channel or message to create thread from.

If given as a channel instance, will create a private thread, else a public one.

channel_template

None, Channel

None

Channel to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

applied_tag_ids

None, (list | tuple)<int | ForumTag>, int, ForumTag

The tags' identifier which have been applied to the thread.

applied_tags

None, (list | tuple)<int | ForumTag>, int, ForumTag

Alternative for applied_tag_ids.

auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

channel_type

None, ChannelType, int

None

The type of the created (thread) channel.

flags

int, ChannelFlag

The channel's flags.

invitable

bool

Whether non-moderators can invite other non-moderators to the threads.

name

str

The channel's name.

open_

bool

Whether the thread channel is open.

slowmode

int

The channel's slowmode.

Returns

thread_channel : Channel

The created thread channel.

Raises

TypeError

If any parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_join(thread_channel)

Joins the client to the given thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to join to, or it's identifier.

Raises

TypeError

If thread_channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_leave(thread_channel)

Leaves the client to the given thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to join to, or it's identifier.

Raises

TypeError

If thread_channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_user_add(thread_channel, user)

Adds the user to the thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to add the user to, or it's identifier.

user

ClientUserBase, int

The user to add to the the thread.

Raises

TypeError

  • If thread_channel 's type is incorrect.
  • If user 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_user_delete(thread_channel, user)

Deletes the user to the thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to remove the user from, or it's identifier.

user

ClientUserBase, int

The user to remove from the thread.

Raises

TypeError

  • If thread_channel 's type is incorrect.
  • If user 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_user_get(thread_channel, user)

Gets a user's thread profile inside of a thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to get the user's thread profile of.

user

ClientUserBase, int

The user to get it's thread profile of.

Returns

user : ClientUserBase

The user, who's thread profile was requested.

Raises

TypeError

  • If thread_channel 's type is incorrect.
  • If user 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

thread_user_get_all(thread_channel)

Gets all the users of a thread channel.

This method is a coroutine.

ParameterTypeDescription
thread_channel

Channel, int

The channel to get it's users of.

Returns

users : list of ClientUserBase

The created users.

Raises

TypeError

If thread_channel 's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

to_data(...)

Tries to convert the user back to a json serializable dictionary.

ParameterTypeOptionalKeyword onlyDefaultDescription
defaults

bool

False

Whether default values should be included as well.

include_internals

bool

False

Whether internal fields should be included as well.

Returns

data : dict of (str, object) items

top_role_at(guild, ...)

Returns the top role of the user at the given guild.

ParameterTypeOptionalDefaultDescription
guild

None, Guild, int

The guild where the user's top role will be looked up.

default

object

None

If the user is not a member of the guild, or if has no roles there, then the given default value is returned. Defaults to None.

Returns

top_role Role, default

typing(channel)

Sends a typing event to the given channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

The channel where typing will be triggered.

Raises

TypeError

If channel was not given neither as Channel nor int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

The client will be shown up as typing for 8 seconds, or till it sends a message at the respective channel.

update_application_info()

Updates the client's application's info.

This method is a coroutine.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

Meanwhile the clients logs in this method is called to ensure that the client's application info is loaded.

This endpoint is available only for bot accounts.

user_achievement_get_all(access)

Requests the achievements of a user with it's oauth2 access.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str.

The access of the user, who's achievements will be requested.

Returns

achievements : list of Achievement objects

Raises

TypeError

If access was not given neither as Oauth2Access, Oauth2User or str.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint is unintentionally documented and will never work. For reference: https://github.com/discordapp/discord-api-docs/issues/1230.

Always drops DiscordException UNAUTHORIZED (401): 401: Unauthorized.

user_achievement_update(user, achievement, percent_complete)

Updates the user 's achievement with the given percentage. The achievement should be secure. This method only updates the achievement's percentage.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user, who's achievement will be updated.

achievement

Achievement, int

The achievement, what's state will be updated

percent_complete

int

The completion percentage of the achievement.

Can be in range [0:100]. If outside is adjusted to the respective limit.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

This endpoint cannot grant achievement, but can it even update them?. For reference: https://github.com/discordapp/discord-api-docs/issues/1230.

Only secure updates are supported, if they are even.

  • When updating secure achievement: DiscordException NOT FOUND (404), code = 10029: Unknown Entitlement
  • When updating non secure: DiscordException FORBIDDEN (403), code = 40001: Unauthorized

user_application_role_connection_edit(access, ...)

Edits a user's application role connections with it's Oauth2Access. The user must provide the Oauth2Scope.role_connections_write scope for this request to succeed.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
access

Oauth2Access, Oauth2User, str

The access of the user, who will's application role connections will be requested..

application_role_connection_template

None, ApplicationRoleConnection

None

Application role connection to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters either to define the template, or to overwrite specific fields' values.

platform_name

None, str

The vanity name of the platform the application represents.

platform_user_name

None, str

The name of the user on the application's platform.

metadata_values

None, dict of (str, str) items

Metadata key to attached value relation.

Returns

application_role_connection : ApplicationRoleConnection

Raises

TypeError

ValueError

  • If the given access is not providing the required scope.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_application_role_connection_get(access)

Requests a user's application role connections with it's Oauth2Access. The user must provide the Oauth2Scope.role_connections_write scope for this request to succeed.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str

The access of the user, who will's application role connections will be requested..

Returns

application_role_connection : ApplicationRoleConnection

Raises

TypeError

ValueError

  • If the given access is not providing the required scope.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_connection_get_all(access)

Requests a user's connections. This method will work only if the access token has the 'connections' scope. At the returned list includes the user's hidden connections as well.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str

Oauth2 access to the respective user or it's access token.

Returns

connections : list of Connection

The user's connections.

Raises

TypeError

ValueError

  • If the given access is not providing the required scope.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_get(user, ...)

Gets an user by it's id. If the user is already loaded updates it.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
user

ClientUserBase, int

The user, who will be requested.

force_update

bool

False

Whether the user should be requested even if it supposed to be up to date.

Returns

user : ClientUserBase

Raises

TypeError

If user was not given as ClientUserBase, nor as int.

user_guild_get_all(access)

Requests a user's guilds with it's Oauth2Access. The user must provide the Oauth2Scope.guilds scope for this request to succeed.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str

The access of the user, who's guilds will be requested.

Returns

guilds_and_permissions : list of tuple(Guild, UserGuildPermission)

The guilds and the user's permissions in each of them. Not loaded guilds will show up as partial ones.

Raises

TypeError

ValueError

  • If the given access is not providing the required scope.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_guild_profile_edit(guild, user, ...)

Edits the user's guild profile at the given guild.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
guild

Guild, int

Where the user will be edited.

user

ClientUserBase, int

The user to edit, or their identifier.

reason

None, str

None

Will show up at the guild's audit logs.

**keyword_parameters

Keyword parameters

Additional keyword parameters representing which field of the guild profile should be edited.

deaf

bool

Whether the user should be deafen at the voice channels.

mute

bool

Whether the user should be muted at the voice channels.

nick

None, str

The new nick of the user. You can remove the current one by passing it as None, an empty string.

voice_channel

None, Channel, int

Moves the user to the given voice channel. Only applicable if the user is already at a voice channel.

Pass it as None to disconnect the user from it's voice channel.

role_ids

None, iterable of (Role, int)

The new roles of the user. Give it as None to remove all of the user's roles.

roles

None, iterable of (Role, int)

Alternative of role_ids.

timed_out_until

None, DateTime

Until when the user is timed out.

timeout_duration

int, float, TimeDelta

The timeout duration of the user in seconds.

The max allowed value equals to 28 days.

voice_channel

None, Channel, int

Alternative of voice_channel_id.

voice_channel_id

None, Channel, int

Moves the user to the given voice channel. Only applicable if the user is already at a voice channel.

Pass it as None to disconnect the user from it's voice channel.

Raises

TypeError

  • If a parameter's type is incorrect.

ValueError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_info_get(access)

Request the a user's information with oauth2 access token. By default a bot account should be able to request every public information about a user (but you do not need oauth2 for that). If the access token has email or/and identify scopes, then more information should show up like this.

This method is a coroutine.

ParameterTypeDescription
access

Oauth2Access, Oauth2User, str

Oauth2 access to the respective user or it's access token.

Returns

oauth2_user : Oauth2User

The requested user object.

Raises

TypeError

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

Needs 'email' or / and 'identify' scopes granted for more data

user_role_add(user, role, ...)

Adds the role on the user.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
user

ClientUserBase, int

The user who will get the role.

role

Role, tuple(int, int)

The role to add on the user.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int.
  • 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.

user_role_delete(user, role, ...)

Deletes the role from the user.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
user

ClientUserBase, int

The user from who the role will be removed.

role

Role, tuple(int, int)

The role to remove from the user.

reason

None, str

None

Shows up at the respective guild's audit logs.

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int.
  • 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.

user_voice_kick(user, guild)

Kicks the user from the guild's voice channels. The user must be in a voice channel at the guild.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user who will be kicked from the voice channel.

guild

Guild, int

The guild from what's voice channel the user will be kicked.

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_voice_move(user, channel)

Moves the user to the given voice channel. The user must be in a voice channel at the respective guild already.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user to move.

channel

Channel, tuple(int, int)

The channel where the user will be moved.

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int.
  • If channel was not given neither as Channel nor as tuple of (int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_voice_move_to_audience(user, channel)

Moves the user to the audience inside of a stage channel.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user to move.

channel

Channel, tuple(int, int)

The channel where the user will be moved.

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int.
  • If channel was not given neither as Channel nor as tuple of (int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

user_voice_move_to_speakers(user, channel)

Moves the user to the speakers inside of a stage channel.

This method is a coroutine.

ParameterTypeDescription
user

ClientUserBase, int

The user to move.

channel

Channel, tuple(int, int)

The channel where the user will be moved.

Raises

TypeError

  • If user was not given neither as ClientUserBase, neither as int.
  • If channel was not given neither as Channel nor as tuple of (int, int).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

vanity_invite_edit()

Deprecated and will be removed in 2023 February. Please use .invite_edit_vanity instead.

verification_screen_edit(guild, ...)

Requests the given guild's verification screen.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
guild

Guild, int

The guild what's verification screen will be edited.

verification_screen_template

None, VerificationScreen = None

Verification screen to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the verification screen with.

description

None, str

The guild's description shown in the verification screen.

edited_at

None, datetime

When the last version of the screen was created.

enabled

bool

Whether the verification screen should be enabled.

steps

None, tuple of VerificationScreenStep

The step in the verification screen.

Returns

verification_screen : VerificationScreen

Raises

TypeError

  • If guild was not Guild, int.
  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

verification_screen_get(guild)

Requests the given guild's verification screen.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's verification screen will be requested.

Returns

verification_screen : None, VerificationScreen

Raises

TypeError

  • If guild was not Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If the guild has no verification screen enabled, will not do any request.

voice_client_for(message)

Returns the voice client for the given message's guild if it has any.

ParameterTypeDescription
message

Message

The message what's voice client will be looked up.

Returns

voice_client : None, VoiceClient

The voice client if applicable.

voice_region_get_all()

Returns all the voice regions.

This method is a coroutine.

Returns

voice_regions : list of VoiceRegion objects

Received voice regions.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

wait_for(event_name, check, ...)

O(n) event waiter with massive overhead compared to other optimized event waiters.

This method is a coroutine.

ParameterTypeOptionalDefaultDescription
event_name

str

The respective event's name.

check

callable

Check, what tells that the waiting is over.

If the check returns True the received args are passed to the waiter future and returned by the method. However if the check returns any non bool value, then that object is passed next to args and returned as well.

timeout

None, float

None

Timeout after TimeoutError is raised and the waiting is cancelled.

Returns

result : object

Parameters passed to the check and the value returned by the check if it's type is not bool.

Raised

TimeoutError

Timeout occurred.

BaseException

Any exception raised by check.

webhook_create(channel, name, ...)

Creates a webhook at the given channel.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel

Channel, int

The channel of the created webhook.

name

str

The name of the new webhook. It's length can be in range [1:80].

avatar

None, bytes-like

None

The webhook's avatar. Can be 'jpg', 'png', 'webp', 'gif' image's raw data. However if set as 'gif', it will not have any animation.

Returns

webhook : Webhook

The created webhook.

Raises

TypeError

  • If channel was not given neither as Channel nor as int.
  • If avatar was not given neither as None, bytes-like.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was not given as str.
  • If name range is out of the expected range [1:80].
  • If avatar 's type is not any of the expected ones: 'jpg', 'png', 'webp', 'gif'.

webhook_delete(webhook)

Deletes the webhook.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, int

The webhook to delete.

Raises

TypeError

If webhook was not given neither as Webhook, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

.webhook_delete_token: Deleting webhook with Discord's webhook API.

webhook_delete_token(webhook, webhook)

Deletes the webhook through Discord's webhook API.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, tuple(int, str)

The webhook to delete.

webhook

Webhook

The webhook to delete.

Raises

TypeError

If webhook was not given neither as Webhook neither as a tuple(int, str).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

webhook_edit(webhook, ...)

Edits and updates the given webhook.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
webhook

Webhook, int

The webhook to edit.

name

str

The webhook's new name. It's length can be in range [1:80].

avatar

None, bytes-like

The webhook's new avatar. Can be 'jpg', 'png', 'webp', 'gif' image's raw data. However if set as 'gif', it will not have any animation. If passed as None, will remove the webhook's current avatar.

channel

Channel, int

The webhook's channel.

Raises

TypeError

  • If webhook was not given neither as Webhook neither as int.
  • If avatar was not given neither as None nor as bytes-like.
  • If channel was not given neither as Channel neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

  • If name was given but not as str.
  • If name 's length is out of range [1:80].
  • If avatar 's type is not any of the expected ones: 'jpg', 'png', 'webp', 'gif'.

See Also

.webhook_edit_token: Editing webhook with Discord's webhook API.

webhook_edit_token(webhook, ...)

Edits and updates the given webhook through Discord's webhook API.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
webhook

Webhook, tuple(int, str)

The webhook to edit.

name

str

The webhook's new name. It's length can be between 1 and 80.

avatar

None, bytes-like

The webhook's new avatar. Can be 'jpg', 'png', 'webp', 'gif' image's raw data. However if set as 'gif', it will not have any animation. If passed as None, will remove the webhook's current avatar.

Returns

webhook : Webhook

The updated webhook.

Raises

TypeError

  • If webhook was not given neither as Webhook neither as a tuple(int, str).
  • If avatar was not given neither as None nor 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.
  • If name 's length is out of range [1:80].
  • If avatar 's type is not any of the expected ones: 'jpg', 'png', 'webp', 'gif'.

Notes

This endpoint cannot edit the webhook's channel, like .webhook_edit.

webhook_get(webhook)

Requests the webhook by it's id.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, int

The webhook to update or the webhook's id to get.

Returns

webhook : Webhook

Raises

TypeError

If webhook was not given neither as Webhook neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If the webhook already loaded and if it's guild's webhooks are up to date, no request is done.

See Also

.webhook_get_token: Getting webhook with Discord's webhook API.

webhook_get_all_channel(channel)

Requests all the webhooks of the channel.

This method is a coroutine.

ParameterTypeDescription
channel

Channel, int

The channel, what's webhooks will be requested.

Returns

webhooks : list of Webhook objects

Raises

TypeError

If channel was not given neither as Channel, neither as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

You may expect the following exceptions:

Error codeInternal nameReason
10003unknown_channelThe channel not exists.
50013missing_permissionsYou need manage_webhooks permission. (Or the client has no access to the channel.)
60003mfa_requiredYou need to have multi-factor authorization to do this operation (guild setting dependent). For bot accounts it means their owner needs mfa.

Discord drops Forbidden (403), code = 50013: Missing Permissions instead of Forbidden (403), code = 50001: Missing Access.

AssertionError

If channel was given as a channel's identifier but it detectably not refers to a Channel.

Notes

No request is done, if the passed channel is partial, or if the channel's guild's webhooks are up to date.

webhook_get_all_guild(guild)

Requests the webhooks of the given guild.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild, what's webhooks will be requested.

Returns

webhooks : list of Webhook objects

Raises

TypeError

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

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

No request is done, if the guild's webhooks are up to date.

webhook_get_own_channel(channel)

Requests the webhooks of the given channel and returns the first owned one.

ParameterTypeDescription
channel

Channel, int

The channel, what's webhooks will be requested.

Returns

webhooks : list of Webhook objects

webhook_get_token(webhook)

Requests the webhook through Discord's webhook API. The client do not needs to be in the guild of the webhook.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, tuple(int, str)

The webhook to update or the webhook's id and token.

Returns

webhook : Webhook

Raises

TypeError

If webhook was not given neither as Webhook neither as a tuple(int, str).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

If the webhook already loaded and if it's guild's webhooks are up to date, no request is done.

webhook_message_create(webhook, ...)

Sends a message with the given webhook. If there is nothing to send, or if wait was not passed as True returns None.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDefaultDescription
webhook

Webhook, tuple(int, str)

The webhook through what will the message be sent.

*positional_parameters

Positional parameters

Additional parameters to create the message with.

thread

None, Channel, int

None

The thread of the webhook's channel where the message should be sent.

wait

None, bool

None

Whether we should wait for the message to send and receive it's data as well.

**keyword_parameters

Keyword parameters

Additional parameters to create the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

applied_tag_ids

None, (list | tuple)<int | ForumTag>, int, ForumTag

The tags' identifier which have been applied to the thread. Applicable for threads of a forum-like channels.

applied_tags

None, (list | tuple)<int | ForumTag>, int, ForumTag

Alternative for applied_tag_ids.

attachments

None, object

Attachments to send.

avatar_url

None, str

None

The message's author's avatar's url. Defaults to the webhook's avatar' url by Discord.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

content

None, str

The message's content if given.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's flags.

name

None, str

None

The message's author's new name. Default to the webhook's name by Discord.

silent

bool

False

Whether the message should be delivered silently.

suppress_embeds

bool

False

Whether the message's embeds should be suppressed initially.

thread_name

None, str

The thread's name to create. Applicable only in forum-like channels.

tts

bool

False

Whether the message is text-to-speech.

Returns

message : Message, None

Returns None if there is nothing to send or if wait was given as False(so by default).

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

webhook_message_delete(webhook, message)

Deletes the message sent by the webhook.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, tuple(int, str)

The webhook who created the message.

message

Message, int

The webhook's message to delete.

Raises

TypeError

  • If message was not given neither as Message, int.
  • If webhook was not given neither as Webhook neither as a tuple(int, str).

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

AssertionError

If message was detectably not sent by the webhook.

See Also

webhook_message_edit(webhook, message, ...)

Edits the message sent by the given webhook. The message's author must be the webhook itself.

ParameterTypeOptionalKeyword onlyDescription
webhook

Webhook, tuple(int, str)

The webhook who created the message.

message

Message, int

The webhook's message to edit.

*positional_parameters

Positional parameters

Additional parameters to edit the message with.

**keyword_parameters

Keyword parameters

Additional parameters to edit the message with.

allowed_mentions

None, AllowedMentionProxy, str, UserBase, Role, list of (str, UserBase, Role)

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

attachments

None, object

Attachments to send.

components

None, Component, (tuple | list)<Component, (tuple | list)<Component>>

Components attached to the message.

Pass it as None remove the actual ones.

content

None, str

The new content of the message.

embed

None, Embed

Alternative for embeds.

embeds

None, list<Embed>

The new embedded content of the message.

By passing it as None, you can remove the old.

file

None, object

Alternative for attachments.

files

None, object

Alternative for attachments.

flags

int, MessageFlag

The message's new flags.

suppress_embeds

bool

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

Raises

TypeError

  • If a parameter's type is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

Notes

Embed messages ignore suppression with their endpoint, not like .message_edit endpoint.

Editing the message with empty string is broken.

See Also

webhook_message_get(webhook, message_id)

Gets a previously sent message with the webhook.

This method is a coroutine.

ParameterTypeDescription
webhook

Webhook, tuple(int, str)

The webhook who created the message.

message_id

int

The webhook's message's identifier to get.

Returns

message : Message

Raises

TypeError

  • If webhook was not given neither as Webhook neither as a tuple(int, str).
  • If message_id was not given as int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

See Also

welcome_screen_edit(guild, ...)

Edits the given guild's welcome screen.

This method is a coroutine.

ParameterTypeOptionalKeyword onlyDescription
guild

Guild, int

The guild, what's welcome screen will be edited.

welcome_screen_template

None, WelcomeScreen = None

Welcome screen to use as a template.

**keyword_parameters

Keyword parameters

Additional keyword parameters to edit the welcome screen with.

description

None, str

Description, of what is the server about.

enabled

bool

Whether the welcome screen should be enabled.

welcome_channels

None, iterable of WelcomeScreenChannel

The featured channels by the welcome screen.

Returns

welcome_screen : WelcomeScreen

Raises

TypeError

  • If guild is not Guild, int.
  • If a parameter's type is incorrect.

ValueError

  • If a parameter's value is incorrect.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

welcome_screen_get(guild)

Requests the given guild's welcome screen.

You need to have manage guild permission to request the welcome screen if the guild has it disabled.

This method is a coroutine.

ParameterTypeDescription
guild

Guild, int

The guild what's welcome screen will be requested.

Returns

welcome_screen : WelcomeScreen

Raises

TypeError

  • If guild is not Guild, int.

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

_bypass_no_cache(data, guild_profile_data, guild_id)

Sets a Client 's guild profile.

Only available when user or presence caching is disabled.

ParameterTypeDescription
data

dict<str, object>

Received user data.

guild_profile_data

dict<str, object>

The user's guild profile's data.

guild_id

int

A respective guild's identifier from where the user data was received. Picked up if the given data includes guild member data as well.

Returns

user : ClientUserBase

_compare_attributes(other)

Compares the two user's user attributes (excluding id obviously).

ParameterTypeDescription
other

instance<type<self>>

The other user.

Returns

is_equal : bool

_compare_user_attributes_extended(other)

Compares the two user's user attributes (excluding id obviously).

ParameterTypeDescription
other

instance<type<self>>

The other user.

Returns

is_equal : bool

_connect()

Connects the client's gateway(s) to Discord and reconnects them if needed.

This method is a coroutine.

_create_empty(user_id)

Creates a user with its default attributes values set.

ParameterTypeDescription
user_id

int

The user's identifier.

Returns

self : instance<cls>

_delay_ready(guild_datas, shard_id)

Delays the client's "ready" till it receives all of it guild's data. If caching is allowed (so by default), then it waits additional time till it requests all the members of it's guilds.

ParameterTypeDescription
guild_datas

list of dict(str, object) items

Partial data for all the guilds to request the users of.

shard_id

int

The received shard's identifier.

_delete()

Clears up the client's references. By default this is not called when a client is stopped. This method should be used when you want to get rid of every allocated objects by the client. Take care, local modules might still have active references to the client or to some other objects, what could cause them to not garbage collect.

Raises

RuntimeError

If called when the client is still running.

Examples

>>> from hata import Client, GUILDS
>>> import gc
>>> TOKEN = 'a token goes here'
>>> client = Client(TOKEN)
>>> client.start()
>>> len(GUILDS)
4
>>> client.stop()
>>> client._delete()
>>> client = None
>>> gc.collect()
680
>>> len(GUILDS)
0

_difference_update_attributes(data)

Updates the user and returns it's overwritten attributes as a dict with a attribute-name- old-value relation.

ParameterTypeDescription
data

dict of (str, object) items

User data received from Discord.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

KeysValuesApplicable for
avatarIconall
avatar_decorationNone, AvatarDecorationClient, User
bannerIconClient, User
banner_colorNone, ColorClient, User
channel_idintWebhook
discriminatorintClient, User
display_nameNone, strClient, User
emailNone, strClient
email_verifiedboolClient
flagsUserFlagClient, User
localeLocaleClient
mfa_enabledboolClient
namestrall
premium_typePremiumTypeClient

_difference_update_presence(data)

Updates the user's presence and returns it's overwritten attributes as a dict with a attribute-name- old-value relation. An exception from this is activities, because that's a ActivityChange containing all the changes of the user's activities.

ParameterTypeDescription
data

dict of (str, object) items

Received guild member data.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

KeysValues
activitiesActivityChange
statusStatus
statusesNone, dict of (str, str) items

_difference_update_profile(data, guild)

Tries to find the user's respective guild profile. If it cannot find it, creates it.

ParameterTypeDescription
data

dict<str, object>

Received guild profile data.

guild

Guild

The respective guild of the profile to update.

Returns

old_attributes : None | dict<str, object>

The changed attributes of the respective guild profile as a dict with attribute-name- old-attribute relation.

May return None indicating that the guild profile was not cached before so we cannot determine whether it would have been updated.

The possible keys and values within old_attributes are all optional and they can be any of the following:

KeysValues
avatarIcon
boosts_sinceNone, DateTime
flagsNone, GuildProfileFlags
nickNone, str
pendingbool
role_idsNone, tuple of int
timed_out_untilNone, DateTime

_from_client(client, include_internals)

Creates a client alter ego.

ParameterTypeDescription
client

Client

The client to copy.

include_internals

bool

Whether internal fields should be copied as well.

Returns

user : ClientUserBase

_from_data_and_difference_update_profile(data, guild)

First tries to find the user, then it's respective guild profile for the given guild to update it.

If the method cannot find the user, or the respective guild profile, then creates them.

ParameterTypeDescription
data

dict<str, object>

Received guild member data.

guild

Guild

The respective guild of the profile to update.

Returns

user : ClientUserBase

The respective user.

old_attributes : None | dict<str, object>

The changed attributes of the respective guild profile as a dict with attribute-name- old-attribute relation.

May return None indicating that the guild profile was not cached before so we cannot determine whether it would have been updated.

The possible keys and values within old_attributes are all optional and they can be any of the following:

KeysValues
avatarIcon
boosts_sinceNone, DateTime
flagsNone, GuildProfileFlags
nickNone, str
pendingbool
role_idsNone, tuple of int
timed_out_untilNone, DateTime

_from_data_and_update_profile(data, guild)

First tries to find the user, then it's respective guild profile for the given guild to update it.

If the method cannot find the user, or the respective guild profile, then creates them.

Not like ._from_data_and_difference_update_profile, this method not calculates changes.

ParameterTypeDescription
data

dict<str, object>

Received guild member data.

guild

Guild

The respective guild of the profile to update.

Returns

user : ClientUserbase

The updated user.

_get_hash_partial()

Returns a partial user's hash value.

Returns

hash_value : int

_init_on_ready(data)

Fills up the client's instance attributes on login. If there is an already existing User object with the same id, the client will replace it at channel participants, at USERS weakreference dictionary, at guild.users. This replacing is avoidable, if at the creation of the client the .client_id parameter is set.

ParameterTypeDescription
data

dict of (str, object) items

Data requested from Discord by the .client_login_static method.

Raises

RuntimeError

Creating the same client multiple times is not allowed.

_is_equal_same_type(other)

Returns whether the two users are equal. self and other must be the same type.

ParameterTypeDescription
other

instance<type<self>>

The other user.

Returns

is_equal : bool

_load_messages_till(channel, index)

An internal function to load the messages at the given channel till the given index. Should not be called if the channel reached it's message history's end.

This method is a coroutine.

ParameterTypeDescription
channel

Channel

The channel from where the messages will be requested.

index

int

Till which index the messages should be requested at the given channel.

Returns

result_state : int

can return the following variables describing a state:

ValueDescription
0Success.
1index could not be reached, there is no more messages at the channel.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

_maybe_replace_alter_ego()

Replaces the type User alter_ego of the client if applicable.

_request_users(guild_id)

Requests the members of the given guild. Called when the client joins a guild and user caching is enabled (so by default).

This method is a coroutine.

ParameterTypeDescription
guild_id

int

The guild, what's members will be requested.

_role_reorder_roles_element_validator(item)

Validates a role-position pair.

This method is a coroutine.

ParameterTypeDescription
item

tuple(Role or (tuple(int, int ), int ) items or object

A dict, list, set, tuple, which contains role-position items.

Yields

item : None, tuple(Role, Guild, int)

Returns

role : Role

The validated role.

guild : None, Guild

The role's guild.

Raises

TypeError

If item has invalid format.

_role_reorder_roles_validator(roles)

Validates roles parameter of .role_reorder.

This method is an asynchronous generator.

ParameterTypeDescription
roles

(dict like or iterable) of tuple(Role or (tuple(int, int ), int) items

A dict, list, set, tuple, which contains role-position items.

Yields

item : None, tuple(Role, Guild, int)

Raises

TypeError

If roles 's format is not any of the expected ones.

_set_default_attributes()

Sets the user's attribute's to their default.

_update_attributes(data)

Updates the user with the given data by overwriting it's old attributes.

ParameterTypeDescription
data

dict of (str, object) items

User data received from Discord.

_update_presence(data)

Updates the user's presences with the given data.

ParameterTypeDescription
data

dict of (str, object) items

Received guild member data.

_update_profile(data, guild)

Tries to find the user's respective guild profile. If it cannot find it, creates it.

ParameterTypeDescription
data

dict<str, object>

Received guild profile data.

guild

Guild

The respective guild of the profile to update.

Returns

updated : bool

Returns True if the guild profile was updated and False when created.

__eq__()

Return whether the user's id is equal to the other.

__format__(code)

Formats the user in a format string.

ParameterTypeDescription
code

str

The option on based the result will be formatted.

Returns

user : str

Raises

ValueError

Unknown format code.

Examples

>>> from hata import User, now_as_id
>>> user = User.precreate(now_as_id(), name = 'Neko', discriminator = 2012)
>>> user
<User id = 730233383967260672, name = 'Neko#2012'>
>>> # no code stands for `user.name`.
>>> f'{user}'
'Neko'
>>> # 'f' stands for full name
>>> f'{user:f}'
'Neko#2012'
>>> # 'm' stands for mention.
>>> f'{user:m}'
'<@730233383967260672>'
>>> # 'c' stands for created at.
>>> f'{user:c}'
'2020.07.08-01:26:45'

__ge__()

Returns whether the user's id is greater or equal to the other.

__getattr__()

Drops a rich attribute error.

__gt__()

Returns whether the user's id is greater than the other's.

__hash__()

Returns the user's hash.

__le__()

Returns whether the user's id is less or equal to the other.

__lt__()

Returns whether the user's id is less than the other's.

__ne__()

Returns whether the user's id is different as the other's.

__repr__()

Returns the user's representation.