User and DM HTTP Methods for the alterself REST API Guide

User operations in alterself range from looking up another account’s public profile to modifying your own avatar and display name. All methods live on bot.http, the library’s shared HTTP client, and are async — you must await every call. The client automatically applies rate-limit management and realistic browser headers on every request, keeping your traffic consistent with a normal Discord session.

User Methods

fetch_me

Fetch the full User object for your own account.

me = await bot.http.fetch_me()

Returns: A dict representing your own User object, including your id, username, global_name, discriminator, avatar, and account flags.

fetch_user

Retrieve publicly available information about any Discord user by their ID.

user = await bot.http.fetch_user(user_id)

int | str

required

The ID of the user to look up.

Returns: A partial User object dict containing publicly visible fields only. You will not receive email, phone, or other private fields for other users.

fetch_profile

Retrieve a user’s full public profile, including mutual guilds, mutual friends, connected accounts, and premium (Nitro) status. Optionally scope the lookup to a specific guild for server-specific details like the member’s nickname and roles.

profile = await bot.http.fetch_profile(user_id)
profile = await bot.http.fetch_profile(user_id, guild_id=guild_id)

int | str

required

The ID of the user whose profile you want to fetch.

int | str

When provided, the response includes guild-specific member data such as the user’s server nickname, roles, and join date for that guild.

Returns: A dict containing the user’s user object, connected_accounts, mutual_guilds, mutual_friends, and premium information.

Profile fetches are rate-limited more aggressively than standard user lookups. Avoid fetching large numbers of profiles in rapid succession.

edit_me

Modify your own account’s username, display name, avatar, or other settings.

me = await bot.http.edit_me(
    username    = "newname",
    global_name = "Display Name",
    # avatar: pass base64-encoded "data:image/png;base64,..." string
)

str

Your new username. Must be unique across Discord and between 2 and 32 characters. Changing your username may alter your discriminator.

str

Your new display name (shown in place of your username in most UI surfaces). Between 1 and 32 characters.

str

A base64-encoded image string in the format "data:image/png;base64,<data>". JPEG and GIF are also accepted. Pass null to remove your avatar.

str

A base64-encoded image string for your profile banner. Requires an active Nitro subscription.

Returns: The updated User object as a dict.

Discord rate-limits username changes strictly — you can only change your username a limited number of times. Rapid automated changes can trigger account verification prompts.

To load an avatar from a file, read it and encode it yourself before passing it to edit_me:

import base64

with open("avatar.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

await bot.http.edit_me(avatar=f"data:image/png;base64,{b64}")

fetch_me_guilds

Retrieve a list of all guilds your account is currently a member of.

guilds = await bot.http.fetch_me_guilds()

Returns: A list[dict] of partial Guild objects. Each entry includes the guild’s id, name, icon, owner flag, and your permission bitfield for that guild.

fetch_connections

Retrieve the list of third-party accounts (Twitch, YouTube, GitHub, Steam, etc.) connected to your Discord account.

conns = await bot.http.fetch_connections()

Returns: A list[dict], each representing a connected account with fields like type, id, name, and verified.

DMs and Relationships

open_dm

Open (or re-open) a Direct Message channel with another user. If a DM channel already exists, Discord returns the existing one.

dm = await bot.http.open_dm(user_id)

int | str

required

The ID of the user you want to open a DM with.

Returns: A Channel object dict of type 1 (DM). Use dm["id"] as the channel_id for subsequent send_message calls.

fetch_relationships

Retrieve all relationships on your account — friends, pending incoming/outgoing friend requests, and blocked users.

rels = await bot.http.fetch_relationships()

Returns: A list[dict], each containing a type integer and a partial user object.

`type`	Meaning
`1`	Friend
`2`	Blocked
`3`	Incoming friend request
`4`	Outgoing friend request

add_friend

Send a friend request to another user.

await bot.http.add_friend(user_id)

int | str

required

The ID of the user to send a friend request to.

Returns: None on success.

remove_friend

Unfriend a user or cancel a pending friend request.

await bot.http.remove_friend(user_id)

int | str

required

The ID of the user to remove from your friends list.

Returns: None on success.

block_user

Block a user. Blocked users cannot send you friend requests or DMs.

await bot.http.block_user(user_id)

int | str

required

The ID of the user to block.

Returns: None on success.

Raw Requests

When you need to call a Discord endpoint that alterself doesn’t yet wrap with a dedicated method, you can drop down to the raw request method. Construct an Endpoint object with the HTTP verb and path, then pass it directly to bot.http.request. All rate-limit management, header spoofing, and retry logic still applies — you get the full benefit of the client without being limited to the built-in helpers.

from alterself.http.route import Endpoint

ep   = Endpoint("GET", "/users/@me/affinities/guilds")
data = await bot.http.request(ep)

Endpoint

required

An Endpoint instance created via Endpoint(method, path) where method is an HTTP verb string ("GET", "POST", "PATCH", "DELETE", etc.) and path is the Discord API path starting with /.

dict

A JSON-serialisable dict to send as the request body. Used for POST, PATCH, and PUT requests.

dict

Query string parameters to append to the URL.

Returns: The parsed JSON response as a dict or list, depending on the endpoint. Returns None for endpoints that respond with 204 No Content.

Check the Discord API documentation for a full list of available endpoints and their required fields when using raw requests.

Rate Limits

alterself’s HTTP client manages Discord’s complex per-route rate-limit buckets automatically. When a bucket is exhausted, the client sleeps until the reset time and retries — your await simply takes longer rather than raising an exception. You never need to write backoff logic yourself. You can inspect the current state of the rate-limit manager at any time:

print(bot.http._rl.stats())
# {'buckets': 12, 'global_until': 0.0, 'exhausted': []}

Key	Type	Description
`buckets`	`int`	Number of distinct rate-limit buckets currently tracked by the client.
`global_until`	`float`	Unix timestamp at which a global rate-limit clears. `0.0` means no active global limit.
`exhausted`	`list[str]`	List of bucket identifiers currently waiting for their reset window. Empty is healthy.

_rl is an internal attribute. Its interface may change between alterself releases. Use stats() for observability only — do not modify the rate-limit state directly.

​User Methods

​fetch_me

​fetch_user

​fetch_profile

​edit_me

​fetch_me_guilds

​fetch_connections

​DMs and Relationships

​open_dm

​fetch_relationships

​add_friend

​remove_friend

​block_user

​Raw Requests

​Rate Limits

User Methods

fetch_me

fetch_user

fetch_profile

edit_me

fetch_me_guilds

fetch_connections

DMs and Relationships

open_dm

fetch_relationships

add_friend

remove_friend

block_user

Raw Requests

Rate Limits