Class DiscordSocketClient
Represents a WebSocket-based Discord client.
Inherited Members
Namespace: Discord.WebSocket
Assembly: Discord.Net.WebSocket.dll
Syntax
public class DiscordSocketClient : BaseSocketClient, IDiscordClient, IDisposable, IAsyncDisposable
Constructors
| Improve this Doc View SourceDiscordSocketClient()
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
| Improve this Doc View SourceActivity
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
| Improve this Doc View SourceConnectionState
Gets the current connection state of this client.
Declaration
public ConnectionState ConnectionState { get; }
Property Value
Type | Description |
---|---|
ConnectionState |
DefaultStickerPacks
Gets a collection of default stickers.
Declaration
public override IReadOnlyCollection<StickerPack<SocketSticker>> DefaultStickerPacks { get; }
Property Value
Type | Description |
---|---|
IReadOnlyCollection<StickerPack<SocketSticker>> |
Overrides
| Improve this Doc View SourceDMChannels
Gets a collection of direct message channels opened in this session.
Declaration
public IReadOnlyCollection<SocketDMChannel> DMChannels { get; }
Property Value
Type | Description |
---|---|
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 |
---|---|
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 |
---|---|
IReadOnlyCollection<SocketGuild> | A read-only collection of guilds that the current user is in. |
Overrides
| Improve this Doc View SourceLatency
Gets the estimated round-trip latency, in milliseconds, to the gateway server.
Declaration
public override int Latency { get; protected set; }
Property Value
Type | Description |
---|---|
Int32 | An |
Overrides
| Improve this Doc View SourcePrivateChannels
Gets a collection of private channels opened in this session.
Declaration
public override IReadOnlyCollection<ISocketPrivateChannel> PrivateChannels { get; }
Property Value
Type | Description |
---|---|
IReadOnlyCollection<ISocketPrivateChannel> | A read-only collection of private channels that the user currently partakes in. |
Overrides
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
| Improve this Doc View SourceShardId
Gets the shard of this client.
Declaration
public int ShardId { get; }
Property Value
Type | Description |
---|---|
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
Methods
| Improve this Doc View SourceBulkOverwriteGlobalApplicationCommandsAsync(ApplicationCommandProperties[], RequestOptions)
Declaration
public async Task<IReadOnlyCollection<SocketApplicationCommand>> BulkOverwriteGlobalApplicationCommandsAsync(ApplicationCommandProperties[] properties, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
ApplicationCommandProperties[] | properties | |
RequestOptions | options |
Returns
Type | Description |
---|---|
Task<IReadOnlyCollection<SocketApplicationCommand>> |
CreateGlobalApplicationCommandAsync(ApplicationCommandProperties, RequestOptions)
Declaration
public async Task<SocketApplicationCommand> CreateGlobalApplicationCommandAsync(ApplicationCommandProperties properties, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
ApplicationCommandProperties | properties | |
RequestOptions | options |
Returns
Type | Description |
---|---|
Task<SocketApplicationCommand> |
DownloadUsersAsync(IEnumerable<IGuild>)
Attempts to download users into the user cache for the selected guilds.
Declaration
public override async Task DownloadUsersAsync(IEnumerable<IGuild> guilds)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<IGuild> | guilds | The guilds to download the members from. |
Returns
Type | Description |
---|---|
Task | A task that represents the asynchronous download operation. |
Overrides
| Improve this Doc View SourceGetApplicationInfoAsync(RequestOptions)
Gets a Discord application information for the logged-in user.
Declaration
public override async Task<RestApplication> GetApplicationInfoAsync(RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
Task<RestApplication> | A task that represents the asynchronous get operation. The task result contains the application information. |
Overrides
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 |
---|---|---|
UInt64 | id | The snowflake identifier of the channel (e.g. |
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
| Improve this Doc View SourceGetChannelAsync(UInt64, RequestOptions)
Gets a generic channel from the cache or does a rest request if unavailable.
Declaration
public async ValueTask<IChannel> GetChannelAsync(ulong id, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The snowflake identifier of the channel (e.g. |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
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}");
}
|
Improve this Doc
View Source
GetGlobalApplicationCommandAsync(UInt64, RequestOptions)
Gets a global application command.
Declaration
public async ValueTask<SocketApplicationCommand> GetGlobalApplicationCommandAsync(ulong id, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The id of the command. |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
ValueTask<SocketApplicationCommand> | A ValueTask that represents the asynchronous get operation. The task result contains the application command if found, otherwise null. |
GetGlobalApplicationCommandsAsync(Boolean, String, RequestOptions)
Gets a collection of all global commands.
Declaration
public async Task<IReadOnlyCollection<SocketApplicationCommand>> GetGlobalApplicationCommandsAsync(bool withLocalizations = false, string locale = null, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
Boolean | withLocalizations | Whether to include full localization dictionaries in the returned objects, instead of the name localized and description localized fields. |
String | locale | The target locale of the localized name and description fields. Sets |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
Task<IReadOnlyCollection<SocketApplicationCommand>> | A task that represents the asynchronous get operation. The task result contains a read-only collection of global application commands. |
GetGuild(UInt64)
Gets a guild.
Declaration
public override SocketGuild GetGuild(ulong id)
Parameters
Type | Name | Description |
---|---|---|
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
| Improve this Doc View SourceGetSticker(UInt64)
Gets a sticker.
Declaration
public SocketSticker GetSticker(ulong id)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The unique identifier of the sticker. |
Returns
Type | Description |
---|---|
SocketSticker | A sticker if found, otherwise null. |
GetStickerAsync(UInt64, CacheMode, RequestOptions)
Gets a sticker.
Declaration
public override async Task<SocketSticker> GetStickerAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The id of the sticker to get. |
CacheMode | mode | Whether or not to allow downloading from the api. |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
Task<SocketSticker> | A SocketSticker if found, otherwise null. |
Overrides
| Improve this Doc View SourceGetUser(String, String)
Gets a user.
Declaration
public override SocketUser GetUser(string username, string discriminator = null)
Parameters
Type | Name | Description |
---|---|---|
String | username | The name of the user. |
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
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
GetUser(UInt64)
Gets a generic user.
Declaration
public override SocketUser GetUser(ulong id)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The user snowflake ID. |
Returns
Type | Description |
---|---|
SocketUser | A generic WebSocket-based user; null when the user cannot be found. |
Overrides
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)
Gets a user from the cache or does a rest request if unavailable.
Declaration
public async ValueTask<IUser> GetUserAsync(ulong id, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
UInt64 | id | The snowflake identifier of the user (e.g. |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
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}.";
|
Improve this Doc
View Source
GetVoiceRegionAsync(String, RequestOptions)
Gets a voice region.
Declaration
public override async ValueTask<RestVoiceRegion> GetVoiceRegionAsync(string id, RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
String | id | The identifier of the voice region (e.g. |
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
ValueTask<RestVoiceRegion> | A task that contains a REST-based voice region associated with the identifier; null if the voice region is not found. |
Overrides
| Improve this Doc View SourceGetVoiceRegionsAsync(RequestOptions)
Gets all voice regions.
Declaration
public override async ValueTask<IReadOnlyCollection<RestVoiceRegion>> GetVoiceRegionsAsync(RequestOptions options = null)
Parameters
Type | Name | Description |
---|---|---|
RequestOptions | options | The options to be used when sending the request. |
Returns
Type | Description |
---|---|
ValueTask<IReadOnlyCollection<RestVoiceRegion>> | A task that contains a read-only collection of REST-based voice regions. |
Overrides
| Improve this Doc View SourcePurgeChannelCache()
Clears all cached channels from the client.
Declaration
public void PurgeChannelCache()
PurgeDMChannelCache()
Clears cached DM channels from the client.
Declaration
public void PurgeDMChannelCache()
PurgeUserCache()
Clears cached users from the client.
Declaration
public void PurgeUserCache()
SetActivityAsync(IActivity)
Sets the activity
of the logged-in user.
Declaration
public override async Task SetActivityAsync(IActivity activity)
Parameters
Type | Name | Description |
---|---|---|
IActivity | activity | The activity to be set. |
Returns
Type | Description |
---|---|
Task | A task that represents the asynchronous set operation. |
Overrides
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.
Declaration
public override async Task SetCustomStatusAsync(string status)
Parameters
Type | Name | Description |
---|---|---|
String | status | The string that will be displayed as status. |
Returns
Type | Description |
---|---|
Task | A task that represents the asynchronous set operation. |
Overrides
| Improve this Doc View SourceSetGameAsync(String, String, ActivityType)
Sets the game of the user.
Declaration
public override async Task SetGameAsync(string name, string streamUrl = null, ActivityType type = default(ActivityType))
Parameters
Type | Name | Description |
---|---|---|
String | name | The name of the game. |
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 |
---|---|
Task | A task that represents the asynchronous set operation. |
Overrides
Remarks
warning
Bot accounts cannot set CustomStatus as their activity type and it will have no effect.
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);
|
Improve this Doc
View Source
SetStatusAsync(UserStatus)
Sets the current status of the user (e.g. Online, Do not Disturb).
Declaration
public override async Task SetStatusAsync(UserStatus status)
Parameters
Type | Name | Description |
---|---|---|
UserStatus | status | The new status to be set. |
Returns
Type | Description |
---|---|
Task | A task that represents the asynchronous set operation. |
Overrides
Examples
The following example sets the status of the current user to Do Not Disturb.
await client.SetStatusAsync(UserStatus.DoNotDisturb);
|
Improve this Doc
View Source
StartAsync()
Declaration
public override async Task StartAsync()
Returns
Type | Description |
---|---|
Task |
Overrides
| Improve this Doc View SourceStopAsync()
Declaration
public override async Task StopAsync()
Returns
Type | Description |
---|---|
Task |
Overrides
Events
| Improve this Doc View SourceConnected
Fired when connected to the Discord gateway.
Declaration
public event Func<Task> Connected
Event Type
Type | Description |
---|---|
Func<Task> |
Disconnected
Fired when disconnected to the Discord gateway.
Declaration
public event Func<Exception, Task> Disconnected
Event Type
Type | Description |
---|---|
Func<Exception, Task> |
LatencyUpdated
Fired when a heartbeat is received from the Discord gateway.
Declaration
public event Func<int, int, Task> LatencyUpdated
Event Type
Type | Description |
---|---|
Func<Int32, Int32, Task> |
Ready
Fired when guild data has finished downloading.
Declaration
public event Func<Task> Ready
Event Type
Type | Description |
---|---|
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.