Table of Contents

Entities in Discord.Net

Discord.Net provides a versatile entity system for navigating the Discord API.

Tip

It is vital that you use the proper IDs for an entity when using a GetXXX method. It is recommended that you enable Discord's developer mode to allow easy access to entity IDs, found in Settings > Appearance > Advanced. Read more about it in the FAQ page.

Inheritance

Due to the nature of the Discord API, some entities are designed with multiple variants; for example, IUser and IGuildUser.

All models will contain the most detailed version of an entity possible, even if the type is less detailed.

Socket & REST

REST entities are retrieved over REST, and will be disposed after use. It is suggested to limit the amount of REST calls as much as possible, as calls over REST interact with the API, and are thus prone to rate-limits.

Socket entities are created through the gateway, most commonly through DiscordSocketClient events. These entities will enter the clients' global cache for later use.

In the case of the MessageReceived event, a SocketMessage is passed in with a channel property of type SocketMessageChannel. All messages come from channels capable of messaging, so this is the only variant of a channel that can cover every single case.

But that doesn't mean a message can't come from a SocketTextChannel, which is a message channel in a guild. To retrieve information about a guild from a message entity, you will need to cast its channel object to a SocketTextChannel.

Note

You can find out the inheritance tree & definitions of various entities here

All socket entities have navigation properties on them, which allow you to easily navigate to an entity's parent or children. As explained above, you will sometimes need to cast to a more detailed version of an entity to navigate to its parent.

Accessing Socket Entities

The most basic forms of entities, SocketGuild, SocketUser, and SocketChannel can be pulled from the DiscordSocketClient's global cache, and can be retrieved using the respective GetXXX method on DiscordSocketClient.

More detailed versions of entities can be pulled from the basic entities, e.g., SocketGuild.GetUser, which returns a SocketGuildUser, or SocketGuild.GetChannel, which returns a SocketGuildChannel. Again, you may need to cast these objects to get a variant of the type that you need.

Sample

public string GetChannelTopic(ulong id)
{
    var channel = client.GetChannel(81384956881809408) as SocketTextChannel;
    return channel?.Topic;
}

public SocketGuildUser GetGuildOwner(SocketChannel channel)
{
    var guild = (channel as SocketGuildChannel)?.Guild;
    return guild?.Owner;
}

Accessing REST Entities

REST entities work almost the same as Socket entities, but are much less frequently used. To access REST entities, the DiscordSocketClient's Rest property is required. Another option here is to create your own DiscordRestClient, independent of the Socket gateway.

Sample

// RestUser entities expose the accent color and banner of a user.
// This being one of the few use-cases for requesting a RestUser instead of depending on the Socket counterpart.
public static EmbedBuilder WithUserColor(this EmbedBuilder builder, IUser user)
{
    var restUser = await _client.Rest.GetUserAsync(user.Id);
    return builder.WithColor(restUser.AccentColor ?? Color.Blue);
    // The accent color can still be null, so a check for this needs to be done to prevent an exception to be thrown.
}
Edit this page