Class DiscordSocketClient

Represents a WebSocket-based Discord client.

Inheritance

System.Object

BaseDiscordClient

BaseSocketClient

DiscordSocketClient

Implements

IDiscordClient

System.IDisposable

Inherited Members

BaseSocketClient.BaseConfig

BaseSocketClient.CurrentUser

BaseSocketClient.CreateGuildAsync(String, IVoiceRegion, Stream, RequestOptions)

BaseSocketClient.GetConnectionsAsync(RequestOptions)

BaseSocketClient.GetInviteAsync(String, RequestOptions)

BaseSocketClient.ChannelCreated

BaseSocketClient.ChannelDestroyed

BaseSocketClient.ChannelUpdated

BaseSocketClient.MessageReceived

BaseSocketClient.MessageDeleted

BaseSocketClient.MessagesBulkDeleted

BaseSocketClient.MessageUpdated

BaseSocketClient.ReactionAdded

BaseSocketClient.ReactionRemoved

BaseSocketClient.ReactionsCleared

BaseSocketClient.RoleCreated

BaseSocketClient.RoleDeleted

BaseSocketClient.RoleUpdated

BaseSocketClient.JoinedGuild

BaseSocketClient.LeftGuild

BaseSocketClient.GuildAvailable

BaseSocketClient.GuildUnavailable

BaseSocketClient.GuildMembersDownloaded

BaseSocketClient.GuildUpdated

BaseSocketClient.UserJoined

BaseSocketClient.UserLeft

BaseSocketClient.UserBanned

BaseSocketClient.UserUnbanned

BaseSocketClient.UserUpdated

BaseSocketClient.GuildMemberUpdated

BaseSocketClient.UserVoiceStateUpdated

BaseSocketClient.VoiceServerUpdated

BaseSocketClient.CurrentUserUpdated

BaseSocketClient.UserIsTyping

BaseSocketClient.RecipientAdded

BaseSocketClient.RecipientRemoved

BaseDiscordClient.Log

BaseDiscordClient.LoggedIn

BaseDiscordClient.LoggedOut

BaseDiscordClient.LoginState

BaseDiscordClient.TokenType

BaseDiscordClient.LoginAsync(TokenType, String, Boolean)

BaseDiscordClient.LogoutAsync()

BaseDiscordClient.Dispose()

BaseDiscordClient.GetRecommendedShardCountAsync(RequestOptions)

BaseDiscordClient.IDiscordClient.ConnectionState

BaseDiscordClient.IDiscordClient.CurrentUser

BaseDiscordClient.IDiscordClient.GetWebhookAsync(UInt64, RequestOptions)

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Discord.WebSocket

Assembly: Discord.Net.WebSocket.dll

Syntax

public class DiscordSocketClient : BaseSocketClient, IDiscordClient, IDisposable

Constructors

DiscordSocketClient()

Initializes a new REST/WebSocket-based Discord client.

Declaration

public DiscordSocketClient()

DiscordSocketClient(DiscordSocketConfig)

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

Declaration

public DiscordSocketClient(DiscordSocketConfig config)

Parameters

Type	Name	Description
DiscordSocketConfig	config	The configuration to be used with the client.

Properties

Activity

Gets the activity for the logged-in user.

Declaration

public override IActivity Activity { get; protected set; }

Property Value

Type	Description
IActivity	An activity object that represents the user's current activity.

Overrides

BaseSocketClient.Activity

ConnectionState

Gets the current connection state of this client.

Declaration

public ConnectionState ConnectionState { get; }

Property Value

Type	Description
ConnectionState

DMChannels

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

Declaration

public IReadOnlyCollection<SocketDMChannel> DMChannels { get; }

Property Value

Type	Description
System.Collections.Generic.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.

GroupChannels

Gets a collection of group channels opened in this session.

Declaration

public IReadOnlyCollection<SocketGroupChannel> GroupChannels { get; }

Property Value

Type	Description
System.Collections.Generic.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.

Declaration

public override IReadOnlyCollection<SocketGuild> Guilds { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyCollection<SocketGuild>	A read-only collection of guilds that the current user is in.

Overrides

BaseSocketClient.Guilds

Latency

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

Declaration

public override int Latency { get; protected set; }

Property Value

Type	Description
System.Int32	An System.Int32 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.

Overrides

BaseSocketClient.Latency

PrivateChannels

Gets a collection of private channels opened in this session.

Declaration

public override IReadOnlyCollection<ISocketPrivateChannel> PrivateChannels { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyCollection<ISocketPrivateChannel>	A read-only collection of private channels that the user currently partakes in.

Overrides

BaseSocketClient.PrivateChannels

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.

Declaration

public override DiscordSocketRestClient Rest { get; }

Property Value

Type	Description
DiscordSocketRestClient

Overrides

BaseSocketClient.Rest

ShardId

Gets the shard of of this client.

Declaration

public int ShardId { get; }

Property Value

Type	Description
System.Int32

Status

Gets the status for the logged-in user.

Declaration

public override UserStatus Status { get; protected set; }

Property Value

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

Overrides

BaseSocketClient.Status

VoiceRegions

Gets a collection of available voice regions.

Declaration

public override IReadOnlyCollection<RestVoiceRegion> VoiceRegions { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyCollection<RestVoiceRegion>	A read-only collection of voice regions that the user has access to.

Overrides

BaseSocketClient.VoiceRegions

Methods

DownloadUsersAsync(IEnumerable<IGuild>)

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

Declaration

public override Task DownloadUsersAsync(IEnumerable<IGuild> guilds)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<IGuild>	guilds	The guilds to download the members from.

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous download operation.

Overrides

BaseSocketClient.DownloadUsersAsync(IEnumerable<IGuild>)

GetApplicationInfoAsync(RequestOptions)

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

Declaration

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

Parameters

Type	Name	Description
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<RestApplication>	A task that represents the asynchronous get operation. The task result contains the application information.

Overrides

BaseSocketClient.GetApplicationInfoAsync(RequestOptions)

Remarks

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

GetChannel(UInt64)

Gets a channel.

Declaration

public override SocketChannel GetChannel(ulong id)

Parameters

Type	Name	Description
System.UInt64	id	The snowflake identifier of the channel (e.g. 381889909113225237).

Returns

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

Overrides

BaseSocketClient.GetChannel(UInt64)

GetGuild(UInt64)

Gets a guild.

Declaration

public override SocketGuild GetGuild(ulong id)

Parameters

Type	Name	Description
System.UInt64	id	The guild snowflake identifier.

Returns

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

Overrides

BaseSocketClient.GetGuild(UInt64)

GetUser(String, String)

Gets a user.

Declaration

public override SocketUser GetUser(string username, string discriminator)

Parameters

Type	Name	Description
System.String	username	The name of the user.
System.String	discriminator	The discriminator value of the user.

Returns

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

Overrides

BaseSocketClient.GetUser(String, String)

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(UInt64, RequestOptions).

GetUser(UInt64)

Gets a generic user.

Declaration

public override SocketUser GetUser(ulong id)

Parameters

Type	Name	Description
System.UInt64	id	The user snowflake ID.

Returns

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

Overrides

BaseSocketClient.GetUser(UInt64)

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(UInt64, RequestOptions).

GetVoiceRegion(String)

Gets a voice region.

Declaration

public override RestVoiceRegion GetVoiceRegion(string id)

Parameters

Type	Name	Description
System.String	id	The identifier of the voice region (e.g. eu-central ).

Returns

Type	Description
RestVoiceRegion	A REST-based voice region associated with the identifier; null if the voice region is not found.

Overrides

BaseSocketClient.GetVoiceRegion(String)

SetActivityAsync(IActivity)

Sets the activity of the logged-in user.

Declaration

public override Task SetActivityAsync(IActivity activity)

Parameters

Type	Name	Description
IActivity	activity	The activity to be set.

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous set operation.

Overrides

BaseSocketClient.SetActivityAsync(IActivity)

Remarks

This method sets the activity of the user.

note

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

warning

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

SetGameAsync(String, String, ActivityType)

Sets the game of the user.

Declaration

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

Parameters

Type	Name	Description
System.String	name	The name of the game.
System.String	streamUrl	If streaming, the URL of the stream. Must be a valid Twitch URL.
ActivityType	type	The type of the game.

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous set operation.

Overrides

BaseSocketClient.SetGameAsync(String, String, ActivityType)

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

SetStatusAsync(UserStatus)

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

Declaration

public override Task SetStatusAsync(UserStatus status)

Parameters

Type	Name	Description
UserStatus	status	The new status to be set.

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous set operation.

Overrides

BaseSocketClient.SetStatusAsync(UserStatus)

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..

Declaration

public override Task StartAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous start operation.

Overrides

BaseSocketClient.StartAsync()

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.

Declaration

public override Task StopAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous stop operation.

Overrides

BaseSocketClient.StopAsync()

Events

Connected

Fired when connected to the Discord gateway.

Declaration

public event Func<Task> Connected

Event Type

Type	Description
System.Func<System.Threading.Tasks.Task>

Disconnected

Fired when disconnected to the Discord gateway.

Declaration

public event Func<Exception, Task> Disconnected

Event Type

Type	Description
System.Func<System.Exception, System.Threading.Tasks.Task>

LatencyUpdated

Fired when a heartbeat is received from the Discord gateway.

Declaration

public event Func<int, int, Task> LatencyUpdated

Event Type

Type	Description
System.Func<System.Int32, System.Int32, System.Threading.Tasks.Task>

Ready

Fired when guild data has finished downloading.

Declaration

public event Func<Task> Ready

Event Type

Type	Description
System.Func<System.Threading.Tasks.Task>

Explicit Interface Implementations

IDiscordClient.CreateGuildAsync(String, IVoiceRegion, Stream, RequestOptions)

Creates a guild for the logged-in user who is in less than 10 active guilds.

Declaration

Task<IGuild> IDiscordClient.CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon, RequestOptions options)

Parameters

Type	Name	Description
System.String	name	The name of the new guild.
IVoiceRegion	region	The voice region to create the guild with.
System.IO.Stream	jpegIcon	The icon of the guild.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IGuild>	A task that represents the asynchronous creation operation. The task result contains the created guild.

Remarks

This method creates a new guild on behalf of the logged-in user.

warning

Due to Discord's limitation, this method will only work for users that are in less than 10 guilds.

IDiscordClient.GetApplicationInfoAsync(RequestOptions)

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

Declaration

Task<IApplication> IDiscordClient.GetApplicationInfoAsync(RequestOptions options)

Parameters

Type	Name	Description
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IApplication>	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.

IDiscordClient.GetChannelAsync(UInt64, CacheMode, RequestOptions)

Gets a generic channel.

Declaration

Task<IChannel> IDiscordClient.GetChannelAsync(ulong id, CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
System.UInt64	id	The snowflake identifier of the channel (e.g. 381889909113225237).
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<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.

IDiscordClient.GetConnectionsAsync(RequestOptions)

Gets the connections that the user has set up.

Declaration

Task<IReadOnlyCollection<IConnection>> IDiscordClient.GetConnectionsAsync(RequestOptions options)

Parameters

Type	Name	Description
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IConnection>>	A task that represents the asynchronous get operation. The task result contains a read-only collection of connections.

IDiscordClient.GetDMChannelsAsync(CacheMode, RequestOptions)

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

Declaration

Task<IReadOnlyCollection<IDMChannel>> IDiscordClient.GetDMChannelsAsync(CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IDMChannel>>	A task that represents the asynchronous get operation. The task result contains a read-only collection of direct-message channels that the user currently partakes in.

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.

IDiscordClient.GetGroupChannelsAsync(CacheMode, RequestOptions)

Gets a collection of group channels opened in this session.

Declaration

Task<IReadOnlyCollection<IGroupChannel>> IDiscordClient.GetGroupChannelsAsync(CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IGroupChannel>>	A task that represents the asynchronous get operation. The task result contains a read-only collection of group channels that the user currently partakes in.

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.

IDiscordClient.GetGuildAsync(UInt64, CacheMode, RequestOptions)

Gets a guild.

Declaration

Task<IGuild> IDiscordClient.GetGuildAsync(ulong id, CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
System.UInt64	id	The guild snowflake identifier.
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IGuild>	A task that represents the asynchronous get operation. The task result contains the guild associated with the snowflake identifier; null when the guild cannot be found.

IDiscordClient.GetGuildsAsync(CacheMode, RequestOptions)

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

Declaration

Task<IReadOnlyCollection<IGuild>> IDiscordClient.GetGuildsAsync(CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IGuild>>	A task that represents the asynchronous get operation. The task result contains a read-only collection of guilds that the current user is in.

IDiscordClient.GetInviteAsync(String, RequestOptions)

Gets an invite.

Declaration

Task<IInvite> IDiscordClient.GetInviteAsync(string inviteId, RequestOptions options)

Parameters

Type	Name	Description
System.String	inviteId	The invitation identifier.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IInvite>	A task that represents the asynchronous get operation. The task result contains the invite information.

IDiscordClient.GetPrivateChannelsAsync(CacheMode, RequestOptions)

Gets a collection of private channels opened in this session.

Declaration

Task<IReadOnlyCollection<IPrivateChannel>> IDiscordClient.GetPrivateChannelsAsync(CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IPrivateChannel>>	A task that represents the asynchronous get operation. The task result contains 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.

IDiscordClient.GetUserAsync(String, String, RequestOptions)

Gets a user.

Declaration

Task<IUser> IDiscordClient.GetUserAsync(string username, string discriminator, RequestOptions options)

Parameters

Type	Name	Description
System.String	username	The name of the user (e.g. Still).
System.String	discriminator	The discriminator value of the user (e.g. 2876).
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IUser>	A task that represents the asynchronous get operation. The task result contains the user associated with the name and the discriminator; null if the user is not found.

IDiscordClient.GetUserAsync(UInt64, CacheMode, RequestOptions)

Gets a user.

Declaration

Task<IUser> IDiscordClient.GetUserAsync(ulong id, CacheMode mode, RequestOptions options)

Parameters

Type	Name	Description
System.UInt64	id	The snowflake identifier of the user (e.g. 168693960628371456).
CacheMode	mode	The CacheMode that determines whether the object should be fetched from cache.
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<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.

IDiscordClient.GetVoiceRegionAsync(String, RequestOptions)

Gets a voice region.

Declaration

Task<IVoiceRegion> IDiscordClient.GetVoiceRegionAsync(string id, RequestOptions options)

Parameters

Type	Name	Description
System.String	id	The identifier of the voice region (e.g. eu-central ).
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<IVoiceRegion>	A task that represents the asynchronous get operation. The task result contains the voice region associated with the identifier; null if the voice region is not found.

IDiscordClient.GetVoiceRegionsAsync(RequestOptions)

Gets a collection of the available voice regions.

Declaration

Task<IReadOnlyCollection<IVoiceRegion>> IDiscordClient.GetVoiceRegionsAsync(RequestOptions options)

Parameters

Type	Name	Description
RequestOptions	options	The options to be used when sending the request.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<IVoiceRegion>>	A task that represents the asynchronous get operation. The task result contains a read-only collection with all of the available voice regions in this session.

IDiscordClient.StartAsync()

Starts the connection between Discord and the client..

Declaration

Task IDiscordClient.StartAsync()

Returns

Type	Description
System.Threading.Tasks.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.

IDiscordClient.StopAsync()

Stops the connection between Discord and the client.

Declaration

Task IDiscordClient.StopAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A task that represents the asynchronous stop operation.

Implements

IDiscordClient

System.IDisposable