hikari.channels#

Application and entities that are used to describe both DMs and guild channels on Discord.

Module Contents#

class hikari.channels.ChannelFlag[source]#

Bases: hikari.internal.enums.Flag

The flags for a channel.

NONE[source]#

None.

PINNED[source]#

The thread is pinned in a forum channel.

Note

As of writing, this can only be set for threads belonging to a forum channel.

REQUIRE_TAG[source]#

Whether a tag is required to be specified when creating a thread in a forum channel

Note

As of writing, this can only be set for forum channels.

class hikari.channels.ChannelFollow[source]#

Relationship between a news channel and a subscriber channel.

The subscriber channel will receive crosspost messages that correspond to any “broadcast” announcements that the news channel creates.

app: hikari.traits.RESTAware[source]#

Client application that models may use for procedures.

channel_id: hikari.snowflakes.Snowflake[source]#

Return the channel ID of the channel being followed.

webhook_id: hikari.snowflakes.Snowflake[source]#

Return the ID of the webhook for this follow.

async fetch_channel()[source]#

Fetch the object of the guild channel being followed.

Returns:
typing.Union[hikari.channels.GuildNewsChannel, hikari.channels.GuildTextChannel]

The channel being followed.

While this will usually be GuildNewsChannel, if the channel’s news status has been removed then this will be a GuildTextChannel.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the READ_MESSAGES permission in the channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_webhook()[source]#

Fetch the webhook attached to this follow.

Returns:
hikari.webhooks.ChannelFollowerWebhook

The webhook attached to this follow.

Raises:
hikari.errors.ForbiddenError

If you are missing the MANAGE_WEBHOOKS permission in the guild or channel this follow is targeting.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.NotFoundError

If the webhook is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

get_channel()[source]#

Get the channel being followed from the cache.

Warning

This will always be None if you are not in the guild that this channel exists in.

Returns:
typing.Union[hikari.channels.GuildNewsChannel, hikari.channels.GuildTextChannel, None]

The object of the guild channel that was found in the cache or None. While this will usually be GuildNewsChannel or None, if the channel referenced has since lost it’s news status then this will return a GuildTextChannel.

class hikari.channels.ChannelType[source]#

Bases: int, hikari.internal.enums.Enum

The known channel types that are exposed to us by the API.

DM = 1[source]#

A direct channel between two users.

GROUP_DM = 3[source]#

A direct channel between multiple users.

GUILD_CATEGORY = 4[source]#

An category used for organizing channels in a guild.

GUILD_FORUM = 15[source]#

A channel consisting of a collection of public guild threads.

GUILD_NEWS = 5[source]#

A channel that can be followed and can crosspost.

GUILD_NEWS_THREAD = 10[source]#

A temporary sub-channel within a ChannelType.GUILD_NEWS channel.

GUILD_PRIVATE_THREAD = 12[source]#

A temporary sub-channel with restricted access.

Like ChannelType.GUILD_PUBLIC_THREAD, these exist within ChannelType.GUILD_TEXT channels but can only be accessed by members who are invited to them or have MANAGE_THREADS permission.

GUILD_PUBLIC_THREAD = 11[source]#

A temporary sub-channel within a ChannelType.GUILD_TEXT channel.

GUILD_STAGE = 13[source]#

A few to many voice channel for hosting events.

GUILD_TEXT = 0[source]#

A text channel in a guild.

GUILD_VOICE = 2[source]#

A voice channel in a guild.

class hikari.channels.DMChannel[source]#

Bases: PrivateChannel, TextableChannel

Represents a direct message text channel that is between you and another user.

property shard_id: Literal[0][source]#

Return the shard ID for the shard.

recipient: hikari.users.User[source]#

The user recipient of this DM.

class hikari.channels.ForumLayoutType[source]#

Bases: int, hikari.internal.enums.Enum

The layout type for forum channels.

GALLERY_VIEW = 2[source]#

Gallery View.

LIST_VIEW = 1[source]#

List View.

NOT_SET = 0[source]#

Not Set.

class hikari.channels.ForumSortOrderType[source]#

Bases: int, hikari.internal.enums.Enum

The sort order for forum channels.

CREATION_DATE = 1[source]#

Creation Date.

LATEST_ACTIVITY = 0[source]#

Latest Activity.

class hikari.channels.ForumTag[source]#

Bases: hikari.snowflakes.Unique

Represents a forum tag.

property emoji_id: hikari.snowflakes.Snowflake | None[source]#

ID of the emoji of this tag.

property unicode_emoji: hikari.emojis.UnicodeEmoji | None[source]#

Unicode emoji of this tag.

id: hikari.snowflakes.Snowflake[source]#

The ID of the tag.

When creating tags, this will be 0.

moderated: bool[source]#

The whether this flag can only be applied by moderators.

Moderators are those with MANAGE_CHANNEL or ADMINISTRATOR permissions.

name: str[source]#

The name of the tag.

class hikari.channels.GroupDMChannel[source]#

Bases: PrivateChannel

Represents a group direct message channel.

Note

This doesn’t have the methods found on TextableChannel as bots cannot interact with a group DM that they own by sending or seeing messages in it.

property icon_url: hikari.files.URL | None[source]#

Icon for this group DM, if set.

application_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the application that created the group DM.

If the group DM was not created by a bot, this will be None.

icon_hash: str | None[source]#

The CDN hash of the icon of the group, if an icon is set.

nicknames: MutableMapping[hikari.snowflakes.Snowflake, str][source]#

A mapping of set nicknames within this group DMs to user IDs.

owner_id: hikari.snowflakes.Snowflake[source]#

The ID of the owner of the group.

recipients: Mapping[hikari.snowflakes.Snowflake, hikari.users.User][source]#

The recipients of the group DM.

make_icon_url(*, ext='png', size=4096)[source]#

Generate the icon for this group, if set.

Parameters:
extstr

The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.

sizeint

The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns:
typing.Optional[hikari.files.URL]

The URL, or None if no icon is present.

Raises:
ValueError

If size is not a power of two between 16 and 4096 (inclusive).

class hikari.channels.GuildCategory[source]#

Bases: PermissibleGuildChannel

Represents a guild category channel.

These can contain other channels inside, and act as a method for organisation.

parent_id: None[source]#

The ID of the parent channel the channel belongs to.

This is always None for categories.

class hikari.channels.GuildChannel[source]#

Bases: PartialChannel

The base for anything that is a guild channel.

property shard_id: int | None[source]#

Return the shard ID for the shard.

This may be None if the shard count is not known.

guild_id: hikari.snowflakes.Snowflake[source]#

The ID of the guild the channel belongs to.

parent_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the parent channel the channel belongs to.

For thread channels this will refer to the parent textable guild channel. For other guild channel types this will refer to the parent category and if no parent category is set for the channel, this will be None. For guild categories this will always be None.

async edit(*, name=undefined.UNDEFINED, position=undefined.UNDEFINED, topic=undefined.UNDEFINED, nsfw=undefined.UNDEFINED, bitrate=undefined.UNDEFINED, video_quality_mode=undefined.UNDEFINED, user_limit=undefined.UNDEFINED, rate_limit_per_user=undefined.UNDEFINED, region=undefined.UNDEFINED, permission_overwrites=undefined.UNDEFINED, parent_category=undefined.UNDEFINED, default_auto_archive_duration=undefined.UNDEFINED, flags=undefined.UNDEFINED, archived=undefined.UNDEFINED, auto_archive_duration=undefined.UNDEFINED, locked=undefined.UNDEFINED, invitable=undefined.UNDEFINED, applied_tags=undefined.UNDEFINED, reason=undefined.UNDEFINED)[source]#

Edit the text channel.

Other Parameters:
namehikari.undefined.UndefinedOr[[str]

If provided, the new name for the channel.

positionhikari.undefined.UndefinedOr[[int]

If provided, the new position for the channel.

topichikari.undefined.UndefinedOr[str]

If provided, the new topic for the channel.

nsfwhikari.undefined.UndefinedOr[bool]

If provided, whether the channel should be marked as NSFW or not.

bitratehikari.undefined.UndefinedOr[int]

If provided, the new bitrate for the channel.

video_quality_mode: hikari.undefined.UndefinedOr[typing.Union[hikari.channels.VideoQualityMode, int]]

If provided, the new video quality mode for the channel.

user_limithikari.undefined.UndefinedOr[int]

If provided, the new user limit in the channel.

rate_limit_per_userhikari.undefined.UndefinedOr[hikari.internal.time.Intervalish]

If provided, the new rate limit per user in the channel.

regionhikari.undefined.UndefinedOr[typing.Union[hikari.voices.VoiceRegion, str]]

If provided, the voice region to set for this channel. Passing None here will set it to “auto” mode where the used region will be decided based on the first person who connects to it when it’s empty.

permission_overwriteshikari.undefined.UndefinedOr[typing.Sequence[hikari.channels.PermissionOverwrite]]

If provided, the new permission overwrites for the channel.

parent_categoryhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildCategory]]

If provided, the new guild category for the channel.

default_auto_archive_durationhikari.undefined.UndefinedOr[hikari.internal.time.Intervalish]

If provided, the auto archive duration Discord’s end user client should default to when creating threads in this channel.

This should be either 60, 1440, 4320 or 10080 minutes, as of writing.

flagshikari.undefined.UndefinedOr[ChannelFlag]

If provided, the new channel flags to use for the channel. This can only be used on a forum channel to apply ChannelFlag.REQUIRE_TAG, or on a forum thread to apply ChannelFlag.PINNED.

archivedhikari.undefined.UndefinedOr[bool]

If provided, the new archived state for the thread. This only applies to threads.

auto_archive_durationhikari.undefined.UndefinedOr[time.Intervalish]

If provided, the new auto archive duration for this thread. This only applies to threads.

This should be either 60, 1440, 4320 or 10080 minutes, as of writing.

lockedhikari.undefined.UndefinedOr[bool]

If provided, the new locked state for the thread. This only applies to threads.

If it’s locked then only people with MANAGE_THREADS can unarchive it.

invitablehikari.undefined.UndefinedOr[bool]

If provided, the new setting for whether non-moderators can invite new members to a private thread. This only applies to threads.

applied_tagshikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.channels.ForumTag]]

If provided, the new tags to apply to the thread. This only applies to threads in a forum channel.

reasonhikari.undefined.UndefinedOr[str]

If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns:
hikari.channels.PartialChannel

The edited channel.

Raises:
hikari.errors.BadRequestError

If any of the fields that are passed have an invalid value.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing permissions to edit the channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_guild()[source]#

Fetch the guild linked to this channel.

Returns:
hikari.guilds.RESTGuild

The requested guild.

Raises:
hikari.errors.ForbiddenError

If you are not part of the guild.

hikari.errors.NotFoundError

If the guild is not found.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

get_guild()[source]#

Return the guild linked to this channel.

Returns:
typing.Optional[hikari.guilds.Guild]

The linked guild object or None if it’s not cached.

class hikari.channels.GuildForumChannel[source]#

Bases: PermissibleGuildChannel

Represents a guild forum channel.

available_tags: Sequence[ForumTag][source]#

The available tags to select from when creating a thread.

default_auto_archive_duration: datetime.timedelta[source]#

The auto archive duration Discord’s client defaults to for threads in this channel.

This may be be either 1 hour, 1 day, 3 days or 1 week.

default_layout: ForumLayoutType[source]#

The default layout for the forum.

default_reaction_emoji_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the default reaction emoji.

default_reaction_emoji_name: str | hikari.emojis.UnicodeEmoji | None[source]#

Name of the default reaction emoji.

Either the string name of the custom emoji, the object of the hikari.emojis.UnicodeEmoji or None when the relevant custom emoji’s data is not available (e.g. the emoji has been deleted).

default_sort_order: ForumSortOrderType[source]#

The default sort order for the forum.

default_thread_rate_limit_per_user: datetime.timedelta[source]#

The default delay (in seconds) between a user can send a message in created threads.

If there is no rate limit, this will be 0 seconds.

Note

Any user that has permissions allowing MANAGE_MESSAGES, MANAGE_CHANNEL, ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

flags: ChannelFlag[source]#

The channel flags for this channel.

Note

As of writing, the only flag that can be set is ChannelFlag.REQUIRE_TAG.

last_thread_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last thread created in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

rate_limit_per_user: datetime.timedelta[source]#

The delay (in seconds) between a user can create threads in this channel.

If there is no rate limit, this will be 0 seconds.

Note

Any user that has permissions allowing MANAGE_MESSAGES, MANAGE_CHANNEL, ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

topic: str | None[source]#

The guidelines for the channel.

class hikari.channels.GuildNewsChannel[source]#

Bases: PermissibleGuildChannel, TextableGuildChannel

Represents an news channel.

default_auto_archive_duration: datetime.timedelta[source]#

The auto archive duration Discord’s client defaults to for threads in this channel.

This may be be either 1 hour, 1 day, 3 days or 1 week.

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

last_pin_timestamp: datetime.datetime | None[source]#

The timestamp of the last-pinned message.

Note

This may be None in several cases; Discord does not document what these cases are. Trust no one!

topic: str | None[source]#

The topic of the channel.

class hikari.channels.GuildNewsThread[source]#

Bases: GuildThreadChannel

Represents a guild news channel public thread.

class hikari.channels.GuildPrivateThread[source]#

Bases: GuildThreadChannel

Represents a guild private thread.

is_invitable: bool[source]#

Whether non-moderators can add other non-moderators to a private thread.

class hikari.channels.GuildPublicThread[source]#

Bases: GuildThreadChannel

Represents a non-news guild channel public thread.

applied_tag_ids: Sequence[hikari.snowflakes.Snowflake][source]#

The IDs of the applied tags on this thread.

This will only apply to threads created inside a forum channel.

flags: ChannelFlag[source]#

The channel flags for this thread.

This will only apply to threads created inside a forum channel.

Note

As of writing, the only flag that can be set is ChannelFlag.PINNED.

class hikari.channels.GuildStageChannel[source]#

Bases: PermissibleGuildChannel, TextableGuildChannel

Represents a stage channel.

bitrate: int[source]#

The bitrate for the stage channel (in bits per second).

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

region: str | None[source]#

ID of the voice region for this stage channel.

If set to None then this is set to “auto” mode where the used region will be decided based on the first person who connects to it when it’s empty.

user_limit: int[source]#

The user limit for the stage channel.

If this is 0, then assume no limit.

class hikari.channels.GuildTextChannel[source]#

Bases: PermissibleGuildChannel, TextableGuildChannel

Represents a guild text channel.

default_auto_archive_duration: datetime.timedelta[source]#

The auto archive duration Discord’s client defaults to for threads in this channel.

This may be be either 1 hour, 1 day, 3 days or 1 week.

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

last_pin_timestamp: datetime.datetime | None[source]#

The timestamp of the last-pinned message.

Note

This may be None in several cases; Discord does not document what these cases are. Trust no one!

rate_limit_per_user: datetime.timedelta[source]#

The delay (in seconds) between a user can send a message to this channel.

If there is no rate limit, this will be 0 seconds.

Note

Any user that has permissions allowing MANAGE_MESSAGES, MANAGE_CHANNEL, ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

topic: str | None[source]#

The topic of the channel.

class hikari.channels.GuildThreadChannel[source]#

Bases: TextableGuildChannel

Base class for all guild thread channels.

approximate_member_count: int[source]#

Approximate count of members in the thread channel.

Warning

This stop counting at 50.

approximate_message_count: int[source]#

Approximate number of messages in the thread channel.

Warning

This stops counting at 50 for threads created before 2022/06/01.

archive_timestamp: datetime.datetime[source]#

When the thread’s archived state was last changed.

Note

If the thread has never been archived then this will be the thread’s creation date and this will be changed when a thread is unarchived.

auto_archive_duration: datetime.timedelta[source]#

How long the thread will be left inactive before being automatically archived.

As of writing this may either 1 hour, 1 day, 3 days or 1 week.

is_archived: bool[source]#

Whether the thread is archived.

is_locked: bool[source]#

Whether the thread is locked.

When a thread is locked, only users with MANAGE_THREADS permission can un-archive it.

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

last_pin_timestamp: datetime.datetime | None[source]#

The timestamp of the last-pinned message.

Note

This may be None in several cases; Discord does not document what these cases are. Trust no one!

member: ThreadMember | None[source]#

Thread member object for the current user, if they are in the thread.

Note

This is only returned by some endpoints and on private thread access events.

owner_id: hikari.snowflakes.Snowflake[source]#

ID of the user who created this thread.

parent_id: hikari.snowflakes.Snowflake[source]#

Id of this thread’s textable parent channel.

rate_limit_per_user: datetime.timedelta[source]#

The delay (in seconds) between a user can send a message to this channel.

If there is no rate limit, this will be 0 seconds.

Note

Any user that has permissions allowing MANAGE_MESSAGES, MANAGE_CHANNEL, ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

thread_created_at: datetime.datetime | None[source]#

When the thread was created.

Will be None for threads created before 2020-01-09.

class hikari.channels.GuildVoiceChannel[source]#

Bases: PermissibleGuildChannel, TextableGuildChannel

Represents a voice channel.

bitrate: int[source]#

The bitrate for the voice channel (in bits per second).

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

region: str | None[source]#

ID of the voice region for this voice channel.

If set to None then this is set to “auto” mode where the used region will be decided based on the first person who connects to it when it’s empty.

user_limit: int[source]#

The user limit for the voice channel.

If this is 0, then assume no limit.

video_quality_mode: VideoQualityMode | int[source]#

The video quality mode for the voice channel.

class hikari.channels.PartialChannel[source]#

Bases: hikari.snowflakes.Unique

Channel representation for cases where further detail is not provided.

This is commonly received in HTTP API responses where full information is not available from Discord.

property mention: str[source]#

Return a raw mention string for the channel.

Note

There are platform specific inconsistencies with mentions of GuildCategories, GroupDMChannels and DMChannels showing the correct name but not being interactable.

Returns:
str

The mention string to use.

app: hikari.traits.RESTAware[source]#

Client application that models may use for procedures.

id: hikari.snowflakes.Snowflake[source]#

The ID of this entity.

name: str | None[source]#

The channel’s name. This will be missing for DM channels.

type: ChannelType | int[source]#

The channel’s type.

async delete()[source]#

Delete a channel in a guild, or close a DM.

Note

For Public servers, the set ‘Rules’ or ‘Guidelines’ channels and the ‘Public Server Updates’ channel cannot be deleted.

Returns:
hikari.channels.PartialChannel

Object of the channel that was deleted.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the MANAGE_CHANNEL permission in the channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

class hikari.channels.PermissibleGuildChannel[source]#

Bases: GuildChannel

Base class for all guild channels which have permission overwrites.

Note

This doesn’t apply to thread channels as they implicitly inherit permissions from their parent channel.

is_nsfw: bool[source]#

Whether the channel is marked as NSFW.

permission_overwrites: Mapping[hikari.snowflakes.Snowflake, PermissionOverwrite][source]#

The permission overwrites for the channel.

This maps the ID of the entity in the overwrite to the overwrite data.

position: int[source]#

The sorting position of the channel.

Higher numbers appear further down the channel list.

async edit_overwrite(target, *, target_type=undefined.UNDEFINED, allow=undefined.UNDEFINED, deny=undefined.UNDEFINED, reason=undefined.UNDEFINED)[source]#

Edit permissions for a specific entity in the given guild channel.

This creates new overwrite for the channel, if there no other overwrites present.

Parameters:
targettyping.Union[hikari.users.PartialUser, hikari.guilds.PartialRole, hikari.channels.PermissionOverwrite, hikari.snowflakes.Snowflakeish]

The channel overwrite to edit. This may be the object or the ID of an existing overwrite.

Other Parameters:
target_typehikari.undefined.UndefinedOr[typing.Union[hikari.channels.PermissionOverwriteType, int]]

If provided, the type of the target to update. If unset, will attempt to get the type from target.

allowhikari.undefined.UndefinedOr[hikari.permissions.Permissions]

If provided, the new value of all allowed permissions.

denyhikari.undefined.UndefinedOr[hikari.permissions.Permissions]

If provided, the new value of all disallowed permissions.

reasonhikari.undefined.UndefinedOr[str]

If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Raises:
TypeError

If target_type is unset and we were unable to determine the type from target.

hikari.errors.BadRequestError

If any of the fields that are passed have an invalid value.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

hikari.errors.NotFoundError

If the channel is not found or the target is not found if it is a role.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async remove_overwrite(target)[source]#

Delete a custom permission for an entity in a given guild channel.

Parameters:
targettyping.Union[hikari.users.PartialUser, hikari.guilds.PartialRole, hikari.channels.PermissionOverwrite, hikari.snowflakes.Snowflakeish]

The channel overwrite to delete.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

hikari.errors.NotFoundError

If the channel is not found or the target is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

class hikari.channels.PermissionOverwrite[source]#

Represents permission overwrites for a channel or role in a channel.

You may sometimes need to make instances of this object to add/edit permission overwrites on channels.

Examples

Creating a permission overwrite.

overwrite = PermissionOverwrite(
    id=163979124820541440,
    type=PermissionOverwriteType.MEMBER,
    allow=(
        Permissions.VIEW_CHANNEL
        | Permissions.READ_MESSAGE_HISTORY
        | Permissions.SEND_MESSAGES
    ),
    deny=(
        Permissions.MANAGE_MESSAGES
        | Permissions.SPEAK
    ),
)
property unset: hikari.permissions.Permissions[source]#

Bitfield of all permissions not explicitly allowed or denied by this overwrite.

allow: hikari.permissions.Permissions[source]#

The permissions this overwrite allows.

deny: hikari.permissions.Permissions[source]#

The permissions this overwrite denies.

id: hikari.snowflakes.Snowflake[source]#

The ID of this entity.

type: PermissionOverwriteType | int[source]#

The type of entity this overwrite targets.

class hikari.channels.PermissionOverwriteType[source]#

Bases: int, hikari.internal.enums.Enum

The type of entity a Permission Overwrite targets.

MEMBER = 1[source]#

A permission overwrite that targets a specific guild member.

ROLE = 0[source]#

A permission overwrite that targets all the members with a specific role.

class hikari.channels.PrivateChannel[source]#

Bases: PartialChannel

The base for anything that is a private (non-guild bound) channel.

last_message_id: hikari.snowflakes.Snowflake | None[source]#

The ID of the last message sent in this channel.

Warning

This might point to an invalid or deleted message. Do not assume that this will always be valid.

class hikari.channels.TextableChannel[source]#

Bases: PartialChannel

Mixin class for a channel which can have text messages in it.

async delete_messages(messages, /, *other_messages)[source]#

Bulk-delete messages from the channel.

Note

This API endpoint will only be able to delete 100 messages at a time. For anything more than this, multiple requests will be executed one-after-the-other, since the rate limits for this endpoint do not favour more than one request per bucket.

If one message is left over from chunking per 100 messages, or only one message is passed to this coroutine function, then the logic is expected to defer to delete_message. The implication of this is that the delete_message endpoint is ratelimited by a different bucket with different usage rates.

Warning

This endpoint is not atomic. If an error occurs midway through a bulk delete, you will not be able to revert any changes made up to this point.

Warning

Specifying any messages more than 14 days old will cause the call to fail, potentially with partial completion.

Parameters:
messages

Either the object/ID of an existing message to delete or an iterable (sync or async) of the objects and/or IDs of existing messages to delete.

Other Parameters:
*other_messageshikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]

The objects and/or IDs of other existing messages to delete.

Raises:
hikari.errors.BulkDeleteError

An error containing the messages successfully deleted, and the messages that were not removed. The BaseException.__cause__ of the exception will be the original error that terminated this process.

fetch_history(*, before=undefined.UNDEFINED, after=undefined.UNDEFINED, around=undefined.UNDEFINED)[source]#

Browse the message history for a given text channel.

Note

This call is not a coroutine function, it returns a special type of lazy iterator that will perform API calls as you iterate across it, thus any errors documented below will happen then. See hikari.iterators for the full API for this iterator type.

Other Parameters:
beforehikari.undefined.UndefinedOr[snowflakes.SearchableSnowflakeishOr[hikari.snowflakes.Unique]]

If provided, fetch messages before this snowflakes. If you provide a datetime object, it will be transformed into a snowflakes. This may be any other Discord entity that has an ID. In this case, the date the object was first created will be used.

afterhikari.undefined.UndefinedOr[snowflakes.SearchableSnowflakeishOr[hikari.snowflakes.Unique]]

If provided, fetch messages after this snowflakes. If you provide a datetime object, it will be transformed into a snowflakes. This may be any other Discord entity that has an ID. In this case, the date the object was first created will be used.

aroundhikari.undefined.UndefinedOr[snowflakes.SearchableSnowflakeishOr[hikari.snowflakes.Unique]]

If provided, fetch messages around this snowflakes. If you provide a datetime object, it will be transformed into a snowflakes. This may be any other Discord entity that has an ID. In this case, the date the object was first created will be used.

Returns:
hikari.iterators.LazyIterator[hikari.messages.Message]

A iterator to fetch the messages.

Raises:
TypeError

If you specify more than one of before, after, about.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you lack permissions to read message history in the given channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_message(message)[source]#

Fetch a specific message in the given text channel.

Parameters:
messagehikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]

The message to fetch. This may be the object or the ID of an existing channel.

Returns:
hikari.messages.Message

The requested message.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the READ_MESSAGE_HISTORY in the channel.

hikari.errors.NotFoundError

If the channel is not found or the message is not found in the given text channel.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_pins()[source]#

Fetch the pinned messages in this text channel.

Returns:
typing.Sequence[hikari.messages.Message]

The pinned messages in this text channel.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the READ_MESSAGES in the channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async pin_message(message)[source]#

Pin an existing message in the text channel.

Parameters:
messagehikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]

The message to pin. This may be the object or the ID of an existing message.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the MANAGE_MESSAGES in the channel.

hikari.errors.NotFoundError

If the channel is not found, or if the message does not exist in the given channel.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async send(content=undefined.UNDEFINED, *, attachment=undefined.UNDEFINED, attachments=undefined.UNDEFINED, component=undefined.UNDEFINED, components=undefined.UNDEFINED, embed=undefined.UNDEFINED, embeds=undefined.UNDEFINED, sticker=undefined.UNDEFINED, stickers=undefined.UNDEFINED, tts=undefined.UNDEFINED, reply=undefined.UNDEFINED, reply_must_exist=undefined.UNDEFINED, mentions_everyone=undefined.UNDEFINED, mentions_reply=undefined.UNDEFINED, user_mentions=undefined.UNDEFINED, role_mentions=undefined.UNDEFINED, flags=undefined.UNDEFINED)[source]#

Create a message in this channel.

Parameters:
contenthikari.undefined.UndefinedOr[typing.Any]

If provided, the message contents. If hikari.undefined.UNDEFINED, then nothing will be sent in the content. Any other value here will be cast to a str.

If this is a hikari.embeds.Embed and no embed nor embeds kwarg is provided, then this will instead update the embed. This allows for simpler syntax when sending an embed alone.

Likewise, if this is a hikari.files.Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

Other Parameters:
attachmenthikari.undefined.UndefinedOr[hikari.files.Resourceish]

If provided, the message attachment. This can be a resource, or string of a path on your computer or a URL.

Attachments can be passed as many different things, to aid in convenience.

  • If a pathlib.PurePath or str to a valid URL, the

    resource at the given URL will be streamed to Discord when sending the message. Subclasses of hikari.files.WebResource such as hikari.files.URL, hikari.messages.Attachment, hikari.emojis.Emoji, EmbedResource, etc will also be uploaded this way. This will use bit-inception, so only a small percentage of the resource will remain in memory at any one time, thus aiding in scalability.

  • If a hikari.files.Bytes is passed, or a str

    that contains a valid data URI is passed, then this is uploaded with a randomized file name if not provided.

  • If a hikari.files.File, pathlib.PurePath or

    str that is an absolute or relative path to a file on your file system is passed, then this resource is uploaded as an attachment using non-blocking code internally and streamed using bit-inception where possible. This depends on the type of concurrent.futures.Executor that is being used for the application (default is a thread pool which supports this behaviour).

attachmentshikari.undefined.UndefinedOr[typing.Sequence[hikari.files.Resourceish]]

If provided, the message attachments. These can be resources, or strings consisting of paths on your computer or URLs.

componenthikari.undefined.UndefinedOr[hikari.api.special_endpoints.ComponentBuilder]

If provided, builder object of the component to include in this message.

componentshikari.undefined.UndefinedOr[typing.Sequence[hikari.api.special_endpoints.ComponentBuilder]]

If provided, a sequence of the component builder objects to include in this message.

embedhikari.undefined.UndefinedOr[hikari.embeds.Embed]

If provided, the message embed.

embedshikari.undefined.UndefinedOr[typing.Sequence[hikari.embeds.Embed]]

If provided, the message embeds.

stickerhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.stickers.PartialSticker]]

If provided, the object or ID of a sticker to send on the message.

As of writing, bots can only send custom stickers from the current guild.

stickershikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.stickers.PartialSticker]]

If provided, a sequence of the objects and IDs of up to 3 stickers to send on the message.

As of writing, bots can only send custom stickers from the current guild.

ttshikari.undefined.UndefinedOr[bool]

If provided, whether the message will be TTS (Text To Speech).

replyhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]]

If provided, the message to reply to.

reply_must_existhikari.undefined.UndefinedOr[bool]

If provided, whether to error if the message being replied to does not exist instead of sending as a normal (non-reply) message. Defaults to True.

This will not do anything if not being used with reply.

mentions_everyonehikari.undefined.UndefinedOr[bool]

If provided, whether the message should parse @everyone/@here mentions.

mentions_replyhikari.undefined.UndefinedOr[bool]

If provided, whether to mention the author of the message that is being replied to.

This will not do anything if not being used with reply.

user_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.users.PartialUser], bool]]

If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.users.PartialUser derivatives to enforce mentioning specific users.

role_mentionshikari.undefined.UndefinedOr[typing.Union[hikari.snowflakes.SnowflakeishSequence[hikari.guilds.PartialRole], bool]]

If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed. Alternatively this may be a collection of hikari.snowflakes.Snowflake, or hikari.guilds.PartialRole derivatives to enforce mentioning specific roles.

flagshikari.undefined.UndefinedOr[hikari.messages.MessageFlag]

If provided, optional flags to set on the message. If hikari.undefined.UNDEFINED, then nothing is changed.

Note that some flags may not be able to be set. Currently the only flags that can be set are NONE and SUPPRESS_EMBEDS.

Returns:
hikari.messages.Message

The created message.

Raises:
hikari.errors.BadRequestError

This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds; reply not found or not in the same channel; too many components.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you lack permissions to send messages in the given channel.

hikari.errors.NotFoundError

If the channel is not found.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

ValueError

If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

TypeError

If both attachment and attachments are specified.

trigger_typing()[source]#

Trigger typing in a given channel.

This returns an object that can either be awaited to trigger typing once, or used as an async context manager to keep typing until the block completes.

await channel.trigger_typing()   # type for 10s

async with channel.trigger_typing():
    await asyncio.sleep(35)            # keep typing until this finishes

Note

Sending a message to this channel will stop the typing indicator. If using an async with, it will start up again after a few seconds. This is a limitation of Discord’s API.

Returns:
hikari.api.special_endpoints.TypingIndicator

The typing indicator object.

async unpin_message(message)[source]#

Unpin a given message from the text channel.

Parameters:
messagehikari.snowflakes.SnowflakeishOr[hikari.messages.PartialMessage]

The message to unpin. This may be the object or the ID of an existing message.

Raises:
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.ForbiddenError

If you are missing the MANAGE_MESSAGES permission.

hikari.errors.NotFoundError

If the channel is not found or the message is not a pinned message in the given channel.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

class hikari.channels.TextableGuildChannel[source]#

Bases: GuildChannel, TextableChannel

Mixin class for any guild channel which can have text messages in it.

class hikari.channels.ThreadMember[source]#

Represents a thread’s member.

flags: int[source]#

Bitfield flag of the user’s settings for the thread.

Note

As of writing, the values of this field’s are undocumented.

joined_at: datetime.datetime[source]#

When the user joined the relevant thread.

thread_id: hikari.snowflakes.Snowflake[source]#

ID of the thread this member is in.

user_id: hikari.snowflakes.Snowflake[source]#

The member’s user ID.

Note

This will only ever be None on thread members attached to guild create events, where this is the current bot’s user.

class hikari.channels.VideoQualityMode[source]#

Bases: int, hikari.internal.enums.Enum

The camera quality of the voice chat.

AUTO = 1[source]#

Video quality will be set for optimal performance.

FULL = 2[source]#

Video quality will be set to 720p.

hikari.channels.WebhookChannelT[source]#

Union of the channel types which incoming and follower webhooks can be attached to.

The following types are in this:

hikari.channels.WebhookChannelTypes: Tuple[Type[GuildTextChannel], Type[GuildNewsChannel]] = ()[source]#

Tuple of the channel types which are valid for WebhookChannelT.

This includes: