Server Members

The following section documents everything related to server members.

Models

BaseMember

Attributes

• avatar
• badges
• bot
• bot_owner
• default_avatar_url
• discriminator
• display_name
• dm_channel
• dm_channel_id
• flags
• id
• internal_avatar
• internal_user
• mention
• messages
• name
• online
• pm
• pm_id
• privileged
• raw_badges
• raw_flags
• relationship
• server_id
• state
• status
• tag
• user

Methods

• async acknowledge
• async ban
• async begin_typing
• async connect
• async edit
• async end_typing
• def eq
• 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
• def get_server
• def get_user
• async history
• def is_sentinel
• async join_call
• async kick
• async mutual_friend_ids
• async mutual_server_ids
• async mutuals
• def ne
• async open_dm
• async remove_friend
• async report
• async search
• async send
• async timeout
• def typing
• async unblock

class stoat.BaseMember(*, state, server_id, internal_user)

Represents a Stoat base member to a Server.

This inherits from Connectable and Messageable.

state

State that controls this member.

Type:

State

server_id

The server’s ID the member in.

Type:

str

internal_user

The ID of the user, or full user instance.

Type:

Union[User, str]

get_bot_owner()

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()

str: Retrieves the channel’s ID, if possible.

get_server()

Optional[Server]: The server this member belongs to.

get_user()

Optional[User]: The user.

eq(other, /)

bool: Checks whether two members are equal.

Added in version 1.2.

ne(other, /)

bool: Checks whether two members are not equal.

Added in version 1.2.

property user

The user.

Type:

User

property bot_owner

Returns the user who created this bot user.

Type:

Optional[User]

property id

The ID of the member user.

Type:

str

property default_avatar_url

The URL to member user’s default avatar.

Type:

str

property mention

The member user mention.

Type:

str

property dm_channel_id

The ID of the private channel with this member.

Type:

Optional[str]

property pm_id

The ID of the private channel with this member.

Type:

Optional[str]

property dm_channel

The private channel with this member.

Type:

Optional[DMChannel]

property pm

The private channel with this member.

Type:

Optional[DMChannel]

property name

The member’s username.

Type:

str

property discriminator

The member user’s discriminator.

Type:

str

property display_name

The member user’s display name.

Type:

Optional[str]

property internal_avatar

The stateless avatar of the member user.

Type:

Optional[StatelessAsset]

property avatar

The avatar of the member user.

Type:

Optional[Asset]

property raw_badges

The member user’s badges raw value.

Type:

int

property badges

The member user’s badges.

Type:

UserBadges

property status

The current member user’s status.

Type:

Optional[UserStatus]

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)

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)

Begins typing in channel, until end_typing() is called.

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)

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

Parameters:

• channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

• node (Optional[str]) –

  The node’s name to use for starting a call.

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

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

  Added in version 1.2.

Raises:

• HTTPException – Possible values for type:

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

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to join a call.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation
  InternalError	Somehow something went during retrieving token.

• TypeError – If livekit dependency is not installed.

await end_typing(*, http_overrides=None)

Ends typing in channel.

await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)

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:

Message

get_message(message_id, /)

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)

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]

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)

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 messages

Returns all messages in this channel.

Type:

Mapping[str, Message]

property raw_flags

The member user’s flags raw value.

Type:

int

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

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)

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:

Message

typing()

Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

property flags

The member user’s flags.

Type:

UserFlags

property privileged

Whether the member user is privileged.

Type:

bool

property bot

The information about the bot.

Type:

Optional[BotUserMetadata]

property relationship

The current user’s relationship with this member user.

Type:

RelationshipStatus

property online

Whether the member user is currently online.

Type:

bool

property tag

The tag of the member user.

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

Type:

str

await ban(*, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

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

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await fetch_channel_id(*, http_overrides=None)

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)

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)

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)

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:

UserProfile

await edit(*, http_overrides=None, nick=UNDEFINED, avatar=UNDEFINED, roles=UNDEFINED, timeout=UNDEFINED, can_publish=UNDEFINED, can_receive=UNDEFINED, voice=UNDEFINED)

This function is a coroutine.

Edits the member.

Fires ServerMemberUpdateEvent for all server members, and optionally fires multiple/single ServerChannelCreateEvent / ChannelDeleteEvent events for target member if roles parameter is provided.

For Livekit instances:

• If voice parameter is provided, fires VoiceChannelMoveEvent / VoiceChannelLeaveEvent if specified as None, otherwise VoiceChannelLeaveEvent is fired. The specified events are fired for all users who can see voice channel the member is currently in.

• If any of roles, can_publish or can_receive parameters is provided, may fire UserVoiceStateUpdateEvent for all users who can see voice channel the member is currently in.

Parameters:

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

• nick (UndefinedOr[Optional[str]]) –

  The member’s new nick. Use None to remove the nickname.

  To provide this, you must have manage_nicknames if changing other member’s nick. Otherwise, change_nickname is required instead.

• avatar (UndefinedOr[Optional[ResolvableResource]]) –

  The member’s new avatar. Use None to remove the avatar.

  You can only change your own server avatar.

  You must have change_avatar to provide this.

• roles (UndefinedOr[Optional[List[ULIDOr[BaseRole]]]]) –

  The member’s new list of roles. This replaces the roles.

  You must have assign_roles to provide this.

• timeout (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

  If the member has timeout_members, this will throw a NonElevated error.

  You must have timeout_members to provide this.

• can_publish (UndefinedOr[Optional[bool]]) –

  Whether the member should send voice data.

  You must have mute_members to provide this.

• can_receive (UndefinedOr[Optional[bool]]) –

  Whether the member should receive voice data.

  You must have deafen_members to provide this.

• voice (UndefinedOr[Optional[ULIDOr[Union[TextChannel, VoiceChannel]]]]) –

  The voice channel to move the member to.

  You must have move_members to provide this.

  Changed in version 1.3: Members can be kicked from the current voice channel.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.
  LivekitUnavailable	The voice server is unavailable. Only applicable to instances using Livekit.
  NotAVoiceChannel	The channel passed in voice parameter was not voice-like channel. Only 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
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.
  NotElevated	Ranking of one of roles you tried to add is lower than ranking of your top role.

• NotFound – Possible values for type:

  Value	Reason
  InvalidRole	One of provided roles passed in roles parameter was not found.
  NotFound	The server/member was not found.
  UnknownChannel	The channel passed in voice parameter 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 editing member.

Returns:

The newly updated member.

Return type:

Member

await kick(*, http_overrides=None)

This function is a coroutine.

Kicks the member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

await mutual_friend_ids(*, http_overrides=None)

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)

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)

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:

Mutuals

await open_dm(*, http_overrides=None)

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:

Union[SavedMessagesChannel, DMChannel]

await remove_friend(*, http_overrides=None)

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:

User

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)

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 timeout(length, *, http_overrides=None)

This function is a coroutine.

Timeouts the member.

If the member has timeout_members, this will throw a NonElevated error.

You must have timeout_members to do this.

Fires ServerMemberUpdateEvent for all server members.

Parameters:

• length (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/member 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 editing member.

Returns:

The newly updated member.

Return type:

Member

await unblock(*, http_overrides=None)

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

is_sentinel()

bool: Returns whether the user is sentinel (Stoat#0000).

PartialMember

Attributes

• avatar
• badges
• bot
• bot_owner
• can_publish
• can_receive
• default_avatar_url
• discriminator
• display_name
• dm_channel
• dm_channel_id
• flags
• id
• internal_avatar
• internal_server_avatar
• internal_user
• mention
• messages
• name
• nick
• online
• pm
• pm_id
• privileged
• raw_badges
• raw_flags
• relationship
• role_ids
• server_avatar
• server_id
• state
• status
• tag
• timed_out_until
• user

Methods

• async acknowledge
• async ban
• async begin_typing
• async connect
• async edit
• async end_typing
• def eq
• 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
• def get_server
• def get_user
• async history
• def is_sentinel
• async join_call
• async kick
• async mutual_friend_ids
• async mutual_server_ids
• async mutuals
• def ne
• async open_dm
• async remove_friend
• async report
• async search
• async send
• async timeout
• def typing
• async unblock

class stoat.PartialMember(*, state, server_id, internal_user, nick, internal_server_avatar, role_ids, timed_out_until, can_publish, can_receive)

Represents a partial Stoat member to a Server.

Unmodified fields will have UNDEFINED value.

This inherits from BaseMember.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)

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

The avatar of the member user.

Type:

Optional[Asset]

property badges

The member user’s badges.

Type:

UserBadges

await ban(*, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

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

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await begin_typing(*, http_overrides=None)

Begins typing in channel, until end_typing() is called.

property bot

The information about the bot.

Type:

Optional[BotUserMetadata]

property bot_owner

Returns the user who created this bot user.

Type:

Optional[User]

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)

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

The URL to member user’s default avatar.

Type:

str

property discriminator

The member user’s discriminator.

Type:

str

property display_name

The member user’s display name.

Type:

Optional[str]

property dm_channel

The private channel with this member.

Type:

Optional[DMChannel]

property dm_channel_id

The ID of the private channel with this member.

Type:

Optional[str]

await edit(*, http_overrides=None, nick=UNDEFINED, avatar=UNDEFINED, roles=UNDEFINED, timeout=UNDEFINED, can_publish=UNDEFINED, can_receive=UNDEFINED, voice=UNDEFINED)

This function is a coroutine.

Edits the member.

Fires ServerMemberUpdateEvent for all server members, and optionally fires multiple/single ServerChannelCreateEvent / ChannelDeleteEvent events for target member if roles parameter is provided.

For Livekit instances:

• If voice parameter is provided, fires VoiceChannelMoveEvent / VoiceChannelLeaveEvent if specified as None, otherwise VoiceChannelLeaveEvent is fired. The specified events are fired for all users who can see voice channel the member is currently in.

• If any of roles, can_publish or can_receive parameters is provided, may fire UserVoiceStateUpdateEvent for all users who can see voice channel the member is currently in.

Parameters:

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

• nick (UndefinedOr[Optional[str]]) –

  The member’s new nick. Use None to remove the nickname.

  To provide this, you must have manage_nicknames if changing other member’s nick. Otherwise, change_nickname is required instead.

• avatar (UndefinedOr[Optional[ResolvableResource]]) –

  The member’s new avatar. Use None to remove the avatar.

  You can only change your own server avatar.

  You must have change_avatar to provide this.

• roles (UndefinedOr[Optional[List[ULIDOr[BaseRole]]]]) –

  The member’s new list of roles. This replaces the roles.

  You must have assign_roles to provide this.

• timeout (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

  If the member has timeout_members, this will throw a NonElevated error.

  You must have timeout_members to provide this.

• can_publish (UndefinedOr[Optional[bool]]) –

  Whether the member should send voice data.

  You must have mute_members to provide this.

• can_receive (UndefinedOr[Optional[bool]]) –

  Whether the member should receive voice data.

  You must have deafen_members to provide this.

• voice (UndefinedOr[Optional[ULIDOr[Union[TextChannel, VoiceChannel]]]]) –

  The voice channel to move the member to.

  You must have move_members to provide this.

  Changed in version 1.3: Members can be kicked from the current voice channel.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.
  LivekitUnavailable	The voice server is unavailable. Only applicable to instances using Livekit.
  NotAVoiceChannel	The channel passed in voice parameter was not voice-like channel. Only 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
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.
  NotElevated	Ranking of one of roles you tried to add is lower than ranking of your top role.

• NotFound – Possible values for type:

  Value	Reason
  InvalidRole	One of provided roles passed in roles parameter was not found.
  NotFound	The server/member was not found.
  UnknownChannel	The channel passed in voice parameter 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 editing member.

Returns:

The newly updated member.

Return type:

Member

await end_typing(*, http_overrides=None)

Ends typing in channel.

eq(other, /)

bool: Checks whether two members are equal.

Added in version 1.2.

await fetch_channel_id(*, http_overrides=None)

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)

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)

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)

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:

Message

await fetch_profile(*, http_overrides=None)

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:

UserProfile

property flags

The member user’s flags.

Type:

UserFlags

get_bot_owner()

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()

str: Retrieves the channel’s ID, if possible.

get_message(message_id, /)

Retrieves a channel message from cache.

Parameters:

message_id (str) – The message ID.

Returns:

The message or None if not found.

Return type:

Optional[Message]

get_server()

Optional[Server]: The server this member belongs to.

get_user()

Optional[User]: The user.

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

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

• channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

• limit (Optional[int]) –

  The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

  If nearby is provided, then this is (limit + 2).

• before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.

• after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.

• sort (Optional[MessageSort]) – The message sort direction. Defaults to latest

• nearby (Optional[ULIDOr[BaseMessage]]) –

  The message to search around.

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

  It will also take half of limit rounded as the limits to each side. It also fetches the message specified.

• populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to read the message history.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

property id

The ID of the member user.

Type:

str

property internal_avatar

The stateless avatar of the member user.

Type:

Optional[StatelessAsset]

internal_user

The ID of the user, or full user instance.

Type:

Union[User, str]

is_sentinel()

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)

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]

await kick(*, http_overrides=None)

This function is a coroutine.

Kicks the member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

property mention

The member user mention.

Type:

str

property messages

Returns all messages in this channel.

Type:

Mapping[str, Message]

await mutual_friend_ids(*, http_overrides=None)

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)

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)

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:

Mutuals

property name

The member’s username.

Type:

str

ne(other, /)

bool: Checks whether two members are not equal.

Added in version 1.2.

property online

Whether the member user is currently online.

Type:

bool

await open_dm(*, http_overrides=None)

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:

Union[SavedMessagesChannel, DMChannel]

property pm

The private channel with this member.

Type:

Optional[DMChannel]

property pm_id

The ID of the private channel with this member.

Type:

Optional[str]

property privileged

Whether the member user is privileged.

Type:

bool

property raw_badges

The member user’s badges raw value.

Type:

int

property raw_flags

The member user’s flags raw value.

Type:

int

property relationship

The current user’s relationship with this member user.

Type:

RelationshipStatus

await remove_friend(*, http_overrides=None)

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:

User

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)

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)

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)

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:

Message

server_id

The server’s ID the member in.

Type:

str

state

State that controls this member.

Type:

State

property status

The current member user’s status.

Type:

Optional[UserStatus]

property tag

The tag of the member user.

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

Type:

str

await timeout(length, *, http_overrides=None)

This function is a coroutine.

Timeouts the member.

If the member has timeout_members, this will throw a NonElevated error.

You must have timeout_members to do this.

Fires ServerMemberUpdateEvent for all server members.

Parameters:

• length (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/member 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 editing member.

Returns:

The newly updated member.

Return type:

Member

typing()

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)

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

property user

The user.

Type:

User

nick

The new member’s nick.

Type:

UndefinedOr[Optional[str]]

internal_server_avatar

The new member’s avatar.

Type:

UndefinedOr[Optional[StatelessAsset]]

role_ids

The new member’s roles.

Type:

UndefinedOr[List[str]]

timed_out_until

When member’s time out expires now.

Type:

UndefinedOr[Optional[datetime]]

can_publish

Whether the member can send voice data now.

Type:

UndefinedOr[Optional[bool]]

can_receive

Whether the member can receive voice data now.

Type:

UndefinedOr[Optional[bool]]

property server_avatar

The member’s avatar on server.

Type:

UndefinedOr[Optional[Asset]]

Member

Attributes

• avatar
• badges
• bot
• bot_owner
• can_publish
• can_receive
• default_avatar_url
• discriminator
• display_name
• dm_channel
• dm_channel_id
• flags
• id
• internal_avatar
• internal_server_avatar
• internal_user
• joined_at
• mention
• messages
• name
• nick
• online
• pm
• pm_id
• privileged
• raw_badges
• raw_flags
• relationship
• role_ids
• roles
• server_avatar
• server_id
• server_permissions
• state
• status
• tag
• timed_out_until
• top_role
• user

Methods

• async acknowledge
• async ban
• async begin_typing
• async connect
• async edit
• async end_typing
• def eq
• 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
• def get_server
• def get_user
• async history
• def is_sentinel
• async join_call
• async kick
• def locally_update
• async mutual_friend_ids
• async mutual_server_ids
• async mutuals
• def ne
• async open_dm
• async remove_friend
• async report
• async search
• async send
• async timeout
• def to_dict
• def typing
• async unblock

class stoat.Member(*, state, server_id, internal_user, joined_at, nick, internal_server_avatar, role_ids, timed_out_until, can_publish, can_receive)

Represents a Stoat member to a Server.

This inherits from BaseMember.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)

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

The avatar of the member user.

Type:

Optional[Asset]

property badges

The member user’s badges.

Type:

UserBadges

await ban(*, http_overrides=None, reason=None)

This function is a coroutine.

Bans an user from the server.

You must have ban_members to do this.

May fire ServerMemberRemoveEvent for banned user and all server members.

Parameters:

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

• reason (Optional[str]) – The ban reason. Can be only up to 1024 characters long.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to ban yourself.
  FailedValidation	The payload was invalid.
  InvalidOperation	You tried to ban server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The created ban.

Return type:

Ban

await begin_typing(*, http_overrides=None)

Begins typing in channel, until end_typing() is called.

property bot

The information about the bot.

Type:

Optional[BotUserMetadata]

property bot_owner

Returns the user who created this bot user.

Type:

Optional[User]

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)

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

The URL to member user’s default avatar.

Type:

str

property discriminator

The member user’s discriminator.

Type:

str

property display_name

The member user’s display name.

Type:

Optional[str]

property dm_channel

The private channel with this member.

Type:

Optional[DMChannel]

property dm_channel_id

The ID of the private channel with this member.

Type:

Optional[str]

await edit(*, http_overrides=None, nick=UNDEFINED, avatar=UNDEFINED, roles=UNDEFINED, timeout=UNDEFINED, can_publish=UNDEFINED, can_receive=UNDEFINED, voice=UNDEFINED)

This function is a coroutine.

Edits the member.

Fires ServerMemberUpdateEvent for all server members, and optionally fires multiple/single ServerChannelCreateEvent / ChannelDeleteEvent events for target member if roles parameter is provided.

For Livekit instances:

• If voice parameter is provided, fires VoiceChannelMoveEvent / VoiceChannelLeaveEvent if specified as None, otherwise VoiceChannelLeaveEvent is fired. The specified events are fired for all users who can see voice channel the member is currently in.

• If any of roles, can_publish or can_receive parameters is provided, may fire UserVoiceStateUpdateEvent for all users who can see voice channel the member is currently in.

Parameters:

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

• nick (UndefinedOr[Optional[str]]) –

  The member’s new nick. Use None to remove the nickname.

  To provide this, you must have manage_nicknames if changing other member’s nick. Otherwise, change_nickname is required instead.

• avatar (UndefinedOr[Optional[ResolvableResource]]) –

  The member’s new avatar. Use None to remove the avatar.

  You can only change your own server avatar.

  You must have change_avatar to provide this.

• roles (UndefinedOr[Optional[List[ULIDOr[BaseRole]]]]) –

  The member’s new list of roles. This replaces the roles.

  You must have assign_roles to provide this.

• timeout (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

  If the member has timeout_members, this will throw a NonElevated error.

  You must have timeout_members to provide this.

• can_publish (UndefinedOr[Optional[bool]]) –

  Whether the member should send voice data.

  You must have mute_members to provide this.

• can_receive (UndefinedOr[Optional[bool]]) –

  Whether the member should receive voice data.

  You must have deafen_members to provide this.

• voice (UndefinedOr[Optional[ULIDOr[Union[TextChannel, VoiceChannel]]]]) –

  The voice channel to move the member to.

  You must have move_members to provide this.

  Changed in version 1.3: Members can be kicked from the current voice channel.

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.
  LivekitUnavailable	The voice server is unavailable. Only applicable to instances using Livekit.
  NotAVoiceChannel	The channel passed in voice parameter was not voice-like channel. Only 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
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.
  NotElevated	Ranking of one of roles you tried to add is lower than ranking of your top role.

• NotFound – Possible values for type:

  Value	Reason
  InvalidRole	One of provided roles passed in roles parameter was not found.
  NotFound	The server/member was not found.
  UnknownChannel	The channel passed in voice parameter 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 editing member.

Returns:

The newly updated member.

Return type:

Member

await end_typing(*, http_overrides=None)

Ends typing in channel.

eq(other, /)

bool: Checks whether two members are equal.

Added in version 1.2.

await fetch_channel_id(*, http_overrides=None)

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)

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)

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)

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:

Message

await fetch_profile(*, http_overrides=None)

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:

UserProfile

property flags

The member user’s flags.

Type:

UserFlags

get_bot_owner()

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()

str: Retrieves the channel’s ID, if possible.

get_message(message_id, /)

Retrieves a channel message from cache.

Parameters:

message_id (str) – The message ID.

Returns:

The message or None if not found.

Return type:

Optional[Message]

get_server()

Optional[Server]: The server this member belongs to.

get_user()

Optional[User]: The user.

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

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

• channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

• limit (Optional[int]) –

  The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

  If nearby is provided, then this is (limit + 2).

• before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.

• after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.

• sort (Optional[MessageSort]) – The message sort direction. Defaults to latest

• nearby (Optional[ULIDOr[BaseMessage]]) –

  The message to search around.

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

  It will also take half of limit rounded as the limits to each side. It also fetches the message specified.

• populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  MissingPermission	You do not have the proper permissions to read the message history.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The channel was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

Returns:

The messages retrieved.

Return type:

List[Message]

property id

The ID of the member user.

Type:

str

property internal_avatar

The stateless avatar of the member user.

Type:

Optional[StatelessAsset]

internal_user

The ID of the user, or full user instance.

Type:

Union[User, str]

is_sentinel()

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)

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]

await kick(*, http_overrides=None)

This function is a coroutine.

Kicks the member from the server.

Fires ServerMemberRemoveEvent for kicked user and all server members.

Parameters:

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotRemoveYourself	You tried to kick yourself.
  InvalidOperation	You tried to kick server owner.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  NotElevated	Rank of your top role is higher than rank of top role of user you’re trying to ban.
  MissingPermission	You do not have the proper permissions to ban members.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/user was not found.

• InternalServerError – Possible values for type:

  Value	Reason	Populated attributes
  DatabaseError	Something went wrong during querying database.	collection, operation

property mention

The member user mention.

Type:

str

property messages

Returns all messages in this channel.

Type:

Mapping[str, Message]

await mutual_friend_ids(*, http_overrides=None)

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)

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)

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:

Mutuals

property name

The member’s username.

Type:

str

ne(other, /)

bool: Checks whether two members are not equal.

Added in version 1.2.

property online

Whether the member user is currently online.

Type:

bool

await open_dm(*, http_overrides=None)

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:

Union[SavedMessagesChannel, DMChannel]

property pm

The private channel with this member.

Type:

Optional[DMChannel]

property pm_id

The ID of the private channel with this member.

Type:

Optional[str]

property privileged

Whether the member user is privileged.

Type:

bool

property raw_badges

The member user’s badges raw value.

Type:

int

property raw_flags

The member user’s flags raw value.

Type:

int

property relationship

The current user’s relationship with this member user.

Type:

RelationshipStatus

await remove_friend(*, http_overrides=None)

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:

User

await report(reason, *, http_overrides=None, additional_context=None, message_context=None)

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)

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)

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:

Message

server_id

The server’s ID the member in.

Type:

str

state

State that controls this member.

Type:

State

property status

The current member user’s status.

Type:

Optional[UserStatus]

property tag

The tag of the member user.

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

Type:

str

await timeout(length, *, http_overrides=None)

This function is a coroutine.

Timeouts the member.

If the member has timeout_members, this will throw a NonElevated error.

You must have timeout_members to do this.

Fires ServerMemberUpdateEvent for all server members.

Parameters:

• length (UndefinedOr[Optional[Union[datetime, timedelta, float, int]]]) –

  The duration/date the member’s timeout should expire, or None to remove the timeout.

  This must be a timezone-aware datetime object. Consider using stoat.utils.utcnow().

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

Raises:

• HTTPException – Possible values for type:

  Value	Reason
  CannotTimeoutYourself	You tried to time out yourself.

• Unauthorized – Possible values for type:

  Value	Reason
  InvalidSession	The current bot/user token is invalid.

• Forbidden – Possible values for type:

  Value	Reason
  IsElevated	The member has timeout_members, and as such cannot be timed out.
  MissingPermission	You do not have the proper permissions to edit this member.

• NotFound – Possible values for type:

  Value	Reason
  NotFound	The server/member 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 editing member.

Returns:

The newly updated member.

Return type:

Member

typing()

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)

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

property user

The user.

Type:

User

joined_at

When the member joined the server.

Type:

datetime

nick

The member’s nick.

Type:

Optional[str]

internal_server_avatar

The member’s avatar on server.

Type:

Optional[StatelessAsset]

role_ids

The member’s roles.

Type:

List[str]

timed_out_until

The timestamp this member is timed out until.

Type:

Optional[datetime]

can_publish

Whether the member can send voice data.

Type:

bool

can_receive

Whether the member can receive voice data.

Type:

bool

locally_update(data, /)

Locally updates member with provided data.

Warning

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

Parameters:

data (PartialMember) – The data to update member with.

property roles

The member’s roles.

Type:

List[Role]

property server_avatar

The member’s avatar on server.

Type:

Optional[Asset]

property server_permissions

The permissions for this member in the server.

Type:

Permissions

property top_role

The member’s top role.

Type:

Optional[Role]

to_dict()

dict: Convert server member to raw data.

MemberList

Attributes

• members
• users

class stoat.MemberList(*, members, users)

A list of members in a server.

members

The members in server.

Type:

List[Member]

users

The users.

Type:

List[User]