API Reference

The section dives into every aspect of the core API of NeoCord.

Core

Client

class neocord.Client

Represents a client that interacts with the Discord API. This is the starter point of any bot and core class for creating discord bots.

This class takes no required parameters in initalization however a number of parameters can be passed in the initalization to modify the behaviour of class as needed. All parameters are optional and keyword-only.

Parameters

loop (asyncio.AbstractEventLoop) – The asyncio event loop to use. if not provided, it will be obtained by calling asyncio.get_event_loop() function.
session (aiohttp.ClientSession) – The aiohttp session to use in HTTP or websocket operations. if not provided, Library creates it’s own session.
intents (GatewayIntents) – The gateway intents to use while connecting to gateway. If not provided, all the unprivelged intents are enabled by default.
message_cache_limit (int) – The amount of messages that would be cached by the client at a time. This can be no larger then 1000. 0 can be passed to disable the message cache. On reaching this amount, The client would discard all the previous messages and would start re-filling the cache. Defaults to 500
allowed_mentions (AllowedMentions) – The global mentions configuration that applies to every bot’s message. This can be overridden per message.
debug_events (bool) – Whether to dispatch debug events i.e on_socket_dispatch(). You should almost never set this to True in production enivornments as this can cause performance issues.
max_reconnect_attempts (int) – The number of times library should attempt to reconnect before closing the websocket connection. This can be set to 0 or None to disable reconnections. Defaults to 5.

add_listener(listener, name, *, once=False)

Adds an event listener to the bot.

This is a non-decorator and lower level interface to on() decorator. Consider using it instead as it is more easy to use.

Example:

async def on_message(message):
    ...

bot.add_listener(on_message, 'message')

Parameters

listener – The async function that represents the event’s callback.
name (str) – The name of event to listen to.
once (bool) – Whether this listener should be called only once.

clear_listeners(event)

Removes all the listeners for the provided event.

Parameters: event (str) – The event name to clear listeners for.

async connect()

Connects to the Discord websocket. This method must be called after logging in, i.e after calling login()

A shorthand start() can also be used that calls login() and connect().

Raises: LoginError – No authorization token is set.

async connect_hook()

A hook that is called whenever the client connects initially to the Discord gateway.

By default, This method does nothing however, it can be overridden to add functionality like creating a database connection etc.

Note that this hook is called BEFORE ready event is fired which means that you shouldn’t rely on client’s cache in this hook as it is more then likely that it is not filled at all or is in process of filling.

event(func)

A decorator that registers a callback for an event.

Example:

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

This is equivalent to:

Example:

class Client(neocord.Client):
    def __init__(self):
        ...

    async def on_ready():
        print('Ready called.')

Warning

You cannot register multiple callbacks using this decorator, Consider using listeners API for that. See documentation for on() decorator.

Note

The callback’s name MUST be prefixed with on_.

async fetch_channel(id)

Fetches a channel.

This method is an API call. Consider using Guild.get_channel() or get_private_channel() for general use cases.

Parameters

id (int) – The ID of channel.

Returns

The fetched channel.

Return type

Union[GuildChannel, PrivateChannel]

Raises

NeocordException – The parent guild of channel could not be resolved.
NotFound – The channel ID is invalid.
HTTPError – The fetching failed.

async fetch_guild(id, with_counts=True)

Fetches a guild from the API.

This is an API call. You can use get_guild() to obtain guild from cache.

Parameters

id (int) – The ID of the guild.
with_counts (bool) – Whether to include approximate member and presence count in returned guild.

Raises

NotFound – Provided guild ID is invalid.
HTTPError – The guild fetch failed somehow.

Returns

The requested guild.

Return type

Guild

async fetch_guild_template(code)

Fetches a guild template from it’s code.

Parameters

code (str) – The code of template.

Returns

The fetched template.

Return type

GuildTemplate

Raises

NotFound – The template with provided code does not exist.
HTTPError – Fetching of template failed.

async fetch_invite(code, *, with_counts=False, with_expiration=False, guild_scheduled_event=None)

Fetch an invite by it’s code.

Parameters

with_counts (bool) – Whether to include approximate_presence_count and approximate_member_count in returned invite.
with_expiration (bool) – Whether to include expires_at in returned invite.
guild_scheduled_event (ScheduledEvent) – The scheduled event attached with invite.

Returns

The fetched invite.

Return type

Invite

Raises

NotFound – The invite with provided code does not exist.
HTTPError – An error occured.

async fetch_stage_instance(channel_id, /)

Fetches a stage instance by the stage channel ID.

This is an API call. Consider using Guild.get_stage_instance() or StageChannel.instance instead.

Parameters

id (int) – The ID of stage channel.

Returns

The fetched stage instance.

Return type

StageInstance

Raises

NotFound – The stage instance was not found.
HTTPError – An error occured while fetching.

async fetch_sticker(id, /)

Fetches a sticker by ID.

Parameters

id (int) – The ID of sticker.

Returns

The requested sticker.

Return type

Sticker

Raises

NotFound – The sticker ID is invalid.
HTTPError – The fetching failed.

async fetch_sticker_packs()

Fetches the list of standard nitro sticker packs.

Returns: The list of sticker packs.
Return type: List[StickerPack]
Raises: HTTPError – The fetching failed.

async fetch_user(id)

Fetches a user from the API.

This is an API call. For general usage and if you have member intents enabled, you can use get_user()

Parameters

id (int) – The ID of the user.

Raises

NotFound – Provided user ID is invalid.
HTTPError – The user fetch failed somehow.

Returns

The requested user.

Return type

User

async fetch_webhook(id, token=None)

Fetches a webhook by it’s ID and token (if provided).

When a token of webhook is provided, No authorization with a bot token is required however when using only the ID, The client must be initialized with a valid token first.

The Webhook.user is not available when fetching webhook using a token.

Parameters

id (int) – The ID of webhook.
token (Optional[str]) – The token of webhook.

Returns

The fetched webhook.

Return type

Webhook

Raises

HTTPError – Fetching of webhook failed.

get_guild(id, /)

Gets a guild from the client’s internal cache. This method returns None is the guild is not found in internal cache.

Parameters: id (int) – The ID of the guild.
Returns: The requested guild.
Return type: Guild

get_listeners(event, *, include_temporary=False)

Returns the registered event listeners for the provided event.

Parameters

event (str) – The event name to get listeners for.
include_temporary (bool) – Whether to include temporary listeners, i.e those that are marked to call only once. Defaults to False. Setting this to True would also return the internal listeners i.e the one’s that were added by wait_for()

Returns

Return type

The list of event listeners callbacks.

get_private_channel(id)

Returns the private channel for provided ID.

This method returns None if no channel for provided ID is found. Consider using User.create_dm instead as channel may not be cached.

Parameters: id (int) – The ID of private channel.
Returns: The private channel if found, Otherwise None.
Return type: Optional[PrivateChannel]

get_private_channel_by_recipient(id)

Returns the private channel by the user’s ID.

Consider using User.create_dm instead as channel may not be cached.

Parameters: id (int) – The ID of user.
Returns
Return type: Optional[PrivateChannel]

get_user(id, /)

Gets a user from the client’s internal cache. This method returns None is the user is not found in internal cache.

Parameters: id (int) – The ID of the user.
Returns: The requested user.
Return type: User

property guild_ids

Returns the snowflake IDs of guilds that the client can see.

Type: List[int]

property guilds

Returns the guilds that the client can see.

Type: List[Guild]

is_ready()

Returns a boolean representation of whether the client is in ready state, as such client has connected to Discord and has successfully filled the internal cache.

Returns: Whether the client is ready or not.
Return type: bool

property latency

Returns the websocket latency of the client.

This is calculated on the basis of interval between heartbeat sent by client and the acknowledgment of it by Discord gateway.

Type: float

async login(token)

Logins to Discord using an authorization bot token.

This method does not establishes a websocket connection but simply logins by fetching the information of the client user associated with the token.

Parameters: token (str) – The token that should be used for login.
Raises: Forbidden – The token is invalid.

on(*args, **kwargs)

A decorator that registers a listener to listen to gateway events.

Example:

@client.on('ready')
# or
# @client.on('on_ready')

async def ready_event():
    print('Ready.')

Unlike event(), You can register as many events you want.

Example:

@client.on('ready')
async def ready1():
    print('Ready called.')

@client.on('ready')
async def ready2():
    print('Ready 2 called.')

Parameters

name (str) – The name of event to listen to.
once (bool) – Whether this listener should be called only once.

run(token)

A blocking method that runs the client. This abstracts away the asyncio event loop handling.

Parameters: token (str) – The token that should be used for login.

property session

Returns the HTTP client session attached to this client.

Warning

You should never close this session while the bot is running as it can result in unexpected issues.

Type: aiohttp.ClientSession

async start(token)

A short-hand coroutine that logins and connects to Discord websocket.

This one coroutine is roughly equivalent to login() + connect()

Parameters: token (str) – The token that should be used for login.

property user

Returns the user associated to this client. This is only available after the client has logged in.

Type: ClientUser

property user_ids

Returns the snowflake IDs of users that the client can see.

Type: List[int]

property users

Returns the users that the client can see. This requires GatewayIntents.users.

Type: List[User]

async wait_for(event, *, check=None, timeout=None)

Waits for an event to dispatch.

This method returns the tuple of arguments that belong to the event.

Example:

message = await bot.wait_for('message', check=lambda m: m.author.id == 1234, timeout=60.0)
if message.content == 'yes':
    await message.channel.send('Affirmative.')
else:
    await message.channel.send('Negative.')

Parameters

event (str) – The event to wait for.
check – The check that will be checked for when returning result. This CANNOT be a coroutine.
timeout (float) – The timeout after which this method would stop.

Raises

asyncio.TimeoutError – The timeout period expired and event was not dispatched.

async wait_until_ready(): A coroutine that waits until the client is in ready state. The client is considered in ready state when it has connected to Discord websocket and has successfully filled the internal cache.

Events Reference

This section outlines the gateway events. These events are sent by Discord over websocket and can be listened to, using the events listener.

Listening to events

A very basic way of listening to an event is simply overriding it:

class MyClient(neocord.Client):
    async def on_ready():
        print('The bot is ready.')

However, there is another easy way of doing above task:

@client.event
async def on_ready():
    print('The bot is ready.')

Both methods are equivalent.

However there are one problem here, that you cannot register multiple events listeners using above method and that’s why library provides a more granular system for listeners handling that is using Client.on() decorator:

@client.on('ready')
# or
# @client.on('on_ready')
async def ready_listener():
    print('The bot is ready.')

You can easily register any number of listeners you want using this method. See relevant documentation for more information.

Below section will list all the gateway events that are sent by Discord and can be listened to.

Library Events

neocord.on_ready()

An event that fires when the client’s internal cache is completely filled.

Important point to note is that this event is not guranteed to call once and similarly, This is also not the very first event to call. Due to reconnections, This event may call multiple times.

Consider using Client.connect_hook() if you want a hook that calls initally and only once.

neocord.on_resume(): Calls when websocket connection with Discord is resumed.

neocord.on_socket_dispatch(event, data)

Note

This is a debug event and will not be called unless opted-in. To enable debug events, Set debug_events to True in Client.

Warning

You should never enable debug_events in production enivornment as it can cause performance issues.

Calls when an event dispatch is sent by Discord gateway.

Parameters

event (str) – The name of event.
data – The raw event data.

User Events

neocord.on_user_update(user)

Calls when properties of a discord user like name, avatar etc. change.

Parameters

before (User) – The user before update.
after (User) – The user after update.

Guild Events

neocord.on_guild_join(guild)

Calls when a guild is joined by the client user.

Requires GatewayIntents.guilds to be enabled.

Parameters: guild (Guild) – The guild that was joined.

neocord.on_guild_update(before, after)

Calls when properties of a guild is changed.

Requires GatewayIntents.guilds to be enabled.

Parameters

before (Guild) – The guild before update.
after (Guild) – The guild after update.

neocord.on_guild_delete(guild)

Calls when a guild is deleted i.e became unavailable due to an outage, the client user was removed etc.

Consider using on_guild_leave() or on_guild_unavailable() for only leave or unavailable events respectively.

Requires GatewayIntents.guilds to be enabled.

Parameters: guild (Guild) – The guild that was deleted.

neocord.on_guild_leave(guild)

Calls when client user leaves a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters: guild (Guild) – The guild that was left.

neocord.on_guild_unavailable(guild)

Calls when a guild becomes unavailable due to an outage etc.

Requires GatewayIntents.guilds to be enabled.

Parameters: guild (Guild) – The guild that became unavailable.

Member Events

neocord.on_member_join(member)

Calls when a member joins a guild etc.

Requires GatewayIntents.members to be enabled.

Parameters: member (GuildMember) – The joined member.

neocord.on_member_leave(member)

Calls when a member leaves a guild etc.

Requires GatewayIntents.members to be enabled.

Parameters: member (GuildMember) – The member who left the guild.

neocord.on_member_update(before, after)

Calls when properties of a guild member updates like nickname change, avatar change etc.

Requires GatewayIntents.members to be enabled.

Parameters

before (GuildMember) – The member before update.
after (GuildMember) – The member after update.

Role Events

neocord.on_role_create(role)

Calls when a role is created in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters: role (Role) – The created role.

neocord.on_role_update(before, after)

Calls when a role is updated in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters

before (Role) – Role before the update.
after (Role) – Role after the update.

neocord.on_role_delete(role)

Calls when a role is deleted in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters: role (Role) – The deleted role.

Channel Events

neocord.on_channel_create(channel)

Calls when a channel is created in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters: channel (GuildChannel) – The created channel.

neocord.on_channel_update(before, after)

Calls when a channel’s properties are updated in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters

before (GuildChannel) – Channel before the update.
after (GuildChannel) – Channel after the update.

neocord.on_channel_delete(channel)

Calls when a channel is deleted in a guild.

Requires GatewayIntents.guilds to be enabled.

Parameters: channel (GuildChannel) – The deleted channel.

on_channel_pins_update(channel):

Calls when pins of a channel update.

Requires GatewayIntents.channels to be enabled.

Parameters: channel (Union[GuildChannel, DirectChannel]) – The channel whose pins were updated.

neocord.on_typing(channel, user, timestamp)

Calls when someone starts typing in a channel.

Requires GatewayIntents.typing to be enabled.

Parameters

channel (GuildChannel) – The channel where typing started.
user ([GuildMember, User]) – The user that started typing.
timestamp (datetime.datetime) – The time when typing started.

Message Events

neocord.on_message(message)

Calls when a message is sent in either a guild channel or a DM channel.

Requires GatewayIntents.messages to be enabled.

Parameters: message (Message) – The sent message.

neocord.on_message_delete(message)

Calls when a message is deleted in either a guild channel or a DM channel.

Requires GatewayIntents.messages to be enabled.

This only dispatches if the deleted message is cached by the bot.

Parameters: message (Message) – The deleted message.

Scheduled Events

neocord.on_scheduled_event_create(event)

Calls when a scheduled event is created in a guild.

Requires GatewayIntents.scheduled_events to be enabled.

Parameters: event (ScheduledEvent) – The created scheduled event.

neocord.on_scheduled_event_update(before, after)

Calls when a scheduled event’s properties are updated.

Requires GatewayIntents.scheduled_events to be enabled.

Parameters

before (ScheduledEvent) – Scheduled event before the update.
after (ScheduledEvent) – Scheduled event after the update.

neocord.on_scheduled_event_delete(event)

Calls when a scheduled event is deleted, ended or cancelled.

Requires GatewayIntents.scheduled_events to be enabled.

Parameters: event (ScheduledEvent) – The deleted scheduled event.

Emojis Events

neocord.on_emojis_update(before, after)

Calls when emojis of a guild update i.e either some emojis were added or removed.

Requires GatewayIntents.emojis_and_stickers to be enabled.

Parameters

before (List[Emoji]) – The list of emojis before update was applied.
after (List[Emoji]) – The list of emojis after update was applied.

Stickers Events

neocord.on_guild_stickers_update(before, after)

Calls when stickers of a guild update i.e either some stickers were added or removed.

Requires GatewayIntents.emojis_and_stickers to be enabled.

Parameters

before (List[GuildSticker]) – The list of stickers before update was applied.
after (List[GuildSticker]) – The list of stickers after update was applied.

Threads Events

neocord.on_thread_create(thread)

Calls when a thread is created.

Requires GatewayIntents.guilds to be enabled.

Parameters: thread (Thread) – The created thread.

neocord.on_thread_update(before, after)

Calls when a thread is updated.

Requires GatewayIntents.guilds to be enabled.

Parameters

before (Thread) – The thread before the update.
before – The thread after the update.

neocord.on_thread_delete(thread)

Calls when a thread is deleted.

Requires GatewayIntents.guilds to be enabled.

Parameters: thread (Thread) – The deleted thread.

neocord.on_thread_join(thread)

Calls when a thread is joined by the connected user.

Requires GatewayIntents.guilds to be enabled.

Parameters: thread (Thread) – The joined thread.

neocord.on_thread_leave(thread)

Calls when a thread is left by the current user.

Requires GatewayIntents.guilds to be enabled.

Parameters: thread (Thread) – The removed thread.

neocord.on_thread_member_add(member)

Calls when a member joins a thread.

Requires GatewayIntents.guilds to be enabled.

Parameters: member (ThreadMember) – The joined member.

neocord.on_thread_member_remove(member)

Calls when a member leaves a thread.

Requires GatewayIntents.guilds to be enabled.

Parameters: member (ThreadMember) – The left member.

Reactions Events

neocord.on_reaction_add(reaction, user)

Calls when a user reacts to a message.

Requires GatewayIntents.reactions to be enabled.

Parameters: reaction (Reaction) – The reaction that was added.

neocord.on_reaction_remove(reaction, user)

Calls when a user unreacts from a message.

Requires GatewayIntents.reactions to be enabled.

Parameters: reaction (Reaction) – The reaction that was removed.

neocord.on_reactions_clear(message, reactions)

Calls when all reactions from a message are explicitly cleared.

Requires GatewayIntents.reactions to be enabled.

Parameters

message (Message) – The message whose reactions were removed. This is the updated message.
reactions (List[Reaction]) – The reactions that were removed.

neocord.on_reactions_clear_emoji(message, reactions, emoji)

Calls when all reactions for a certain emoji are explicitly cleared.

Requires GatewayIntents.reactions to be enabled.

Parameters

message (Message) – The message whose reactions were removed. This is the updated message.
reactions (List[Reaction]) – The reactions that were removed.
emoji (PartialEmoji) – The emoji whose reactions were removed.

Invites Events

neocord.on_invite_create(invite)

Calls when an invite is created.

Requires GatewayIntents.invites and guilds to be enabled.

Note

In this event, Invite.channel and Invite.guild are GuildChannel and Guild respectively instead of partial invite instances.

Parameters: invite (Invite) – The create invite.

neocord.on_invite_delete(channel, code)

Calls when an invite is deleted/revoked.

Requires GatewayIntents.invites and guilds to be enabled.

Parameters

channel (GuildChannel) – The channel whose invite was deleted.
code (str) – The code of invite that was revoked.

Webhooks Events

neocord.on_webhooks_update(channel)

Calls when webhook(s) for a guild text channel is updated, deleted or created.

Requires GatewayIntents.webhooks to be enabled.

Parameters: channel (TextChannel) – The channel whose webhooks were updated.

Enumerations

Enumerations are classes that detail a certain Discord enum. These classes aid in dealing with Discord’s integers based enumerations.

ChannelType

class neocord.ChannelType

An enumeration that details the types of a Discord Channel.

TEXT: 0: Guild Text Channel.

DM: 1: Private Direct Message between two users.

VOICE: 2: Guild Voice Channel.

GROUP: 3: Private Group Channel.

CATEGORY: 4: Organizational category channel in a guild.

NEWS: 5: Guild News aka “Announcement” channel.

STORE: 6: Guild Store channel.

NEWS_THREAD: 10: Thread originated from a news text channel.

PUBLIC_THREAD: 11: Thread originated from a text channel and is publicly accessible.

PRIVATE_THREAD: 12: Thread originated from a text channel and is private.

STAGE: 13: Guild stage channel

ChannelOverwriteType

class neocord.ChannelOverwriteType

An enumeration that details the permission overwrite type of a guild channel.

ROLE: 0: The overwrite details the permission of a role.

MEMBER: 1: The overwrite details the permission of a guild member.

EventStatus

class neocord.EventStatus

An enumeration that details the status of a ScheduledEvent.

SCHEDULED: 1: The event is scheduled and hasn’t started yet.

ACTIVE: 2: The event is currently running.

COMPLETED: 3: The event has finished.

CANCELLED: 4: The event has been cancelled.

EntityType

class neocord.EntityType

An enumeration that details the type of entity of ScheduledEvent.

VOICE_CHANNEL: 1: The event is being hosted in a voice channel.

STAGE_INSTANCE: 2: The event is being hosted in a stage instance.

EXTERNAL: 3: The event is being hosted elsewhere.

EventPrivacyLevel

class neocord.EventPrivacyLevel

An enumeration that details the privacy level of ScheduledEvent.

GUILD_ONLY: 2: The event is only accessible within the guild.

StagePrivacyLevel

class neocord.StagePrivacyLevel

An enumeration that details the privacy level of a StageInstance.

PUBLIC: 1: The event is publicly discoverable.

GUILD_ONLY: 2: The event is only accessible within the parent guild.

StickerType

class neocord.StickerType

An enumeration that details the type of a Sticker.

STANDARD: 1: Standard Nitro Sticker.

GUILD: 2: Guild Custom Sticker.

StickerFormatType

class neocord.StickerFormatType

An enumeration that details the format type of a Sticker.

PNG: 1: PNG format.

APNG: 2: APNG format.

LOTTIE: 3: Lottie format.

VideoQualityMode

class neocord.VideoQualityMode

An enumeration that details the video quality mode of a VoiceChannel.

AUTO: 1: Automatic Quality.

FULL: 2: 720p Quality.

NotificationLevel

class neocord.NotificationLevel

An enumeration that details the notification level of a Guild.

ALL_MESSAGES: 1: Members recieve notifications for all messages send in guild.

ONLY_MENTIONS: 2: Members recieve notifications for messages that contain their mention.

ContentFilter

class neocord.ContentFilter

An enumeration that details the explicit content filter of a Guild.

DISABLED: 0: No messages will be scanned.

MEMBERS_WITHOUT_ROLES: 1: Messages of members with no role assigned will be scanned.

ALL_MEMBERS: 2: Messages of all members will be scanned.

MFALevel

class neocord.MFALevel

An enumeration that details the 2-factor-authentication requirement for moderation actions in a Guild.

DISABLED: 0: 2FA is not required for moderation actions.

ELEVATED: 1: 2FA is required on moderator account to perform actions.

VerificationLevel

class neocord.VerificationLevel

An enumeration that details verification level that members of Guild need for access to guild.

NONE: 0: No verification is needed.

LOW: 1: Members must have verified email on the account.

MEDIUM: 2: Members must be registered on Discord for longer then 5 minutes.

HIGH: 3: Members must be in the guild for longer then 10 minutes.

VERY_HIGH: 4: Members must have verified phone numbers on account.

NSFWLevel

class neocord.NSFWLevel

An enumeration that details NSFW level of a Guild.

DEFAULT: 0: Guild has no NSFW level.

EXPLICIT: 1: Guild is marked as explicit.

SAFE: 2: Guild is marked as safe for work (SFW).

AGE_RESTRICTED: 3: Guild is marked as age restricted.

PremiumTier

class neocord.PremiumTier

An enumeration that details premium or nitro boosts levels of a Guild.

NONE: 0: Guild has no server boosts level.

TIER_1: 1: Guild has enabled server boosts level 1 perks.

TIER_2: 2: Guild has enabled server boosts level 2 perks.

TIER_3: 3: Guild has enabled server boosts level 3 perks..

MessageType

class neocord.MessageType

An enumeration that the type of a Message.

DEFAULT: 0: Message is a “simple” message.

RECIPIENT_ADD: 1: Message is a message indicating that recipient is added to group channel.

RECIPIENT_REMOVE: 2: Message is a message indicating that recipient is removed from group channel.

CALL: 3: Message indicates a call’s state.

CHANNEL_NAME_CHANGE: 4: Message indicates the update of channel’s name.

CHANNEL_ICON_CHANGE: 5: Message indicates the update of channel’s icon.

CHANNEL_PINNED_MESSAGE: 6: Message indicates that a message was pinned in a channel.

GUILD_MEMBER_JOIN: 7: Message indicates that a member joined the guild.

USER_PREMIUM_GUILD_SUBSCRIPTION: 8: Message indicates that guild’s premium count was updated i.e guild was boosted.

USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1: 9: Message indicates that guild’s premium tier or boost level reached level 1.

USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_2: 10: Message indicates that guild’s premium tier or boost level reached level 2.

USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_3: 11: Message indicates that guild’s premium tier or boost level reached level 3.

CHANNEL_FOLLOW_ADD: 12: Message indicates that channel started following another channel for crossposted messages.

GUILD_DISCOVERY_DISQUALIFIED: 14: Message indicates that guild is disqualified for server discovery feature.

GUILD_DISCOVERY_REQUALIFIED: 15: Message indicates that guild has requalified for server discovery feature.

GUILD_DISCOVERY_GRACE_PERIOD_INITIAL_WARNING: 16: Message indicates guild’s server discovery initial warning.

GUILD_DISCOVERY_GRACE_PERIOD_FINAL_WARNING: 17: Message indicates guild’s server discovery final warning.

THREAD_CREATE: 18: Message indicates that a thread is created in the channel.

REPLY: 19: Message is a reply to another message.

CHAT_INPUT_COMMAND: 20: Message is a response to a slash command.

THREAD_STARTER_MESSAGE: 21: Message is a thread’s starter message.

GUILD_INVITE_REMINDER: 22: Message is an “invite reminder” message for the guild.

CONTEXT_MENU_COMMAND: 23: Message is a response to a context menu command.

InviteTargetType

class neocord.InviteTargetType

An enumeration that details the target type of Invite.

STREAM: 1: The invite target is a user’s video stream.

EMBEDDED: 2: The invite target is an embedded activity.

WebhookType

class neocord.WebhookType

An enumeration that the type of a Webhook.

INCOMING: 1: Token based incoming webhook.

CHANNEL_FOLLOWER: 2: Internal Discord webhook used to crosspost messages in news channels.

APPLICATION: 3: Webhook used for interactions.

Discord Data Models

These classes wrap the Discord complex data models into easy to use object oriented interface.

These classes are not meant to be initalized by users. You should also never modify the instance of these classes provided by library as it may cause many issues like cache issues etc.

Due to the nature of these objects that they are often cached, All objects have defined __slots__ to avoid memory issues so it is impossible to have dynamic attributes on these classes.

Attachment

class neocord.Attachment

Represents an attachment on a message.

id

The ID of attachment.

Type: int

filename

The name of file that this attachment has.

Type: str

description

The description of attachment.

Type: Optional[str]

content_type

The content type of this attachment.

Type: Optional[str]

size

The size of attachment in bytes.

Type: int

url

The URL of attachment.

Type: str

proxy_url

The proxied URL of attachment.

Type: Optional[str]

height

The height of attachment. Only valid for images.

Type: Optional[int]

width

The width of attachment. Only valid for images.

Type: Optional[int]

ephemeral

Whether this attachment is sent ephemerally as an interaction response.

Type: bool

CDNAsset

class neocord.CDNAsset

Represents an asset from Discord’s CDN like icons, avatars etc.

url

The URL of the asset.

Type: str

key

The identification unique key of the asset.

Type: str

animated

Whether this asset is animated.

Type: bool

property animated: Returns a boolean representing, Whether this asset is animated or not.

property url: Returns the access URL of this asset.

with_size(size)

Returns the URL of asset with provided size.

Parameters: size (int) – The size of asset, size can be power of 2 between 16 to 4096.
Raises: ValueError – The provided size is not valid.
Returns: The URL with desired size attached.
Return type: str

Emoji

class neocord.Emoji

Represents a custom emoji in a guild.

id

The ID of this role.

Type: int

name

The name of this emoji.

Type: str

roles

The list of roles that can manage this emoji.

Type: List[Role]

user

The user that created this emoji.

Type: User

require_colons

Whether this emoji requires to be wrapped in “:” (colons) to be used.

Type: bool

managed

Whether this emoji is managed by an integration like Twitch etc.

Type: bool

available

Whether this emoji is available for use. Could be False if the emoji became unavailable due to server losing boosts.

Type: bool

animated

Whether the emoji is animated or not.

Type: bool

guild

The guild that this emoji belongs to.

Type: Guild

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async delete(*, reason=None)

Deletes the custom emoji from the guild.

Parameters

reason (str) – The reason to delete that shows up on audit log.

Raises

Forbidden: – You don’t have permissions to delete this emoji.
NotFound: – Emoji not found.
HTTPError – Deleting of emoji failed.

async edit(*, name=None, roles=..., reason=None)

Edits the custom guild emoji.

You must have manage_emojis to perform this action in the guild.

Parameters

name (str) – The new name of emoji.
roles (List[Role]) – The list of roles that can use this emoji. None to disable the explicit restriction.
reason (str) – Reason for editing this emoji that shows up on guild’s audit log.

Raises

Forbidden: – You don’t have permissions to edit an emoji.
HTTPError – Editing of emoji failed.

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string representation that is used to use an emoji in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

property url

Returns the URL of the emoji.

Type: str

Guild

class neocord.Guild

Represents a discord guild entity often referred as a “Server” in the UI.

id

The unique snowflake ID of the guild.

Type: int

name

The name of guild.

Type: str

afk_timeout

The number of seconds after which idle members would be moved to the AFK channel. 0 means there is no timeout.

Type: int

widget_enabled

Whether the guild has enabled embed widget.

Type: bool

verification_level

The verification level for the users of this guild.

Type: VerificiationLevel

default_message_notifications

The message notification level of this guild.

Type: NotificationLevel

explicit_content_filter

The explicit content filter of this guild. i.e if the sent media is scanned or not.

Type: ContentFilter

features

The list of the features this guild has, Guild features represent the features this guild has access to like role icons, welcome screen etc.

Type: str

mfa_level

The MFA level of this guild.

Type: MFALevel

application_id

The ID of application that created this guild if it is bot created, This is usually None

Type: Optional[int]

large

Whether this guild is marked as a large guild. This is not available if the guild if fetched manually instead of getting from client’s internal cache.

Type: Optional[bool]

unavailable

Whether this guild is unavailable due to an outage. This is not available if the guild if fetched manually instead of getting from client’s internal cache.

Type: Optional[bool]

member_count

The member count of this guild. This is not available if the guild if fetched manually instead of getting from client’s internal cache.

Type: Optional[int]

vanity_url_code

The vanity URL code of this guild if any, Otherwise None.

Type: Optional[str]

description

The description of the guild. Could be None

Type: Optional[str]

premium_tier

The premium tier of this guild “aka” the server boost level.

Type: PremiumTier

premium_subscription_count

The premium subscription count of this guild “aka” the number of boosts this guild has.

Type: int

preferred_locale

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

Type: str

approximate_member_count

The approximate member count of the guild, This is only available when fetching the guild using fetch_guild() with with_counts parameter to True

Type: int

approximate_presence_count

The approximate presences count of the guild, This is only available when fetching the guild using fetch_guild() with with_counts parameter to True

Type: int

nsfw_level

The NSFW level of the guild.

Type: NSFWLevel

system_channel_flags

The system channel’s attributes of the guild.

Type: SystemChannelFlags

async ban_member(member, *, delete_message_days=None, reason=None)

Bans a member from the guild.

Requires Permissions.ban_members to perform this action.

Parameters

member (Union[User, GuildMember]) – The member or user to ban.
delete_message_days (int) – The number of days to purge banned user message history for. Can be between 0 to 7.
reason (str) – The reason for performing this action.

Raises

Forbidden – You don’t have permissions to ban.
HTTPError – Banning of member failed.

property banner

Returns the CDN asset for the invite banner of guild.

This may be None if the guild has no banner set.

Type: Optional[CDNAsset]

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property channel_ids

Returns the list of IDs of channels in this guild.

Type: List[int]

property channels

Returns the list of channels in guild.

These are sorted in the same way as in the Discord client i.e voice channels below other channels.

Type: List[GuildChannel]

async create_channel(*, type, name, topic=None, bitrate=None, user_limit=None, rate_limit_per_user=None, position=None, permission_overwrites=None, category=None, nsfw=False, reason=None)

Creates a channel in the guild.

This action requires manage_channels in the guild.

Only type and name keyword arguments are required.

Parameters

type (ChannelType) – The type of channel.
name (str) – The name of channel.
topic (str) – The topic of channel.
bitrate (int) – The bitrate (in bits) of the voice channel.
user_limit (int) – The limit of users that can communicate at a time in the voice channel.
rate_limit_per_user (int) – The cooldown delay of channel in seconds.
position (int) – The position of channel.

permission_overwrites (List[ChannelPermissionOverwrite]) –

A dict of entity to PermissionOverwrite to apply on channel. The key of dict should be the entity whose overwrite is being defined. Can either be GuildMember or Role and with value being the PermissionOverwrite object.

Example:

muted_role = guild.get_role(muted_role_id)
admin_role = guild.get_role(admin_role_id)

overwrites = {}
overwrites[muted_role] = neocord.PermissionOverwrite(
    send_messages=False,
    add_reactions=False,
    connect=False,
)
overwrites[admin_role] = neocord.PermissionOverwrite(
    manage_messages=True,
    manage_channel=True,
)

await guild.create_channel(type=ChannelType.TEXT, name='general', permission_overwrites=overwrites)

category (CategoryChannel) – The category this channel should be placed in.
nsfw (bool) – Whether the channel is NSFW.
reason (str) – Reason from performing this action that shows up on audit log.

Returns

The created channel.

Return type

GuildChannel

Raises

Forbidden – The bot doesn’t has required permissions.
HTTPError – Failed to create the channel.

async create_emoji(*, emoji, name, roles=None, reason=None)

Creates a custom guild emoji.

You must have manage_emojis to perform this action in the guild.

Parameters

emoji (bytes) – The bytes like object of data representing the emoji. The size must be less then or equal to 256kb. Supported types are GIF, PNG, JPEG, and WebP.
name (str) – The name of emoji.
roles (List[Role]) – The list of roles that can use this emoji.
reason (str) – Reason for creating this emoji that shows up on guild’s audit log.

Raises

Forbidden: – You don’t have permissions to create an emoji.
HTTPError – Creation of emoji failed.

async create_role(*, name=None, permissions=None, color=None, colour=None, hoist=None, icon=None, unicode_emoji=None, mentionable=None, reason=None)

Creates a role in the guild.

All parameters to this method are optional and lets Discord to set all the defaults.

Parameters

name (str) – The name of role. By default, “new role” – similar to Discord client.
permissions (Permissions) – The permissions for this role. By default, The @everyone role permissions are set.
color (Color) – The color of role. Defaults to no color.
colour (Color) – An alias of color parameter.
hoist (bool) – Whether to show this role separate then other roles. Defaults to False.
icon (bytes) – The bytes-like object representing icon of role. This parameter cannot be mixed with unicode_emoji
unicode_emoji (str) – The unicode emoji used as icon for role. This parameter cannot be mixed with icon
mentionable (bool) – Whether this role can be mentioned.
reason (str) – The reason for performing this action. Shows up on audit log.

Returns

The created role. This role isn’t the same as the one that is added to cache later.

Return type

Role

Raises

Forbidden – You cannot perform this action.
HTTPError – Creation of role failed.

async create_scheduled_event(*, name, starts_at, ends_at=None, entity_type=None, description=None, channel=None, location=None, privacy_level=2)

Creates a new scheduled event in the guild.

Requires you to have Permissions.manage_events in the targeted guild.

Parameters

name (str) – The name of event.
starts_at (datetime.datetime) – The datetime representation of the time when the event will be scheduled to start.
ends_at (datetime.datetime) – The datetime representation of the time when the event will be scheduled to end. Ending time is required for external events but optional for non-external events.
description (str) – The description of event.
channel (Union[VoiceChannel, StageChannel]) – The channel where the event is being hosted. Cannot be mixed with location.
location (str) – The external location name where event is being hosted. Cannot be mixed with channel.
privacy_level (EventPrivacyLevel) – The privacy level of event. Defaults to GUILD_ONLY
entity_type (EntityType) – The type of entity where event is being hosted. This is usually automatically determined by library depending on parameters that you pass. However, you can set it manually.

Raises

Forbidden: – You don’t have permissions to create an event.
HTTPError – Creation of event failed.

Returns

The created event.

Return type

ScheduledEvent

async create_template(*, name, description=None)

Create a guild template in this template.

This action requires Permissions.manage_guild in the guild.

Parameters

name (str) – The title of template.
description (str) – The optional description of template.

Returns

The created template.

Return type

GuildTemplate

Raises

Forbidden – You cannot perform this action.
HTTPError – Creation of template failed.

property discovery_splash

Returns the CDN asset for the discovery splash of guild.

This may be None if the guild has no discovery splash set. This is only applicable for guilds with DISCOVERY feature enabled.

Type: Optional[CDNAsset]

async edit_member(member, *, nick=..., roles=..., mute=..., deaf=..., voice_channel=..., reason=None)

Edits a member from this guild.

This is a shorthand to GuildMember.edit() except this doesn’t requires the member to be fetched explicitly.

Except member, All parameters are optional and keyword only.

Parameters

member (Member) – The member that will be edited.
nick (str) – The new nickname of member.
roles (List[Role]) – List of roles that should be assigned to member.
mute (bool) – Whether to mute the member in voice channel. Requires member to be in voice channel.
deaf (bool) – Whether to deafen the member in voice channel. Requires member to be in voice channel.
voice_channel (VoiceChannel) – The voice channel to move the member to. Requires member to be in voice channel.
reason (str) – The reason for this action that shows up on audit log.

property emoji_ids

Returns the list of IDs of custom emojis in this guild.

Type: List[int]

property emojis

Returns the list of custom emojis that belong to this guild.

Type: List[Emoji]

async fetch_ban(user_id, /)

Fetches a ban for provided user ID.

Requires Permissions.manage_bans to fetch ban.

Parameters

user_id (int) – The ID of user to fetch ban for.

Raises

NotFound – User isn’t banned or provided user ID is invalid.
Forbidden – You don’t have permissions to fetch bans.
HTTPError – Fetching of bans failed.

Returns

The fetched ban.

Return type

GuildBan

async fetch_bans()

Fetches all bans of a guild.

Requires Permissions.manage_bans to fetch bans.

Raises

Forbidden – You don’t have permissions to fetch bans.
HTTPError – Fetching of bans failed.

Returns

The list of bans guild has.

Return type

List[GuildBan]

async fetch_channels()

Fetches all channels from this guild excluding threads.

Returns: The list of channels.
Return type: List[GuildChannel]
Raises: HTTPError – Failed to fetch channels.

async fetch_emoji(id, /)

Fetches a custom emoji from the guild.

This is a direct API call and shouldn’t be used in general cases. Consider using get_emoji() instead.

Parameters

id (int) – The snowflake ID of emoji.

Returns

The requested emoji.

Return type

Emoji

Raises

NotFound: – Emoji not found.
HTTPError – Fetching of emoji failed.

async fetch_emojis()

Fetches all custom emojis from the guild.

This is a direct API call and shouldn’t be used in general cases. Consider using emojis instead.

Returns: The list of emojis in the guild.
Return type: List[Emoji]
Raises: HTTPError – Fetching of emojis failed.

async fetch_invites()

Fetches all invites of this guild.

Requires Permissions.manage_guild permissions in the guild.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invite failed.

async fetch_member(id, /)

Fetches a member from the guild.

This is a direct API call and shouldn’t be used in general cases. If you have member intents, Consider using get_member()

Parameters

id (int) – The snowflake ID of member.

Returns

The requested member.

Return type

GuildMember

Raises

NotFound: – Member not found.
HTTPError – Fetching of member failed.

async fetch_roles()

Fetches all the roles that are in this guild.

This method is an API call, Consider using roles for general usage.

Returns: List of fetched roles.
Return type: List[Role]
Raises: HTTPError – The roles fetching failed.

async fetch_scheduled_event(id, /)

Fetches a scheduled event from the guild.

This is a direct API call and shouldn’t be used in general cases. Consider using get_scheduled_event() instead.

Parameters

id (int) – The snowflake ID of scheduled event.

Returns

The requested event.

Return type

ScheduledEvent

Raises

NotFound: – Event not found.
HTTPError – Fetching of event failed.

async fetch_scheduled_events()

Fetches all scheduled events from the guild.

This is a direct API call and shouldn’t be used in general cases. Consider using scheduled_events instead.

Returns: The list of events in the guild.
Return type: List[ScheduledEvent]
Raises: HTTPError – Fetching of events failed.

async fetch_sticker(id)

Fetches a sticker by it’s ID.

If the bot does not have Permissions.manage_emojis_and_stickers permission, then Sticker.user will be None.

Parameters

id (int) – The ID of sticker.

Raises

NotFound – The sticker of provided ID is not found.
HTTPError – Fetching of sticker failed.

Returns

The fetched sticker.

Return type

GuildSticker

async fetch_stickers()

Fetches all stickers of a guild.

If the bot does not have Permissions.manage_emojis_and_stickers permission, then Sticker.user will be None in returned stickers.

Raises: HTTPError – Fetching of stickers failed.
Returns: The list of stickers.
Return type: List[GuildSticker]

async fetch_templates()

Fetches all templates from this guild.

This action requires Permissions.manage_guild in the guild.

If you don’t have permission, Consider fetching template with the code using Client.fetch_guild_template()

Returns

The list of templates.

Return type

List[GuildTemplate]

Raises

Forbidden – You don’t have enough permissions.
HTTPError – Fetching of templates failed.

async fetch_webhooks()

Fetches all webhooks of this guild.

Requires Permissions.manage_webhooks permissions in the guild.

Returns

The list of webhooks.

Return type

List[Webhook]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of webhooks failed.

get_channel(id, /)

Gets a channel from the guild. This method returns None is the channel with ID is not found.

Parameters: id (int) – The ID of the channel.
Returns: The requested channel.
Return type: GuildChannel

get_channel_or_thread(id)

Returns a thread or channel from cache by it’s ID.

If neither thread nor channel of provided ID is not found, None is returned instead.

Parameters: id (int) – The ID of thread or channel.
Returns: The relevant thread or channel, if found.
Return type: Optional[Union[Thread, GuildChannel]]

get_emoji(id, /)

Gets a custom emoji from the guild. This method returns None is the emoji with provided ID is not found.

Parameters: id (int) – The ID of the emoji.
Returns: The requested emoji.
Return type: Emoji

get_member(id, /)

Gets a member from the guild. This method returns None is the member with ID is not found.

This requires GatewayIntents.guild_members to be enabled.

Parameters: id (int) – The ID of the member.
Returns: The requested member.
Return type: GuildMember

get_role(id, /)

Gets a role from the guild. This method returns None is the role with ID is not found.

Parameters: id (int) – The ID of the role.
Returns: The requested role.
Return type: Role

get_scheduled_event(id, /)

Gets a scheduled event from the guild. This method returns None is the scheduled event with provided ID is not found.

Parameters: id (int) – The ID of the event.
Returns: The requested event, if found.
Return type: Optional[ScheduledEvent]

get_stage_instance(id, /)

Gets a live stage instance from the guild. This method returns None is no instance with provided ID is not found.

Parameters: id (int) – The ID of the stage instance.
Returns: The requested instance, if found.
Return type: Optional[StageInstance]

get_sticker(id, /)

Gets a sticker from the guild. This method returns None is no sticker with provided ID is not found.

Parameters: id (int) – The ID of the sticker.
Returns: The requested sticker, if found.
Return type: Optional[GuildSticker]

get_thread(id, /)

Returns a thread from cache by it’s ID.

If thread of provided ID is not found, None is returned instead.

Parameters: id (int) – The ID of thread.
Returns: The relevant thread, if found.
Return type: Optional[Thread]

property icon

Returns the CDN asset for the icon of guild.

This may be None if the guild has no icon set.

Type: Optional[CDNAsset]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property joined_at

Returns datetime.datetime representation of when the bot has joined the guild.

This could be unavailable in some (rare) cases.

async kick_member(member, *, reason=None)

Kicks a member from this guild.

This is a shorthand to GuildMember.kick() except this doesn’t requires the member to be fetched explicitly.

Except member, All parameters are optional and keyword only.

Parameters

member (GuildMember) – The member that will be kicked.
reason (str) – The reason for this action that shows up on audit log.

async leave()

Deletes this guild.

The client user must own the guild to delete it.

Raises

Forbidden – The client user is not guild owner.
HTTPError – Failed to delete this guild.

property member_ids

Returns the list of IDs of members in this guild.

Type: List[int]

property members

Returns the list of GuildMember that belong to this guild.

This requires GatewayIntents.guild_members to be enabled.

property role_ids

Returns the list of IDs of roles in this guild.

Type: List[int]

property roles: Returns the list of Role that belong to this guild.

property scheduled_event_ids

Returns the list of IDs of scheduled events in this guild.

Type: List[int]

property scheduled_events

Returns the list of scheduled events that belong to this guild.

Type: List[ScheduledEvent]

property splash

Returns the CDN asset for the splash of guild.

This may be None if the guild has no splash set.

Type: Optional[CDNAsset]

property stage_instance_ids

Returns the list of IDs of stage instances in this guild.

Type: List[int]

property stage_instances

Returns the list of stage instances that are active in this guild.

Type: List[StageInstance]

property sticker_ids

Returns the list of IDs of stickers in this guild.

Type: List[int]

property stickers

Returns the list of stickers in this guild.

Type: List[GuildSticker]

property thread_ids

Returns the list of IDs of threads that are active in the guild.

Type: List[int]

property threads

Returns the list of threads that are active in the guild.

Type: List[Thread]

async unban_member(user, *, reason=None)

Unbans a user from the guild.

Requires Permissions.ban_members to perform this action.

Parameters

user (User) – The user to unban.
reason (str) – The reason for performing this action.

Raises

Forbidden – You don’t have permissions to unban.
HTTPError – Unbanning of member failed.

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

property vanity_invite: Returns the string for guild’s vanity invite URL if available.

GuildMember

class neocord.GuildMember

Represents a guild member entity. A member is just a user inside a guild.

joined_at

The time when member joined the guild.

Type: datetime.datetime

deaf

Whether the member is deaf in voice channel.

Type: bool

mute

Whether the member is mute in voice channel.

Type: bool

pending

Whether the member has passed membership screening or not.

Type: bool

communication_disabled_until

The time till when member cannot interact with the guild often referred as “timeout” in the UI. If this is None or the time is in past then it denotes that member is not timed out.

Tip

Use has_communication_disabled() for efficient checking of whether member has communication disabled.

Type: Optional[datetime.datetime]

async add_roles(*roles, reason=None)

Adds roles to a member. This method is a wrapper around edit().

The roles to add are passed as positional arguments. This method would only add the roles and won’t bulk overwrite them. If member already has the provided role, That role would not be removed and would silently be ignored.

Parameters

*roles – The roles to add.
reason (str) – The reason for performing this action. Shows up on audit log.

property avatar

Returns the avatar of member.

With following considerations:

Returns the guild specific avatar of member if available.
If member has no guild specific avatar set, The global avatar is returned.
If member has no global avatar set either, Default avatar is returned.

Returns: The avatar asset.
Return type: CDNAsset

async ban(*, delete_message_days=None, reason=None)

Bans this member from parent guild.

Equivalent to Guild.ban_member().

property bot: Equivalent to User.bot

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async create_dm(*args, **kwargs): Equivalent to User.create_dm()

property discriminator: Equivalent to User.discriminator

async edit(*, nick=..., roles=..., mute=..., deaf=..., voice_channel=..., communication_disabled_until=..., reason=None)

Edits the member.

Parameters

nick (str) – The new nickname of member.
roles (List[Role]) – List of roles that should be assigned to member.
mute (bool) – Whether to mute the member in voice channel. Requires member to be in voice channel.
deaf (bool) – Whether to deafen the member in voice channel. Requires member to be in voice channel.
voice_channel (VoiceChannel) – The voice channel to move the member to. Requires member to be in voice channel.
communication_disabled_until (datetime.datetime) – The time until the member cannot interact with the guild (aka timeout). None can be used to denote the removal of timeout. This can be not be longer then 28 days.
reason (str) – The reason for this action that shows up on audit log.

get_role(id, /)

Gets a role from the member. This method returns None is the role with ID is not found.

Parameters: id (int) – The ID of the role.
Returns: The requested role.
Return type: Role

property guild_avatar

Returns the guild specific avatar of member if any.

If no guild specific avatar is set, Then returns either one

Note

Consider using display_avatar instead that automatically falls back to available avatar i.e guild, global or default.

has_communication_disabled(): bool: Returns a boolean representing whether the member is timed out.

property id: Equivalent to User.id

is_boosting(): Indicates whether the member is (nitro) boosting the guild.

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

async kick(*, reason=None)

Kicks the member.

Equivalent to Guild.kick_member().

Parameters: reason (str) – The reason for this action that shows up on audit log.

property mention: Equivalent to User.mention

property name

Returns the name of member in the guild.

With following considerations:

Returns the guild specific name of member; if available.
If no guild specific nickname is set, Then global name of user is returned instead.

Returns: The name of member.
Return type: str

property nickname

Returns the guild nickname of the user. If user has no guild specific nickname, Then None is returned instead.

Note

Consider using name instead that automatically falls back to global name if no guild specific nickname is set.

Returns: The nickname of member; If available.
Return type: Optional[str]

property premium_since

Returns datetime.datetime of time when member started boosting the server.

This is None if member is not boosting.

property public_flags: Equivalent to User.public_flags

async remove_all_roles(*, reason=None)

Remove all roles from a member.

Parameters: reason (str) – The reason for performing this action. Shows up on audit log.
Returns: The list of removed roles.
Return type: List[Role]

async remove_roles(*roles, reason=None)

Remove roles from a member. This method is a wrapper around edit().

The roles to remove are passed as positional arguments. This method would only remove the roles and won’t bulk overwrite them. If member already doesn’t has the provided role, It would silently be ignored.

Parameters

*roles – The roles to remove.
reason (str) – The reason for performing this action. Shows up on audit log.

property role_ids

Returns the list of IDs of roles on this member.

Type: List[int]

property roles: Returns the list of roles that are attached on this member.

async send(*args, **kwargs): Equivalent to User.send()

async unban(*, reason=None)

Unbans this member from parent guild.

Equivalent to Guild.unban_member().

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

property user

Returns the user that this member belongs to.

Returns: The user that this member belongs to.
Return type: User

Message

class neocord.Message

Represents a discord message entity.

id

The snowflake ID of this message.

Type: int

channel_id

The ID of channel in which the message was sent.

Type: int

guild_id

The ID of guild in which message was sent.

Type: int

content

The content of message, this may be None if message has no content.

Type: str

created_at

The datetime representation of the time when message was sent.

Type: datetime.datetime

tts

Whether message is a “text-to-speech” message.

Type: bool

mention_everyone

Whether this message involves the @everyone or @here mention.

Type: bool

pinned

Whether the message is pinned in the parent channel.

Type: bool

type

The type of message.

Type: MessageType

webhook_id

If a webhook has sent this message, then this is the ID of that webhook.

Type: int

author

The user that sent this message, this could be None. If the message was sent in a DM, Then it is User, otherwise, it’s a GuildMember

Type: Union[GuildMember, User]

interaction

The interaction information if this message is an interaction response.

Type: MessageInteraction

embeds

The list of embeds on this message.

Type: List[Embed]

application_id

If message is an interaction, The application ID of the interaction.

Type: int

role_mentions

The list of roles that are mentioned in message.

Type: List[Role]

raw_role_mentions

The list of role IDs that are mentioned in message.

Type: List[int]

mentions

The mentions that are done in the message.

Type: [User, GuildMember]

flags

The flags attached to this message.

Type: MessageFlags

attachments

The list of attachments attached to this message.

Type: List[Attachment]

reactions

The list of reactions on this message.

Type: Reaction

async add_reaction(emoji)

Adds a reaction to this message.

This requires add_reactions in the message’s channel if message has no reactions previously.

Parameters

emoji (Union[str, PartialEmoji, Emoji]) – The emoji to react with.

Raises

Forbidden – You don’t have permissions to perform this action.
HTTPError – Adding the reaction failed.

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property channel

Returns the channel in which message was sent.

Type: GuildChannel

async clear_reactions(emoji=None)

Clears all reactions or reactions for specified emoji from this message.

This requires manage_messages in the message’s channel.

Parameters

emoji (Union[str, PartialEmoji, Emoji]) – The emoji to remove reaction for. If not provided, Clears all reactions on the message.

Raises

Forbidden – You don’t have permissions to perform this action.
HTTPError – Removing the reactions failed.

async crosspost()

Crossposts the message.

send_messages permission is required to perform this action.

If the message is not created by client user then the manage_messages permission is also needed.

Raises

Forbidden – Missing permissions.
HTTPError – Failed to crosspost the message.

async delete()

Deletes the message.

Raises

Forbidden – You are not allowed to delete this message.
HTTPError – The message sending failed somehow.

async edit(content=..., *, embed=..., embeds=..., allowed_mentions=..., attachments=..., suppress=...)

Edits the message.

Parameters

content (str) – The content of message.
embed (Embed) – The embed to show in message. Cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to show in message. Cannot be mixed with embed.
allowed_mentions (AllowedMentions) – The new allowed mentions of message.
suppress (bool) – Whether to suppress the embeds in the message.

Raises

Forbidden – You cannot edit this message.
HTTPError – Editing of message failed.

property guild

Returns the guild in which message was sent. Could be None if message was sent in a DM channel.

Type: Guild

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

is_interaction_response(): Returns a boolean showing whether this message is an interaction i.e application command or message component’s response.

async pin(*, reason=None)

Pins the message in the channel.

This requires manage_messages permission in targetted channel.

A channel can only have at max, 50 pins.

Parameters

reason (str) – The reason for performing this action. Shows up on Audit log.

Raises

Forbidden – You don’t have enough permissions to perform this action.
HTTPError – Pin creation failed.

async remove_reaction(emoji, user=None)

Removes a reaction from this message.

This requires manage_messages if removing another user’s reaction.

Parameters

emoji (Union[str, PartialEmoji, Emoji]) – The emoji to remove reaction for.
user (Union[User, GuildMember]) – The user to remove reaction of. If not provided, Defaults to ownself.

Raises

Forbidden – You don’t have permissions to perform this action.
HTTPError – Removing the reaction failed.

async reply(*args, **kwargs)

Replies to the message. This is a shorthand for TextChannel.send() and so does take same parameters.

Raises

Forbidden – You are not allowed to send this message.
HTTPError – The message sending failed somehow.

Returns

The created message.

Return type

Message

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

async unpin(*, reason=None)

Unpins the message from the channel.

This requires manage_messages permission in targetted channel.

Parameters

reason (str) – The reason for performing this action. Shows up on Audit log.

Raises

Forbidden – You don’t have enough permissions to perform this action.
HTTPError – Pin deletion failed.

Reaction

class neocord.Reaction

Represents a reaction on Message.

message

The message this reaction belongs to.

Type: Message

count

The number of reactions.

Type: int

me

Whether the connected user has reacted.

Type: bool

emoji

The emoji of this reaction.

Tip

You can resolve this to a proper Emoji if you have the parent Guild by using PartialEmoji.resolve() method.

Type: PartialEmoji

Role

class neocord.Role

Represents a guild’s role entity.

A role can be used to modify a guild member’s permissions, appearence and other characters or organize members.

id

The unique snowflake ID of the role.

Type: int

name

The name of the role.

Type: str

hoist

Whether the role is shown seperate from online members and other roles.

Type: bool

position

An integer representing the position of the role in role heirarchy.

Type: int

managed

Whether the role is managed by an integration.

Type: bool

mentionable

Whether the role is mentioned by members.

Type: bool

unicode_emoji

The string representation of the unicode emoji as role icon if any. This would be None if there is no unicode emoji on role icon.

Type: Optional[str]

color

The color of the role.

Type: Colour

tags

The tags present on the role.

Type: RoleTags

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async delete(*, reason=None)

Deletes the role.

Parameters

reason (str) – The reason for deleting the role; Shows up on audit log.

Raises

Forbidden: – You don’t have permissions to delete the role.
HTTPError – The deletion of role failed somehow.

async edit(*, name=None, hoist=None, position=None, mentionable=None, unicode_emoji=..., color=..., colour=..., icon=..., reason=None)

Edits the role.

You need Permissions.manage_roles in role’s guild to edit the role.

Parameters

name (str) – The name of the role.
hoist (bool) – Whether the role is shown seperate from online members and other roles.
position (int) – An integer representing the position of the role in role heirarchy.
managed (bool) – Whether the role is managed by an integration.
mentionable (bool) – Whether the role is mentioned by members.
unicode_emoji (Optional[str]) – The string representation of the unicode emoji as role icon if any. This could be None to remove the icon.
color (Colour) – The color of the role.
icon (bytes) – The bytes-like object representing the new icon, None can be passed to remove the icon.
reason (str) – The reason for editing the role, Shows up on the audit log.

Raises

Forbidden: – You don’t have permissions to edit the role.
HTTPError – The editing of role failed somehow.

property icon

Returns the asset that represents the icon of this role. Could be None if role has no icon set.

Type: Optional[CDNAsset]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property members

Returns the list of members that have this role assigned.

Type: List[GuildMember]

property mention

Returns a string used to mention the role in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

ClientUser

class neocord.ClientUser

Represents a Discord User for the connected client. The most common way of accessing this is by neocord.Client.user attribute.

name

The username of user as shown in Discord.

Type: str

id

The user’s unique snowflake ID.

Type: int

discriminator

The 4 digits discriminator of user.

Type: str

bot

A boolean representing if the user is a bot or not, In case of this class this is usually True

Type: bool

system

A boolean representing if the user is a system user i.e Official Discord System This is usually False

Type: bool

verified

A boolean representing if the user has a verified email on the account.

Type: bool

locale

The language tag used to identify the language the user is using.

Type: Optional[str]

mfa_enabled

A boolean representing if the user has MFA enabled on the account.

Type: bool

property accent_color

Returns the color representation of the user’s banner color.

Type: Color

property accent_colour

Returns the color representation of the user’s banner color.

Type: Color

property avatar

Returns the CDN asset for user avatar.

If user has no avatar set, None is returned. Consider using display_avatar that automatically falls back to default avatar if no avatar is set.

Type: Optional[CDNAsset]

property banner

Returns the CDN asset for user banner.

Type: CDNAsset

property default_avatar

Returns the default avatar of user.

This is not the actual avatar of user but is calculated on the basis of user discriminator.

Type: CDNAsset

property display_avatar

Returns the avatar displayed by Discord client.

Type: CDNAsset

async edit(*, name=..., avatar=...)

Edits the client user.

All parameters in this method are optional. This method returns None and updates the instance in-place with new data.

Parameters

name (str) – The new name of the user.
avatar (Optional[bytes]) – The bytes like object that represents the new avatar’s image data. None can be passed to remove the avatar.

property mention

Returns a string used to mention the user in Discord.

Type: str

property public_flags

`UserFlags: Returns the public flags of a user.

Type: class

User

class neocord.User

Represents a discord user entity.

name

The username of user as shown in Discord.

Type: str

id

The user’s unique snowflake ID.

Type: int

discriminator

The 4 digits discriminator of user.

Type: str

bot

A boolean representing if the user is a bot or not, In case of this class this is usually True

Type: bool

system

A boolean representing if the user is a system user i.e Official Discord System This is usually False

Type: bool

property accent_color

Returns the color representation of the user’s banner color.

Type: Color

property accent_colour

Returns the color representation of the user’s banner color.

Type: Color

property avatar

Returns the CDN asset for user avatar.

If user has no avatar set, None is returned. Consider using display_avatar that automatically falls back to default avatar if no avatar is set.

Type: Optional[CDNAsset]

property banner

Returns the CDN asset for user banner.

Type: CDNAsset

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async create_dm(use_cache=True)

Creates a direct message with this user.

You should not use this to create a DM channel to message in as it is automatically done transparently when using User.send().

The channel returned by this method is cached and on further uses of this method, The cached channel is returned.

Parameters: use_cache (bool) – Whether to return the cached channel if found. Defaults to True and highly recommended to be True.
Returns: The direct message channel.
Return type: DirectChannel
Raises: HTTPError – Channel could not be created.

property default_avatar

Returns the default avatar of user.

This is not the actual avatar of user but is calculated on the basis of user discriminator.

Type: CDNAsset

async delete_message(message)

Deletes a message from the destination. A shorthand and a lower level of Message.delete().

Parameters

message (Message) – The message to delete.

Raises

Forbidden: – You are not allowed to delete this message.
HTTPError: – The message deleting failed somehow.

property display_avatar

Returns the avatar displayed by Discord client.

Type: CDNAsset

property dm

Returns the direct message channel with this user.

This can be None if the direct message channel is not cached. Consider using User.send() if you just want to send a message to automatically retrieve channel.

Type: Optional[DirectChannel]

async fetch_message(id, /)

Fetches a message from this channel.

Parameters

id (int) – The ID of the message.

Returns

The requested message.

Return type

Message

Raises

NotFound: – Message was not found. i.e ID is incorrect.
Forbidden: – You are not allowed to fetch this message.
HTTPError: – The fetching failed somehow.

async fetch_pins()

Fetches the list of messages that are pinned in the channel.

Returns: The pinned messages.
Return type: List[Message]
Raises: HTTPError – Fetching of pins failed.

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string used to mention the user in Discord.

Type: str

property public_flags

`UserFlags: Returns the public flags of a user.

Type: class

async send(content=None, *, embed=None, embeds=None, delete_after=None, allowed_mentions=None, file=None, files=None, sticker=None, stickers=None, reference=None, mention_replied_user=None)

Sends a message to the channel.

A message must contain at least one of the following:

content
sticker or stickers
embed or embeds
file or files

Parameters

content (str) – The content of message.
embed (Embed) – The embed shown in message. This parameter cannot be mixed with embeds
embeds (List[Embed]) – The list of embeds shown in message. This parameter cannot be mixed with embed
file (File) – The file sent in message. This parameter cannot be mixed with files
files (List[File]) – The list of files sent in message. This parameter cannot be mixed with file
sticker (Sticker) – The sticker to send. Cannot be mixed with stickers.
stickers (List[Sticker]) – The list of stickers to send. Cannot be mixed with sticker.
reference (Union[MessageReference, Message]) – The message reference to reply this message for.
mention_replied_user (bool) – Whether to mention the author when replying. When set, Overrides the AllowedMentions.mention_replied_user
delete_after (float) – The interval after which this message would be deleted automatically.

Returns

The message that was sent.

Return type

Message

Raises

Forbidden: – You are not allowed to send message at this destination.
HTTPError: – The message sending failed somehow.

async trigger_typing_indicator()

Triggers the typing indicator in provided channel.

The typing indicators ends after few seconds or when a message is sent the channel.

Raises

Forbidden – Cannot start typing indicator because user is missing permissions.
HTTPError – Typing triggering failed.

typing()

Returns a context manager interface that triggers typing in the channel.

Example:

async with channel.typing():
    # do something long
    await asyncio.sleep(5)
    await channel.send("Done!")

This can be used in both simple and async context managers.

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

GuildChannel

class neocord.GuildChannel

Base class that implements basic operations for all channels types in a guild.

Currently, the classes that inherit this are:

TextChannel
VoiceChannel
StageChannel
CategoryChannel

id

The snowflake ID of the channel.

Type: int

guild

The guild that this channel belongs to.

Type: Guild

category_id

The ID of parent category that this channel exists in.

Type: int

type

The ChannelType of channel

Type: int

position

The position of channel on the channels list.

Type: int

name

The name of channel.

Type: str

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of this channel. None if channel has no parent category.

Type: Optional[CategoryChannel]

async create_invite(*, max_age=..., max_uses=..., temporary=..., unique=..., target_user_id=None, target_application_id=None, reason=None)

Creates a invite for this channel.

This requires create_instant_invite permission in the channel.

All parameters are optional. The target_user_id and target_application_id parameters cannot be mixed.

Parameters

max_age (int) – The maximum age of invites in seconds. None or 0 sets the invite to never expire. The age can be between 0 (never) to 604800 (week). Defaults to 86400 (1 day).
max_uses (int) – The maximum times this invite can be used. Defaults to 0 (unlimited). Can be between 0 to 100.
temporary (bool) – Whether this invite only grants temporary membership.
unique (bool) – Whether this invite is a one time use invite.
target_user_id (int) – The ID of user this invite will show stream of when creating invite for a voice channel.
target_application_id (int) – The ID of embedded application this invite targets.
reason (str) – The reason for creating invite.

Returns

The created invite.

Return type

Invite

Raises

TypeError – Invalid arguments passed.
Forbidden – Required permissions are missing.
HTTPError – Creation of invite failed.

async delete(*, reason=None)

Deletes the channel.

Parameters

reason (str) – The reason for this action.

Raises

Forbidden – You are not allowed to delete this channel.
HTTPError – The deletion failed somehow.

async delete_permissions_overwrite(entity, *, reason=None)

Deletes a permission overwrite for provided entity from the channel.

This action requires manage_roles permission.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Deletion of permissions overwrite failed.

async edit_permissions(entity, overwrite, *, reason=None)

Adds or edits a permission overwrite for a member or role.

This action requires manage_roles permission.

This method is useful to lock or unlock channels to certain role.

For example, to deny everyone from viewing and sending messages in a channel:

special_role_overwrite = neocord.PermissionOverwrite(view_channel=True, send_messages=True)
default_overwrite = neocord.PermissionOverwrite(view_channel=False, send_messages=False)

await channel.edit_permissions(special_role, special_role_overwrite)
await channel.edit_permissions(guild.default_role, default_overwrite)

If another overwrite exists for provided entity already, It will be overwritten.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
overwrite (PermissionOverwrite) – The new permission overwrite.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Editing of permissions failed.

async fetch_invites()

Fetches all invites of this channel.

Requires Permissions.manage_channel permissions in the channel.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invites failed.

get_permission_overwrite_for(entity)

Returns a permission overwrite for requested entity.

The entity can either be a Role or a GuildMember. If no overwrite is found for provided entity, None is returned.

Parameters: entity (Union[Role, GuildMember]) – The entity to get overwrite for. Either a role or member.
Returns: The permission overwrite for relevant entity.
Return type: Optional[PermissionOverwrite]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string used to mention the channel in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

TextChannel

class neocord.TextChannel

Represents a text channel in a guild.

Like all guild channels, This also inherits GuildChannel so all operations valid there are valid here too.

last_message_id

The ID of last message.

Type: int

last_pin_timestamp

The timestamp when last message pin was created.

Type: Optional[datetime.datetime]

rate_limit_per_user

The ratelimit aka the slowmode in text channel. 0 means no ratelimit.

Type: int

topic

The topic of channel.

Type: Optional[str]

nsfw

Whether this channel is marked as not safe for work (NSFW)

Type: bool

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of this channel. None if channel has no parent category.

Type: Optional[CategoryChannel]

async create_invite(*, max_age=..., max_uses=..., temporary=..., unique=..., target_user_id=None, target_application_id=None, reason=None)

Creates a invite for this channel.

This requires create_instant_invite permission in the channel.

All parameters are optional. The target_user_id and target_application_id parameters cannot be mixed.

Parameters

max_age (int) – The maximum age of invites in seconds. None or 0 sets the invite to never expire. The age can be between 0 (never) to 604800 (week). Defaults to 86400 (1 day).
max_uses (int) – The maximum times this invite can be used. Defaults to 0 (unlimited). Can be between 0 to 100.
temporary (bool) – Whether this invite only grants temporary membership.
unique (bool) – Whether this invite is a one time use invite.
target_user_id (int) – The ID of user this invite will show stream of when creating invite for a voice channel.
target_application_id (int) – The ID of embedded application this invite targets.
reason (str) – The reason for creating invite.

Returns

The created invite.

Return type

Invite

Raises

TypeError – Invalid arguments passed.
Forbidden – Required permissions are missing.
HTTPError – Creation of invite failed.

async create_webhook(*, name, avatar=None, reason=None)

Creates a webhook in the channel.

Requires Permissions.manage_webhooks permissions in the channel.

Parameters

name (str) – The name of webhook.
avatar (bytes) – The bytes like object representing avatar of webhook.
reason (str) – The reason for performing this action. Shows up on audit log.

Returns

The created webhook.

Return type

Webhook

Raises

Forbidden – Required permissions are missing.
HTTPError – Creation of webhook failed.

async delete(*, reason=None)

Deletes the channel.

Parameters

reason (str) – The reason for this action.

Raises

Forbidden – You are not allowed to delete this channel.
HTTPError – The deletion failed somehow.

async delete_message(message)

Deletes a message from the destination. A shorthand and a lower level of Message.delete().

Parameters

message (Message) – The message to delete.

Raises

Forbidden: – You are not allowed to delete this message.
HTTPError: – The message deleting failed somehow.

async delete_permissions_overwrite(entity, *, reason=None)

Deletes a permission overwrite for provided entity from the channel.

This action requires manage_roles permission.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Deletion of permissions overwrite failed.

async edit(*, name=None, nsfw=None, position=None, topic=..., rate_limit_per_user=..., default_auto_archive_duration=..., category=..., reason=None)

Edits the text channel.

Parameters

name (str) – The new name of channel.
topic (str) – The new topic of channel.
nsfw (bool) – Whether the channel should be NSFW or not.
position (int) – The new position of channel.
rate_limit_per_user (int) – The ratelimit per user aka channel message cooldown for a user.
default_auto_archive_duration (int) – The default thread auto-archiving durations of this channel.
category (CategoryChannel) – The ID of category that this channel should be put in.
reason (str) – The reason for this edit that appears on Audit log.

Raises

Forbidden – You are not allowed to edit this channel.
HTTPError – The editing of text channel failed somehow.

async edit_permissions(entity, overwrite, *, reason=None)

Adds or edits a permission overwrite for a member or role.

This action requires manage_roles permission.

This method is useful to lock or unlock channels to certain role.

For example, to deny everyone from viewing and sending messages in a channel:

special_role_overwrite = neocord.PermissionOverwrite(view_channel=True, send_messages=True)
default_overwrite = neocord.PermissionOverwrite(view_channel=False, send_messages=False)

await channel.edit_permissions(special_role, special_role_overwrite)
await channel.edit_permissions(guild.default_role, default_overwrite)

If another overwrite exists for provided entity already, It will be overwritten.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
overwrite (PermissionOverwrite) – The new permission overwrite.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Editing of permissions failed.

async fetch_invites()

Fetches all invites of this channel.

Requires Permissions.manage_channel permissions in the channel.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invites failed.

async fetch_message(id, /)

Fetches a message from this channel.

Parameters

id (int) – The ID of the message.

Returns

The requested message.

Return type

Message

Raises

NotFound: – Message was not found. i.e ID is incorrect.
Forbidden: – You are not allowed to fetch this message.
HTTPError: – The fetching failed somehow.

async fetch_pins()

Fetches the list of messages that are pinned in the channel.

Returns: The pinned messages.
Return type: List[Message]
Raises: HTTPError – Fetching of pins failed.

async fetch_webhooks()

Fetches all webhooks of this channel.

Requires Permissions.manage_webhooks permissions in the channel.

Returns

The list of webhooks.

Return type

List[Webhook]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of webhooks failed.

async follow(target_channel, *, reason=None)

Follows this channel with the provided channel.

You must have Permissions.manage_webhooks in the target channel.

Parameters

target_channel (TextChannel) – The target channel i.e the channel that will recieve announcements from this channel.
reason (str) – The reason for performing the action.

Returns

The created channel follower webhook.

Return type

Webhook

Raises

TypeError – This channel is not a news channel.
Forbidden – Missing permissions.
HTTPError – Cannot perform this action.

get_permission_overwrite_for(entity)

Returns a permission overwrite for requested entity.

The entity can either be a Role or a GuildMember. If no overwrite is found for provided entity, None is returned.

Parameters: entity (Union[Role, GuildMember]) – The entity to get overwrite for. Either a role or member.
Returns: The permission overwrite for relevant entity.
Return type: Optional[PermissionOverwrite]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

is_news(): Returns a boolean that indicates if the channel is a news aka announcement channel.

property mention

Returns a string used to mention the channel in Discord.

Type: str

async send(content=None, *, embed=None, embeds=None, delete_after=None, allowed_mentions=None, file=None, files=None, sticker=None, stickers=None, reference=None, mention_replied_user=None)

Sends a message to the channel.

A message must contain at least one of the following:

content
sticker or stickers
embed or embeds
file or files

Parameters

content (str) – The content of message.
embed (Embed) – The embed shown in message. This parameter cannot be mixed with embeds
embeds (List[Embed]) – The list of embeds shown in message. This parameter cannot be mixed with embed
file (File) – The file sent in message. This parameter cannot be mixed with files
files (List[File]) – The list of files sent in message. This parameter cannot be mixed with file
sticker (Sticker) – The sticker to send. Cannot be mixed with stickers.
stickers (List[Sticker]) – The list of stickers to send. Cannot be mixed with sticker.
reference (Union[MessageReference, Message]) – The message reference to reply this message for.
mention_replied_user (bool) – Whether to mention the author when replying. When set, Overrides the AllowedMentions.mention_replied_user
delete_after (float) – The interval after which this message would be deleted automatically.

Returns

The message that was sent.

Return type

Message

Raises

Forbidden: – You are not allowed to send message at this destination.
HTTPError: – The message sending failed somehow.

async start_thread(*, name, message=None, type=None, invitable=None, auto_archive_duration=None, rate_limit_per_user=None, reason=None)

Starts a thread in the text channel.

Permissions.create_public_threads is needed to create public threads whereas to create private threads, Permissions.create_private_threads.

To start a thread from a message, Use message parameter. type parameter cannot be mixed with message.

If channel is a normal text channel, A public thread is created that everyone with access to that channel can access. Similarly; If the channel is a news aka announcement channel, The created thread would have type of NEWS_THREAD.

Parameters

name (str) – The name of thread.
message (Message) – The message from which this thread should be created. If not provided, The channel is created without the message.
type (ChannelType) – The type of thread. Cannot be set if message is set.
invitable (bool) – Whether members can invite other members to this thread. Only applicable when type parameter is set to ChannelType.PRIVATE_THREAD
type – The type of thread.
auto_archive_duration (int) – The inactivity duration in seconds after which thread will be automatically be archived.
rate_limit_per_user (int) – The thread’s slowmode delay in seconds. Can be between 0 to 21600
reason (str) – The reason for creating thread. Shows up on audit log.

Raises

TypeError – Invalid arguments were passed.
Forbidden – You are not allowed create this thread.
HTTPError – Creation of thread failed.

Returns

The created thread. This is not the same thread as the one added to cache.

Return type

Thread

async trigger_typing_indicator()

Triggers the typing indicator in provided channel.

The typing indicators ends after few seconds or when a message is sent the channel.

Raises

Forbidden – Cannot start typing indicator because user is missing permissions.
HTTPError – Typing triggering failed.

typing()

Returns a context manager interface that triggers typing in the channel.

Example:

async with channel.typing():
    # do something long
    await asyncio.sleep(5)
    await channel.send("Done!")

This can be used in both simple and async context managers.

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

VoiceChannel

class neocord.VoiceChannel

Represents a guild voice channel.

bitrate

The bitrate of this voice channel.

Type: int

user_limit

The number of users that can connect to this channel at a time, 0 means that there is no explicit limit set.

Type: int

rtc_region

The voice region of this channel.

Type: str

video_quality_mode

The video streaming quality mode of this channel.

Type: VideoQualityMode

nsfw

Whether this channel is NSFW or not.

Type: bool

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of this channel. None if channel has no parent category.

Type: Optional[CategoryChannel]

async create_invite(*, max_age=..., max_uses=..., temporary=..., unique=..., target_user_id=None, target_application_id=None, reason=None)

Creates a invite for this channel.

This requires create_instant_invite permission in the channel.

All parameters are optional. The target_user_id and target_application_id parameters cannot be mixed.

Parameters

max_age (int) – The maximum age of invites in seconds. None or 0 sets the invite to never expire. The age can be between 0 (never) to 604800 (week). Defaults to 86400 (1 day).
max_uses (int) – The maximum times this invite can be used. Defaults to 0 (unlimited). Can be between 0 to 100.
temporary (bool) – Whether this invite only grants temporary membership.
unique (bool) – Whether this invite is a one time use invite.
target_user_id (int) – The ID of user this invite will show stream of when creating invite for a voice channel.
target_application_id (int) – The ID of embedded application this invite targets.
reason (str) – The reason for creating invite.

Returns

The created invite.

Return type

Invite

Raises

TypeError – Invalid arguments passed.
Forbidden – Required permissions are missing.
HTTPError – Creation of invite failed.

async delete(*, reason=None)

Deletes the channel.

Parameters

reason (str) – The reason for this action.

Raises

Forbidden – You are not allowed to delete this channel.
HTTPError – The deletion failed somehow.

async delete_permissions_overwrite(entity, *, reason=None)

Deletes a permission overwrite for provided entity from the channel.

This action requires manage_roles permission.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Deletion of permissions overwrite failed.

async edit(*, name=None, bitrate=None, user_limit=..., rtc_region=None, video_quality_mode=None, nsfw=None, position=None, category=..., reason=None)

Edits the voice channel.

Parameters

name (str) – The new name of channel.
bitrate (int) – The new bitrate of channel.
user_limit (int) – New user limit of the channel or None to remove it.
position (int) – The new position of channel.
rtc_region (str) – The new voice region of channel.
video_quality_mode (VideoQualityMode) – The new video streaming quality mode of the channel.
category (CategoryChannel) – The ID of category that this channel should be put in.
nsfw (bool) – Whether this channel is NSFW or not.
reason (str) – The reason for this edit that appears on Audit log.

Raises

Forbidden – You are not allowed to edit this channel.
HTTPError – The editing of voice channel failed somehow.

async edit_permissions(entity, overwrite, *, reason=None)

Adds or edits a permission overwrite for a member or role.

This action requires manage_roles permission.

This method is useful to lock or unlock channels to certain role.

For example, to deny everyone from viewing and sending messages in a channel:

special_role_overwrite = neocord.PermissionOverwrite(view_channel=True, send_messages=True)
default_overwrite = neocord.PermissionOverwrite(view_channel=False, send_messages=False)

await channel.edit_permissions(special_role, special_role_overwrite)
await channel.edit_permissions(guild.default_role, default_overwrite)

If another overwrite exists for provided entity already, It will be overwritten.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
overwrite (PermissionOverwrite) – The new permission overwrite.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Editing of permissions failed.

async fetch_invites()

Fetches all invites of this channel.

Requires Permissions.manage_channel permissions in the channel.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invites failed.

get_permission_overwrite_for(entity)

Returns a permission overwrite for requested entity.

The entity can either be a Role or a GuildMember. If no overwrite is found for provided entity, None is returned.

Parameters: entity (Union[Role, GuildMember]) – The entity to get overwrite for. Either a role or member.
Returns: The permission overwrite for relevant entity.
Return type: Optional[PermissionOverwrite]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string used to mention the channel in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

StageChannel

class neocord.StageChannel

Represents a guild stage channel.

bitrate

The bitrate of this stage channel.

Type: int

user_limit

The number of users that can connect to this channel at a time, 0 means that there is no explicit limit set.

Type: int

rtc_region

The voice region of this channel.

Type: str

topic

The topic of this stage channel.

Type: str

nsfw

Whether this stage channel is NSFW or not.

Type: bool

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of this channel. None if channel has no parent category.

Type: Optional[CategoryChannel]

async create_instance(*, topic, privacy_level=2, reason=None)

Creates a new “live” stage instance in this stage channel.

The user has to be stage moderator to perform this action i.e has following permissions:

Permissions.manage_channels
Permissions.mute_members
Permissions.move_members

Parameters

topic (str) – The topic of stage instance.
privacy_level (StagePrivacyLevel) – The privacy level of stage instance. Defaults to GUILD_ONLY
reason (str) – The reason for creating the stage instance. Shows up on audit log.

Returns

The created instance.

Return type

StageInstance

Raises

Forbidden – You are not allowed to create this instance.
HTTPError – An error occured while performing this action.

async create_invite(*, max_age=..., max_uses=..., temporary=..., unique=..., target_user_id=None, target_application_id=None, reason=None)

Creates a invite for this channel.

This requires create_instant_invite permission in the channel.

All parameters are optional. The target_user_id and target_application_id parameters cannot be mixed.

Parameters

max_age (int) – The maximum age of invites in seconds. None or 0 sets the invite to never expire. The age can be between 0 (never) to 604800 (week). Defaults to 86400 (1 day).
max_uses (int) – The maximum times this invite can be used. Defaults to 0 (unlimited). Can be between 0 to 100.
temporary (bool) – Whether this invite only grants temporary membership.
unique (bool) – Whether this invite is a one time use invite.
target_user_id (int) – The ID of user this invite will show stream of when creating invite for a voice channel.
target_application_id (int) – The ID of embedded application this invite targets.
reason (str) – The reason for creating invite.

Returns

The created invite.

Return type

Invite

Raises

TypeError – Invalid arguments passed.
Forbidden – Required permissions are missing.
HTTPError – Creation of invite failed.

async delete(*, reason=None)

Deletes the channel.

Parameters

reason (str) – The reason for this action.

Raises

Forbidden – You are not allowed to delete this channel.
HTTPError – The deletion failed somehow.

async delete_permissions_overwrite(entity, *, reason=None)

Deletes a permission overwrite for provided entity from the channel.

This action requires manage_roles permission.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Deletion of permissions overwrite failed.

async edit(*, name=None, bitrate=None, user_limit=..., rtc_region=None, nsfw=None, position=None, category=..., topic=..., reason=None)

Edits the stage channel.

Parameters

name (str) – The new name of channel.
bitrate (int) – The new bitrate of channel.
user_limit (int) – New user limit of the channel or None to remove it.
position (int) – The new position of channel.
rtc_region (str) – The new voice region of channel.
topic (str) – The topic of the channel.
category (CategoryChannel) – The ID of category that this channel should be put in.
nsfw (bool) – Whether this channel is NSFW or not.
reason (str) – The reason for this edit that appears on Audit log.

Raises

Forbidden – You are not allowed to edit this channel.
HTTPError – The editing of voice channel failed somehow.

async edit_permissions(entity, overwrite, *, reason=None)

Adds or edits a permission overwrite for a member or role.

This action requires manage_roles permission.

This method is useful to lock or unlock channels to certain role.

For example, to deny everyone from viewing and sending messages in a channel:

special_role_overwrite = neocord.PermissionOverwrite(view_channel=True, send_messages=True)
default_overwrite = neocord.PermissionOverwrite(view_channel=False, send_messages=False)

await channel.edit_permissions(special_role, special_role_overwrite)
await channel.edit_permissions(guild.default_role, default_overwrite)

If another overwrite exists for provided entity already, It will be overwritten.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
overwrite (PermissionOverwrite) – The new permission overwrite.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Editing of permissions failed.

async fetch_instance()

Fetches a stage instance that is associated with this stage channel.

This is an API call. Consider using instance instead.

Parameters

id (int) – The ID of stage instance.

Returns

The fetched stage instance.

Return type

StageInstance

Raises

NotFound – The stage instance was not found i.e there is no instance associated to channel.
HTTPError – An error occured while fetching.

async fetch_invites()

Fetches all invites of this channel.

Requires Permissions.manage_channel permissions in the channel.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invites failed.

get_permission_overwrite_for(entity)

Returns a permission overwrite for requested entity.

The entity can either be a Role or a GuildMember. If no overwrite is found for provided entity, None is returned.

Parameters: entity (Union[Role, GuildMember]) – The entity to get overwrite for. Either a role or member.
Returns: The permission overwrite for relevant entity.
Return type: Optional[PermissionOverwrite]

property instance

Returns the live stage instance that is currently running in stage channel. Returns None if no instance is running.

Type: Optional[StageInstance]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string used to mention the channel in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

CategoryChannel

class neocord.CategoryChannel

Represents a category channel.

A category channel can be used to organize other channels in a guild as such other channels can inherit the permissions and options for a category.

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of this channel. None if channel has no parent category.

Type: Optional[CategoryChannel]

property channels

Returns the channels within this organizational category.

Returns
Return type: List[GuildChannel]

async create_invite(*, max_age=..., max_uses=..., temporary=..., unique=..., target_user_id=None, target_application_id=None, reason=None)

Creates a invite for this channel.

This requires create_instant_invite permission in the channel.

All parameters are optional. The target_user_id and target_application_id parameters cannot be mixed.

Parameters

max_age (int) – The maximum age of invites in seconds. None or 0 sets the invite to never expire. The age can be between 0 (never) to 604800 (week). Defaults to 86400 (1 day).
max_uses (int) – The maximum times this invite can be used. Defaults to 0 (unlimited). Can be between 0 to 100.
temporary (bool) – Whether this invite only grants temporary membership.
unique (bool) – Whether this invite is a one time use invite.
target_user_id (int) – The ID of user this invite will show stream of when creating invite for a voice channel.
target_application_id (int) – The ID of embedded application this invite targets.
reason (str) – The reason for creating invite.

Returns

The created invite.

Return type

Invite

Raises

TypeError – Invalid arguments passed.
Forbidden – Required permissions are missing.
HTTPError – Creation of invite failed.

async delete(*, reason=None)

Deletes the channel.

Parameters

reason (str) – The reason for this action.

Raises

Forbidden – You are not allowed to delete this channel.
HTTPError – The deletion failed somehow.

async delete_permissions_overwrite(entity, *, reason=None)

Deletes a permission overwrite for provided entity from the channel.

This action requires manage_roles permission.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Deletion of permissions overwrite failed.

async edit(*, name=None, position=None, nsfw=None, reason=None)

Edits the category channel.

Parameters

name (str) – The new name of channel.
nsfw (bool) – Whether the channel should be NSFW or not.
position (int) – The new position of channel.
reason (str) – The reason for this edit that appears on Audit log.

Raises

Forbidden – You are not allowed to edit this channel.
HTTPError – The editing of category channel failed somehow.

async edit_permissions(entity, overwrite, *, reason=None)

Adds or edits a permission overwrite for a member or role.

This action requires manage_roles permission.

This method is useful to lock or unlock channels to certain role.

For example, to deny everyone from viewing and sending messages in a channel:

special_role_overwrite = neocord.PermissionOverwrite(view_channel=True, send_messages=True)
default_overwrite = neocord.PermissionOverwrite(view_channel=False, send_messages=False)

await channel.edit_permissions(special_role, special_role_overwrite)
await channel.edit_permissions(guild.default_role, default_overwrite)

If another overwrite exists for provided entity already, It will be overwritten.

Parameters

entity (Union[User, GuildMember, Role]) – The entity whose overwrite is being defined.
overwrite (PermissionOverwrite) – The new permission overwrite.
reason (str) – The reason for performing this action. Shows up on guild’s audit log.

Raises

Forbidden – Cannot perfom this action because required permissions are missing.
HTTPError – Editing of permissions failed.

async fetch_invites()

Fetches all invites of this channel.

Requires Permissions.manage_channel permissions in the channel.

Returns

The list of invite.

Return type

List[Invite]

Raises

Forbidden – Required permissions are missing.
HTTPError – Fetching of invites failed.

get_permission_overwrite_for(entity)

Returns a permission overwrite for requested entity.

The entity can either be a Role or a GuildMember. If no overwrite is found for provided entity, None is returned.

Parameters: entity (Union[Role, GuildMember]) – The entity to get overwrite for. Either a role or member.
Returns: The permission overwrite for relevant entity.
Return type: Optional[PermissionOverwrite]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

property mention

Returns a string used to mention the channel in Discord.

Type: str

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

Thread

class neocord.Thread

Represents a thread inside a TextChannel.

guild

The guild this thread belongs to.

Type: Guild

id

The ID of thread.

Type: int

parent_id

The ID of parent text channel that this thread was created in.

Type: int

last_message_id

The last message’s ID in this thread.

Type: int

owner_id

The ID of user that created this thread.

Type: int

member_count

Number of members that are in this thread.

Type: int

message_count

The number of messages in thread. Stops counting at 50.

Type: int

rate_limit_per_user

The per-user slowmode in thread.

Type: int

type

The type of thread.

Type: ChannelType

name

The name of thread.

Type: str

locked

Whether the thread is locked or not. If a thread is locked, it means only a moderator i.e member with manage_threads permissions can unarchive the thread.

Type: bool

archived

Whether the thread is archived or not.

Type: bool

invitable

Whether the other members can invite members to this thread. This only applies to private threads.

Type: bool

auto_archive_duration

The time when thread will be auto archived.

Type: int

archive_updated_at

The time when thread’s archive status was last changed.

Type: datetime.datetime

async add_member(member)

Adds a member to the thread.

You must have the permissions to send messages in the thread and thread must not be archived.

Parameters

member (Union[User, GuildMember]) – The member to add.

Raises

Forbidden – You don’t have enough permission to perform this action.
HTTPError – Adding of thread member failed.

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property category

Returns the category of thread’s parent.

Type: Optional[CategoryChannel]

property category_id

Returns the category’s ID of thread’s parent.

Type: Optional[int]

async delete(*, reason=None)

Deletes the thread.

This action requires manage_threads permissions.

Parameters

reason (str) – The reason that shows up on audit log.

Raises

Forbidden – You don’t have enough permissions.
HTTPError – Thread deletion failed.

async delete_message(message)

Deletes a message from the destination. A shorthand and a lower level of Message.delete().

Parameters

message (Message) – The message to delete.

Raises

Forbidden: – You are not allowed to delete this message.
HTTPError: – The message deleting failed somehow.

async edit(*, name=..., archived=..., auto_archive_duration=..., locked=..., invitable=..., rate_limit_per_user=..., reason=None)

Edits the thread.

This action requires manage_threads permissions.

Parameters

name (str) – The name of thread.
archived (bool) – Whether the thread should be archived or not. Setting this to True archives the thread and vice versa.
auto_archive_duration (int) – The auto archive duration of thread. Can be set to 60, 1440, 4320, 10080. For 4320 and above, Server boost level 2 is required for parent guild.
locked (bool) – Whether only moderators can update thread’s archive status.
invitable (bool) – Whether the thread is invitable. Only applicable to private threads.
rate_limit_per_user (int) – The thread’s slowmode delay in seconds. Can be between 0-21600
reason (str) – The reason that shows up on audit log.

Raises

Forbidden – You don’t have enough permissions.
HTTPError – Thread editing failed.

async fetch_member(id)

Fetches a thread member by ID.

Consider using get_member() for general usage. This method is an API call while former uses the internal cache.

Parameters

id (int) – The ID of member.

Returns

The requested thread member.

Return type

ThreadMember

Raises

NotFound – The ID is invalid or user is not member of thread.
HTTPError – Fetching of thread member failed.

async fetch_members()

Fetches all members of this thread.

Consider using members for general usage. This method is an API call while former uses the internal cache.

Returns: The list of members of this thread.
Return type: List[ThreadMember]
Raises: HTTPError – Fetching of thread members failed.

async fetch_message(id, /)

Fetches a message from this channel.

Parameters

id (int) – The ID of the message.

Returns

The requested message.

Return type

Message

Raises

NotFound: – Message was not found. i.e ID is incorrect.
Forbidden: – You are not allowed to fetch this message.
HTTPError: – The fetching failed somehow.

async fetch_pins()

Fetches the list of messages that are pinned in the channel.

Returns: The pinned messages.
Return type: List[Message]
Raises: HTTPError – Fetching of pins failed.

get_member(id, /)

Gets a member from this thread. This method returns None is the member with ID is not found in the thread.

Parameters: id (int) – The ID of the thread member.
Returns: The requested thread member. If found.
Return type: Optional[ThreadMember]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

is_news(): bool: Indicates whether this thread belongs to an “announcement” channel.

is_nsfw(): bool: Indicates whether this thread is a NSFW thread.

is_private(): bool: Indicates whether this thread is a private thread.

async join()

Joins the thread.

Raises

Forbidden – You cannot join this thread.
HTTPError – Joining the thread failed.

async leave()

Leaves the thread.

Raises: HTTPError – Leaving the thread failed.

property me

Own thread member. This could be unavailable.

Type: Optional[ThreadMember]

property member_ids

The list of IDs of members of this thread.

Type: List[int]

property members

The list of members of thread.

Type: List[ThreadMember]

property parent

Returns the parent channel that this thread belongs to.

Type: Optional[TextChannel]

async remove_member(member)

Removes a member from the thread.

You must have the manage_threads permissions in the thread and thread must not be archived.

Parameters

member (Union[User, GuildMember]) – The member to remove.

Raises

Forbidden – You don’t have enough permission to perform this action.
HTTPError – Removal of thread member failed.

async send(content=None, *, embed=None, embeds=None, delete_after=None, allowed_mentions=None, file=None, files=None, sticker=None, stickers=None, reference=None, mention_replied_user=None)

Sends a message to the channel.

A message must contain at least one of the following:

content
sticker or stickers
embed or embeds
file or files

Parameters

content (str) – The content of message.
embed (Embed) – The embed shown in message. This parameter cannot be mixed with embeds
embeds (List[Embed]) – The list of embeds shown in message. This parameter cannot be mixed with embed
file (File) – The file sent in message. This parameter cannot be mixed with files
files (List[File]) – The list of files sent in message. This parameter cannot be mixed with file
sticker (Sticker) – The sticker to send. Cannot be mixed with stickers.
stickers (List[Sticker]) – The list of stickers to send. Cannot be mixed with sticker.
reference (Union[MessageReference, Message]) – The message reference to reply this message for.
mention_replied_user (bool) – Whether to mention the author when replying. When set, Overrides the AllowedMentions.mention_replied_user
delete_after (float) – The interval after which this message would be deleted automatically.

Returns

The message that was sent.

Return type

Message

Raises

Forbidden: – You are not allowed to send message at this destination.
HTTPError: – The message sending failed somehow.

async trigger_typing_indicator()

Triggers the typing indicator in provided channel.

The typing indicators ends after few seconds or when a message is sent the channel.

Raises

Forbidden – Cannot start typing indicator because user is missing permissions.
HTTPError – Typing triggering failed.

typing()

Returns a context manager interface that triggers typing in the channel.

Example:

async with channel.typing():
    # do something long
    await asyncio.sleep(5)
    await channel.send("Done!")

This can be used in both simple and async context managers.

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

ThreadMember

class neocord.ThreadMember

Represents a member of Thread.

id

The ID of member.

Type: int

thread_id

The ID of thread.

Type: int

thread

The thread that this member belongs to.

Type: Thread

joined_at

The time when this member joined the thread.

Type: datetime.datetime

StageInstance

class neocord.StageInstance

Represents a stage instance.

A stage instance is an event in stage channel that users can discover using stage discovery and join the stage channel.

id

The snowflake ID of this instance.

Type: int

guild_id

The guild ID that this instance belongs to.

Type: int

channel_id

The snowflake ID of the stage channel that this instance is associated to.

Type: int

topic

The topic of stage instance.

Type: Optional[str]

privacy_level

The privacy level of this instance.

Type: StagePrivacyLevel

discoverable_disabled

Whether this instance is disabled to be publicly discoverable.

Type: bool

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async delete(*, reason=None)

Deletes the stage instance or in other words end the live stage.

The user has to be stage moderator to perform this action i.e has following permissions:

Permissions.manage_channels
Permissions.mute_members
Permissions.move_members

Parameters

reason (str) – The reason for deleting the stage instance. Shows up on audit log.

Raises

Forbidden – You are not allowed to delete this instance.
HTTPError – An error occured while performing this action.

async edit(*, topic=..., privacy_level=..., reason=None)

Edits the stage instance.

The user has to be stage moderator to perform this action i.e has following permissions:

Permissions.manage_channels
Permissions.mute_members
Permissions.move_members

Parameters

topic (str) – The topic of stage instance.
privacy_level (StagePrivacyLevel) – The privacy level of stage instance.
reason (str) – The reason for editing the stage instance. Shows up on audit log.

Raises

Forbidden – You are not allowed to edit this instance.
HTTPError – An error occured while performing this action.

property guild

Returns the guild that belongs to this stage instance.

Requires GatewayIntents.guilds to be enabled.

Type: Optional[Guild]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

PrivateChannel

class neocord.PrivateChannel

Base class for all “private” channels.

Currently following classes implement this class:

DirectChannel

me

The user representing the connected user.

Type: ClientUser

id

The ID of channel.

Type: int

DirectChannel

class neocord.DirectChannel

Represents a direct message channel with another user.

recipient

The user that this channel is with.

Type: User

me

The user representing the client.

Type: ClientUser

id

The ID of this channel.

Type: int

last_pin_timestamp

The time when last pin in the channel was created.

Type: datetime.datetime

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async close()

Closes the direct message with recipient.

You should generally not use this method as private channels management is done by library transparently.

Raises: HTTPError – Closing of DM channel failed.

async delete_message(message)

Deletes a message from the destination. A shorthand and a lower level of Message.delete().

Parameters

message (Message) – The message to delete.

Raises

Forbidden: – You are not allowed to delete this message.
HTTPError: – The message deleting failed somehow.

async fetch_message(id, /)

Fetches a message from this channel.

Parameters

id (int) – The ID of the message.

Returns

The requested message.

Return type

Message

Raises

NotFound: – Message was not found. i.e ID is incorrect.
Forbidden: – You are not allowed to fetch this message.
HTTPError: – The fetching failed somehow.

async fetch_pins()

Fetches the list of messages that are pinned in the channel.

Returns: The pinned messages.
Return type: List[Message]
Raises: HTTPError – Fetching of pins failed.

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

async send(content=None, *, embed=None, embeds=None, delete_after=None, allowed_mentions=None, file=None, files=None, sticker=None, stickers=None, reference=None, mention_replied_user=None)

Sends a message to the channel.

A message must contain at least one of the following:

content
sticker or stickers
embed or embeds
file or files

Parameters

content (str) – The content of message.
embed (Embed) – The embed shown in message. This parameter cannot be mixed with embeds
embeds (List[Embed]) – The list of embeds shown in message. This parameter cannot be mixed with embed
file (File) – The file sent in message. This parameter cannot be mixed with files
files (List[File]) – The list of files sent in message. This parameter cannot be mixed with file
sticker (Sticker) – The sticker to send. Cannot be mixed with stickers.
stickers (List[Sticker]) – The list of stickers to send. Cannot be mixed with sticker.
reference (Union[MessageReference, Message]) – The message reference to reply this message for.
mention_replied_user (bool) – Whether to mention the author when replying. When set, Overrides the AllowedMentions.mention_replied_user
delete_after (float) – The interval after which this message would be deleted automatically.

Returns

The message that was sent.

Return type

Message

Raises

Forbidden: – You are not allowed to send message at this destination.
HTTPError: – The message sending failed somehow.

async trigger_typing_indicator()

Triggers the typing indicator in provided channel.

The typing indicators ends after few seconds or when a message is sent the channel.

Raises

Forbidden – Cannot start typing indicator because user is missing permissions.
HTTPError – Typing triggering failed.

typing()

Returns a context manager interface that triggers typing in the channel.

Example:

async with channel.typing():
    # do something long
    await asyncio.sleep(5)
    await channel.send("Done!")

This can be used in both simple and async context managers.

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

ScheduledEvent

class neocord.ScheduledEvent

Represents a guild scheduled event.

guild

The guild that this event belongs to.

Type: Guild

id

The ID of this event.

Type: int

channel_id

The ID of voice or stage channel where the event is hosted. Could be None if event is external.

Type: Optional[int]

creator_id

The ID of user that created this event. Could be None in some rare cases.

Type: Optional[int]

entity_id

The iD of associated entity i.e stage channel.

Type: int

name

The name of event.

Type: str

description

The description of event.

Type: Optional[str]

starts_at

The datetime representation of time when the event is scheduled to start.

Type: datetime.datetime

ends_at

The datetime representation of time when the event is scheduled to end. Could be None if no time is set.

Type: Optional[datetime.datetime]

privacy_level

The privacy level of event.

Type: EventPrivacyLevel

status

The current status of event.

Type: EventStatus

entity_type

The entity type of event.

Type: entity_type

location

The external location where event is being hosted. Could be None if event is hosted in a channel.

Type: Optional[str]

creator

The creator of this event. Could be None in some rare cases.

Type: Optional[User]

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

property channel

Returns the channel that this event is hosted in. Could be None if the event is hosted externally.

Returns
Return type: Optional[Union[VoiceChannel, StageChannel]]

async delete()

Deletes the guild scheduled event.

Returns

The deleted event.

Return type

ScheduledEvent

Raises

Forbidden – You don’t have permissions to delete this event.
NotFound – Event not found.
HTTPError – Deleting of event failed.

async edit(*, channel=..., location=..., name=..., privacy_level=..., starts_at=..., ends_at=..., description=..., entity_type=..., status=...)

Edits the scheduled event.

Requires you to have Permissions.manage_events in the event’s guild.

Parameters

name (str) – The name of event.
starts_at (datetime.datetime) – The datetime representation of the time when the event will be scheduled to start.
ends_at (datetime.datetime) – The datetime representation of the time when the event will be scheduled to end. Ending time is required for external events but optional for non-external events.
description (str) – The description of event.
channel (Union[VoiceChannel, StageChannel]) – The channel where the event is being hosted. Cannot be mixed with location.
location (str) – The external location name where event is being hosted. Cannot be mixed with channel.
privacy_level (EventPrivacyLevel) – The privacy level of event. Defaults to GUILD_ONLY
entity_type (EntityType) – The type of entity where event is being hosted. You must provide this to edit the entity of event from channel to location and vice versa.
status (EventStatus) –
The new status of the event. This parameter can be used to start, end or cancel the event.

There are some considerations for this parameter. Some major ones are mentioned below:
- You cannot start an already active event.
- You cannot cancel an active event.
- You cannot end a scheduled event. You can only cancel it.
- You can only end an active event.

Raises

Forbidden – You don’t have permissions to edit an event.
HTTPError – Editing of event failed.

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

GuildTemplate

class neocord.GuildTemplate

Represents a guild template that can be used to create clone of guilds.

code

The unique code of this template.

Type: int

name

The title of template.

Type: str

description

The description of template.

Type: Optional[str]

usage_count

Number of times this template was used to create a guild.

Type: int

creator

The user who created this template.

Type: User

creator_id

The ID of creator of this template.

Type: int

created_at

The time when the template was created.

Type: datetime.datetime

last_synced_at

The time when the template was last synced.

Type: datetime.datetime

source_guild_id

The ID of guild that this template belongs to.

Type: int

source_guild

The guild that this template belongs to. If the parent guild is not cached, This guild will be partial and miss some attributes.

Type: Guild

dirty

Whether this template has unsynced changes.

Type: bool

async create_guild(*, name, icon=None)

Create a guild from this template.

Note

Only bots that are in less then 10 guilds can create guilds.

Parameters

name (str) – The name of guild.
icon (bytes) – The icon of guild if any. Defaults to None.

Returns

The created guild. This guild is not the same guild as the one that is cached later.

Return type

Guild

Raises

HTTPError – Creation of guild failed.

async delete()

Deletes this template.

This action requires Permissions.manage_guild permission in parent guild.

Raises

Forbidden – You are not allowed to perform this action.
HTTPError – Deleting for template failed.

async edit(*, name=None, description=...)

Edits this template.

This action requires Permissions.manage_guild permission in parent guild.

Parameters

name (str) – The title of template.
description (str) – The description of template.

Raises

Forbidden – You are not allowed to perform this action.
HTTPError – Editing for template failed.

async sync()

Syncs this template.

This action requires Permissions.manage_guild permission in parent guild.

Raises

Forbidden – You are not allowed to perform this action.
HTTPError – Syncing for template failed.

property url

Returns the URL of this template.

Type: str

Sticker

class neocord.Sticker

Represents a sticker.

This class is a base class for sticker types. Currently following are the available types of stickers:

StandardSticker
GuildSticker

id

The sticker ID.

Type: int

name

The name of sticker.

Type: str

description

The description of sticker.

Type: str

type

The type of sticker.

Type: StickerType

format_type

The format type of sticker.

Type: StickerFormatType

property url

Returns the CDN URL of this sticker.

Type: str

StandardSticker

class neocord.StandardSticker

Represents a “standard” Discord sticker that can be used by Nitro users.

pack_id

The ID of pack that this sticker belongs to.

Type: int

sort_value

The sorting position in the sticker pack that this sticker belongs to.

Type: int

async fetch_pack(use_cache=True)

Fetches the pack that this standard sticker belongs to.

Parameters

use_cache (bool) – Whether to use cache if available. Defaults to True.

Returns

The fetched sticker pack.

Return type

StickerPack

Raises

NotFound – The pack isn’t found.
HTTPError – Could not fetch this pack.
NeocordException – Pack does not exist.

property tags

Returns a list of autocomplete tags for this sticker.

Type: List[str]

property url

Returns the CDN URL of this sticker.

Type: str

GuildSticker

class neocord.GuildSticker

Represents a sticker in a Guild.

available

Whether this sticker is available. A sticker may not be available due to loss of server boosts.

Type: bool

guild_id

The ID of guild that this sticker belongs to.

Type: int

user

The user that uploaded this sticker. Only available if the user has Permissions.manage_emojis_and_stickers permission in parent guild.

Type: User

emoji

The relevant unicode emoji of this sticker.

Type: str

cache(*, overwrite=False)

Adds this entity to the cache.

If the entity is already cached, This method would silently return unless overwrite is set to True.

Parameters: overwrite (bool) – Whether to force overwrite the cache.

async delete(*, reason=None)

Deletes the sticker.

This requires Permissions.manage_emojis_and_stickers.

Parameters

reason (str) – The reason for deleting the sticker.

Raises

Forbidden – You are not allowed to delete the sticker.
HTTPError – The sticker deletion failed.

async edit(*, name=None, description=..., emoji=None, reason=None)

Edits the sticker.

This requires Permissions.manage_emojis_and_stickers.

Parameters

name (str) – The name of sticker.
description (str) – The description of sticker.
emoji (str) – The unicode emoji or emoji’s name that relates to sticker.
reason (str) – The reason for deleting the sticker.

Raises

Forbidden – You are not allowed to edit the sticker.
HTTPError – The sticker editing failed.

property guild

The guild this sticker belongs to.

Type: Optional[Guild]

is_cached()

Indicates if this entity is cached or not.

Returns: Whether the entity is cached or not.
Return type: bool

uncache()

Removes this entity from the cache.

Any error would be suppressed if the entity isn’t cached already.

property url

Returns the CDN URL of this sticker.

Type: str

StickerPack

class neocord.StickerPack

Represents a standard sticker pack.

id

The ID of this sticker pack.

Type: int

stickers

The list of standard stickers that are available in this sticker pack.

Type: List[StandardSticker]

name

The name of this sticker pack.

Type: str

sku_id

The SKU ID of this sticker pack.

Type: int

cover_sticker_id

The ID of sticker that is shown on sticker pack as an icon. This may be None in some cases.

Type: Optional[int]

description

The description of sticker pack.

Type: str

banner_asset_id

The ID of asset that is shown as banner for this pack.

Type: int

banner_asset_url(size=512, format='png')

Returns the URL of the banner asset that this pack has.

Parameters

size (int) – The size that should be returned. Must be a power of 2 between 16 to 4096. Defaults to 512.
format (str) –
The format to return URL as. Valid formats are:
- png
- jpg or jpeg
- webp
Defaults to PNG.

property cover_sticker

The sticker that is shown as icon of this pack.

Type: StandardSticker

Invite

class neocord.Invite

Represents an invite to a guild or channel.

Note

Due to Discord API limitations, Some attributes are not sent in specific cases which are described below.

Following attributes are only available when fetching invite with either of Guild.fetch_invites() or GuildChannel.fetch_invites():

uses
max_uses
max_age
temporary
created_at

Following attributes are only available when fetching invite with Client.fetch_invite() method.

expires_at (When with_expiration set to True.)
approximate_presence_count (When with_counts set to True.)
approximate_member_count (When with_counts set to True.)
scheduled_event (When guild_scheduled_event set.)

code

The code of this invite.

Type: str

uses

The number of time this invite has been used.

Type: Optional[int]

max_uses

The number of time this invite can been used.

Type: Optional[int]

max_age

The invite’s maximum age in seconds.

Type: Optional[int]

temporary

Whether this invite is temporary i.e members joining with this invite get kicked after disconnect.

Type: Optional[bool]

created_at

The time this invite was created at.

Type: Optional[datetime.datetime]

target_type

The type of target of invite.

Type: InviteTargetType

approximate_presence_count

The approximate presence count of this invite’s guild.

Type: Optional[int]

approximate_member_count

The approximate member count of this invite’s guild.

Type: Optional[int]

expires_at

The time when this invite expires.

Type: Optional[datetime.datetime]

guild

The invite guild. This is always InviteGuild except for on_invite_create() gateway event when it is Guild.

Type: Union[Guild, InviteGuild]

channel

The invite channel. This is always InviteChannel except for on_invite_create() gateway event when it is GuildChannel.

Type: Union[GuildChannel, InviteChannel]

scheduled_event

The scheduled event that belongs to the invite.

Type: Optional[ScheduledEvent]

async delete(*, reason=None)

Deletes or “revokes” the invite.

Requires Permissions.manage_channels to delete an invite from a channel or Permissions.manage_guild to delete it from a guild.

Parameters

reason (str) – The reason that shows up on audit log entry for this action.

Raises

Forbidden – Missing permissions to perform this action.
HTTPError – Invite deletion failed.

InviteChannel

class neocord.InviteChannel

Represents a channel sent in an Invite.

id

The ID of channel.

Type: int

name

The name of channel.

Type: str

type

The type of channel.

Type: ChannelType

InviteGuild

class neocord.InviteGuild

Represents a guild sent in an Invite.

id

The ID of guild.

Type: int

name

The name of guild.

Type: str

features

The list of strings representing the guild features.

Type: List[str]

verification_level

The verification level of guild.

Type: VerificationLevel

vanity_url_code

The vanity URL code of guild if any.

Type: Optional[str]

description

The description of guild if any.

Type: Optional[str]

property banner

Returns the CDN asset for the invite banner of guild.

This may be None if the guild has no banner set.

Type: Optional[CDNAsset]

property icon

Returns the CDN asset for the icon of guild.

This may be None if the guild has no icon set.

Type: Optional[CDNAsset]

property splash

Returns the CDN asset for the splash of guild.

This may be None if the guild has no splash set.

Type: Optional[CDNAsset]

Webhook

class neocord.Webhook

Represents a webhook from Discord.

A webhook is used to post messages to Discord without having a Bot user. Webhooks are also used by interactions. There are currently three types of webhooks.

Incoming webhooks can post messages to channels with a generated token.
Channel Follower webhooks are internal webhooks used with Channel Following to crosspost new messages into channels.
Application webhooks are used for interactions.

Out of all types, Only first one can be created by user using a token (See create()) and remaining are handled transparently.

id

The snowflake ID of webhook.

Type: int

type

The type of webhook.

Type: WebhookType

guild_id

The ID of guild this webhook belongs to or None if no webhook has no parent guild.

Type: Optional[int]

channel_id

The ID of channel this webhook belongs to or None if no webhook has no parent channel.

Type: Optional[int]

user

The user that created the webhook. This is not returned when creating the webhook via create().

Type: Optional[User]

name

The name of webhook.

Type: Optional[str]

token

The token of webhook.

Type: Optional[str]

application_id

The ID of application that created the webhook only if it is application-owned.

Type: Optional[int]

source_guild

The source guild that the webhook belongs to. Only applicable for channel webhooks.

Type: Optional[WebhookGuild]

source_channel

The source channel that the webhook belongs to. Only applicable for channel webhooks.

Type: Optional[WebhookChannel]

property authenticated

Indicates whether this webhook has a bot token attached.

Type: bool

async delete(*, reason=None, use_auth=True)

Deletes the webhook.

This operation requires manage_webhooks in the channel when deleting the webhook with a bot token. Otherwise, when a webhook token is present, No permissions are required.

When deleting a webhook with a webhook token, You cannot supply a reason for audit log.

While no errors would be raised when passing above parameters, They will have no affect.

Parameters

reason (str) – The reason for performing the action. Cannot be applied when deleting webhook with a webhook token.
use_auth (bool) – Whether to use bot token when available. If set to False, The webhook will be edited with it’s token. Defaults to True.

Raises

HTTPError – Deletion of webhook failed.

async delete_message(message, *, thread=None)

Deletes a message sent by this webhook.

A lower level of WebhookMessage.delete().

Parameters

message (Union[WebhookMessage, Message]) – The message to delete.
thread (Thread) – The thread message is in.

Raises

HTTPError – Failed to delete the message.

async edit(*, name=None, channel=None, avatar=..., reason=None, use_auth=True)

Edits the webhook.

The editing requires manage_webhooks in the channel when editing the webhook with a bot token. Otherwise; when editing webhook with it’s own token, No permissions are required.

Caveats to note when editing a webhook with a webhook token are:

You cannot supply a reason for audit log.
channel parameter cannot be edited.

While no errors would be raised when passing above parameters, They will have no affect.

Parameters

name (str) – The name of webhook.
avatar (Optional[bytes]) – The avatar of webhook. To remove the avatar, Pass None.
channel (TextChannel) – The channel in which webhook posts the messages. Cannot be applied when editing webhook with a webhook token.
reason (str) – The reason for performing the action. Cannot be applied when editing webhook with a webhook token.
use_auth (bool) – Whether to use bot token when available. If set to False, The webhook will be edited with it’s token. Defaults to True.

Raises

HTTPError – Editing of webhook failed.

async edit_message(message, *, thread=None, content=..., embed=..., embeds=..., file=..., files=..., allowed_mentions=None)

Edits a message sent by this webhook.

A lower level of WebhookMessage.edit().

Parameters

message (Union[WebhookMessage, Message]) – The message to edit.
thread (Thread) – The thread message is in.
content (str) – The content of message.
embeds (List[Embed]) – The embeds to include in message. Cannot be mixed with embed.
embed (Embed) – The embed to include in message. Cannot be mixed with embeds.
file (File) – The file to include with message. Cannot be mixed with files.
files (List[File]) – The list of files to include in message. Cannot be mixed with file.
allowed_mentions (AllowedMentions) – The allowed mentions to apply on new message content.

Returns

The updated message. This is a fresh instance, not the one passed in method.

Return type

WebhookMessage

Raises

NotFound – Message is deleted.
HTTPError – Failed to edit the message.

async fetch_message(id, *, thread=None)

Fetches a message sent by this webhook.

Parameters

id (int) – The ID of message.
thread (Thread) – The thread message is in.

Returns

The fetched message.

Return type

WebhookMessage

Raises

NotFound – The ID is invalid or message is deleted.
HTTPError – Failed to fetch the message.

async send(content=None, *, name=None, avatar=..., embeds=None, embed=None, files=None, file=None, allowed_mentions=None, tts=False, thread=None, wait=True)

Sends a message through this webhook.

The webhook must have a webhook token attached to it.

A message must contain at least one of the following:

content
embed or embeds
file or files

Parameters

content (str) – The content of message.
embeds (List[Embed]) – The embeds to send in message. Cannot be mixed with embed.
embed (Embed) – The embed to send in message. Cannot be mixed with embeds.
file (File) – The file to attach with message. Cannot be mixed with files.
files (List[File]) – The list of files to attach in message. Cannot be mixed with file.
allowed_mentions (AllowedMentions) – The allowed mentions to apply on message.
tts (bool) – Whether the message is a text-to-speech message.
thread (Thread) – The thread to send message in.
name (str) – The username that webhook should adapt for this message.
avatar (bytes) – The avatar that webhook should adapt for this message. Can be None to use the default discord avatar.
wait (bool) – Whether for wait for message to create. If set to False, No message will be returned by this method. Defaults to True.

Returns

The sent webhook message. If wait is false, this is not returned.

Return type

Optional[WebhookMessage]

Raises

HTTPError – Failed to send the message.

property url

Returns the URL of the webhook.

Type: str

WebhookMessage

class neocord.WebhookMessage

Represents a message sent by a Webhook.

This class inherits Message and modifies the edit() and delete() methods.

async delete(*, thread=None)

Deletes the message.

Parameters: thread (Thread) – The thread message is in.
Raises: HTTPError – Failed to delete the message.

async edit(**kw)

Edits the message.

Parameters

thread (Thread) – The thread message is in.
content (str) – The content of message.
embeds (List[Embed]) – The embeds to include in message. Cannot be mixed with embed.
embed (Embed) – The embed to include in message. Cannot be mixed with embeds.
file (File) – The file to include with message. Cannot be mixed with files.
files (List[File]) – The list of files to include in message. Cannot be mixed with file.
allowed_mentions (AllowedMentions) – The allowed mentions to apply on new message content.

Returns

The updated message. This is a fresh instance.

Return type

WebhookMessage

Raises

NotFound – Message is deleted.
HTTPError – Failed to edit the message.

WebhookGuild

class neocord.WebhookGuild

Represents a partial guild often returned by channel follower webhooks.

id

The ID of guild.

Type: int

name

The name of guild.

Type: str

property icon

Returns the CDN asset for the icon of guild.

This may be None if the guild has no icon set.

Type: Optional[CDNAsset]

WebhookChannel

class neocord.WebhookChannel

Represents a partial channel often returned by channel follower webhooks.

id

The ID of guild.

Type: int

name

The name of guild.

Type: str

Dataclasses

These data classes can be created by users and provide a rich interface for certain tasks like embeds creation etc.

Object

class neocord.Object

Represents a generic Discord object.

This data class can be useful if you just have the ID of desired Discord model. Most of the methods that require a specific discord model to be passed as parameters can also take this class. However in some cases, This class may not be supported.

For example you can edit a message without fetching the actual message if you just have the message’s ID:

message_id = 12345678910
fake_message = neocord.Object(id=message_id)
await channel.edit_message(fake_message, content='Edited!')

Parameters: id (int) – The ID of object.

Color

class neocord.Color

A class that wraps the integer color values in (r, g, b) like form.

This class also provides some pre-made factory methods that generates different common colors and some from Discord’s branding.

This class is used to represent the color of entities sent by Discord like roles, embeds, banners etc.

An alias Colour is also available for this class.

Parameters: value (int) – The integer value of color.

r

The RED value from (r, g, b)

Type: int

g

The GREEN value from (r, g, b)

Type: int

b

The BLUE value from (r, g, b)

Type: int

Embed

class neocord.Embed

A class that provides an easy to handle interface for creating and managing rich message embeds.

This class implements some helpers that make management of embeds easy.

clear_fields()

Removes all the fields from embed.

Returns: The list of fields that were removed.
Return type: List[EmbedField]

create_field(**options)

Adds a field in embed at the end.

Parameters

name (str) – The name of field.
value (str) – The value of field.
inline (bool) – Whether the field should line with last field.

Returns

The added field.

Return type

EmbedField

insert_field(index, **options)

Adds a field in embed at the provided index.

Parameters

index (int) – The index to add field on.
name (str) – The name of field.
value (str) – The value of field.
inline (bool) – Whether the field should line with last field.

Returns

The added field.

Return type

EmbedField

remove_field(index)

Removes a field from embed.

This method will not raise the error if field with provided index does not exist.

Parameters: index (int) – The index of field.
Returns: The popped field, if any.
Return type: Optional[EmbedField]

remove_image(): Removes the image from embed.

remove_thumbnail()

Removes the thumbnail from embed.

Returns: The removed thumbnail. If any.
Return type: Optional[EmbedThumbnail]

set_image(**options)

Sets an image on embed.

Parameters: url (str) – The URL of image.
Returns: The added image.
Return type: EmbedImage

set_thumbnail(**options)

Sets a thumbnail on embed.

Parameters: url (str) – The URL of thumbnail.
Returns: The added thumbnail.
Return type: EmbedThumbnail

AllowedMentions

class neocord.AllowedMentions

A dataclass that handles the logic for allowing and disallowing mentions in a Message.

Creating an instance without any parameters creates the object with all options set to True.

Parameters

mention_users (bool) – Whether to enable user mentions in messages.
mention_roles (bool) – Whether to enable role mentions in messages.
mention_everyone_here (bool) – Whether to enable @everyone and @here mentions in messages.
mention_replied_user (bool) – Whether to mention the user whose message is being replied by message.

roles

List of roles IDs that will be mentioned by message.

Type: List[int]

users

List of users IDs that will be mentioned by message.

Type: List[int]

add_role(role)

Adds a specific role that will be mentioned in message.

Parameters: role (int) – The role ID that will be mentioned.

add_user(user)

Adds a specific user that will be mentioned in message.

Parameters: user (int) – The user ID that will be mentioned.

classmethod none()

Creates an allowed mentions object with all options disabled.

Returns
Return type: AllowedMentions

remove_role(role)

Removes a specific role from list of roles that will be mentioned.

If provided role is not found, This function would not raise any error.

Parameters: role (int) – The role ID to remove.

remove_user(user)

Removes a specific user from list of roles that will be mentioned.

If provided user is not found, This function would not raise any error.

Parameters: user (int) – The user ID to remove.

File

class neocord.File

A class that aids in sending file attachments in messages.

Example:

file = neocord.File('path/to/file.png')
await channel.send(file=file)

Note

This class is meant to be for one time use only and you should re-create the class everytime you want to send a file.

Parameters

fp (Union[os.PathLike, io.BufferedIOBase]) – The path to the file or the file-like object opened in read or read-binary mode.
name (str) – The name of file.
spoiler (bool) – Whether this file is marked as spoiler.
description (str) – The description of file attachment.

PermissionOverwrite

class neocord.PermissionOverwrite

Represents a permission overwrite for a specific channel.

The default value of a permission in this class is None which represents that no overwrite is applied. If a permission is False, it indicates that permission has been explicitly denied and for a permission set to True indicates permission is explicitly allowed.

This class takes same parameters (permissions) as Permissions.

classmethod from_pair(allow, deny)

Creates a permission overwrite with allow, deny permissions pair.

Parameters

allow (Permissions) – The permissions to allow.
deny (Permissions) – The permissions to deny.

Returns

The created permission overwrite.

Return type

PermissionOverwrite

pair()

Creates a (allow, deny) tuple of permissions from this permission overwrite.

Returns
Return type: Tuple[Permissions, Permissions]

PartialEmoji

class neocord.PartialEmoji

Represents a “partial” custom or unicode emoji.

This data class can be constructed by users and is also returned in many scenarios when complete emoji could not be resolved by the library.

Parameters

id (Optional[int]) – The ID of emoji or None if the emoji is unicode emoji.
name (Optional[str]) – For custom guild emojis, This is the name of emoji and for unicode emojis, This is the representation of emoji. This can be None if the custom emoji is deleted.
animated (bool) – Whether the emoji is animated. Always False for unicode emojis.

is_unicode(): bool: Indicates whether the emoji is unicode emoji.

property mention

Returns the string representation used to render emoji in Discord.

Type: str

async resolve(guild)

Resolves this emoji to a Emoji.

The emoji must not be a unicode emoji and must belong to provided guild. This method tries to get the emoji from guild’s cache and if emoji is not found, it makes an API call to fetch it.

If either one of the methods cannot fetch the emoji, None is returned.

Parameters: guild (Guild) – The guild to which the emoji belongs to.
Returns: The resolved emoji. If emoji could not be resolved, None is returned.
Return type: Optional[Emoji]
Raises: TypeError – The emoji is not a custom emoji.

Flags

These classes wrap the flags management in an easy to use interface.

GatewayIntents

class neocord.GatewayIntents

Represents the gateway intents.

Intents allow you to choose to enable or disable certain events that you don’t want or need to recieve over gateway.

Following are the privileged intents that are required to be explicitly enabled from Discord Developer portal and require whitelisting if the bot if in over 100 guilds:

GatewayIntents.members
GatewayIntents.presence

To see a brief list of events that would be recieved over gateway for certain intents, See the official `documentation`_ <https://discord.com/developers/docs/topics/gateway#gateway-intents>.

value

The raw integer value of the intents.

Type: int

messages

A shorthand that represents both guild_messages and direct_messages

Type: bool

reactions

A shorthand that represents both guild_messages_reactions and direct_messages_reactions

Type: bool

typing

A shorthand that represents both guild_messages_typing and direct_messages_typing

Type: bool

guilds

Returns True if the guild intents are enabled.

Type: bool

members

Returns True if the guild members intents are enabled.

This is a privileged intent and must be explicitly enabled from Developers portal. If your bot is in more then 100 Guilds, you would require verification and intents whitelisting.

Type: bool

bans

Returns True if the guild bans intents are enabled.

Type: bool

emojis_and_stickers

Returns True if the emojis and stickers intents are enabled.

Type: bool

integrations

Returns True if the guild integrations intents are enabled.

Type: bool

webhooks

Returns True if the guild webhooks intents are enabled.

Type: bool

invites

Returns True if the guild invites intents are enabled.

Type: bool

voice_states

Returns True if the voice states intents are enabled.

Type: bool

presences

Returns True if the guild members presences intents are enabled.

Type: bool

guild_messages

Returns True if the guild messages intents are enabled.

Type: bool

guild_messages_typing

Returns True if the guild messages typing trigger intents are enabled.

Type: bool

guild_messages_reactions

Returns True if the guild message reactions intents are enabled.

Type: bool

direct_messages

Returns True if the direct messages intents are enabled.

Type: bool

direct_messages_typing

Returns True if the direct messages typing trigger intents are enabled.

Type: bool

direct_messages_reactions

Returns True if the DM message reactions intents are enabled.

Type: bool

scheduled_events

Returns True if the scheduled events intents are enabled.

Type: bool

classmethod all()

Constructs a GatewayIntents with all intents enabled (including privileged ones).

Returns
Return type: GatewayIntents

classmethod unprivileged()

Constructs a GatewayIntents with all default intents enabled except privileged ones.

Returns
Return type: GatewayIntents

SystemChannelFlags

class neocord.SystemChannelFlags

Represents the flags for a guild system channel.

value

The raw integer value of flag.

Type: int

suppress_join_notifications

Returns True if join notifications is enabled in system channels.

Type: bool

suppress_premium_subscriptions

Returns True if server boosts notifications is enabled in system channels.

Type: bool

suppress_guild_reminder_notifications

Returns True if guild reminders in system channels is enabled.

Type: bool

suppress_join_notification_replies

Returns True if user are allowed to reply to system channel join messages.

Type: bool

UserFlags

class neocord.UserFlags

Represents the public flags of a user that appear on the user accounts. They are often referred as “badges” in the UI and are shown on the profile of users.

This class is not generally created manually.

value

The raw integer value of flags.

Type: int

discord_employee

Returns True if the user is a Discord staff.

Type: bool

partnered_server_owner

Returns True if the user has the partnered server owner badge.

Type: bool

hypesquad_events

Returns True if the user has Hypesquad events badge.

Type: bool

bug_hunter_level_1

Returns True if the user has the level one of bug hunter badge.

Type: bool

house_bravery

Returns True if the user’s house is HypeSquad Bravery.

Type: bool

house_brilliance

Returns True if the user’s house is HypeSquad Brilliance.

Type: bool

house_balance

Returns True if the user’s house is HypeSquad Balance.

Type: bool

early_supporter

Returns True if the user has the “Early Supporter” badge.

Type: bool

team_user

Returns True if user is a “team user”.

Type: bool

bug_hunter_level_2

Returns True if the has the user level two on bug hunter badge.

Type: bool

verified_bot

Returns True if the has the user is a verified bot.

Type: bool

early_verified_bot_developer

Returns True if the has the “Early Verified Bot Developer” badge.

Type: bool

discord_certified_moderator

Returns True if the has the “Certified Discord Moderator” badge.

Type: bool

MessageFlags

class neocord.MessageFlags

Represents the flags for a message.

crossposted

Returns True if message has been published.

Type: bool

crosspost

Returns True if message is a crosspost by a channel followed by message’s channel.

Type: bool

suppress_embeds

Returns True if embeds on the message should be suppressed.

Type: bool

source_message_deleted

Returns True if message is a crosspost and the original message has been deleted.

Type: bool

urgent

Returns True if the message is an urgent system message.

Type: bool

thread_parent

Returns True if the message has a thread belonging to it.

Type: bool

ephemeral

Returns True if only the user who created the interaction can see this message.

Type: bool

loading

Returns True if the message is an interaction response and the application is currently in “Thinking” state.

Type: bool

Permissions

class neocord.Permissions

Represents the permissions that can be applied on channels, roles, users and other entities.

This data class wraps the permissions bitwise in user friendly form so they can be easily manipulated.

You can either pass a raw permission bitwise value or permissions as keyword arguments to initalize an instance of this class.

Parameters: value (int) – The raw permissions value.