Users ¶

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

This function is a coroutine.

Blocks an user.

Fires UserRelationshipUpdateEvent for the current user and blocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you already had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The blocked user.

Return type:

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

This function is a coroutine.

Denies another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you denide friend request from.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you denied friend request from.

Return type:

await edit(*, http_overrides=None, display_name=UNDEFINED, avatar=UNDEFINED, status=UNDEFINED, profile=UNDEFINED, badges=UNDEFINED, flags=UNDEFINED)[source]¶

This function is a coroutine.

Edits the user.

Fires UserUpdateEvent for all users who are subscribed to target user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
display_name (UndefinedOr[Optional[str]]) – The new display name. Must be between 2 and 32 characters and not contain zero width space, newline or carriage return characters.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new avatar. Could be None to remove avatar.
status (UndefinedOr[UserStatusEdit]) – The new user status.
profile (UndefinedOr[UserProfileEdit]) – The new user profile data. This is applied as a partial.
badges (UndefinedOr[UserBadges]) – The new user badges. You must be privileged user to provide this.
flags (UndefinedOr[UserFlags]) – The new user flags. You must be privileged user to provide this.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotPrivileged

You tried to edit fields that require you to be privileged, or tried to edit bot you do not own.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated user.

Return type:

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

This function is a coroutine.

Retrieve user’s information.

You must have access 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user.

Return type:

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_default_avatar(*, http_overrides=None)[source]¶

This function is a coroutine.

Return a default user avatar based on the given ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The image in PNG format.
Return type:: bytes

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

This function is a coroutine.

Retrieves flags for user.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The retrieved flags.
Return type:: UserFlags

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

This function is a coroutine.

Retrieve profile of an user.

You must have view_profile 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user profile.

Return type:

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

This function is a coroutine.

Retrieves a list of mutual friend user IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual friend user IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual server IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual server IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual friends and servers with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutuals.

Return type:

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

This function is a coroutine.

Retrieve a DM (or create if it doesn’t exist) with another user.

If target is current user, a SavedMessagesChannel is always returned.

You must have send_messages to do this.

May fire PrivateChannelCreateEvent for the current user and user you opened DM with.

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.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to open DM with this user.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The private channel.

Return type:

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

This function is a coroutine.

Removes the user from friend list.

Fires UserRelationshipUpdateEvent for the current user and user you removed from friend list.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you removed from friend list.

Return type:

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)[source]¶

This function is a coroutine.

Report the user to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

reason (UserReportReason) – The reason for reporting user.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.
message_context (Optional[ULIDOr[BaseMessage]]) –
The message context.

Internally, 15 messages around provided message will be snapshotted for context. All attachments of provided message are snapshotted as well.

Raises:

HTTPException – Possible values for type:

Value

Reason

CannotReportYourself

You tried to report yourself.

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

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

This function is a coroutine.

Unblocks an user.

Fires UserRelationshipUpdateEvent for the current user and unblocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you didn’t had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user 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 wrong during unblocking user.

Returns:

The unblocked user.

Return type:

DisplayUser¶

Attributes

avatar
default_avatar_url
discriminator
display_avatar_url
dm_channel
dm_channel_id
id
internal_avatar
mention
messages
name
pm
pm_id
state
tag

Methods

async accept_friend_request
async acknowledge
async begin_typing
async block
async connect
async deny_friend_request
async edit
async end_typing
async fetch
async fetch_channel_id
async fetch_default_avatar
async fetch_flags
async fetch_message
async fetch_profile
def get_channel_id
def get_message
async history
def is_sentinel
async join_call
async mutual_friend_ids
async mutual_server_ids
async mutuals
async open_dm
async remove_friend
async report
async search
async send
async send_friend_request
def typing
async unblock

class stoat.DisplayUser(*, state, id, name, discriminator, internal_avatar)[source]¶

Represents an user on Stoat that can be easily displayed in UI.

This inherits from BaseUser.

name¶

The username of the user.

Type:: str

discriminator¶

The discriminator of the user.

Type:: str

internal_avatar¶

The stateless avatar of the user.

Type:: Optional[StatelessAsset]

property avatar[source]¶

The avatar of the user.

Type:: Optional[Asset]

property display_avatar_url[source]¶

The URL to user’s avatar, or their default avatar if they have none set.

Type:: str

property tag[source]¶

The tag of the user.

Assuming that User.name is 'kotlin.Unit' and User.discriminator is '3510', example output would be 'kotlin.Unit#3510'.

Type:: str

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

This function is a coroutine.

Sends a friend request to this user.

Fires UserRelationshipUpdateEvent for the current user and user you sent friend request to.

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
`InvalidProperty`	You did not provide a discriminator.
`IsBot`	Either the current user or user you tried to accept friend request from are bot accounts.
`TooManyPendingFriendRequests`	You sent too many outgoing friend requests.

NoEffect – You tried to accept friend request from yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

BlockedOther

The user you tried to send friend request to have blocked you.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.

Conflict – Possible values for type:

Value	Reason
`AlreadyFriends`	You’re already friends with user you tried to send friend request to.
`AlreadySentRequest`	You already sent friend request to this user.
`Blocked`	You have blocked the user you tried to send friend request to.

InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you sent friend request to.

Return type:

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

This function is a coroutine.

Accept another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you accepted friend request from.

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

IsBot

Either the current user or user you tried to accept friend request from are bot accounts.

TooManyPendingFriendRequests

You sent too many outgoing friend requests.
NoEffect – You tried to accept friend request from yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

BlockedOther

The user you tried to accept friend request from have blocked you.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.

Conflict – Possible values for type:

Value	Reason
`AlreadyFriends`	You’re already friends with user you tried to accept friend request from.
`AlreadySentRequest`	You already sent friend request to this user.
`Blocked`	You have blocked the user you tried to accept friend request from.

InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you accepted friend request from.

Return type:

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 block(*, http_overrides=None)[source]¶

This function is a coroutine.

Blocks an user.

Fires UserRelationshipUpdateEvent for the current user and blocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you already had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The blocked user.

Return type:

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.

property default_avatar_url[source]¶

The URL to user’s default avatar.

Type:: str

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

This function is a coroutine.

Denies another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you denide friend request from.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you denied friend request from.

Return type:

property dm_channel[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property dm_channel_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

await edit(*, http_overrides=None, display_name=UNDEFINED, avatar=UNDEFINED, status=UNDEFINED, profile=UNDEFINED, badges=UNDEFINED, flags=UNDEFINED)[source]¶

This function is a coroutine.

Edits the user.

Fires UserUpdateEvent for all users who are subscribed to target user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
display_name (UndefinedOr[Optional[str]]) – The new display name. Must be between 2 and 32 characters and not contain zero width space, newline or carriage return characters.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new avatar. Could be None to remove avatar.
status (UndefinedOr[UserStatusEdit]) – The new user status.
profile (UndefinedOr[UserProfileEdit]) – The new user profile data. This is applied as a partial.
badges (UndefinedOr[UserBadges]) – The new user badges. You must be privileged user to provide this.
flags (UndefinedOr[UserFlags]) – The new user flags. You must be privileged user to provide this.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotPrivileged

You tried to edit fields that require you to be privileged, or tried to edit bot you do not own.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated user.

Return type:

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

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

This function is a coroutine.

Retrieve user’s information.

You must have access 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user.

Return type:

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_default_avatar(*, http_overrides=None)[source]¶

This function is a coroutine.

Return a default user avatar based on the given ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The image in PNG format.
Return type:: bytes

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

This function is a coroutine.

Retrieves flags for user.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The retrieved flags.
Return type:: UserFlags

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_profile(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieve profile of an user.

You must have view_profile 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user profile.

Return type:

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

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

is_sentinel()[source]¶: bool: Returns whether the user is sentinel (Stoat#0000).

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]¶

The user mention.

Type:: str

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

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

This function is a coroutine.

Retrieves a list of mutual friend user IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual friend user IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual server IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual server IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual friends and servers with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutuals.

Return type:

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

This function is a coroutine.

Retrieve a DM (or create if it doesn’t exist) with another user.

If target is current user, a SavedMessagesChannel is always returned.

You must have send_messages to do this.

May fire PrivateChannelCreateEvent for the current user and user you opened DM with.

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.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to open DM with this user.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The private channel.

Return type:

property pm[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property pm_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

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

This function is a coroutine.

Removes the user from friend list.

Fires UserRelationshipUpdateEvent for the current user and user you removed from friend list.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you removed from friend list.

Return type:

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)[source]¶

This function is a coroutine.

Report the user to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

reason (UserReportReason) – The reason for reporting user.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.
message_context (Optional[ULIDOr[BaseMessage]]) –
The message context.

Internally, 15 messages around provided message will be snapshotted for context. All attachments of provided message are snapshotted as well.

Raises:

HTTPException – Possible values for type:

Value

Reason

CannotReportYourself

You tried to report yourself.

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

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.

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

This function is a coroutine.

Unblocks an user.

Fires UserRelationshipUpdateEvent for the current user and unblocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you didn’t had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user 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 wrong during unblocking user.

Returns:

The unblocked user.

Return type:

BotUserMetadata¶

Attributes

owner_id

Methods

def to_dict

class stoat.BotUserMetadata(*, owner_id)[source]¶

Represents a bot-specific metadata for an user.

owner_id¶

The user’s ID who owns bot.

Type:: str

to_dict()[source]¶: dict: Convert bot user metadata to raw data.

PartialUser¶

Methods

async accept_friend_request
async acknowledge
async begin_typing
async block
async connect
async deny_friend_request
async edit
async end_typing
async fetch
async fetch_channel_id
async fetch_default_avatar
async fetch_flags
async fetch_message
async fetch_profile
def get_channel_id
def get_message
async history
def is_sentinel
async join_call
async mutual_friend_ids
async mutual_server_ids
async mutuals
async open_dm
async remove_friend
async report
async search
async send
def typing
async unblock

class stoat.PartialUser(*, state, id, name, discriminator, display_name, internal_avatar, raw_badges, status, raw_flags, bot, online)[source]¶

Represents a partial user on Stoat.

This inherits from BaseUser.

name¶

The new user’s name.

Type:: UndefinedOr[str]

discriminator¶

The new user’s discriminator.

Type:: UndefinedOr[str]

display_name¶

The new user’s display name.

Type:: UndefinedOr[Optional[str]]

internal_avatar¶

The new user’s stateless avatar.

Type:: UndefinedOr[Optional[StatelessAsset]]

raw_badges¶

The new user’s badges raw value.

Type:: UndefinedOr[int]

status¶

The new user’s status.

Type:: UndefinedOr[UserStatusEdit]

raw_flags¶

The user’s flags raw value.

Type:: UndefinedOr[int]

bot¶

The information about the bot.

Type:: UndefinedOr[BotUserMetadata]

online¶

Whether the user came online.

Type:: UndefinedOr[bool]

property avatar[source]¶

The new user’s avatar.

Type:: UndefinedOr[Optional[Asset]]

property badges[source]¶

The new user’s badges.

Type:: UndefinedOr[UserBadges]

property flags[source]¶

The user’s flags.

Type:: UndefinedOr[UserFlags]

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

This function is a coroutine.

Accept another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you accepted friend request from.

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

IsBot

Either the current user or user you tried to accept friend request from are bot accounts.

TooManyPendingFriendRequests

You sent too many outgoing friend requests.
NoEffect – You tried to accept friend request from yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

BlockedOther

The user you tried to accept friend request from have blocked you.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.

Conflict – Possible values for type:

Value	Reason
`AlreadyFriends`	You’re already friends with user you tried to accept friend request from.
`AlreadySentRequest`	You already sent friend request to this user.
`Blocked`	You have blocked the user you tried to accept friend request from.

InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you accepted friend request from.

Return type:

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 block(*, http_overrides=None)[source]¶

This function is a coroutine.

Blocks an user.

Fires UserRelationshipUpdateEvent for the current user and blocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you already had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The blocked user.

Return type:

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.

property default_avatar_url[source]¶

The URL to user’s default avatar.

Type:: str

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

This function is a coroutine.

Denies another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you denide friend request from.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you denied friend request from.

Return type:

property dm_channel[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property dm_channel_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

await edit(*, http_overrides=None, display_name=UNDEFINED, avatar=UNDEFINED, status=UNDEFINED, profile=UNDEFINED, badges=UNDEFINED, flags=UNDEFINED)[source]¶

This function is a coroutine.

Edits the user.

Fires UserUpdateEvent for all users who are subscribed to target user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
display_name (UndefinedOr[Optional[str]]) – The new display name. Must be between 2 and 32 characters and not contain zero width space, newline or carriage return characters.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new avatar. Could be None to remove avatar.
status (UndefinedOr[UserStatusEdit]) – The new user status.
profile (UndefinedOr[UserProfileEdit]) – The new user profile data. This is applied as a partial.
badges (UndefinedOr[UserBadges]) – The new user badges. You must be privileged user to provide this.
flags (UndefinedOr[UserFlags]) – The new user flags. You must be privileged user to provide this.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotPrivileged

You tried to edit fields that require you to be privileged, or tried to edit bot you do not own.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated user.

Return type:

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

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

This function is a coroutine.

Retrieve user’s information.

You must have access 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user.

Return type:

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_default_avatar(*, http_overrides=None)[source]¶

This function is a coroutine.

Return a default user avatar based on the given ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The image in PNG format.
Return type:: bytes

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

This function is a coroutine.

Retrieves flags for user.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The retrieved flags.
Return type:: UserFlags

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_profile(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieve profile of an user.

You must have view_profile 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user profile.

Return type:

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

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

is_sentinel()[source]¶: bool: Returns whether the user is sentinel (Stoat#0000).

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]¶

The user mention.

Type:: str

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

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

This function is a coroutine.

Retrieves a list of mutual friend user IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual friend user IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual server IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual server IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual friends and servers with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutuals.

Return type:

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

This function is a coroutine.

Retrieve a DM (or create if it doesn’t exist) with another user.

If target is current user, a SavedMessagesChannel is always returned.

You must have send_messages to do this.

May fire PrivateChannelCreateEvent for the current user and user you opened DM with.

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.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to open DM with this user.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The private channel.

Return type:

property pm[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property pm_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

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

This function is a coroutine.

Removes the user from friend list.

Fires UserRelationshipUpdateEvent for the current user and user you removed from friend list.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you removed from friend list.

Return type:

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)[source]¶

This function is a coroutine.

Report the user to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

reason (UserReportReason) – The reason for reporting user.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.
message_context (Optional[ULIDOr[BaseMessage]]) –
The message context.

Internally, 15 messages around provided message will be snapshotted for context. All attachments of provided message are snapshotted as well.

Raises:

HTTPException – Possible values for type:

Value

Reason

CannotReportYourself

You tried to report yourself.

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

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.

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

This function is a coroutine.

Unblocks an user.

Fires UserRelationshipUpdateEvent for the current user and unblocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you didn’t had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user 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 wrong during unblocking user.

Returns:

The unblocked user.

Return type:

User¶

Methods

async accept_friend_request
async acknowledge
async begin_typing
async block
async connect
async deny_friend_request
async edit
async end_typing
async fetch
async fetch_channel_id
async fetch_default_avatar
async fetch_flags
async fetch_message
async fetch_profile
def get_bot_owner
def get_channel_id
def get_message
async history
def is_active_supporter
def is_banned
def is_deleted
def is_developer
def is_early_adopter
def is_founder
def is_paw
def is_platform_moderator
def is_relevant_joke_1
def is_relevant_joke_2
def is_responsible_disclosure
def is_sentinel
def is_spammer
def is_supporter
def is_suspended
def is_translator
async join_call
def locally_update
async mutual_friend_ids
async mutual_server_ids
async mutuals
async open_dm
async remove_friend
async report
async search
async send
async send_friend_request
def to_dict
def typing
async unblock

class stoat.User(*, state, id, name, discriminator, internal_avatar, display_name, raw_badges, status, raw_flags, privileged, bot, relationship, online)[source]¶

Represents an user on Stoat.

This inherits from DisplayUser.

display_name¶

The user’s display name.

Type:: Optional[str]

raw_badges¶

The user’s badges raw value.

Type:: int

status¶

The current user’s status.

Type:: Optional[UserStatus]

raw_flags¶

The user’s flags raw value.

Type:: int

privileged¶

Whether the user is privileged.

Type:: bool

bot¶

The information about the bot.

Type:: Optional[BotUserMetadata]

relationship¶

The current user’s relationship with this user.

Type:: RelationshipStatus

online¶

Whether the user is currently online.

Type:: bool

get_bot_owner()[source]¶

Returns the user who created this bot user.

Returns:: The bot owner and their ID (may be empty if user is not a bot).
Return type:: Tuple[Optional[User], str]

locally_update(data, /)[source]¶: Locally updates user with provided data.

Warning

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

property badges[source]¶

The user’s badges.

Type:: UserBadges

property bot_owner[source]¶

Returns the user who created this bot user.

Type:: Optional[User]

property flags[source]¶

The user’s badges.

Type:: UserFlags

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

This function is a coroutine.

Accept another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you accepted friend request from.

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

IsBot

Either the current user or user you tried to accept friend request from are bot accounts.

TooManyPendingFriendRequests

You sent too many outgoing friend requests.
NoEffect – You tried to accept friend request from yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

BlockedOther

The user you tried to accept friend request from have blocked you.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.

Conflict – Possible values for type:

Value	Reason
`AlreadyFriends`	You’re already friends with user you tried to accept friend request from.
`AlreadySentRequest`	You already sent friend request to this user.
`Blocked`	You have blocked the user you tried to accept friend request from.

InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you accepted friend request from.

Return type:

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.

property avatar[source]¶

The avatar of the user.

Type:: Optional[Asset]

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

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

This function is a coroutine.

Blocks an user.

Fires UserRelationshipUpdateEvent for the current user and blocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you already had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The blocked user.

Return type:

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.

property default_avatar_url[source]¶

The URL to user’s default avatar.

Type:: str

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

This function is a coroutine.

Denies another user’s friend request.

Fires UserRelationshipUpdateEvent for the current user and user you denide friend request from.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you denied friend request from.

Return type:

discriminator¶

The discriminator of the user.

Type:: str

property display_avatar_url[source]¶

The URL to user’s avatar, or their default avatar if they have none set.

Type:: str

property dm_channel[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property dm_channel_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

await edit(*, http_overrides=None, display_name=UNDEFINED, avatar=UNDEFINED, status=UNDEFINED, profile=UNDEFINED, badges=UNDEFINED, flags=UNDEFINED)[source]¶

This function is a coroutine.

Edits the user.

Fires UserUpdateEvent for all users who are subscribed to target user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
display_name (UndefinedOr[Optional[str]]) – The new display name. Must be between 2 and 32 characters and not contain zero width space, newline or carriage return characters.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new avatar. Could be None to remove avatar.
status (UndefinedOr[UserStatusEdit]) – The new user status.
profile (UndefinedOr[UserProfileEdit]) – The new user profile data. This is applied as a partial.
badges (UndefinedOr[UserBadges]) – The new user badges. You must be privileged user to provide this.
flags (UndefinedOr[UserFlags]) – The new user flags. You must be privileged user to provide this.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotPrivileged

You tried to edit fields that require you to be privileged, or tried to edit bot you do not own.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated user.

Return type:

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

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

This function is a coroutine.

Retrieve user’s information.

You must have access 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user.

Return type:

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_default_avatar(*, http_overrides=None)[source]¶

This function is a coroutine.

Return a default user avatar based on the given ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The image in PNG format.
Return type:: bytes

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

This function is a coroutine.

Retrieves flags for user.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The retrieved flags.
Return type:: UserFlags

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_profile(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieve profile of an user.

You must have view_profile 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user profile.

Return type:

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

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

internal_avatar¶

The stateless avatar of the user.

Type:: Optional[StatelessAsset]

is_sentinel()[source]¶: bool: Returns whether the user is sentinel (Stoat#0000).

is_suspended()[source]¶: bool: Whether this user has been suspended from the platform.

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]¶

The user mention.

Type:: str

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

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

This function is a coroutine.

Retrieves a list of mutual friend user IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual friend user IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual server IDs with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutual server IDs.

Return type:

List[str]

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

This function is a coroutine.

Retrieves a list of mutual friends and servers with another user.

You must have view_profile to do this.

Parameters:

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

Raises:

HTTPException – Possible values for type:

Value

Reason

InvalidOperation

You tried to retrieve mutuals with yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to view user profile.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The found mutuals.

Return type:

name¶

The username of the user.

Type:: str

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

This function is a coroutine.

Retrieve a DM (or create if it doesn’t exist) with another user.

If target is current user, a SavedMessagesChannel is always returned.

You must have send_messages to do this.

May fire PrivateChannelCreateEvent for the current user and user you opened DM with.

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.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to open DM with this user.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The private channel.

Return type:

property pm[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property pm_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

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

This function is a coroutine.

Removes the user from friend list.

Fires UserRelationshipUpdateEvent for the current user and user you removed from friend list.

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

IsBot

Either the current user or user you tried to deny friend request from are bot accounts.
NoEffect – You tried to deny friend request from user you had no friend request sent from/to.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you removed from friend list.

Return type:

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)[source]¶

This function is a coroutine.

Report the user to the instance moderation team.

Fires ReportCreateEvent internally (but not fired over WebSocket).

Note

This can only be used by non-bot accounts.

Parameters:

reason (UserReportReason) – The reason for reporting user.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
additional_context (Optional[str]) – The additional context for moderation team. Can be only up to 1000 characters.
message_context (Optional[ULIDOr[BaseMessage]]) –
The message context.

Internally, 15 messages around provided message will be snapshotted for context. All attachments of provided message are snapshotted as well.

Raises:

HTTPException – Possible values for type:

Value

Reason

CannotReportYourself

You tried to report yourself.

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

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

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

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:

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

This function is a coroutine.

Sends a friend request to this user.

Fires UserRelationshipUpdateEvent for the current user and user you sent friend request to.

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
`InvalidProperty`	You did not provide a discriminator.
`IsBot`	Either the current user or user you tried to accept friend request from are bot accounts.
`TooManyPendingFriendRequests`	You sent too many outgoing friend requests.

NoEffect – You tried to accept friend request from yourself.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

BlockedOther

The user you tried to send friend request to have blocked you.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.

Conflict – Possible values for type:

Value	Reason
`AlreadyFriends`	You’re already friends with user you tried to send friend request to.
`AlreadySentRequest`	You already sent friend request to this user.
`Blocked`	You have blocked the user you tried to send friend request to.

InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The user you sent friend request to.

Return type:

state¶

The state that controls this entity.

Type:: State

property tag[source]¶

The tag of the user.

Assuming that User.name is 'kotlin.Unit' and User.discriminator is '3510', example output would be 'kotlin.Unit#3510'.

Type:: str

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

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

This function is a coroutine.

Unblocks an user.

Fires UserRelationshipUpdateEvent for the current user and unblocked user.

Note

This is not supposed to be used by bot accounts.

Parameters:

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

Raises:

NoEffect – You tried to block yourself or someone that you didn’t had blocked.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

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

Value

Reason

NotFound

The user 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 wrong during unblocking user.

Returns:

The unblocked user.

Return type:

is_deleted()[source]¶: bool: Whether this user is deleted his account.

is_banned()[source]¶: bool: Whether this user is banned off the platform.

is_spammer()[source]¶: bool: Whether this user was marked as spam and removed from platform.

is_developer()[source]¶: bool: Whether this user is Stoat developer.

is_translator()[source]¶: bool: Whether this user helped translate Stoat.

is_supporter()[source]¶: bool: Whether this user monetarily supported Stoat.

is_responsible_disclosure()[source]¶: bool: Whether this user responsibly disclosed a security issue.

is_founder()[source]¶: bool: Whether this user is Stoat founder.

is_platform_moderator()[source]¶: bool: Whether this user is platform moderator.

is_active_supporter()[source]¶: bool: Whether this user is active monetary supporter.

is_paw()[source]¶: bool: Whether this user likes fox/raccoon (🦊🦝).

is_early_adopter()[source]¶: bool: Whether this user have joined Stoat as one of the first 1000 users in 2021.

is_relevant_joke_1()[source]¶: bool: Whether this user have given funny joke (Called “sus”, displayed as Amogus in Revite).

is_relevant_joke_2()[source]¶: bool: Whether this user have given other funny joke (Called as “It’s Morbin Time” in Revite).

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

OwnUser¶

Methods

async acknowledge
async begin_typing
async connect
async edit
async end_typing
async fetch
async fetch_channel_id
async fetch_default_avatar
async fetch_flags
async fetch_message
async fetch_profile
def get_bot_owner
def get_channel_id
def get_message
async history
def is_active_supporter
def is_banned
def is_deleted
def is_developer
def is_early_adopter
def is_founder
def is_paw
def is_platform_moderator
def is_relevant_joke_1
def is_relevant_joke_2
def is_responsible_disclosure
def is_sentinel
def is_spammer
def is_supporter
def is_suspended
def is_translator
async join_call
def locally_update
async open_dm
async search
async send
def to_dict
def typing

class stoat.OwnUser(*, state, id, name, discriminator, internal_avatar, display_name, raw_badges, status, raw_flags, privileged, bot, relationship, online, relations)[source]¶

Represents a current user on Stoat.

This inherits from User.

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.

property avatar[source]¶

The avatar of the user.

Type:: Optional[Asset]

property badges[source]¶

The user’s badges.

Type:: UserBadges

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

bot¶

The information about the bot.

Type:: Optional[BotUserMetadata]

property bot_owner[source]¶

Returns the user who created this bot user.

Type:: Optional[User]

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.

property default_avatar_url[source]¶

The URL to user’s default avatar.

Type:: str

discriminator¶

The discriminator of the user.

Type:: str

property display_avatar_url[source]¶

The URL to user’s avatar, or their default avatar if they have none set.

Type:: str

display_name¶

The user’s display name.

Type:: Optional[str]

property dm_channel[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property dm_channel_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

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

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

This function is a coroutine.

Retrieve user’s information.

You must have access 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user.

Return type:

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_default_avatar(*, http_overrides=None)[source]¶

This function is a coroutine.

Return a default user avatar based on the given ID.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The image in PNG format.
Return type:: bytes

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

This function is a coroutine.

Retrieves flags for user.

Parameters:: http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
Returns:: The retrieved flags.
Return type:: UserFlags

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_profile(*, http_overrides=None)[source]¶

This function is a coroutine.

Retrieve profile of an user.

You must have view_profile 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

MissingUserPermission

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

Value

Reason

NotFound

The user was not found.

Returns:

The retrieved user profile.

Return type:

property flags[source]¶

The user’s badges.

Type:: UserFlags

get_bot_owner()[source]¶

Returns the user who created this bot user.

Returns:: The bot owner and their ID (may be empty if user is not a bot).
Return type:: Tuple[Optional[User], str]

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

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

internal_avatar¶

The stateless avatar of the user.

Type:: Optional[StatelessAsset]

is_active_supporter()[source]¶: bool: Whether this user is active monetary supporter.

is_banned()[source]¶: bool: Whether this user is banned off the platform.

is_deleted()[source]¶: bool: Whether this user is deleted his account.

is_developer()[source]¶: bool: Whether this user is Stoat developer.

is_early_adopter()[source]¶: bool: Whether this user have joined Stoat as one of the first 1000 users in 2021.

is_founder()[source]¶: bool: Whether this user is Stoat founder.

is_paw()[source]¶: bool: Whether this user likes fox/raccoon (🦊🦝).

is_platform_moderator()[source]¶: bool: Whether this user is platform moderator.

is_relevant_joke_1()[source]¶: bool: Whether this user have given funny joke (Called “sus”, displayed as Amogus in Revite).

is_relevant_joke_2()[source]¶: bool: Whether this user have given other funny joke (Called as “It’s Morbin Time” in Revite).

is_responsible_disclosure()[source]¶: bool: Whether this user responsibly disclosed a security issue.

is_sentinel()[source]¶: bool: Returns whether the user is sentinel (Stoat#0000).

is_spammer()[source]¶: bool: Whether this user was marked as spam and removed from platform.

is_supporter()[source]¶: bool: Whether this user monetarily supported Stoat.

is_suspended()[source]¶: bool: Whether this user has been suspended from the platform.

is_translator()[source]¶: bool: Whether this user helped translate Stoat.

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]

locally_update(data, /)[source]¶: Locally updates user with provided data.

Warning

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

property mention[source]¶

The user mention.

Type:: str

property messages[source]¶

Returns all messages in this channel.

Type:: Mapping[str, Message]

name¶

The username of the user.

Type:: str

online¶

Whether the user is currently online.

Type:: bool

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

This function is a coroutine.

Retrieve a DM (or create if it doesn’t exist) with another user.

If target is current user, a SavedMessagesChannel is always returned.

You must have send_messages to do this.

May fire PrivateChannelCreateEvent for the current user and user you opened DM with.

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.
NotFound – Possible values for type:

Value

Reason

NotFound

The user was not found.
Forbidden – Possible values for type:

Value

Reason

MissingUserPermission

You do not have the proper permissions to open DM with this user.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The private channel.

Return type:

property pm[source]¶

The private channel with this user.

Type:: Optional[DMChannel]

property pm_id[source]¶

The ID of the private channel with this user.

Type:: Optional[str]

privileged¶

Whether the user is privileged.

Type:: bool

raw_badges¶

The user’s badges raw value.

Type:: int

raw_flags¶

The user’s flags raw value.

Type:: int

relationship¶

The current user’s relationship with this user.

Type:: RelationshipStatus

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: