Channels ¶

permissions_for(_target, /)[source]¶

Calculate permissions for given user.

By default, this returns no permissions.

Parameters:: target (Union[User, Member]) – The member or user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

PartialChannel¶

Attributes

active
category_id
default_permissions
description
icon
id
internal_icon
last_message_id
mention
name
nsfw
owner_id
permissions
raw_permissions
role_permissions
state
voice

Methods

async close
async edit
def message
def permissions_for

class stoat.PartialChannel(*, state, id, name, owner_id, description, internal_icon, nsfw, active, raw_permissions, role_permissions, default_permissions, last_message_id, category_id, voice)[source]¶

Represents a partial channel on Stoat.

This inherits from BaseChannel.

name¶

The new channel name, if applicable. Only for GroupChannel and BaseServerChannel’s.

Type:: UndefinedOr[str]

owner_id¶

The ID of new group owner, if applicable. Only for GroupChannel.

Type:: UndefinedOr[str]

description¶

The new channel’s description, if applicable. Only for GroupChannel and BaseServerChannel’s.

Type:: UndefinedOr[Optional[str]]

internal_icon¶

The new channel’s stateless icon, if applicable. Only for GroupChannel and BaseServerChannel’s.

Type:: UndefinedOr[Optional[StatelessAsset]]

nsfw¶

Whether the channel have been marked as NSFW, if applicable. Only for GroupChannel and BaseServerChannel’s.

Type:: UndefinedOr[bool]

active¶

Whether the DM channel is active now, if applicable. Only for DMChannel’s.

Type:: UndefinedOr[bool]

raw_permissions¶

The new channel’s permissions raw value, if applicable. Only for GroupChannel’s.

Type:: UndefinedOr[int]

role_permissions¶

The new channel’s permission overrides for roles, if applicable. Only for BaseServerChannel’s.

Type:: UndefinedOr[Dict[str, PermissionOverride]]

default_permissions¶

The new channel’s permission overrides for everyone, if applicable. Only for BaseServerChannel’s.

Type:: UndefinedOr[Optional[PermissionOverride]]

last_message_id¶

The last message ID sent in the channel.

Type:: UndefinedOr[str]

category_id¶

The new category ID the channel is in.

Added in version 1.2.

Type:: UndefinedOr[str]

voice¶

The new voice-specific metadata for this channel.

Added in version 1.2.

Type:: UndefinedOr[ChannelVoiceMetadata]

property icon[source]¶

The new channel’s icon, if applicable. Only for GroupChannel and BaseServerChannel's.

Type:: UndefinedOr[Optional[Asset]]

property permissions[source]¶

The new channel’s permissions, if applicable. Only for GroupChannel's.

Type:: UndefinedOr[Permissions]

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

id¶

The ID of the entity.

Type:: str

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

permissions_for(_target, /)[source]¶

Calculate permissions for given user.

By default, this returns no permissions.

Parameters:: target (Union[User, Member]) – The member or user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

state¶

The state that controls this entity.

Type:: State

SavedMessagesChannel¶

Attributes

id
me
mention
messages
server
state
type
user_id

Methods

async acknowledge
async begin_typing
async close
async edit
async end_typing
async fetch_channel_id
async fetch_message
def get_channel_id
def get_me
def get_message
async history
def locally_update
def message
def permissions_for
async search
async send
def to_dict
def typing

class stoat.SavedMessagesChannel(*, state, id, user_id)[source]¶

Represents a personal “Saved Notes” channel which allows users to save messages.

This inherits from BaseChannel and Messageable.

user_id¶

The ID of the user this channel belongs to.

Type:: str

get_channel_id()[source]¶: str: Retrieves the channel’s ID, if possible.

get_me()[source]¶: Optional[User]: The own user.

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

property me[source]¶

The own user.

Type:: User

property server[source]¶

The server this channel belongs to.

Type:: Optional[Server]

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.saved_messages]

permissions_for(target, /)[source]¶

Calculate permissions for given member.

Parameters:: target (Union[User, Member]) – The user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

to_dict()[source]¶: dict: Convert channel to raw data.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

message (ULIDOr[BaseMessage]) – The message to mark as read.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

await begin_typing(*, http_overrides=None)[source]¶: Begins typing in channel, until end_typing() is called.

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await end_typing(*, http_overrides=None)[source]¶: Ends typing in channel.

await fetch_channel_id(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The channel’s ID.
Return type:: str

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves a message.

Parameters:

message (ULIDOr[BaseMessage]) – The message to retrieve.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/message was not found.
InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

get_message(message_id, /)[source]¶

Retrieves a channel message from cache.

Parameters:: message_id (str) – The message ID.
Returns:: The message or None if not found.
Return type:: Optional[Message]

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]¶

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to read the message history.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

id¶

The ID of the entity.

Type:: str

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]¶

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

query (Optional[str]) – The full-text search query. See MongoDB documentation for more information.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

HTTPException – Possible values for type:

Value	Reason
`FailedValidation`	One of `before`, `after` or `nearby` parameters were invalid IDs.
`InvalidOperation`	You provided both `query` and `pinned` parameters.
`IsBot`	The current token belongs to bot account.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to search messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages matched.

Return type:

List[Message]

await send(content=None, *, channel_http_overrides=None, http_overrides=None, nonce=None, attachments=None, replies=None, embeds=None, masquerade=None, interactions=None, silent=None, mention_everyone=None, mention_online=None)[source]¶

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

content (Optional[str]) – The message content.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

You must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

You must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The message masquerade.

You must have use_masquerade to provide this.

If color is provided, use_masquerade is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) –
Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

Note

User accounts cannot set this to True.
mention_online (Optional[bool]) –
Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Note

User accounts cannot set this to True.

Raises:

stoat.HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `reactions` elements was invalid.
`InvalidProperty`	`restrict_reactions` was `True` but `reactions` was empty.
`IsBot`	The current token belongs to bot account.
`IsNotBot`	The current token belongs to user account.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply was not found.
stoat.InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

state¶

The state that controls this entity.

Type:: State

typing()[source]¶: Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

DMChannel¶

Attributes

active
id
initiator_id
last_message
last_message_id
me
mention
messages
read_state
recipient
recipient_id
recipient_ids
server
state
type

Methods

async acknowledge
async begin_typing
async close
async connect
async edit
async end_typing
async fetch_channel_id
async fetch_message
def get_channel_id
def get_initiator
def get_last_message
def get_me
def get_message
def get_read_state
def get_recipient
def get_recipients
async history
async join_call
def locally_update
def message
def permissions_for
async search
async send
def to_dict
def typing

class stoat.DMChannel(*, state, id, active, recipient_ids, last_message_id)[source]¶

Represents a private channel between two users.

This inherits from BaseChannel, Connectable and Messageable.

active¶

Whether the DM channel is currently open on both sides.

Type:: bool

recipient_ids¶

The tuple of user IDs participating in DM.

Type:: Tuple[str, str]

last_message_id¶

The last message ID sent in the channel.

Type:: Optional[str]

get_channel_id()[source]¶: str: Retrieves the channel’s ID, if possible.

get_initiator()[source]¶: Optional[User]: The user that initiated this PM.

get_last_message()[source]¶: Optional[Message]: The last message sent in the channel.

get_me()[source]¶: Optional[User]: The own user.

get_read_state(*, default_acked_message_id=None, create_if_not_exists=True)[source]¶

Optional[ReadState]: Returns the channel’s read state.

Parameters:

default_acked_message_id (Optional[str]) – The default acked message ID to use if read state is not found.
create_if_not_exists (bool) – Whether to create a read state and store it if existing was not found.

get_recipient()[source]¶: Optional[User]: The recipient.

get_recipients()[source]¶: Tuple[Optional[User], Optional[User]]: The recipient.

property initiator_id[source]¶

The user’s ID that started this PM.

Type:: str

property last_message[source]¶

The last message sent in the channel.

Type:: Optional[Message]

property me[source]¶

The own user.

Type:: User

property read_state[source]¶

Returns the channel’s read state.

Type:: ReadState

property recipient[source]¶

The recipient.

Type:: User

property recipient_id[source]¶

The recipient’s ID.

Type:: str

property server[source]¶

The server this channel belongs to.

Type:: Optional[Server]

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.private]

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

permissions_for(target, /)[source]¶

Calculate permissions for given user.

Parameters:: target (Union[User, Member]) – The member or user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

to_dict()[source]¶: dict: Convert channel to raw data.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

message (ULIDOr[BaseMessage]) – The message to mark as read.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

await begin_typing(*, http_overrides=None)[source]¶: Begins typing in channel, until end_typing() is called.

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)[source]¶

Connects to a destination voice channel and returns a Room associated with destination.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (Optional[str]) –
The node’s name to use for starting a call.

If None, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.
TypeError – If livekit dependency is not installed.

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await end_typing(*, http_overrides=None)[source]¶: Ends typing in channel.

await fetch_channel_id(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The channel’s ID.
Return type:: str

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves a message.

Parameters:

message (ULIDOr[BaseMessage]) – The message to retrieve.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/message was not found.
InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

get_message(message_id, /)[source]¶

Retrieves a channel message from cache.

Parameters:: message_id (str) – The message ID.
Returns:: The message or None if not found.
Return type:: Optional[Message]

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]¶

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to read the message history.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

id¶

The ID of the entity.

Type:: str

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)[source]¶

This function is a coroutine.

Asks the voice server for a token to join the call in destination channel.

You must have connect to do this.

For Livekit instances, fires MessageCreateEvent and VoiceChannelJoinEvent / VoiceChannelMoveEvent for all users who can see target channel.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (UndefinedOr[Optional[str]]) –
The node’s name to use for starting a call.

If None or UNDEFINED, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.
force_disconnect (UndefinedOr[Optional[bool]]) –
Whether to force disconnect any other existing voice connections. Useful for disconnecting on another device and joining on a new.

Added in version 1.2.
recipients (UndefinedOr[Optional[List[ULIDOr[BaseUser]]]]) –
A list of users which should be notified of the call starting. Only used when the user is the first one connected.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.

Returns:

The token for authenticating with the voice server, and node WebSocket URL (can be empty if instance does not use Livekit).

Return type:

Tuple[str, str]

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]¶

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

query (Optional[str]) –
The full-text search query. See MongoDB documentation for more information.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

HTTPException – Possible values for type:

Value	Reason
`FailedValidation`	One of `before`, `after` or `nearby` parameters were invalid IDs.
`InvalidOperation`	You provided both `query` and `pinned` parameters.
`IsBot`	The current token belongs to bot account.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to search messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages matched.

Return type:

List[Message]

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

content (Optional[str]) – The message content.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

You must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

You must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The message masquerade.

You must have use_masquerade to provide this.

If color is provided, use_masquerade is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) –
Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

Note

User accounts cannot set this to True.
mention_online (Optional[bool]) –
Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Note

User accounts cannot set this to True.

Raises:

stoat.HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `reactions` elements was invalid.
`InvalidProperty`	`restrict_reactions` was `True` but `reactions` was empty.
`IsBot`	The current token belongs to bot account.
`IsNotBot`	The current token belongs to user account.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply was not found.
stoat.InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

state¶

The state that controls this entity.

Type:: State

typing()[source]¶: Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

GroupChannel¶

Methods

async acknowledge
async add
async add_bot
async begin_typing
async close
async connect
async create_invite
async create_webhook
async edit
async end_typing
async fetch_channel_id
async fetch_message
async fetch_recipients
def get_channel_id
def get_last_message
def get_me
def get_message
def get_owner
def get_read_state
async history
async join_call
async leave
def locally_update
def message
def permissions_for
async search
async send
async set_default_permissions
def to_dict
def typing

class stoat.GroupChannel(*, state, id, name, owner_id, description, internal_recipients, internal_icon, last_message_id, raw_permissions, nsfw)[source]¶

Represesnts a Stoat group channel between 1 or more participants.

This inherits from BaseChannel, Connectable and Messageable.

name¶

The group’s name.

Type:: str

owner_id¶

The user’s ID who owns this group.

Type:: str

description¶

The group description.

Type:: Optional[str]

internal_icon¶

The stateless group icon.

Type:: Optional[StatelessAsset]

last_message_id¶

The last message ID sent in the channel.

Type:: Optional[str]

raw_permissions¶

The permissions assigned to members of this group.

Note

This attribute does not apply to the owner of the group.

Type:: Optional[int]

nsfw¶

Whether this group is marked as not safe for work.

Type:: bool

get_channel_id()[source]¶: str: Retrieves the channel’s ID, if possible.

get_last_message()[source]¶: Optional[Message]: The last message sent in the channel.

get_me()[source]¶: Optional[User]: The own user.

get_owner()[source]¶: Optional[User]: The user who owns this group.

get_read_state(*, default_acked_message_id=None, create_if_not_exists=True)[source]¶

Optional[ReadState]: Returns the channel’s read state.

Parameters:

default_acked_message_id (Optional[str]) – The default acked message ID to use if read state is not found.
create_if_not_exists (bool) – Whether to create a read state and store it if existing was not found.

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

property icon[source]¶

The group icon.

Type:: Optional[Asset]

property last_message[source]¶

The last message sent in the channel.

Type:: Optional[Message]

property me[source]¶

The own user.

Type:: User

property owner[source]¶

The user who owns this group.

Type:: User

property permissions[source]¶

The permissions assigned to members of this group.

Note

This attribute does not apply to the owner of the group.

Type:: Optional[Permissions]

property read_state[source]¶

Returns the channel’s read state.

Type:: ReadState

property recipient_ids[source]¶

The IDs of users participating in channel.

Type:: List[str]

property recipients[source]¶

The users participating in channel.

Type:: List[User]

property server[source]¶

The server this channel belongs to.

Type:: Optional[Server]

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.group]

await add(user, *, http_overrides=None)[source]¶

This function is a coroutine.

Adds another user to the group.

You must have create_invites to do this.

Fires PrivateChannelCreateEvent for added recipient, and GroupRecipientAddEvent for rest of group recipients.

Note

This can only be used by non-bot accounts.

Parameters:

user (ULIDOr[BaseUser]) – The user to add.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`GroupTooLarge`	The group exceeded maximum count of recipients.
`MissingPermission`	You do not have the proper permissions to add the recipient.
`NotFriends`	You’re not friends with the user you want to add.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel or user were not found.
Conflict – Possible values for type:

Value

Reason

AlreadyInGroup

The user is already in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await add_bot(bot, *, http_overrides=None)[source]¶

This function is a coroutine.

Invites a bot to a group.

You must have create_invites to do this.

Fires PrivateChannelCreateEvent for bot, GroupRecipientAddEvent and MessageCreateEvent for all group recipients.

Note

This can only be used by non-bot accounts.

Parameters:

bot (ULIDOr[Union[BaseBot, BaseUser]]) – The bot.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Forbidden – Possible values for type:

Value

Reason

BotIsPrivate

You do not own the bot to add it.

GroupTooLarge

The group exceeded maximum count of recipients.

MissingPermission

You do not have the proper permissions to add bots.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot/group/server was not found.
Conflict – Possible values for type:

Value

Reason

AlreadyInGroup

The bot is already in group.

AlreadyInServer

The bot is already in server.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation
TypeError – You specified server and group parameters, or passed no parameters.

await create_invite(*, http_overrides=None)[source]¶

This function is a coroutine.

Creates an invite to group channel.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group or server channel.

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create invites in channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The invite that was created.

Return type:

await create_webhook(*, http_overrides=None, name, avatar=None)[source]¶

This function is a coroutine.

Creates a webhook which 3rd party platforms can use to send.

You must have manage_webhooks permission to do this.

Fires WebhookCreateEvent for all users who can see target channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (str) – The webhook name. Must be between 1 and 32 chars long.
avatar (Optional[ResolvableResource]) – The webhook avatar.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The channel was not type of group or text.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create a webhook.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The created webhook.

Return type:

Webhook

await fetch_recipients(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves all recipients who are part of this group.

Added in version 1.2.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The group recipients.

Return type:

List[User]

await leave(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Leaves a group or closes a group.

You must have view_channel to do this.

Fires PrivateChannelDeleteEvent for all group recipients (including group owner) if the current user is group owner, otherwise PrivateChannelDeleteEvent is fired for the current user, and GroupRecipientRemoveEvent is fired for rest of group recipients.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await set_default_permissions(permissions, *, http_overrides=None)[source]¶

This function is a coroutine.

Sets default permissions for everyone in a channel.

You must have manage_permissions to do this.

Fires ChannelUpdateEvent for all group recipients.

Parameters:

permissions (Permissions) – The new permissions.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`MissingPermission`	You do not have the proper permissions to edit default permissions for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated group with new permissions.

Return type:

GroupChannel

permissions_for(target, /)[source]¶

Calculate permissions for given user.

Parameters:: target (Union[User, Member]) – The member or user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

to_dict()[source]¶: dict: Convert channel to raw data.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

message (ULIDOr[BaseMessage]) – The message to mark as read.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

await begin_typing(*, http_overrides=None)[source]¶: Begins typing in channel, until end_typing() is called.

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)[source]¶

Connects to a destination voice channel and returns a Room associated with destination.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (Optional[str]) –
The node’s name to use for starting a call.

If None, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.
TypeError – If livekit dependency is not installed.

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await end_typing(*, http_overrides=None)[source]¶: Ends typing in channel.

await fetch_channel_id(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The channel’s ID.
Return type:: str

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves a message.

Parameters:

message (ULIDOr[BaseMessage]) – The message to retrieve.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/message was not found.
InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

get_message(message_id, /)[source]¶

Retrieves a channel message from cache.

Parameters:: message_id (str) – The message ID.
Returns:: The message or None if not found.
Return type:: Optional[Message]

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]¶

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to read the message history.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

id¶

The ID of the entity.

Type:: str

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)[source]¶

This function is a coroutine.

Asks the voice server for a token to join the call in destination channel.

You must have connect to do this.

For Livekit instances, fires MessageCreateEvent and VoiceChannelJoinEvent / VoiceChannelMoveEvent for all users who can see target channel.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (UndefinedOr[Optional[str]]) –
The node’s name to use for starting a call.

If None or UNDEFINED, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.
force_disconnect (UndefinedOr[Optional[bool]]) –
Whether to force disconnect any other existing voice connections. Useful for disconnecting on another device and joining on a new.

Added in version 1.2.
recipients (UndefinedOr[Optional[List[ULIDOr[BaseUser]]]]) –
A list of users which should be notified of the call starting. Only used when the user is the first one connected.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.

Returns:

The token for authenticating with the voice server, and node WebSocket URL (can be empty if instance does not use Livekit).

Return type:

Tuple[str, str]

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]¶

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

query (Optional[str]) –
The full-text search query. See MongoDB documentation for more information.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

HTTPException – Possible values for type:

Value	Reason
`FailedValidation`	One of `before`, `after` or `nearby` parameters were invalid IDs.
`InvalidOperation`	You provided both `query` and `pinned` parameters.
`IsBot`	The current token belongs to bot account.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to search messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages matched.

Return type:

List[Message]

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

content (Optional[str]) – The message content.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

You must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

You must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The message masquerade.

You must have use_masquerade to provide this.

If color is provided, use_masquerade is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) –
Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

Note

User accounts cannot set this to True.
mention_online (Optional[bool]) –
Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Note

User accounts cannot set this to True.

Raises:

stoat.HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `reactions` elements was invalid.
`InvalidProperty`	`restrict_reactions` was `True` but `reactions` was empty.
`IsBot`	The current token belongs to bot account.
`IsNotBot`	The current token belongs to user account.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply was not found.
stoat.InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

state¶

The state that controls this entity.

Type:: State

typing()[source]¶: Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

UnknownPrivateChannel¶

Attributes

id
me
mention
payload
server
state
type

Methods

async close
async edit
def get_me
def message
def permissions_for
def to_dict

class stoat.UnknownPrivateChannel(*, state, id, payload)[source]¶

Represents a private channel that is not recognized by library yet.

This inherits from BaseChannel.

payload¶

The raw channel data.

Type:: Dict[str, Any]

get_me()[source]¶: Optional[User]: The own user.

property me[source]¶

The own user.

Type:: User

property server[source]¶

The server this channel belongs to.

Type:: Optional[Server]

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.unknown]

to_dict()[source]¶: dict: Convert channel to raw data.

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

id¶

The ID of the entity.

Type:: str

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

permissions_for(_target, /)[source]¶

Calculate permissions for given user.

By default, this returns no permissions.

Parameters:: target (Union[User, Member]) – The member or user to calculate permissions for.
Returns:: The calculated permissions.
Return type:: Permissions

state¶

The state that controls this entity.

Type:: State

BaseServerChannel¶

Attributes

category
category_id
default_permissions
description
icon
id
internal_icon
me
mention
name
nsfw
role_permissions
server
server_id
state

Methods

async close
async create_invite
async delete
async edit
async fetch_webhooks
def get_category
def get_me
def get_server
def locally_update
def message
def permissions_for
async set_default_permissions
async set_role_permissions

class stoat.BaseServerChannel(*, state, id, server_id, name, description, internal_icon, default_permissions, role_permissions, category_id, nsfw)[source]¶

A base class for server channels.

This inherits from BaseChannel.

server_id¶

The server ID that channel belongs to.

Type:: str

name¶

The display name of the channel.

Type:: str

description¶

The channel description.

Type:: Optional[str]

internal_icon¶

The stateless custom channel icon.

Type:: Optional[StatelessAsset]

default_permissions¶

Default permissions assigned to users in this channel.

Type:: Optional[PermissionOverride]

role_permissions¶

The permissions assigned based on role to this channel.

Type:: Dict[str, PermissionOverride]

category_id¶

The category ID the channel is in.

Added in version 1.2.

Type:: Optional[str]

nsfw¶

Whether this channel is marked as not safe for work.

Type:: bool

get_category()[source]¶: Optional[Category]: The category the channel is in.

Added in version 1.2.

get_me()[source]¶: Optional[Member]: The own user for this server.

get_server()[source]¶: Optional[Server]: The server this channel belongs to.

property category[source]¶

The category the channel is in.

Type:: Optional[Category]

property icon[source]¶

The custom channel icon.

Type:: Optional[Asset]

property me[source]¶

The own user for this server.

Type:: Optional[Member]

property server[source]¶

The server this channel belongs to.

Type:: Server

await create_invite(*, http_overrides=None)[source]¶

This function is a coroutine.

Creates an invite to server channel.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group or server channel.

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create invites in channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The invite that was created.

Return type:

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes a server channel.

You must have view_channel and manage_channels to do this.

For server channels, ServerChannelDeleteEvent is fired for all users who could see target channel, and ServerUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await fetch_webhooks(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves all webhooks in a channel.

You must have manage_webhooks permission to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view webhooks that belong to this channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The webhooks for this channel.

Return type:

List[Webhook]

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for the specified role in a channel.

You must have manage_permissions to do this.

Fires ChannelUpdateEvent for all users who still see target channel, ServerChannelCreateEvent for all users who now can see target channel, and ChannelDeleteEvent for users who no longer can see target channel.

Parameters:

role (ULIDOr[BaseRole]) – The role.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow for role in channel.
deny (Permissions) – The permissions to deny for role in channel.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit overrides for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel/server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

await set_default_permissions(permissions, *, http_overrides=None)[source]¶

This function is a coroutine.

Sets default permissions for everyone in a channel.

You must have manage_permissions to do this.

Fires ChannelUpdateEvent for all users who still see target channel, ServerChannelCreateEvent for all users who now can see target channel, and ChannelDeleteEvent is fired for users who no longer can see target channel.

Parameters:

permissions (PermissionOverride) – The new permissions.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`MissingPermission`	You do not have the proper permissions to edit default permissions for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

permissions_for(target, /, *, safe=True, with_ownership=True, include_timeout=True)[source]¶

Calculate permissions for given user.

Parameters:

target (Union[User, Member]) – The member or user to calculate permissions for.
safe (bool) – Whether to raise exception or not if role is missing in cache.
with_ownership (bool) – Whether to account for ownership.
include_timeout (bool) – Whether to account for timeout.

Raises:

NoData – The server or role is not found in cache.

Returns:

The calculated permissions.

Return type:

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

id¶

The ID of the entity.

Type:: str

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

state¶

The state that controls this entity.

Type:: State

ChannelVoiceMetadata¶

Attributes

max_users

Methods

def to_dict

class stoat.ChannelVoiceMetadata(max_users=0)[source]¶

Represents some voice-specific metadata for text channel.

max_users¶

The maximium amount of users allowed in the voice channel at once.

Zero means an infinite amount of users can connect to voice channel.

Type:: int

Parameters:

max_users (int) –

The maximium amount of users allowed in the voice channel at once.

Zero means an infinite amount of users can connect to voice channel.

Must be greater than 1.

to_dict()[source]¶: dict: Convert channel voice state container to raw data.

TextChannel¶

Methods

async acknowledge
async begin_typing
async close
async connect
async create_invite
async create_webhook
async delete
async edit
async end_typing
async fetch_channel_id
async fetch_message
async fetch_webhooks
def get_category
def get_channel_id
def get_last_message
def get_me
def get_message
def get_read_state
def get_server
async history
async join_call
def locally_update
def message
def permissions_for
async search
async send
async set_default_permissions
async set_role_permissions
def to_dict
def typing

class stoat.TextChannel(*, state, id, server_id, name, description, internal_icon, default_permissions, role_permissions, category_id, nsfw, last_message_id, voice)[source]¶

Represents a text channel that belongs to a server on Stoat.

This inherits from BaseServerChannel, Connectable and Messageable.

last_message_id¶

The last message ID sent in the channel.

Type:: Optional[str]

voice¶

The voice’s metadata in the channel.

Added in version 1.2.

Type:: Optional[ChannelVoiceMetadata]

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

message (ULIDOr[BaseMessage]) – The message to mark as read.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

await begin_typing(*, http_overrides=None)[source]¶: Begins typing in channel, until end_typing() is called.

property category[source]¶

The category the channel is in.

Type:: Optional[Category]

category_id¶

The category ID the channel is in.

Added in version 1.2.

Type:: Optional[str]

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)[source]¶

Connects to a destination voice channel and returns a Room associated with destination.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (Optional[str]) –
The node’s name to use for starting a call.

If None, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.
TypeError – If livekit dependency is not installed.

await create_invite(*, http_overrides=None)[source]¶

This function is a coroutine.

Creates an invite to server channel.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group or server channel.

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create invites in channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The invite that was created.

Return type:

default_permissions¶

Default permissions assigned to users in this channel.

Type:: Optional[PermissionOverride]

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes a server channel.

You must have view_channel and manage_channels to do this.

For server channels, ServerChannelDeleteEvent is fired for all users who could see target channel, and ServerUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

description¶

The channel description.

Type:: Optional[str]

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await end_typing(*, http_overrides=None)[source]¶: Ends typing in channel.

await fetch_channel_id(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The channel’s ID.
Return type:: str

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves a message.

Parameters:

message (ULIDOr[BaseMessage]) – The message to retrieve.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/message was not found.
InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

await fetch_webhooks(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves all webhooks in a channel.

You must have manage_webhooks permission to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view webhooks that belong to this channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The webhooks for this channel.

Return type:

List[Webhook]

get_category()[source]¶: Optional[Category]: The category the channel is in.

Added in version 1.2.

get_me()[source]¶: Optional[Member]: The own user for this server.

get_message(message_id, /)[source]¶

Retrieves a channel message from cache.

Parameters:: message_id (str) – The message ID.
Returns:: The message or None if not found.
Return type:: Optional[Message]

get_server()[source]¶: Optional[Server]: The server this channel belongs to.

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]¶

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to read the message history.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

property icon[source]¶

The custom channel icon.

Type:: Optional[Asset]

id¶

The ID of the entity.

Type:: str

internal_icon¶

The stateless custom channel icon.

Type:: Optional[StatelessAsset]

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)[source]¶

This function is a coroutine.

Asks the voice server for a token to join the call in destination channel.

You must have connect to do this.

For Livekit instances, fires MessageCreateEvent and VoiceChannelJoinEvent / VoiceChannelMoveEvent for all users who can see target channel.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (UndefinedOr[Optional[str]]) –
The node’s name to use for starting a call.

If None or UNDEFINED, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.
force_disconnect (UndefinedOr[Optional[bool]]) –
Whether to force disconnect any other existing voice connections. Useful for disconnecting on another device and joining on a new.

Added in version 1.2.
recipients (UndefinedOr[Optional[List[ULIDOr[BaseUser]]]]) –
A list of users which should be notified of the call starting. Only used when the user is the first one connected.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.

Returns:

The token for authenticating with the voice server, and node WebSocket URL (can be empty if instance does not use Livekit).

Return type:

Tuple[str, str]

property me[source]¶

The own user for this server.

Type:: Optional[Member]

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

name¶

The display name of the channel.

Type:: str

nsfw¶

Whether this channel is marked as not safe for work.

Type:: bool

permissions_for(target, /, *, safe=True, with_ownership=True, include_timeout=True)[source]¶

Calculate permissions for given user.

Parameters:

target (Union[User, Member]) – The member or user to calculate permissions for.
safe (bool) – Whether to raise exception or not if role is missing in cache.
with_ownership (bool) – Whether to account for ownership.
include_timeout (bool) – Whether to account for timeout.

Raises:

NoData – The server or role is not found in cache.

Returns:

The calculated permissions.

Return type:

role_permissions¶

The permissions assigned based on role to this channel.

Type:: Dict[str, PermissionOverride]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]¶

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

query (Optional[str]) –
The full-text search query. See MongoDB documentation for more information.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

HTTPException – Possible values for type:

Value	Reason
`FailedValidation`	One of `before`, `after` or `nearby` parameters were invalid IDs.
`InvalidOperation`	You provided both `query` and `pinned` parameters.
`IsBot`	The current token belongs to bot account.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to search messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages matched.

Return type:

List[Message]

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

content (Optional[str]) – The message content.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

You must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

You must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The message masquerade.

You must have use_masquerade to provide this.

If color is provided, use_masquerade is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) –
Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

Note

User accounts cannot set this to True.
mention_online (Optional[bool]) –
Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Note

User accounts cannot set this to True.

Raises:

stoat.HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `reactions` elements was invalid.
`InvalidProperty`	`restrict_reactions` was `True` but `reactions` was empty.
`IsBot`	The current token belongs to bot account.
`IsNotBot`	The current token belongs to user account.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply was not found.
stoat.InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

property server[source]¶

The server this channel belongs to.

Type:: Server

server_id¶

The server ID that channel belongs to.

Type:: str

await set_default_permissions(permissions, *, http_overrides=None)[source]¶

This function is a coroutine.

Sets default permissions for everyone in a channel.

You must have manage_permissions to do this.

Parameters:

permissions (PermissionOverride) – The new permissions.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`MissingPermission`	You do not have the proper permissions to edit default permissions for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for the specified role in a channel.

You must have manage_permissions to do this.

Parameters:

role (ULIDOr[BaseRole]) – The role.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow for role in channel.
deny (Permissions) – The permissions to deny for role in channel.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit overrides for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel/server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

state¶

The state that controls this entity.

Type:: State

typing()[source]¶: Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

get_channel_id()[source]¶: str: Retrieves the channel’s ID, if possible.

get_last_message()[source]¶: Optional[Message]: The last message sent in the channel.

get_read_state(*, default_acked_message_id=None, create_if_not_exists=True)[source]¶

Optional[ReadState]: Returns the channel’s read state.

Parameters:

default_acked_message_id (Optional[str]) – The default acked message ID to use if read state is not found.
create_if_not_exists (bool) – Whether to create a read state and store it if existing was not found.

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.text]

property last_message[source]¶

The last message sent in the channel.

Type:: Optional[Message]

property read_state[source]¶

Returns the channel’s read state.

Type:: ReadState

property voice_states[source]¶

Returns all voice states in the channel.

Type:: ChannelVoiceStateContainer

await create_webhook(*, http_overrides=None, name, avatar=None)[source]¶

This function is a coroutine.

Creates a webhook which 3rd party platforms can use to send.

You must have manage_webhooks permission to do this.

Fires WebhookCreateEvent for all users who can see target channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (str) – The webhook name. Must be between 1 and 32 chars long.
avatar (Optional[ResolvableResource]) – The webhook avatar.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The channel was not type of group or text.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create a webhook.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The created webhook.

Return type:

Webhook

to_dict()[source]¶: dict: Convert channel to raw data.

VoiceChannel¶

Attributes

category
category_id
default_permissions
description
icon
id
internal_icon
me
mention
messages
name
nsfw
role_permissions
server
server_id
state
type
voice_states

Methods

async acknowledge
async begin_typing
async close
async connect
async create_invite
async delete
async edit
async end_typing
async fetch_channel_id
async fetch_message
async fetch_webhooks
def get_category
def get_channel_id
def get_me
def get_message
def get_server
async history
async join_call
def locally_update
def message
def permissions_for
async search
async send
async set_default_permissions
async set_role_permissions
def to_dict
def typing

class stoat.VoiceChannel(*, state, id, server_id, name, description, internal_icon, default_permissions, role_permissions, category_id, nsfw)[source]¶

Represents a voice channel that belongs to a server on Stoat.

This inherits from BaseServerChannel, Connectable and Messageable.

Deprecated since version 0.7.0: The voice channel type was deprecated in favour of TextChannel.voice.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

message (ULIDOr[BaseMessage]) – The message to mark as read.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

await begin_typing(*, http_overrides=None)[source]¶: Begins typing in channel, until end_typing() is called.

property category[source]¶

The category the channel is in.

Type:: Optional[Category]

category_id¶

The category ID the channel is in.

Added in version 1.2.

Type:: Optional[str]

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)[source]¶

Connects to a destination voice channel and returns a Room associated with destination.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (Optional[str]) –
The node’s name to use for starting a call.

If None, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.
TypeError – If livekit dependency is not installed.

await create_invite(*, http_overrides=None)[source]¶

This function is a coroutine.

Creates an invite to server channel.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group or server channel.

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create invites in channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The invite that was created.

Return type:

default_permissions¶

Default permissions assigned to users in this channel.

Type:: Optional[PermissionOverride]

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes a server channel.

You must have view_channel and manage_channels to do this.

For server channels, ServerChannelDeleteEvent is fired for all users who could see target channel, and ServerUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

description¶

The channel description.

Type:: Optional[str]

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await end_typing(*, http_overrides=None)[source]¶: Ends typing in channel.

await fetch_channel_id(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The channel’s ID.
Return type:: str

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves a message.

Parameters:

message (ULIDOr[BaseMessage]) – The message to retrieve.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/message was not found.
InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

await fetch_webhooks(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves all webhooks in a channel.

You must have manage_webhooks permission to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view webhooks that belong to this channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The webhooks for this channel.

Return type:

List[Webhook]

get_category()[source]¶: Optional[Category]: The category the channel is in.

Added in version 1.2.

get_me()[source]¶: Optional[Member]: The own user for this server.

get_message(message_id, /)[source]¶

Retrieves a channel message from cache.

Parameters:: message_id (str) – The message ID.
Returns:: The message or None if not found.
Return type:: Optional[Message]

get_server()[source]¶: Optional[Server]: The server this channel belongs to.

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]¶

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to read the message history.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

property icon[source]¶

The custom channel icon.

Type:: Optional[Asset]

id¶

The ID of the entity.

Type:: str

internal_icon¶

The stateless custom channel icon.

Type:: Optional[StatelessAsset]

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)[source]¶

This function is a coroutine.

Asks the voice server for a token to join the call in destination channel.

You must have connect to do this.

For Livekit instances, fires MessageCreateEvent and VoiceChannelJoinEvent / VoiceChannelMoveEvent for all users who can see target channel.

Parameters:

channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
node (UndefinedOr[Optional[str]]) –
The node’s name to use for starting a call.

If None or UNDEFINED, the currently assigned channel node will be used.

If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

Added in version 1.2.
force_disconnect (UndefinedOr[Optional[bool]]) –
Whether to force disconnect any other existing voice connections. Useful for disconnecting on another device and joining on a new.

Added in version 1.2.
recipients (UndefinedOr[Optional[List[ULIDOr[BaseUser]]]]) –
A list of users which should be notified of the call starting. Only used when the user is the first one connected.

Added in version 1.2.

Raises:

HTTPException – Possible values for type:

Value	Reason
`AlreadyConnected`	The current user was already connected to this voice channel.
`CannotJoinCall`	The channel was type of `saved_messages` (or if instance uses legacy voice server, `text`).
`InvalidOperation`	The voice server is unavailable.
`LivekitUnavailable`	The voice server is unavailable. Only applicable to instances using Livekit.
`NotConnected`	The current user was already connected to other voice channel.
`NotAVoiceChannel`	The channel was not a voice channel. Only applicable to instances using Livekit.
`UnknownNode`	The server could not discover a voice node.
`VosoUnavailable`	The voice server is unavailable. Not applicable to instances using Livekit.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to join a call.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went during retrieving token.

Returns:

The token for authenticating with the voice server, and node WebSocket URL (can be empty if instance does not use Livekit).

Return type:

Tuple[str, str]

property me[source]¶

The own user for this server.

Type:: Optional[Member]

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

name¶

The display name of the channel.

Type:: str

nsfw¶

Whether this channel is marked as not safe for work.

Type:: bool

permissions_for(target, /, *, safe=True, with_ownership=True, include_timeout=True)[source]¶

Calculate permissions for given user.

Parameters:

target (Union[User, Member]) – The member or user to calculate permissions for.
safe (bool) – Whether to raise exception or not if role is missing in cache.
with_ownership (bool) – Whether to account for ownership.
include_timeout (bool) – Whether to account for timeout.

Raises:

NoData – The server or role is not found in cache.

Returns:

The calculated permissions.

Return type:

role_permissions¶

The permissions assigned based on role to this channel.

Type:: Dict[str, PermissionOverride]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]¶

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

query (Optional[str]) –
The full-text search query. See MongoDB documentation for more information.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.
limit (Optional[int]) –
The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

If nearby is provided, then this is (limit + 2).
before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.
after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.
sort (Optional[MessageSort]) – The message sort direction. Defaults to latest
nearby (Optional[ULIDOr[BaseMessage]]) –
The message to search around.

Providing this parameter will discard before, after and sort parameters.

It will also take half of limit rounded as the limits to each side. It also fetches the message specified.
populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

HTTPException – Possible values for type:

Value	Reason
`FailedValidation`	One of `before`, `after` or `nearby` parameters were invalid IDs.
`InvalidOperation`	You provided both `query` and `pinned` parameters.
`IsBot`	The current token belongs to bot account.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to search messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The messages matched.

Return type:

List[Message]

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

content (Optional[str]) – The message content.
channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

You must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

You must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The message masquerade.

You must have use_masquerade to provide this.

If color is provided, use_masquerade is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) –
Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

Note

User accounts cannot set this to True.
mention_online (Optional[bool]) –
Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Note

User accounts cannot set this to True.

Raises:

stoat.HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `reactions` elements was invalid.
`InvalidProperty`	`restrict_reactions` was `True` but `reactions` was empty.
`IsBot`	The current token belongs to bot account.
`IsNotBot`	The current token belongs to user account.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply was not found.
stoat.InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

property server[source]¶

The server this channel belongs to.

Type:: Server

server_id¶

The server ID that channel belongs to.

Type:: str

await set_default_permissions(permissions, *, http_overrides=None)[source]¶

This function is a coroutine.

Sets default permissions for everyone in a channel.

You must have manage_permissions to do this.

Parameters:

permissions (PermissionOverride) – The new permissions.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`MissingPermission`	You do not have the proper permissions to edit default permissions for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for the specified role in a channel.

You must have manage_permissions to do this.

Parameters:

role (ULIDOr[BaseRole]) – The role.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow for role in channel.
deny (Permissions) – The permissions to deny for role in channel.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit overrides for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel/server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

state¶

The state that controls this entity.

Type:: State

typing()[source]¶: Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

get_channel_id()[source]¶: str: Retrieves the channel’s ID, if possible.

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

property type[source]¶

The channel’s type.

Type:: Literal[ChannelType.voice]

property voice_states[source]¶

Returns all voice states in the channel.

Type:: ChannelVoiceStateContainer

to_dict()[source]¶: dict: Convert channel to raw data.

UnknownServerChannel¶

Attributes

category
category_id
default_permissions
description
icon
id
internal_icon
me
mention
name
nsfw
payload
role_permissions
server
server_id
state
type

Methods

async close
async create_invite
async delete
async edit
async fetch_webhooks
def get_category
def get_me
def get_server
def locally_update
def message
def permissions_for
async set_default_permissions
async set_role_permissions
def to_dict

class stoat.UnknownServerChannel(*, state, id, server_id, name, description, internal_icon, default_permissions, role_permissions, category_id, nsfw, payload)[source]¶

Represents a server channel that is not recognized by library yet.

This inherits from BaseServerChannel.

property category[source]¶

The category the channel is in.

Type:: Optional[Category]

category_id¶

The category ID the channel is in.

Added in version 1.2.

Type:: Optional[str]

await close(*, http_overrides=None, silent=None)[source]¶

This function is a coroutine.

Deletes a server channel, leaves a group or closes a group.

You must have view_channel to do this. If target channel is server channel, manage_channels is also required.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
silent (Optional[bool]) – Whether to not send message when leaving.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await create_invite(*, http_overrides=None)[source]¶

This function is a coroutine.

Creates an invite to server channel.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

The target channel is not group or server channel.

IsBot

The current token belongs to bot account.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to create invites in channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The target channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The invite that was created.

Return type:

default_permissions¶

Default permissions assigned to users in this channel.

Type:: Optional[PermissionOverride]

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes a server channel.

You must have view_channel and manage_channels to do this.

For server channels, ServerChannelDeleteEvent is fired for all users who could see target channel, and ServerUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view and/or delete the channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

description¶

The channel description.

Type:: Optional[str]

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new channel name. Only applicable when target channel is GroupChannel, or ServerChannel.
description (UndefinedOr[Optional[str]]) – The new channel description. Only applicable when target channel is GroupChannel, or ServerChannel.
owner (UndefinedOr[ULIDOr[BaseUser]]) – The new channel owner. Only applicable when target channel is GroupChannel.
icon (UndefinedOr[Optional[ResolvableResource]]) – The new channel icon. Only applicable when target channel is GroupChannel, or ServerChannel.
nsfw (UndefinedOr[bool]) – To mark the channel as NSFW or not. Only applicable when target channel is GroupChannel, or ServerChannel.
archived (UndefinedOr[bool]) – To mark the channel as archived or not.
voice (UndefinedOr[ChannelVoiceMetadata]) –
The new voice-specific metadata for this channel.

Added in version 1.2.
default_permissions (UndefinedOr[None]) – To remove default permissions or not. Only applicable when target channel is GroupChannel, or ServerChannel.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.

InvalidOperation

The target channel was not group/text/voice channel.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to edit the channel.

NotOwner

You do not own the group.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.

NotInGroup

The new owner was not in group.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated channel.

Return type:

await fetch_webhooks(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieves all webhooks in a channel.

You must have manage_webhooks permission to do this.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to view webhooks that belong to this channel.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The webhooks for this channel.

Return type:

List[Webhook]

get_category()[source]¶: Optional[Category]: The category the channel is in.

Added in version 1.2.

get_me()[source]¶: Optional[Member]: The own user for this server.

get_server()[source]¶: Optional[Server]: The server this channel belongs to.

property icon[source]¶

The custom channel icon.

Type:: Optional[Asset]

id¶

The ID of the entity.

Type:: str

internal_icon¶

The stateless custom channel icon.

Type:: Optional[StatelessAsset]

locally_update(data, /)[source]¶

Locally updates channel with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialChannel) – The data to update channel with.

property me[source]¶

The own user for this server.

Type:: Optional[Member]

property mention[source]¶

Returns the channel’s mention.

Type:: str

message(message, /)[source]¶: BaseMessage: Returns a partial message with specified ID.

name¶

The display name of the channel.

Type:: str

nsfw¶

Whether this channel is marked as not safe for work.

Type:: bool

permissions_for(target, /, *, safe=True, with_ownership=True, include_timeout=True)[source]¶

Calculate permissions for given user.

Parameters:

target (Union[User, Member]) – The member or user to calculate permissions for.
safe (bool) – Whether to raise exception or not if role is missing in cache.
with_ownership (bool) – Whether to account for ownership.
include_timeout (bool) – Whether to account for timeout.

Raises:

NoData – The server or role is not found in cache.

Returns:

The calculated permissions.

Return type:

role_permissions¶

The permissions assigned based on role to this channel.

Type:: Dict[str, PermissionOverride]

property server[source]¶

The server this channel belongs to.

Type:: Server

server_id¶

The server ID that channel belongs to.

Type:: str

await set_default_permissions(permissions, *, http_overrides=None)[source]¶

This function is a coroutine.

Sets default permissions for everyone in a channel.

You must have manage_permissions to do this.

Parameters:

permissions (PermissionOverride) – The new permissions.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`MissingPermission`	You do not have the proper permissions to edit default permissions for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type:

await set_role_permissions(role, *, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for the specified role in a channel.

You must have manage_permissions to do this.

Parameters:

role (ULIDOr[BaseRole]) – The role.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow for role in channel.
deny (Permissions) – The permissions to deny for role in channel.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit overrides for this channel.

NotFound – Possible values for type:

Value

Reason

NotFound

The channel/server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server channel with new permissions.

Return type: