Table of Contents

Class DiscordSocketClient

Namespace
Discord.WebSocket
Assembly
Discord.Net.WebSocket.dll

Represents a WebSocket-based Discord client.

public class DiscordSocketClient : BaseSocketClient, IRestClientProvider, IDiscordClient, IDisposable, IAsyncDisposable
Inheritance
DiscordSocketClient
Implements
Inherited Members
Extension Methods

Constructors

DiscordSocketClient()

Initializes a new REST/WebSocket-based Discord client.

public DiscordSocketClient()

DiscordSocketClient(DiscordSocketConfig)

Initializes a new REST/WebSocket-based Discord client with the provided configuration.

public DiscordSocketClient(DiscordSocketConfig config)

Parameters

config DiscordSocketConfig

The configuration to be used with the client.

Properties

Activity

Gets the activity for the logged-in user.

public override IActivity Activity { get; protected set; }

Property Value

IActivity

An activity object that represents the user's current activity.

ConnectionState

Gets the current state of connection.

public override ConnectionState ConnectionState { get; }

Property Value

ConnectionState

DMChannels

Gets a collection of direct message channels opened in this session.

public IReadOnlyCollection<SocketDMChannel> DMChannels { get; }

Property Value

IReadOnlyCollection<SocketDMChannel>

A collection of DM channels that have been opened in this session.

Remarks

This method returns a collection of currently opened direct message channels.

warning

This method will not return previously opened DM channels outside of the current session! If you have just started the client, this may return an empty collection.

DefaultStickerPacks

Gets a collection of default stickers.

public override IReadOnlyCollection<StickerPack<SocketSticker>> DefaultStickerPacks { get; }

Property Value

IReadOnlyCollection<StickerPack<SocketSticker>>

Entitlements

Gets entitlements from cache.

public IReadOnlyCollection<SocketEntitlement> Entitlements { get; }

Property Value

IReadOnlyCollection<SocketEntitlement>

GroupChannels

Gets a collection of group channels opened in this session.

public IReadOnlyCollection<SocketGroupChannel> GroupChannels { get; }

Property Value

IReadOnlyCollection<SocketGroupChannel>

A collection of group channels that have been opened in this session.

Remarks

This method returns a collection of currently opened group channels.

warning

This method will not return previously opened group channels outside of the current session! If you have just started the client, this may return an empty collection.

Guilds

Gets a collection of guilds that the user is currently in.

public override IReadOnlyCollection<SocketGuild> Guilds { get; }

Property Value

IReadOnlyCollection<SocketGuild>

A read-only collection of guilds that the current user is in.

Latency

Gets the estimated round-trip latency, in milliseconds, to the gateway server.

public override int Latency { get; protected set; }

Property Value

int

An int that represents the round-trip latency to the WebSocket server. Please note that this value does not represent a "true" latency for operations such as sending a message.

PrivateChannels

Gets a collection of private channels opened in this session.

public override IReadOnlyCollection<ISocketPrivateChannel> PrivateChannels { get; }

Property Value

IReadOnlyCollection<ISocketPrivateChannel>

A read-only collection of private channels that the user currently partakes in.

Remarks

This method will retrieve all private channels (including direct-message, group channel and such) that are currently opened in this session.

warning

This method will not return previously opened private channels outside of the current session! If you have just started the client, this may return an empty collection.

Rest

Provides access to a REST-only client with a shared state from this client.

public override DiscordSocketRestClient Rest { get; }

Property Value

DiscordSocketRestClient

ShardId

Gets the shard of this client.

public int ShardId { get; }

Property Value

int

Status

Gets the status for the logged-in user.

public override UserStatus Status { get; protected set; }

Property Value

UserStatus

A status object that represents the user's online presence status.

Subscription

Gets subscriptions from cache.

public IReadOnlyCollection<SocketSubscription> Subscription { get; }

Property Value

IReadOnlyCollection<SocketSubscription>

Methods

BulkOverwriteGlobalApplicationCommandsAsync(ApplicationCommandProperties[], RequestOptions) 

public Task<IReadOnlyCollection<SocketApplicationCommand>> BulkOverwriteGlobalApplicationCommandsAsync(ApplicationCommandProperties[] properties, RequestOptions options = null)

Parameters

properties ApplicationCommandProperties[]
options RequestOptions

Returns

Task<IReadOnlyCollection<SocketApplicationCommand>>

ConsumeEntitlementAsync(ulong, RequestOptions)

Marks a given one-time purchase entitlement for the user as consumed.

public Task ConsumeEntitlementAsync(ulong entitlementId, RequestOptions options = null)

Parameters

entitlementId ulong

The id of the entitlement.

options RequestOptions

The options to be used when sending the request.

Returns

Task

CreateApplicationEmoteAsync(string, Image, RequestOptions)

Creates an emote for the current application.

public Task<Emote> CreateApplicationEmoteAsync(string name, Image image, RequestOptions options = null)

Parameters

name string
image Image
options RequestOptions

Returns

Task<Emote>

CreateGlobalApplicationCommandAsync(ApplicationCommandProperties, RequestOptions) 

public Task<SocketApplicationCommand> CreateGlobalApplicationCommandAsync(ApplicationCommandProperties properties, RequestOptions options = null)

Parameters

properties ApplicationCommandProperties
options RequestOptions

Returns

Task<SocketApplicationCommand>

CreateTestEntitlementAsync(ulong, ulong, SubscriptionOwnerType, RequestOptions)

Creates a test entitlement to a given SKU for a given guild or user.

public Task<RestEntitlement> CreateTestEntitlementAsync(ulong skuId, ulong ownerId, SubscriptionOwnerType ownerType, RequestOptions options = null)

Parameters

skuId ulong
ownerId ulong
ownerType SubscriptionOwnerType
options RequestOptions

Returns

Task<RestEntitlement>

DeleteApplicationEmoteAsync(ulong, RequestOptions)

Deletes an emote for the current application.

public Task DeleteApplicationEmoteAsync(ulong emoteId, RequestOptions options = null)

Parameters

emoteId ulong
options RequestOptions

Returns

Task

DeleteTestEntitlementAsync(ulong, RequestOptions)

Deletes a currently-active test entitlement.

public Task DeleteTestEntitlementAsync(ulong entitlementId, RequestOptions options = null)

Parameters

entitlementId ulong
options RequestOptions

Returns

Task

DownloadUsersAsync(IEnumerable<IGuild>)

Attempts to download users into the user cache for the selected guilds.

public override Task DownloadUsersAsync(IEnumerable<IGuild> guilds)

Parameters

guilds IEnumerable<IGuild>

The guilds to download the members from.

Returns

Task

A task that represents the asynchronous download operation.

GetApplicationEmoteAsync(ulong, RequestOptions)

Gets an emote for the current application.

public Task<Emote> GetApplicationEmoteAsync(ulong emoteId, RequestOptions options = null)

Parameters

emoteId ulong
options RequestOptions

Returns

Task<Emote>

GetApplicationEmotesAsync(RequestOptions)

Gets all emotes for the current application.

public Task<IReadOnlyCollection<Emote>> GetApplicationEmotesAsync(RequestOptions options = null)

Parameters

options RequestOptions

Returns

Task<IReadOnlyCollection<Emote>>

GetApplicationInfoAsync(RequestOptions)

Gets a Discord application information for the logged-in user.

public override Task<RestApplication> GetApplicationInfoAsync(RequestOptions options = null)

Parameters

options RequestOptions

The options to be used when sending the request.

Returns

Task<RestApplication>

A task that represents the asynchronous get operation. The task result contains the application information.

Remarks

This method reflects your application information you submitted when creating a Discord application via the Developer Portal.

GetChannel(ulong)

Gets a channel.

public override SocketChannel GetChannel(ulong id)

Parameters

id ulong

The snowflake identifier of the channel (e.g. 381889909113225237).

Returns

SocketChannel

A generic WebSocket-based channel object (voice, text, category, etc.) associated with the identifier; null when the channel cannot be found.

GetChannelAsync(ulong, RequestOptions)

Gets a generic channel from the cache or does a rest request if unavailable.

public ValueTask<IChannel> GetChannelAsync(ulong id, RequestOptions options = null)

Parameters

id ulong

The snowflake identifier of the channel (e.g. 381889909113225237).

options RequestOptions

The options to be used when sending the request.

Returns

ValueTask<IChannel>

A task that represents the asynchronous get operation. The task result contains the channel associated with the snowflake identifier; null when the channel cannot be found.

Examples

var channel = await _client.GetChannelAsync(381889909113225237);
if (channel != null && channel is IMessageChannel msgChannel)
{
    await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}");
}

GetEntitlement(ulong)

Gets an entitlement from cache. null if not found.

public SocketEntitlement GetEntitlement(ulong id)

Parameters

id ulong

Returns

SocketEntitlement

GetEntitlementsAsync(BaseDiscordClient, int?, ulong?, ulong?, bool, ulong?, ulong?, ulong[], RequestOptions)

Returns all entitlements for a given app, active and expired.

public IAsyncEnumerable<IReadOnlyCollection<IEntitlement>> GetEntitlementsAsync(BaseDiscordClient client, int? limit = 100, ulong? afterId = null, ulong? beforeId = null, bool excludeEnded = false, ulong? guildId = null, ulong? userId = null, ulong[] skuIds = null, RequestOptions options = null)

Parameters

client BaseDiscordClient
limit int?
afterId ulong?
beforeId ulong?
excludeEnded bool
guildId ulong?
userId ulong?
skuIds ulong[]
options RequestOptions

Returns

IAsyncEnumerable<IReadOnlyCollection<IEntitlement>>

GetGlobalApplicationCommandAsync(ulong, RequestOptions)

Gets a global application command.

public ValueTask<SocketApplicationCommand> GetGlobalApplicationCommandAsync(ulong id, RequestOptions options = null)

Parameters

id ulong

The id of the command.

options RequestOptions

The options to be used when sending the request.

Returns

ValueTask<SocketApplicationCommand>

A ValueTask that represents the asynchronous get operation. The task result contains the application command if found, otherwise null.

GetGlobalApplicationCommandsAsync(bool, string, RequestOptions)

Gets a collection of all global commands.

public Task<IReadOnlyCollection<SocketApplicationCommand>> GetGlobalApplicationCommandsAsync(bool withLocalizations = false, string locale = null, RequestOptions options = null)

Parameters

withLocalizations bool

Whether to include full localization dictionaries in the returned objects, instead of the name localized and description localized fields.

locale string

The target locale of the localized name and description fields. Sets X-Discord-Locale header, which takes precedence over Accept-Language.

options RequestOptions

The options to be used when sending the request.

Returns

Task<IReadOnlyCollection<SocketApplicationCommand>>

A task that represents the asynchronous get operation. The task result contains a read-only collection of global application commands.

GetGuild(ulong)

Gets a guild.

public override SocketGuild GetGuild(ulong id)

Parameters

id ulong

The guild snowflake identifier.

Returns

SocketGuild

A WebSocket-based guild associated with the snowflake identifier; null when the guild cannot be found.

GetSKUSubscriptionAsync(ulong, ulong, RequestOptions)

Gets a subscription by its id.

public Task<RestSubscription> GetSKUSubscriptionAsync(ulong skuId, ulong subscriptionId, RequestOptions options = null)

Parameters

skuId ulong
subscriptionId ulong
options RequestOptions

Returns

Task<RestSubscription>

GetSKUSubscriptionsAsync(ulong, int, ulong?, ulong?, ulong?, RequestOptions)

Returns all subscriptions for a given SKU.

public IAsyncEnumerable<IReadOnlyCollection<RestSubscription>> GetSKUSubscriptionsAsync(ulong skuId, int limit = 100, ulong? afterId = null, ulong? beforeId = null, ulong? userId = null, RequestOptions options = null)

Parameters

skuId ulong
limit int
afterId ulong?
beforeId ulong?
userId ulong?
options RequestOptions

Returns

IAsyncEnumerable<IReadOnlyCollection<RestSubscription>>

GetSKUsAsync(RequestOptions)

Returns all SKUs for a given application.

public Task<IReadOnlyCollection<SKU>> GetSKUsAsync(RequestOptions options = null)

Parameters

options RequestOptions

Returns

Task<IReadOnlyCollection<SKU>>

GetSticker(ulong)

Gets a sticker.

public SocketSticker GetSticker(ulong id)

Parameters

id ulong

The unique identifier of the sticker.

Returns

SocketSticker

A sticker if found, otherwise null.

GetStickerAsync(ulong, CacheMode, RequestOptions)

Gets a sticker.

public override Task<SocketSticker> GetStickerAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)

Parameters

id ulong

The id of the sticker to get.

mode CacheMode

Whether or not to allow downloading from the api.

options RequestOptions

The options to be used when sending the request.

Returns

Task<SocketSticker>

A SocketSticker if found, otherwise null.

GetSubscription(ulong)

Gets a subscription from cache. null if not found.

public SocketSubscription GetSubscription(ulong id)

Parameters

id ulong

Returns

SocketSubscription

GetUser(string, string)

Gets a user.

public override SocketUser GetUser(string username, string discriminator = null)

Parameters

username string

The name of the user.

discriminator string

The discriminator value of the user.

Returns

SocketUser

A generic WebSocket-based user; null when the user cannot be found.

Remarks

This method gets the user present in the WebSocket cache with the given condition.

warning

Sometimes a user may return null due to Discord not sending offline users in large guilds (i.e. guild with 100+ members) actively. To download users on startup and to see more information about this subject, see AlwaysDownloadUsers.

note

This method does not attempt to fetch users that the logged-in user does not have access to (i.e. users who don't share mutual guild(s) with the current user). If you wish to get a user that you do not have access to, consider using the REST implementation of GetUserAsync(ulong, RequestOptions).

GetUser(ulong)

Gets a generic user.

public override SocketUser GetUser(ulong id)

Parameters

id ulong

The user snowflake ID.

Returns

SocketUser

A generic WebSocket-based user; null when the user cannot be found.

Remarks

This method gets the user present in the WebSocket cache with the given condition.

warning

Sometimes a user may return null due to Discord not sending offline users in large guilds (i.e. guild with 100+ members) actively. To download users on startup and to see more information about this subject, see AlwaysDownloadUsers.

note

This method does not attempt to fetch users that the logged-in user does not have access to (i.e. users who don't share mutual guild(s) with the current user). If you wish to get a user that you do not have access to, consider using the REST implementation of GetUserAsync(ulong, RequestOptions).

GetUserAsync(ulong, RequestOptions)

Gets a user from the cache or does a rest request if unavailable.

public ValueTask<IUser> GetUserAsync(ulong id, RequestOptions options = null)

Parameters

id ulong

The snowflake identifier of the user (e.g. 168693960628371456).

options RequestOptions

The options to be used when sending the request.

Returns

ValueTask<IUser>

A task that represents the asynchronous get operation. The task result contains the user associated with the snowflake identifier; null if the user is not found.

Examples

var user = await _client.GetUserAsync(168693960628371456);
if (user != null)
    Console.WriteLine($"{user} is created at {user.CreatedAt}.";

GetVoiceRegionAsync(string, RequestOptions)

Gets a voice region.

public override ValueTask<RestVoiceRegion> GetVoiceRegionAsync(string id, RequestOptions options = null)

Parameters

id string

The identifier of the voice region (e.g. eu-central ).

options RequestOptions

The options to be used when sending the request.

Returns

ValueTask<RestVoiceRegion>

A task that contains a REST-based voice region associated with the identifier; null if the voice region is not found.

GetVoiceRegionsAsync(RequestOptions)

Gets all voice regions.

public override ValueTask<IReadOnlyCollection<RestVoiceRegion>> GetVoiceRegionsAsync(RequestOptions options = null)

Parameters

options RequestOptions

The options to be used when sending the request.

Returns

ValueTask<IReadOnlyCollection<RestVoiceRegion>>

A task that contains a read-only collection of REST-based voice regions.

ModifyApplicationEmoteAsync(ulong, Action<ApplicationEmoteProperties>, RequestOptions)

Modifies an emote for the current application.

public Task<Emote> ModifyApplicationEmoteAsync(ulong emoteId, Action<ApplicationEmoteProperties> args, RequestOptions options = null)

Parameters

emoteId ulong
args Action<ApplicationEmoteProperties>
options RequestOptions

Returns

Task<Emote>

PurgeChannelCache()

Clears all cached channels from the client.

public void PurgeChannelCache()

PurgeDMChannelCache()

Clears cached DM channels from the client.

public void PurgeDMChannelCache()

PurgeUserCache()

Clears cached users from the client.

public void PurgeUserCache()

SetActivityAsync(IActivity)

Sets the activity of the logged-in user.

public override Task SetActivityAsync(IActivity activity)

Parameters

activity IActivity

The activity to be set.

Returns

Task

A task that represents the asynchronous set operation.

Remarks

This method sets the activity of the user.

note

Discord will only accept setting of name and the type of activity.

warning

Bot accounts cannot set CustomStatus as their activity type and it will have no effect.

warning

Rich Presence cannot be set via this method or client. Rich Presence is strictly limited to RPC clients only.

SetCustomStatusAsync(string)

Sets the custom status of the logged-in user.

public override Task SetCustomStatusAsync(string status)

Parameters

status string

The string that will be displayed as status.

Returns

Task

A task that represents the asynchronous set operation.

SetGameAsync(string, string, ActivityType)

Sets the game of the user.

public override Task SetGameAsync(string name, string streamUrl = null, ActivityType type = ActivityType.Playing)

Parameters

name string

The name of the game.

streamUrl string

If streaming, the URL of the stream. Must be a valid Twitch URL.

type ActivityType

The type of the game.

Returns

Task

A task that represents the asynchronous set operation.

Examples

The following example sets the activity of the current user to the specified game name. 

await client.SetGameAsync("A Strange Game");

The following example sets the activity of the current user to a streaming status. 

await client.SetGameAsync("Great Stream 10/10", "https://twitch.tv/MyAmazingStream1337", ActivityType.Streaming);

Remarks

warning

Bot accounts cannot set CustomStatus as their activity type and it will have no effect.

SetStatusAsync(UserStatus)

Sets the current status of the user (e.g. Online, Do not Disturb).

public override Task SetStatusAsync(UserStatus status)

Parameters

status UserStatus

The new status to be set.

Returns

Task

A task that represents the asynchronous set operation.

Examples

The following example sets the status of the current user to Do Not Disturb.

await client.SetStatusAsync(UserStatus.DoNotDisturb);

StartAsync()

Starts the connection between Discord and the client..

public override Task StartAsync()

Returns

Task

A task that represents the asynchronous start operation.

Remarks

This method will initialize the connection between the client and Discord.

important

This method will immediately return after it is called, as it will initialize the connection on another thread.

StopAsync()

Stops the connection between Discord and the client.

public override Task StopAsync()

Returns

Task

A task that represents the asynchronous stop operation.

Events

Connected

Fired when connected to the Discord gateway.

public event Func<Task> Connected

Event Type

Func<Task>

Disconnected

Fired when disconnected to the Discord gateway.

public event Func<Exception, Task> Disconnected

Event Type

Func<Exception, Task>

LatencyUpdated

Fired when a heartbeat is received from the Discord gateway.

public event Func<int, int, Task> LatencyUpdated

Event Type

Func<int, int, Task>

Ready

Fired when guild data has finished downloading.

public event Func<Task> Ready

Event Type

Func<Task>

Remarks

It is possible that some guilds might be unsynced if MaxWaitBetweenGuildAvailablesBeforeReady was not long enough to receive all GUILD_AVAILABLEs before READY.

Edit this page