alterself Data Models: User, Guild, Channel, Message

alterself represents every Discord resource as a typed model object. These objects behave like Python dataclasses. Each attribute is strongly typed and populated automatically when the gateway dispatches an event or when an HTTP method returns a response. In addition to raw attributes, most models expose computed properties that derive useful values (such as CDN URLs, mentions, and creation timestamps) without requiring extra API calls.

User

The User model represents any Discord account: a human user, a bot, or the account your selfbot is logged into. You receive User objects from gateway events such as READY, MESSAGE_CREATE, and relationship events.

Attributes

Attribute	Type	Description
`id`	`Flake`	Discord snowflake that uniquely identifies this user.
`username`	`str`	The user’s account username.
`discriminator`	`str`	Legacy four-digit discriminator (e.g. `"0"` for migrated accounts).
`global_name`	`str \| None`	Display name under the new username system; `None` for unmigrated accounts.
`avatar`	`str \| None`	Avatar image hash. Pass to `avatar_url` to build a full CDN URL.
`bot`	`bool`	`True` if this account is a bot application.
`public_flags`	`int`	Bitfield of public badge flags (e.g. Early Supporter, HypeSquad).
`premium_type`	`int`	Nitro subscription tier: `0` = None, `1` = Classic, `2` = Nitro, `3` = Basic.

Properties

Property	Type	Description
`display_name`	`str`	Returns `global_name` if set, otherwise falls back to `username`.
`mention`	`str`	A ready-to-send mention string in the format `<@id>`.
`avatar_url`	`str \| None`	Full Discord CDN URL for the user’s avatar, or `None` if no avatar is set.
`created_at`	`datetime`	UTC `datetime` derived from the snowflake, representing when the account was created.

user = bot.user
print(user.display_name)   # global_name or username
print(user.mention)        # <@123456789012345678>
print(user.avatar_url)     # https://cdn.discordapp.com/avatars/...
print(user.created_at)     # 2020-01-01 00:00:00+00:00

Use display_name instead of username when presenting a user to humans. It always returns the most visible name regardless of whether the account has migrated to the new system.

Guild

The Guild model represents a Discord server. alterself populates guild objects from GUILD_CREATE events and caches them for the lifetime of the session.

Attributes

Attribute	Type	Description
`id`	`Flake`	Unique guild snowflake ID.
`name`	`str`	The guild’s display name.
`icon`	`str \| None`	Icon image hash, or `None` if no icon is set.
`owner_id`	`Flake \| None`	Snowflake of the guild owner’s user account.
`member_count`	`int`	Approximate number of members at the time of the last `GUILD_CREATE` event.
`premium_tier`	`int`	Server boost tier: `0` = none, `1` = Tier 1, `2` = Tier 2, `3` = Tier 3.
`description`	`str \| None`	Community description set by guild administrators, or `None`.

Properties

Property	Type	Description
`channels`	`list[Channel]`	All cached channels that belong to this guild.
`members`	`list[Member]`	All cached members in this guild.
`icon_url`	`str \| None`	Full Discord CDN URL for the guild’s icon, or `None` if no icon is set.

guild = bot.get_guild(guild_id)
print(guild.name)
print(guild.premium_tier)    # 0, 1, 2, or 3
for channel in guild.channels:
    print(channel.name)

member_count reflects the count at the time the guild payload was received. It is not updated incrementally as members join or leave. Use GUILD_MEMBER_ADD and GUILD_MEMBER_REMOVE events to track live changes.

Channel

The Channel model represents any Discord channel: text, voice, category, thread, or DM. The kind attribute tells you which type you are dealing with.

Attributes

Attribute	Type	Description
`id`	`Flake`	Unique channel snowflake ID.
`kind`	`ChannelKind`	Enum value describing the channel type (e.g. `ChannelKind.TEXT`, `ChannelKind.DM`).
`name`	`str \| None`	Channel name, or `None` for DM channels.
`guild_id`	`Flake \| None`	Snowflake of the guild this channel belongs to, or `None` for DMs.
`topic`	`str \| None`	Channel topic text, or `None` if unset.
`nsfw`	`bool`	`True` if the channel is marked as age-restricted.
`parent_id`	`Flake \| None`	Snowflake of the parent category, or parent channel for threads.

Properties

Property	Type	Description
`mention`	`str`	A ready-to-send channel mention in the format `<#id>`.

channel = bot.get_channel(channel_id)
print(channel.mention)   # <#123456789012345678>
print(channel.kind)      # ChannelKind.TEXT

Subclasses

DMChannel

DMChannel extends Channel and is returned for private messages between you and another user.

Attribute	Type	Description
`recipient`	`User \| None`	The other participant in the DM, or `None` if not cached.

GroupChannel

GroupChannel extends Channel and represents a group DM.

Attribute	Type	Description
`recipients`	`list[User]`	All participants in the group DM.
`owner_id`	`Flake \| None`	Snowflake of the user who owns the group DM.

Check channel.guild_id is None to quickly determine whether a channel is a DM rather than importing ChannelKind and comparing against every DM variant.

Message

The Message model represents a Discord message. You receive message objects primarily from MESSAGE_CREATE and MESSAGE_UPDATE gateway events, and from HTTP fetch methods.

Attributes

Attribute	Type	Description
`id`	`Flake`	Unique message snowflake ID.
`channel_id`	`Flake`	Snowflake of the channel this message was sent in.
`guild_id`	`Flake \| None`	Snowflake of the guild, or `None` for DMs.
`author`	`User \| None`	The user who sent the message, or `None` if not available in the payload.
`content`	`str`	Plain text content of the message.
`timestamp`	`datetime \| None`	UTC timestamp of when the message was sent, or `None` if not present in the payload.
`edited_timestamp`	`datetime \| None`	UTC timestamp of the last edit, or `None` if never edited.
`attachments`	`list[dict]`	List of attachment objects included with the message.
`embeds`	`list[dict]`	List of embed objects included with the message.
`reactions`	`list[dict]`	List of reaction objects on the message.
`pinned`	`bool`	`True` if the message is pinned in its channel.
`kind`	`MessageKind`	Enum value describing the message type (e.g. `MessageKind.DEFAULT`, `MessageKind.REPLY`).
`flags`	`int`	Bitfield of message flags.
`referenced_message`	`Message \| None`	The message being replied to, or `None` if not a reply or not cached.

Properties

Property	Type	Description
`channel`	`Channel \| None`	The cached `Channel` object for `channel_id`, or `None` if not in cache.
`guild`	`Guild \| None`	The cached `Guild` object for `guild_id`, or `None` if a DM or not in cache.
`jump_url`	`str`	A `discord.com/channels/...` deep-link URL that opens this message in the client.

@bot.on("MESSAGE_CREATE")
async def on_message(msg):
    print(msg.author.display_name)
    print(msg.content)
    print(msg.jump_url)
    if msg.referenced_message:
        print("Reply to:", msg.referenced_message.content)

channel and guild resolve against the in-memory cache. If alterself has not yet received the corresponding CHANNEL_CREATE or GUILD_CREATE event, for example immediately after connecting, these properties may return None even when channel_id and guild_id are set.

Member

The Member model represents a user’s membership within a specific guild. It combines guild-specific metadata with a reference back to the underlying User object.

Attributes

Attribute	Type	Description
`id`	`Flake`	The user’s snowflake ID (same as `user.id`).
`guild_id`	`Flake \| None`	Snowflake of the guild this membership belongs to, or `None` if not available.
`nick`	`str \| None`	Guild-specific nickname, or `None` if not set.
`roles`	`list[Flake]`	Snowflakes of every role assigned to this member.
`joined_at`	`str \| None`	ISO 8601 timestamp string of when the member joined the guild, or `None` if not available.
`deaf`	`bool`	`True` if the member is server-deafened in voice.
`mute`	`bool`	`True` if the member is server-muted in voice.
`pending`	`bool`	`True` if the member has not yet passed the membership screening.

Properties

Property	Type	Description
`user`	`User \| None`	The underlying `User` object, resolved from cache. `None` if not cached.
`display_name`	`str`	Returns `nick` if set, then `user.display_name` if the user is cached, otherwise the raw ID as a string.

@bot.on("GUILD_MEMBER_ADD")
async def on_join(member):
    print(f"{member.display_name} joined {member.guild_id}")
    print(f"Roles: {member.roles}")

Flake

Flake is alterself’s wrapper around a Discord snowflake ID. Every model’s id attribute is a Flake, not a plain integer, but Flake compares and hashes as an integer, so you can use it wherever an int is expected. The real value of Flake is the structured data it exposes directly from the 64-bit snowflake value.

msg.id.created_at    # datetime : UTC creation time derived from the snowflake
msg.id.timestamp_ms  # int : Unix timestamp in milliseconds
msg.id.worker_id     # int : Internal Discord worker ID (bits 17-21)
msg.id.process_id    # int : Internal Discord process ID (bits 12-16)
msg.id.increment     # int : Per-process increment counter (bits 0-11)

flake = msg.id
print(int(flake))           # 123456789012345678
print(flake.created_at)     # 2021-03-24 17:08:21.141000+00:00
print(flake.timestamp_ms)   # 1616605701141
print(flake == 123456789012345678)  # True

Flake objects are safe to use as dictionary keys and in sets. Two Flake objects with the same integer value are considered equal and produce the same hash.

​User

​Attributes

​Properties

​Guild

​Attributes

​Properties

​Channel

​Attributes

​Properties

​Subclasses

​DMChannel

​GroupChannel

​Message

​Attributes

​Properties

​Member

​Attributes

​Properties

​Flake

User

Attributes

Properties

Guild

Attributes

Properties

Channel

Attributes

Properties

Subclasses

DMChannel

GroupChannel

Message

Attributes

Properties

Member

Attributes

Properties

Flake