Skip to content

hikari.channels#

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

WebhookChannelT module-attribute #

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

The following types are in this:

WebhookChannelTypes module-attribute #

Tuple of the channel types which are valid for hikari.channels.WebhookChannelT.

This includes:

ChannelFlag #

Bases: Flag

The flags for a channel.

NONE class-attribute instance-attribute #

NONE = 0 << 1

None.

PINNED class-attribute instance-attribute #

PINNED = 1 << 1

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 class-attribute instance-attribute #

REQUIRE_TAG = 1 << 4

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.

name property #

name: str

Return the name of the flag combination as a str.

value property #

value: int

Return the int value of the flag.

all #

all(*flags: Self) -> bool

Check if all of the given flags are part of this value.

RETURNS DESCRIPTION
bool

True if any of the given flags are part of this value. Otherwise, return False.

any #

any(*flags: Self) -> bool

Check if any of the given flags are part of this value.

RETURNS DESCRIPTION
bool

True if any of the given flags are part of this value. Otherwise, return False.

difference #

difference(other: Union[int, Self]) -> Self

Perform a set difference with the other set.

This will return all flags in this set that are not in the other value.

Equivalent to using the subtraction - operator.

intersection #

intersection(other: Union[int, Self]) -> Self

Return a combination of flags that are set for both given values.

Equivalent to using the "AND" & operator.

invert #

invert() -> Self

Return a set of all flags not in the current set.

is_disjoint #

is_disjoint(other: Union[int, Self]) -> bool

Return whether two sets have a intersection or not.

If the two sets have an intersection, then this returns False. If no common flag values exist between them, then this returns True.

is_subset #

is_subset(other: Union[int, Self]) -> bool

Return whether another set contains this set or not.

Equivalent to using the "in" operator.

is_superset #

is_superset(other: Union[int, Self]) -> bool

Return whether this set contains another set or not.

none #

none(*flags: Self) -> bool

Check if none of the given flags are part of this value.

Note

This is essentially the opposite of hikari.internal.enums.Flag.any.

RETURNS DESCRIPTION
bool

True if none of the given flags are part of this value. Otherwise, return False.

split #

split() -> Sequence[Self]

Return a list of all defined atomic values for this flag.

Any unrecognised bits will be omitted for brevity.

The result will be a name-sorted typing.Sequence of each member

symmetric_difference #

symmetric_difference(other: Union[int, Self]) -> Self

Return a set with the symmetric differences of two flag sets.

Equivalent to using the "XOR" ^ operator.

For a ^ b, this can be considered the same as (a - b) | (b - a).

union #

union(other: Union[int, Self]) -> Self

Return a combination of all flags in this set and the other set.

Equivalent to using the "OR" ~ operator.

ChannelFollow #

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 class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

channel_id class-attribute instance-attribute #

channel_id: Snowflake = field(hash=True, repr=True)

Return the channel ID of the channel being followed.

webhook_id class-attribute instance-attribute #

webhook_id: Snowflake = field(hash=True, repr=True)

Return the ID of the webhook for this follow.

fetch_channel async #

Fetch the object of the guild channel being followed.

RETURNS DESCRIPTION
Union[GuildNewsChannel, GuildTextChannel]

The channel being followed.

While this will usually be hikari.channels.GuildNewsChannel, if the channel's news status has been removed then this will be a hikari.channels.GuildNewsChannel.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.VIEW_CHANNEL permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

fetch_webhook async #

fetch_webhook() -> ChannelFollowerWebhook

Fetch the webhook attached to this follow.

RETURNS DESCRIPTION
ChannelFollowerWebhook

The webhook attached to this follow.

RAISES DESCRIPTION
ForbiddenError

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

UnauthorizedError

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

NotFoundError

If the webhook is not found.

RateLimitTooLongError

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

InternalServerError

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

get_channel #

get_channel() -> Union[GuildNewsChannel, GuildTextChannel, None]

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 DESCRIPTION
Union[GuildNewsChannel, GuildTextChannel, None]

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

ChannelType #

Bases: int, Enum

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

DM class-attribute instance-attribute #

DM = 1

A direct channel between two users.

GROUP_DM class-attribute instance-attribute #

GROUP_DM = 3

A direct channel between multiple users.

GUILD_CATEGORY class-attribute instance-attribute #

GUILD_CATEGORY = 4

An category used for organizing channels in a guild.

GUILD_FORUM class-attribute instance-attribute #

GUILD_FORUM = 15

A channel consisting of a collection of public guild threads.

GUILD_NEWS class-attribute instance-attribute #

GUILD_NEWS = 5

A channel that can be followed and can crosspost.

GUILD_NEWS_THREAD class-attribute instance-attribute #

GUILD_NEWS_THREAD = 10

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

GUILD_PRIVATE_THREAD class-attribute instance-attribute #

GUILD_PRIVATE_THREAD = 12

A temporary sub-channel with restricted access.

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

GUILD_PUBLIC_THREAD class-attribute instance-attribute #

GUILD_PUBLIC_THREAD = 11

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

GUILD_STAGE class-attribute instance-attribute #

GUILD_STAGE = 13

A few to many voice channel for hosting events.

GUILD_TEXT class-attribute instance-attribute #

GUILD_TEXT = 0

A text channel in a guild.

GUILD_VOICE class-attribute instance-attribute #

GUILD_VOICE = 2

A voice channel in a guild.

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

DMChannel #

Bases: PrivateChannel, TextableChannel

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

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

created_at property #

created_at: datetime

When the object was created.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

last_message_id class-attribute instance-attribute #

last_message_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

recipient class-attribute instance-attribute #

recipient: User = field(eq=False, hash=False, repr=False)

The user recipient of this DM.

shard_id property #

shard_id: Literal[0]

Return the shard ID for the shard.

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

delete_messages async #

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.

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

TYPE: Union[SnowflakeishOr[PartialMessage], Iterable[SnowflakeishOr[PartialMessage]], AsyncIterable[SnowflakeishOr[PartialMessage]]]

PARAMETER DESCRIPTION
*other_messages

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
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 #

fetch_history(
    *,
    before: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    after: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    around: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED
) -> LazyIterator[Message]

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.

PARAMETER DESCRIPTION
before

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

after

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

around

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

RETURNS DESCRIPTION
LazyIterator[Message]

A iterator to fetch the messages.

RAISES DESCRIPTION
TypeError

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

InternalServerError

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

fetch_message async #

fetch_message(message: SnowflakeishOr[PartialMessage]) -> Message

Fetch a specific message in the given text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RETURNS DESCRIPTION
Message

The requested message.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.READ_MESSAGE_HISTORY in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_pins async #

fetch_pins() -> Sequence[Message]

Fetch the pinned messages in this text channel.

RETURNS DESCRIPTION
Sequence[Message]

The pinned messages in this text channel.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the [hikari.permissions.Permissions.VIEW_CHANNEL] permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

pin_message async #

pin_message(message: SnowflakeishOr[PartialMessage]) -> None

Pin an existing message in the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

send async #

send(
    content: UndefinedOr[Any] = undefined.UNDEFINED,
    *,
    attachment: UndefinedOr[Resourceish] = undefined.UNDEFINED,
    attachments: UndefinedOr[Sequence[Resourceish]] = undefined.UNDEFINED,
    component: UndefinedOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedOr[Sequence[ComponentBuilder]] = undefined.UNDEFINED,
    embed: UndefinedOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedOr[Sequence[Embed]] = undefined.UNDEFINED,
    sticker: UndefinedOr[SnowflakeishOr[PartialSticker]] = undefined.UNDEFINED,
    stickers: UndefinedOr[
        SnowflakeishSequence[PartialSticker]
    ] = undefined.UNDEFINED,
    tts: UndefinedOr[bool] = undefined.UNDEFINED,
    reply: UndefinedOr[SnowflakeishOr[PartialMessage]] = undefined.UNDEFINED,
    reply_must_exist: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_reply: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED,
    flags: Union[UndefinedType, int, MessageFlag] = undefined.UNDEFINED
) -> Message

Create a message in this channel.

PARAMETER DESCRIPTION
content

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.

TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED

PARAMETER DESCRIPTION
attachment

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.

TYPE: UndefinedOr[Resourceish]

attachments

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

TYPE: UndefinedOr[Sequence[Resourceish]]

component

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

TYPE: UndefinedOr[ComponentBuilder]

components

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

TYPE: UndefinedOr[Sequence[ComponentBuilder]]

embed

If provided, the message embed.

TYPE: UndefinedOr[Embed]

embeds

If provided, the message embeds.

TYPE: UndefinedOr[Sequence[Embed]]

sticker

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.

TYPE: UndefinedOr[SnowflakeishOr[PartialSticker]]

stickers

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.

TYPE: UndefinedOr[SnowflakeishSequence[PartialSticker]]

tts

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

TYPE: UndefinedOr[bool]

reply

If provided, the message to reply to.

TYPE: UndefinedOr[SnowflakeishOr[PartialMessage]]

reply_must_exist

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

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

TYPE: UndefinedOr[bool]

mentions_everyone

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

TYPE: UndefinedOr[bool]

mentions_reply

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.

TYPE: UndefinedOr[bool]

user_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]

role_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

flags

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 hikari.messages.MessageFlag.NONE and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

TYPE: UndefinedOr[MessageFlag]

RETURNS DESCRIPTION
Message

The created message.

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

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 #

trigger_typing() -> TypingIndicator

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 DESCRIPTION
TypingIndicator

The typing indicator object.

unpin_message async #

unpin_message(message: SnowflakeishOr[PartialMessage]) -> None

Unpin a given message from the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES permission.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

ForumLayoutType #

Bases: int, Enum

The layout type for forum channels.

GALLERY_VIEW class-attribute instance-attribute #

GALLERY_VIEW = 2

Gallery View.

LIST_VIEW class-attribute instance-attribute #

LIST_VIEW = 1

List View.

NOT_SET class-attribute instance-attribute #

NOT_SET = 0

Not Set.

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

ForumSortOrderType #

Bases: int, Enum

The sort order for forum channels.

CREATION_DATE class-attribute instance-attribute #

CREATION_DATE = 1

Creation Date.

LATEST_ACTIVITY class-attribute instance-attribute #

LATEST_ACTIVITY = 0

Latest Activity.

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

ForumTag #

Bases: Unique

Represents a forum tag.

created_at property #

created_at: datetime

When the object was created.

emoji_id property #

emoji_id: Optional[Snowflake]

ID of the emoji of this tag.

id class-attribute instance-attribute #

id: Snowflake = field(
    eq=True, hash=True, repr=True, converter=Snowflake, factory=min
)

The ID of the tag.

When creating tags, this will be 0.

moderated class-attribute instance-attribute #

moderated: bool = field(eq=False, hash=False, repr=False, default=False)

The whether this flag can only be applied by moderators.

Moderators are those with hikari.permissions.Permissions.MANAGE_CHANNELS or hikari.permissions.Permissions.ADMINISTRATOR permissions.

name class-attribute instance-attribute #

name: str = field(eq=False, hash=False, repr=True)

The name of the tag.

unicode_emoji property #

unicode_emoji: Optional[UnicodeEmoji]

Unicode emoji of this tag.

GroupDMChannel #

Bases: PrivateChannel

Represents a group direct message channel.

Note

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

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

application_id class-attribute instance-attribute #

application_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

The ID of the application that created the group DM.

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

created_at property #

created_at: datetime

When the object was created.

icon_hash class-attribute instance-attribute #

icon_hash: Optional[str] = field(eq=False, hash=False, repr=False)

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

icon_url property #

icon_url: Optional[URL]

Icon for this group DM, if set.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

last_message_id class-attribute instance-attribute #

last_message_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

nicknames class-attribute instance-attribute #

nicknames: MutableMapping[Snowflake, str] = field(
    eq=False, hash=False, repr=False
)

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

owner_id class-attribute instance-attribute #

owner_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the owner of the group.

recipients class-attribute instance-attribute #

recipients: Mapping[Snowflake, User] = field(eq=False, hash=False, repr=False)

The recipients of the group DM.

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

make_icon_url #

make_icon_url(*, ext: str = 'png', size: int = 4096) -> Optional[URL]

Generate the icon for this group, if set.

PARAMETER DESCRIPTION
ext

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

TYPE: str DEFAULT: 'png'

size

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

TYPE: int DEFAULT: 4096

RETURNS DESCRIPTION
Optional[URL]

The URL, or None if no icon is present.

RAISES DESCRIPTION
ValueError

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

GuildCategory #

Bases: PermissibleGuildChannel

Represents a guild category channel.

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

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

created_at property #

created_at: datetime

When the object was created.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_nsfw class-attribute instance-attribute #

is_nsfw: bool = field(eq=False, hash=False, repr=False)

Whether the channel is marked as NSFW.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

parent_id class-attribute instance-attribute #

parent_id: None = field(eq=False, hash=False, repr=True)

The ID of the parent channel the channel belongs to.

This is always None for categories.

permission_overwrites class-attribute instance-attribute #

permission_overwrites: Mapping[Snowflake, PermissionOverwrite] = field(
    eq=False, hash=False, repr=False
)

The permission overwrites for the channel.

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

position class-attribute instance-attribute #

position: int = field(eq=False, hash=False, repr=False)

The sorting position of the channel.

Higher numbers appear further down the channel list.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    region: UndefinedOr[Union[VoiceRegion, str]] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Sequence[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    parent_category: UndefinedOr[
        SnowflakeishOr[GuildCategory]
    ] = undefined.UNDEFINED,
    default_auto_archive_duration: UndefinedOr[
        Intervalish
    ] = undefined.UNDEFINED,
    flags: UndefinedOr[ChannelFlag] = undefined.UNDEFINED,
    archived: UndefinedOr[bool] = undefined.UNDEFINED,
    auto_archive_duration: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    locked: UndefinedOr[bool] = undefined.UNDEFINED,
    invitable: UndefinedOr[bool] = undefined.UNDEFINED,
    applied_tags: UndefinedOr[
        SnowflakeishSequence[ForumTag]
    ] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> PartialChannel

Edit the text channel.

PARAMETER DESCRIPTION
name

If provided, the new name for the channel.

TYPE: hikari.undefined.UndefinedOr[[str]

position

If provided, the new position for the channel.

TYPE: hikari.undefined.UndefinedOr[[int]

topic

If provided, the new topic for the channel.

TYPE: UndefinedOr[str]

nsfw

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

TYPE: UndefinedOr[bool]

bitrate

If provided, the new bitrate for the channel.

TYPE: UndefinedOr[int]

video_quality_mode

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

TYPE: UndefinedOr[Union[VideoQualityMode, int]]

user_limit

If provided, the new user limit in the channel.

TYPE: UndefinedOr[int]

rate_limit_per_user

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

TYPE: UndefinedOr[Intervalish]

region

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.

TYPE: UndefinedOr[Union[VoiceRegion, str]]

permission_overwrites

If provided, the new permission overwrites for the channel.

TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

parent_category

If provided, the new guild category for the channel.

TYPE: UndefinedOr[SnowflakeishOr[GuildCategory]]

default_auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

flags

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.

TYPE: UndefinedOr[ChannelFlag]

archived

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

TYPE: UndefinedOr[bool]

auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

locked

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

If it's locked then only people with hikari.permissions.Permissions.MANAGE_THREADS can unarchive it.

TYPE: UndefinedOr[bool]

invitable

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

TYPE: UndefinedOr[bool]

applied_tags

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

TYPE: UndefinedOr[SnowflakeishSequence[ForumTag]]

reason

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

TYPE: UndefinedOr[str]

RETURNS DESCRIPTION
PartialChannel

The edited channel.

RAISES DESCRIPTION
BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing permissions to edit the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit_overwrite async #

edit_overwrite(
    target: Union[Snowflakeish, PartialUser, PartialRole, PermissionOverwrite],
    *,
    target_type: UndefinedOr[
        Union[PermissionOverwriteType, int]
    ] = undefined.UNDEFINED,
    allow: UndefinedOr[Permissions] = undefined.UNDEFINED,
    deny: UndefinedOr[Permissions] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> None

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

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

PARAMETER DESCRIPTION
target

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

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

PARAMETER DESCRIPTION
target_type

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

TYPE: UndefinedOr[Union[PermissionOverwriteType, int]]

allow

If provided, the new value of all allowed permissions.

TYPE: UndefinedOr[Permissions]

deny

If provided, the new value of all disallowed permissions.

TYPE: UndefinedOr[Permissions]

reason

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

TYPE: UndefinedOr[str]

RAISES DESCRIPTION
TypeError

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

BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_guild async #

fetch_guild() -> PartialGuild

Fetch the guild linked to this channel.

RETURNS DESCRIPTION
RESTGuild

The requested guild.

RAISES DESCRIPTION
ForbiddenError

If you are not part of the guild.

NotFoundError

If the guild is not found.

UnauthorizedError

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

RateLimitTooLongError

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

InternalServerError

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

get_guild #

get_guild() -> Optional[GatewayGuild]

Return the guild linked to this channel.

RETURNS DESCRIPTION
Optional[Guild]

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

remove_overwrite async #

remove_overwrite(
    target: Union[PermissionOverwrite, PartialRole, PartialUser, Snowflakeish]
) -> None

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

PARAMETER DESCRIPTION
target

The channel overwrite to delete.

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

GuildChannel #

Bases: PartialChannel

The base for anything that is a guild channel.

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

created_at property #

created_at: datetime

When the object was created.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

parent_id class-attribute instance-attribute #

parent_id: Optional[Snowflake] = field(eq=False, hash=False, repr=True)

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.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    region: UndefinedOr[Union[VoiceRegion, str]] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Sequence[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    parent_category: UndefinedOr[
        SnowflakeishOr[GuildCategory]
    ] = undefined.UNDEFINED,
    default_auto_archive_duration: UndefinedOr[
        Intervalish
    ] = undefined.UNDEFINED,
    flags: UndefinedOr[ChannelFlag] = undefined.UNDEFINED,
    archived: UndefinedOr[bool] = undefined.UNDEFINED,
    auto_archive_duration: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    locked: UndefinedOr[bool] = undefined.UNDEFINED,
    invitable: UndefinedOr[bool] = undefined.UNDEFINED,
    applied_tags: UndefinedOr[
        SnowflakeishSequence[ForumTag]
    ] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> PartialChannel

Edit the text channel.

PARAMETER DESCRIPTION
name

If provided, the new name for the channel.

TYPE: hikari.undefined.UndefinedOr[[str]

position

If provided, the new position for the channel.

TYPE: hikari.undefined.UndefinedOr[[int]

topic

If provided, the new topic for the channel.

TYPE: UndefinedOr[str]

nsfw

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

TYPE: UndefinedOr[bool]

bitrate

If provided, the new bitrate for the channel.

TYPE: UndefinedOr[int]

video_quality_mode

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

TYPE: UndefinedOr[Union[VideoQualityMode, int]]

user_limit

If provided, the new user limit in the channel.

TYPE: UndefinedOr[int]

rate_limit_per_user

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

TYPE: UndefinedOr[Intervalish]

region

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.

TYPE: UndefinedOr[Union[VoiceRegion, str]]

permission_overwrites

If provided, the new permission overwrites for the channel.

TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

parent_category

If provided, the new guild category for the channel.

TYPE: UndefinedOr[SnowflakeishOr[GuildCategory]]

default_auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

flags

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.

TYPE: UndefinedOr[ChannelFlag]

archived

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

TYPE: UndefinedOr[bool]

auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

locked

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

If it's locked then only people with hikari.permissions.Permissions.MANAGE_THREADS can unarchive it.

TYPE: UndefinedOr[bool]

invitable

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

TYPE: UndefinedOr[bool]

applied_tags

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

TYPE: UndefinedOr[SnowflakeishSequence[ForumTag]]

reason

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

TYPE: UndefinedOr[str]

RETURNS DESCRIPTION
PartialChannel

The edited channel.

RAISES DESCRIPTION
BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing permissions to edit the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

fetch_guild async #

fetch_guild() -> PartialGuild

Fetch the guild linked to this channel.

RETURNS DESCRIPTION
RESTGuild

The requested guild.

RAISES DESCRIPTION
ForbiddenError

If you are not part of the guild.

NotFoundError

If the guild is not found.

UnauthorizedError

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

RateLimitTooLongError

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

InternalServerError

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

get_guild #

get_guild() -> Optional[GatewayGuild]

Return the guild linked to this channel.

RETURNS DESCRIPTION
Optional[Guild]

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

GuildForumChannel #

Bases: PermissibleGuildChannel

Represents a guild forum channel.

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

available_tags class-attribute instance-attribute #

available_tags: Sequence[ForumTag] = field(eq=False, hash=False, repr=False)

The available tags to select from when creating a thread.

created_at property #

created_at: datetime

When the object was created.

default_auto_archive_duration class-attribute instance-attribute #

default_auto_archive_duration: timedelta = field(
    eq=False, hash=False, repr=False
)

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 class-attribute instance-attribute #

default_layout: ForumLayoutType = field(eq=False, hash=False, repr=False)

The default layout for the forum.

default_reaction_emoji_id class-attribute instance-attribute #

default_reaction_emoji_id: Optional[Snowflake] = field(
    eq=False, hash=False, repr=False
)

The ID of the default reaction emoji.

default_reaction_emoji_name class-attribute instance-attribute #

default_reaction_emoji_name: Union[str, UnicodeEmoji, None] = field(
    eq=False, hash=False, repr=False
)

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 class-attribute instance-attribute #

default_sort_order: ForumSortOrderType = field(eq=False, hash=False, repr=False)

The default sort order for the forum.

default_thread_rate_limit_per_user class-attribute instance-attribute #

default_thread_rate_limit_per_user: timedelta = field(
    eq=False, hash=False, repr=False
)

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 hikari.permissions.Permissions.MANAGE_MESSAGES, hikari.permissions.Permissions.MANAGE_CHANNELS, hikari.permissions.Permissions.ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

flags class-attribute instance-attribute #

flags: ChannelFlag = field(eq=False, hash=False, repr=False)

The channel flags for this channel.

Note

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

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_nsfw class-attribute instance-attribute #

is_nsfw: bool = field(eq=False, hash=False, repr=False)

Whether the channel is marked as NSFW.

last_thread_id class-attribute instance-attribute #

last_thread_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

parent_id class-attribute instance-attribute #

parent_id: Optional[Snowflake] = field(eq=False, hash=False, repr=True)

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.

permission_overwrites class-attribute instance-attribute #

permission_overwrites: Mapping[Snowflake, PermissionOverwrite] = field(
    eq=False, hash=False, repr=False
)

The permission overwrites for the channel.

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

position class-attribute instance-attribute #

position: int = field(eq=False, hash=False, repr=False)

The sorting position of the channel.

Higher numbers appear further down the channel list.

rate_limit_per_user class-attribute instance-attribute #

rate_limit_per_user: timedelta = field(eq=False, hash=False, repr=False)

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 hikari.permissions.Permissions.MANAGE_MESSAGES, hikari.permissions.Permissions.MANAGE_CHANNELS, hikari.permissions.Permissions.ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

topic class-attribute instance-attribute #

topic: Optional[str] = field(eq=False, hash=False, repr=False)

The guidelines for the channel.

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    region: UndefinedOr[Union[VoiceRegion, str]] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Sequence[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    parent_category: UndefinedOr[
        SnowflakeishOr[GuildCategory]
    ] = undefined.UNDEFINED,
    default_auto_archive_duration: UndefinedOr[
        Intervalish
    ] = undefined.UNDEFINED,
    flags: UndefinedOr[ChannelFlag] = undefined.UNDEFINED,
    archived: UndefinedOr[bool] = undefined.UNDEFINED,
    auto_archive_duration: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    locked: UndefinedOr[bool] = undefined.UNDEFINED,
    invitable: UndefinedOr[bool] = undefined.UNDEFINED,
    applied_tags: UndefinedOr[
        SnowflakeishSequence[ForumTag]
    ] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> PartialChannel

Edit the text channel.

PARAMETER DESCRIPTION
name

If provided, the new name for the channel.

TYPE: hikari.undefined.UndefinedOr[[str]

position

If provided, the new position for the channel.

TYPE: hikari.undefined.UndefinedOr[[int]

topic

If provided, the new topic for the channel.

TYPE: UndefinedOr[str]

nsfw

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

TYPE: UndefinedOr[bool]

bitrate

If provided, the new bitrate for the channel.

TYPE: UndefinedOr[int]

video_quality_mode

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

TYPE: UndefinedOr[Union[VideoQualityMode, int]]

user_limit

If provided, the new user limit in the channel.

TYPE: UndefinedOr[int]

rate_limit_per_user

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

TYPE: UndefinedOr[Intervalish]

region

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.

TYPE: UndefinedOr[Union[VoiceRegion, str]]

permission_overwrites

If provided, the new permission overwrites for the channel.

TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

parent_category

If provided, the new guild category for the channel.

TYPE: UndefinedOr[SnowflakeishOr[GuildCategory]]

default_auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

flags

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.

TYPE: UndefinedOr[ChannelFlag]

archived

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

TYPE: UndefinedOr[bool]

auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

locked

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

If it's locked then only people with hikari.permissions.Permissions.MANAGE_THREADS can unarchive it.

TYPE: UndefinedOr[bool]

invitable

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

TYPE: UndefinedOr[bool]

applied_tags

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

TYPE: UndefinedOr[SnowflakeishSequence[ForumTag]]

reason

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

TYPE: UndefinedOr[str]

RETURNS DESCRIPTION
PartialChannel

The edited channel.

RAISES DESCRIPTION
BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing permissions to edit the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit_overwrite async #

edit_overwrite(
    target: Union[Snowflakeish, PartialUser, PartialRole, PermissionOverwrite],
    *,
    target_type: UndefinedOr[
        Union[PermissionOverwriteType, int]
    ] = undefined.UNDEFINED,
    allow: UndefinedOr[Permissions] = undefined.UNDEFINED,
    deny: UndefinedOr[Permissions] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> None

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

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

PARAMETER DESCRIPTION
target

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

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

PARAMETER DESCRIPTION
target_type

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

TYPE: UndefinedOr[Union[PermissionOverwriteType, int]]

allow

If provided, the new value of all allowed permissions.

TYPE: UndefinedOr[Permissions]

deny

If provided, the new value of all disallowed permissions.

TYPE: UndefinedOr[Permissions]

reason

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

TYPE: UndefinedOr[str]

RAISES DESCRIPTION
TypeError

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

BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_guild async #

fetch_guild() -> PartialGuild

Fetch the guild linked to this channel.

RETURNS DESCRIPTION
RESTGuild

The requested guild.

RAISES DESCRIPTION
ForbiddenError

If you are not part of the guild.

NotFoundError

If the guild is not found.

UnauthorizedError

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

RateLimitTooLongError

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

InternalServerError

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

get_guild #

get_guild() -> Optional[GatewayGuild]

Return the guild linked to this channel.

RETURNS DESCRIPTION
Optional[Guild]

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

remove_overwrite async #

remove_overwrite(
    target: Union[PermissionOverwrite, PartialRole, PartialUser, Snowflakeish]
) -> None

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

PARAMETER DESCRIPTION
target

The channel overwrite to delete.

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

GuildNewsChannel #

Bases: PermissibleGuildChannel, TextableGuildChannel

Represents an news channel.

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

created_at property #

created_at: datetime

When the object was created.

default_auto_archive_duration class-attribute instance-attribute #

default_auto_archive_duration: timedelta = field(
    eq=False, hash=False, repr=False
)

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.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_nsfw class-attribute instance-attribute #

is_nsfw: bool = field(eq=False, hash=False, repr=False)

Whether the channel is marked as NSFW.

last_message_id class-attribute instance-attribute #

last_message_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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 class-attribute instance-attribute #

last_pin_timestamp: Optional[datetime] = field(eq=False, hash=False, repr=False)

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!

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

parent_id class-attribute instance-attribute #

parent_id: Optional[Snowflake] = field(eq=False, hash=False, repr=True)

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.

permission_overwrites class-attribute instance-attribute #

permission_overwrites: Mapping[Snowflake, PermissionOverwrite] = field(
    eq=False, hash=False, repr=False
)

The permission overwrites for the channel.

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

position class-attribute instance-attribute #

position: int = field(eq=False, hash=False, repr=False)

The sorting position of the channel.

Higher numbers appear further down the channel list.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

topic class-attribute instance-attribute #

topic: Optional[str] = field(eq=False, hash=False, repr=False)

The topic of the channel.

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

delete_messages async #

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.

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

TYPE: Union[SnowflakeishOr[PartialMessage], Iterable[SnowflakeishOr[PartialMessage]], AsyncIterable[SnowflakeishOr[PartialMessage]]]

PARAMETER DESCRIPTION
*other_messages

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

TYPE: SnowflakeishOr[PartialMessage]

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    region: UndefinedOr[Union[VoiceRegion, str]] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Sequence[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    parent_category: UndefinedOr[
        SnowflakeishOr[GuildCategory]
    ] = undefined.UNDEFINED,
    default_auto_archive_duration: UndefinedOr[
        Intervalish
    ] = undefined.UNDEFINED,
    flags: UndefinedOr[ChannelFlag] = undefined.UNDEFINED,
    archived: UndefinedOr[bool] = undefined.UNDEFINED,
    auto_archive_duration: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    locked: UndefinedOr[bool] = undefined.UNDEFINED,
    invitable: UndefinedOr[bool] = undefined.UNDEFINED,
    applied_tags: UndefinedOr[
        SnowflakeishSequence[ForumTag]
    ] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> PartialChannel

Edit the text channel.

PARAMETER DESCRIPTION
name

If provided, the new name for the channel.

TYPE: hikari.undefined.UndefinedOr[[str]

position

If provided, the new position for the channel.

TYPE: hikari.undefined.UndefinedOr[[int]

topic

If provided, the new topic for the channel.

TYPE: UndefinedOr[str]

nsfw

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

TYPE: UndefinedOr[bool]

bitrate

If provided, the new bitrate for the channel.

TYPE: UndefinedOr[int]

video_quality_mode

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

TYPE: UndefinedOr[Union[VideoQualityMode, int]]

user_limit

If provided, the new user limit in the channel.

TYPE: UndefinedOr[int]

rate_limit_per_user

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

TYPE: UndefinedOr[Intervalish]

region

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.

TYPE: UndefinedOr[Union[VoiceRegion, str]]

permission_overwrites

If provided, the new permission overwrites for the channel.

TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

parent_category

If provided, the new guild category for the channel.

TYPE: UndefinedOr[SnowflakeishOr[GuildCategory]]

default_auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

flags

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.

TYPE: UndefinedOr[ChannelFlag]

archived

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

TYPE: UndefinedOr[bool]

auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

locked

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

If it's locked then only people with hikari.permissions.Permissions.MANAGE_THREADS can unarchive it.

TYPE: UndefinedOr[bool]

invitable

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

TYPE: UndefinedOr[bool]

applied_tags

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

TYPE: UndefinedOr[SnowflakeishSequence[ForumTag]]

reason

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

TYPE: UndefinedOr[str]

RETURNS DESCRIPTION
PartialChannel

The edited channel.

RAISES DESCRIPTION
BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing permissions to edit the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

edit_overwrite async #

edit_overwrite(
    target: Union[Snowflakeish, PartialUser, PartialRole, PermissionOverwrite],
    *,
    target_type: UndefinedOr[
        Union[PermissionOverwriteType, int]
    ] = undefined.UNDEFINED,
    allow: UndefinedOr[Permissions] = undefined.UNDEFINED,
    deny: UndefinedOr[Permissions] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> None

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

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

PARAMETER DESCRIPTION
target

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

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

PARAMETER DESCRIPTION
target_type

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

TYPE: UndefinedOr[Union[PermissionOverwriteType, int]]

allow

If provided, the new value of all allowed permissions.

TYPE: UndefinedOr[Permissions]

deny

If provided, the new value of all disallowed permissions.

TYPE: UndefinedOr[Permissions]

reason

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

TYPE: UndefinedOr[str]

RAISES DESCRIPTION
TypeError

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

BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_guild async #

fetch_guild() -> PartialGuild

Fetch the guild linked to this channel.

RETURNS DESCRIPTION
RESTGuild

The requested guild.

RAISES DESCRIPTION
ForbiddenError

If you are not part of the guild.

NotFoundError

If the guild is not found.

UnauthorizedError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_history #

fetch_history(
    *,
    before: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    after: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    around: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED
) -> LazyIterator[Message]

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.

PARAMETER DESCRIPTION
before

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

after

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

around

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

RETURNS DESCRIPTION
LazyIterator[Message]

A iterator to fetch the messages.

RAISES DESCRIPTION
TypeError

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

InternalServerError

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

fetch_message async #

fetch_message(message: SnowflakeishOr[PartialMessage]) -> Message

Fetch a specific message in the given text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RETURNS DESCRIPTION
Message

The requested message.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.READ_MESSAGE_HISTORY in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_pins async #

fetch_pins() -> Sequence[Message]

Fetch the pinned messages in this text channel.

RETURNS DESCRIPTION
Sequence[Message]

The pinned messages in this text channel.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the [hikari.permissions.Permissions.VIEW_CHANNEL] permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

get_guild #

get_guild() -> Optional[GatewayGuild]

Return the guild linked to this channel.

RETURNS DESCRIPTION
Optional[Guild]

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

pin_message async #

pin_message(message: SnowflakeishOr[PartialMessage]) -> None

Pin an existing message in the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

remove_overwrite async #

remove_overwrite(
    target: Union[PermissionOverwrite, PartialRole, PartialUser, Snowflakeish]
) -> None

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

PARAMETER DESCRIPTION
target

The channel overwrite to delete.

TYPE: Union[PartialUser, PartialRole, PermissionOverwrite, Snowflakeish]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the MANAGE_PERMISSIONS permission in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

send async #

send(
    content: UndefinedOr[Any] = undefined.UNDEFINED,
    *,
    attachment: UndefinedOr[Resourceish] = undefined.UNDEFINED,
    attachments: UndefinedOr[Sequence[Resourceish]] = undefined.UNDEFINED,
    component: UndefinedOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedOr[Sequence[ComponentBuilder]] = undefined.UNDEFINED,
    embed: UndefinedOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedOr[Sequence[Embed]] = undefined.UNDEFINED,
    sticker: UndefinedOr[SnowflakeishOr[PartialSticker]] = undefined.UNDEFINED,
    stickers: UndefinedOr[
        SnowflakeishSequence[PartialSticker]
    ] = undefined.UNDEFINED,
    tts: UndefinedOr[bool] = undefined.UNDEFINED,
    reply: UndefinedOr[SnowflakeishOr[PartialMessage]] = undefined.UNDEFINED,
    reply_must_exist: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_reply: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED,
    flags: Union[UndefinedType, int, MessageFlag] = undefined.UNDEFINED
) -> Message

Create a message in this channel.

PARAMETER DESCRIPTION
content

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.

TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED

PARAMETER DESCRIPTION
attachment

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.

TYPE: UndefinedOr[Resourceish]

attachments

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

TYPE: UndefinedOr[Sequence[Resourceish]]

component

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

TYPE: UndefinedOr[ComponentBuilder]

components

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

TYPE: UndefinedOr[Sequence[ComponentBuilder]]

embed

If provided, the message embed.

TYPE: UndefinedOr[Embed]

embeds

If provided, the message embeds.

TYPE: UndefinedOr[Sequence[Embed]]

sticker

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.

TYPE: UndefinedOr[SnowflakeishOr[PartialSticker]]

stickers

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.

TYPE: UndefinedOr[SnowflakeishSequence[PartialSticker]]

tts

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

TYPE: UndefinedOr[bool]

reply

If provided, the message to reply to.

TYPE: UndefinedOr[SnowflakeishOr[PartialMessage]]

reply_must_exist

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

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

TYPE: UndefinedOr[bool]

mentions_everyone

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

TYPE: UndefinedOr[bool]

mentions_reply

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.

TYPE: UndefinedOr[bool]

user_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]

role_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

flags

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 hikari.messages.MessageFlag.NONE and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

TYPE: UndefinedOr[MessageFlag]

RETURNS DESCRIPTION
Message

The created message.

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

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 #

trigger_typing() -> TypingIndicator

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 DESCRIPTION
TypingIndicator

The typing indicator object.

unpin_message async #

unpin_message(message: SnowflakeishOr[PartialMessage]) -> None

Unpin a given message from the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES permission.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

GuildNewsThread #

Bases: GuildThreadChannel

Represents a guild news channel public thread.

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

approximate_member_count class-attribute instance-attribute #

approximate_member_count: int = field(eq=False, hash=False, repr=True)

Approximate count of members in the thread channel.

Warning

This stop counting at 50.

approximate_message_count class-attribute instance-attribute #

approximate_message_count: int = field(eq=False, hash=False, repr=True)

Approximate number of messages in the thread channel.

Warning

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

archive_timestamp class-attribute instance-attribute #

archive_timestamp: datetime = field(eq=False, hash=False, repr=True)

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 class-attribute instance-attribute #

auto_archive_duration: timedelta = field(eq=False, hash=False, repr=True)

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.

created_at property #

created_at: datetime

When the object was created.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_archived class-attribute instance-attribute #

is_archived: bool = field(eq=False, hash=False, repr=True)

Whether the thread is archived.

is_locked class-attribute instance-attribute #

is_locked: bool = field(eq=False, hash=False, repr=True)

Whether the thread is locked.

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

last_message_id class-attribute instance-attribute #

last_message_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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 class-attribute instance-attribute #

last_pin_timestamp: Optional[datetime] = field(eq=False, hash=False, repr=False)

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 class-attribute instance-attribute #

member: Optional[ThreadMember] = field(eq=False, hash=False, repr=True)

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.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

owner_id class-attribute instance-attribute #

owner_id: Snowflake = field(eq=False, hash=False, repr=True)

ID of the user who created this thread.

parent_id class-attribute instance-attribute #

parent_id: Snowflake = field(eq=False, hash=False, repr=True)

Id of this thread's textable parent channel.

rate_limit_per_user class-attribute instance-attribute #

rate_limit_per_user: timedelta = field(eq=False, hash=False, repr=False)

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 hikari.permissions.Permissions.MANAGE_MESSAGES, hikari.permissions.Permissions.MANAGE_CHANNELS, hikari.permissions.Permissions.ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

thread_created_at class-attribute instance-attribute #

thread_created_at: Optional[datetime] = field(eq=False, hash=False, repr=True)

When the thread was created.

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

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

delete_messages async #

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.

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

TYPE: Union[SnowflakeishOr[PartialMessage], Iterable[SnowflakeishOr[PartialMessage]], AsyncIterable[SnowflakeishOr[PartialMessage]]]

PARAMETER DESCRIPTION
*other_messages

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

TYPE: SnowflakeishOr[PartialMessage]

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    region: UndefinedOr[Union[VoiceRegion, str]] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Sequence[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    parent_category: UndefinedOr[
        SnowflakeishOr[GuildCategory]
    ] = undefined.UNDEFINED,
    default_auto_archive_duration: UndefinedOr[
        Intervalish
    ] = undefined.UNDEFINED,
    flags: UndefinedOr[ChannelFlag] = undefined.UNDEFINED,
    archived: UndefinedOr[bool] = undefined.UNDEFINED,
    auto_archive_duration: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    locked: UndefinedOr[bool] = undefined.UNDEFINED,
    invitable: UndefinedOr[bool] = undefined.UNDEFINED,
    applied_tags: UndefinedOr[
        SnowflakeishSequence[ForumTag]
    ] = undefined.UNDEFINED,
    reason: UndefinedOr[str] = undefined.UNDEFINED
) -> PartialChannel

Edit the text channel.

PARAMETER DESCRIPTION
name

If provided, the new name for the channel.

TYPE: hikari.undefined.UndefinedOr[[str]

position

If provided, the new position for the channel.

TYPE: hikari.undefined.UndefinedOr[[int]

topic

If provided, the new topic for the channel.

TYPE: UndefinedOr[str]

nsfw

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

TYPE: UndefinedOr[bool]

bitrate

If provided, the new bitrate for the channel.

TYPE: UndefinedOr[int]

video_quality_mode

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

TYPE: UndefinedOr[Union[VideoQualityMode, int]]

user_limit

If provided, the new user limit in the channel.

TYPE: UndefinedOr[int]

rate_limit_per_user

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

TYPE: UndefinedOr[Intervalish]

region

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.

TYPE: UndefinedOr[Union[VoiceRegion, str]]

permission_overwrites

If provided, the new permission overwrites for the channel.

TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

parent_category

If provided, the new guild category for the channel.

TYPE: UndefinedOr[SnowflakeishOr[GuildCategory]]

default_auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

flags

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.

TYPE: UndefinedOr[ChannelFlag]

archived

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

TYPE: UndefinedOr[bool]

auto_archive_duration

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.

TYPE: UndefinedOr[Intervalish]

locked

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

If it's locked then only people with hikari.permissions.Permissions.MANAGE_THREADS can unarchive it.

TYPE: UndefinedOr[bool]

invitable

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

TYPE: UndefinedOr[bool]

applied_tags

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

TYPE: UndefinedOr[SnowflakeishSequence[ForumTag]]

reason

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

TYPE: UndefinedOr[str]

RETURNS DESCRIPTION
PartialChannel

The edited channel.

RAISES DESCRIPTION
BadRequestError

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

UnauthorizedError

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

ForbiddenError

If you are missing permissions to edit the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

fetch_guild async #

fetch_guild() -> PartialGuild

Fetch the guild linked to this channel.

RETURNS DESCRIPTION
RESTGuild

The requested guild.

RAISES DESCRIPTION
ForbiddenError

If you are not part of the guild.

NotFoundError

If the guild is not found.

UnauthorizedError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_history #

fetch_history(
    *,
    before: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    after: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED,
    around: UndefinedOr[SearchableSnowflakeishOr[Unique]] = undefined.UNDEFINED
) -> LazyIterator[Message]

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.

PARAMETER DESCRIPTION
before

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

after

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

around

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.

TYPE: UndefinedOr[SearchableSnowflakeishOr[Unique]]

RETURNS DESCRIPTION
LazyIterator[Message]

A iterator to fetch the messages.

RAISES DESCRIPTION
TypeError

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

InternalServerError

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

fetch_message async #

fetch_message(message: SnowflakeishOr[PartialMessage]) -> Message

Fetch a specific message in the given text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RETURNS DESCRIPTION
Message

The requested message.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.READ_MESSAGE_HISTORY in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

fetch_pins async #

fetch_pins() -> Sequence[Message]

Fetch the pinned messages in this text channel.

RETURNS DESCRIPTION
Sequence[Message]

The pinned messages in this text channel.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the [hikari.permissions.Permissions.VIEW_CHANNEL] permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

get_guild #

get_guild() -> Optional[GatewayGuild]

Return the guild linked to this channel.

RETURNS DESCRIPTION
Optional[Guild]

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

pin_message async #

pin_message(message: SnowflakeishOr[PartialMessage]) -> None

Pin an existing message in the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES in the channel.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

send async #

send(
    content: UndefinedOr[Any] = undefined.UNDEFINED,
    *,
    attachment: UndefinedOr[Resourceish] = undefined.UNDEFINED,
    attachments: UndefinedOr[Sequence[Resourceish]] = undefined.UNDEFINED,
    component: UndefinedOr[ComponentBuilder] = undefined.UNDEFINED,
    components: UndefinedOr[Sequence[ComponentBuilder]] = undefined.UNDEFINED,
    embed: UndefinedOr[Embed] = undefined.UNDEFINED,
    embeds: UndefinedOr[Sequence[Embed]] = undefined.UNDEFINED,
    sticker: UndefinedOr[SnowflakeishOr[PartialSticker]] = undefined.UNDEFINED,
    stickers: UndefinedOr[
        SnowflakeishSequence[PartialSticker]
    ] = undefined.UNDEFINED,
    tts: UndefinedOr[bool] = undefined.UNDEFINED,
    reply: UndefinedOr[SnowflakeishOr[PartialMessage]] = undefined.UNDEFINED,
    reply_must_exist: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_everyone: UndefinedOr[bool] = undefined.UNDEFINED,
    mentions_reply: UndefinedOr[bool] = undefined.UNDEFINED,
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED,
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED,
    flags: Union[UndefinedType, int, MessageFlag] = undefined.UNDEFINED
) -> Message

Create a message in this channel.

PARAMETER DESCRIPTION
content

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.

TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED

PARAMETER DESCRIPTION
attachment

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.

TYPE: UndefinedOr[Resourceish]

attachments

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

TYPE: UndefinedOr[Sequence[Resourceish]]

component

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

TYPE: UndefinedOr[ComponentBuilder]

components

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

TYPE: UndefinedOr[Sequence[ComponentBuilder]]

embed

If provided, the message embed.

TYPE: UndefinedOr[Embed]

embeds

If provided, the message embeds.

TYPE: UndefinedOr[Sequence[Embed]]

sticker

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.

TYPE: UndefinedOr[SnowflakeishOr[PartialSticker]]

stickers

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.

TYPE: UndefinedOr[SnowflakeishSequence[PartialSticker]]

tts

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

TYPE: UndefinedOr[bool]

reply

If provided, the message to reply to.

TYPE: UndefinedOr[SnowflakeishOr[PartialMessage]]

reply_must_exist

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

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

TYPE: UndefinedOr[bool]

mentions_everyone

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

TYPE: UndefinedOr[bool]

mentions_reply

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.

TYPE: UndefinedOr[bool]

user_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]

role_mentions

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.

TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

flags

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 hikari.messages.MessageFlag.NONE and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

TYPE: UndefinedOr[MessageFlag]

RETURNS DESCRIPTION
Message

The created message.

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

UnauthorizedError

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

ForbiddenError

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

NotFoundError

If the channel is not found.

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 #

trigger_typing() -> TypingIndicator

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 DESCRIPTION
TypingIndicator

The typing indicator object.

unpin_message async #

unpin_message(message: SnowflakeishOr[PartialMessage]) -> None

Unpin a given message from the text channel.

PARAMETER DESCRIPTION
message

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

TYPE: SnowflakeishOr[PartialMessage]

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_MESSAGES permission.

NotFoundError

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

RateLimitTooLongError

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

InternalServerError

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

GuildPrivateThread #

Bases: GuildThreadChannel

Represents a guild private thread.

app class-attribute instance-attribute #

app: RESTAware = field(
    repr=False, eq=False, hash=False, metadata={SKIP_DEEP_COPY: True}
)

Client application that models may use for procedures.

approximate_member_count class-attribute instance-attribute #

approximate_member_count: int = field(eq=False, hash=False, repr=True)

Approximate count of members in the thread channel.

Warning

This stop counting at 50.

approximate_message_count class-attribute instance-attribute #

approximate_message_count: int = field(eq=False, hash=False, repr=True)

Approximate number of messages in the thread channel.

Warning

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

archive_timestamp class-attribute instance-attribute #

archive_timestamp: datetime = field(eq=False, hash=False, repr=True)

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 class-attribute instance-attribute #

auto_archive_duration: timedelta = field(eq=False, hash=False, repr=True)

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.

created_at property #

created_at: datetime

When the object was created.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field(eq=False, hash=False, repr=True)

The ID of the guild the channel belongs to.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

The ID of this entity.

is_archived class-attribute instance-attribute #

is_archived: bool = field(eq=False, hash=False, repr=True)

Whether the thread is archived.

is_invitable class-attribute instance-attribute #

is_invitable: bool = field(eq=False, hash=False, repr=True)

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

is_locked class-attribute instance-attribute #

is_locked: bool = field(eq=False, hash=False, repr=True)

Whether the thread is locked.

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

last_message_id class-attribute instance-attribute #

last_message_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

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 class-attribute instance-attribute #

last_pin_timestamp: Optional[datetime] = field(eq=False, hash=False, repr=False)

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 class-attribute instance-attribute #

member: Optional[ThreadMember] = field(eq=False, hash=False, repr=True)

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.

mention property #

mention: str

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

The mention string to use.

name class-attribute instance-attribute #

name: Optional[str] = field(eq=False, hash=False, repr=True)

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

owner_id class-attribute instance-attribute #

owner_id: Snowflake = field(eq=False, hash=False, repr=True)

ID of the user who created this thread.

parent_id class-attribute instance-attribute #

parent_id: Snowflake = field(eq=False, hash=False, repr=True)

Id of this thread's textable parent channel.

rate_limit_per_user class-attribute instance-attribute #

rate_limit_per_user: timedelta = field(eq=False, hash=False, repr=False)

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 hikari.permissions.Permissions.MANAGE_MESSAGES, hikari.permissions.Permissions.MANAGE_CHANNELS, hikari.permissions.Permissions.ADMINISTRATOR will not be limited. Likewise, bots will not be affected by this rate limit.

shard_id property #

shard_id: Optional[int]

Return the shard ID for the shard.

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

thread_created_at class-attribute instance-attribute #

thread_created_at: Optional[datetime] = field(eq=False, hash=False, repr=True)

When the thread was created.

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

type class-attribute instance-attribute #

type: Union[ChannelType, int] = field(eq=False, hash=False, repr=True)

The channel's type.

delete async #

delete() -> PartialChannel

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 DESCRIPTION
PartialChannel

Object of the channel that was deleted.

RAISES DESCRIPTION
UnauthorizedError

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

ForbiddenError

If you are missing the hikari.permissions.Permissions.MANAGE_CHANNELS permission in the channel.

NotFoundError

If the channel is not found.

RateLimitTooLongError

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

InternalServerError

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

delete_messages async #

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.

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

TYPE: Union[SnowflakeishOr[PartialMessage], Iterable[SnowflakeishOr[PartialMessage]], AsyncIterable[SnowflakeishOr[PartialMessage]]]

PARAMETER DESCRIPTION
*other_messages

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

TYPE: SnowflakeishOr[PartialMessage]

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    user_limit: UndefinedOr[