Class BaseSocketClient

Namespace

Discord.WebSocket

Assembly

Discord.Net.WebSocket.dll

Represents the base of a WebSocket-based Discord client.

public abstract class BaseSocketClient : BaseDiscordClient, IDiscordClient, IDisposable, IAsyncDisposable, IRestClientProvider

Inheritance

object

BaseDiscordClient

BaseSocketClient

Implements

IDiscordClient

IDisposable

IAsyncDisposable

IRestClientProvider

Derived

DiscordShardedClient

DiscordSocketClient

Inherited Members

BaseDiscordClient.Log

BaseDiscordClient.LoggedIn

BaseDiscordClient.LoggedOut

BaseDiscordClient.SentRequest

BaseDiscordClient.LoginState

BaseDiscordClient.TokenType

BaseDiscordClient.LoginAsync(TokenType, string, bool)

BaseDiscordClient.LogoutAsync()

BaseDiscordClient.Dispose()

BaseDiscordClient.DisposeAsync()

BaseDiscordClient.GetRecommendedShardCountAsync(RequestOptions)

BaseDiscordClient.GetBotGatewayAsync(RequestOptions)

BaseDiscordClient.ConnectionState

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DiscordClientExtensions.GetDMChannelAsync(IDiscordClient, ulong)

DiscordClientExtensions.GetDMChannelsAsync(IDiscordClient)

DiscordClientExtensions.GetGroupChannelAsync(IDiscordClient, ulong)

DiscordClientExtensions.GetGroupChannelsAsync(IDiscordClient)

DiscordClientExtensions.GetOptimalVoiceRegionAsync(IDiscordClient)

DiscordClientExtensions.GetPrivateChannelAsync(IDiscordClient, ulong)

ClientExtensions.AddGuildUserAsync(BaseDiscordClient, ulong, ulong, string, Action<AddGuildUserProperties>, RequestOptions)

Fields

BaseConfig

protected readonly DiscordSocketConfig BaseConfig

Field Value

DiscordSocketConfig

Properties

Activity

Gets the activity for the logged-in user.

public abstract IActivity Activity { get; protected set; }

Property Value

IActivity

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

CurrentUser

Gets the current logged-in user.

public virtual SocketSelfUser CurrentUser { get; protected set; }

Property Value

SocketSelfUser

DefaultStickerPacks

Gets a collection of default stickers.

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

Property Value

IReadOnlyCollection<StickerPack<SocketSticker>>

Guilds

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

public abstract 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 abstract 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 abstract 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 abstract DiscordSocketRestClient Rest { get; }

Property Value

DiscordSocketRestClient

Status

Gets the status for the logged-in user.

public abstract UserStatus Status { get; protected set; }

Property Value

UserStatus

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

Methods

CreateGuildAsync(string, IVoiceRegion, Stream, RequestOptions)

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

public Task<RestGuild> CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null)

Parameters

name string

The name of the new guild.

region IVoiceRegion

The voice region to create the guild with.

jpegIcon Stream

The icon of the guild.

options RequestOptions

The options to be used when sending the request.

Returns

Task<RestGuild>

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.

DownloadUsersAsync(IEnumerable<IGuild>)

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

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

GetApplicationInfoAsync(RequestOptions)

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

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

GetConnectionsAsync(RequestOptions)

Gets the connections that the user has set up.

public Task<IReadOnlyCollection<RestConnection>> GetConnectionsAsync(RequestOptions options = null)

Parameters

options RequestOptions

The options to be used when sending the request.

Returns

Task<IReadOnlyCollection<RestConnection>>

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

GetGuild(ulong)

Gets a guild.

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

GetInviteAsync(string, RequestOptions, ulong?)

Gets an invite.

public Task<RestInviteMetadata> GetInviteAsync(string inviteId, RequestOptions options = null, ulong? scheduledEventId = null)

Parameters

inviteId string

The invitation identifier.

options RequestOptions

The options to be used when sending the request.

scheduledEventId ulong?

The id of the guild scheduled event to include with the invite.

Returns

Task<RestInviteMetadata>

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

GetStickerAsync(ulong, CacheMode, RequestOptions)

Gets a sticker.

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

GetUser(string, string)

Gets a user.

public abstract 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 abstract 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).

GetVoiceRegionAsync(string, RequestOptions)

Gets a voice region.

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

SetActivityAsync(IActivity)

Sets the activity of the logged-in user.

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

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 abstract Task SetStatusAsync(UserStatus status)

Parameters

status UserStatus

The new status to be set.

Returns

Task

A task that represents the asynchronous set operation.

StartAsync()

Starts the connection between Discord and the client..

public abstract 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 abstract Task StopAsync()

Returns

Task

A task that represents the asynchronous stop operation.

Events

ApplicationCommandCreated

Fired when a guild application command is created.

public event Func<SocketApplicationCommand, Task> ApplicationCommandCreated

Event Type

Func<SocketApplicationCommand, Task>

Remarks

This event is fired when an application command is created. The event handler must return a Task and accept a SocketApplicationCommand as its parameter.

The command that was deleted will be passed into the SocketApplicationCommand parameter.

note

This event is an undocumented discord event and may break at any time, its not recommended to rely on this event

ApplicationCommandDeleted

Fired when a guild application command is deleted.

public event Func<SocketApplicationCommand, Task> ApplicationCommandDeleted

Event Type

Func<SocketApplicationCommand, Task>

Remarks

This event is fired when an application command is deleted. The event handler must return a Task and accept a SocketApplicationCommand as its parameter.

The command that was deleted will be passed into the SocketApplicationCommand parameter.

note

This event is an undocumented discord event and may break at any time, its not recommended to rely on this event

ApplicationCommandUpdated

Fired when a guild application command is updated.

public event Func<SocketApplicationCommand, Task> ApplicationCommandUpdated

Event Type

Func<SocketApplicationCommand, Task>

Remarks

This event is fired when an application command is updated. The event handler must return a Task and accept a SocketApplicationCommand as its parameter.

The command that was deleted will be passed into the SocketApplicationCommand parameter.

note

This event is an undocumented discord event and may break at any time, its not recommended to rely on this event

AuditLogCreated

Fired when a guild audit log entry is created.

public event Func<SocketAuditLogEntry, SocketGuild, Task> AuditLogCreated

Event Type

Func<SocketAuditLogEntry, SocketGuild, Task>

AutoModActionExecuted

Fired when an auto moderation rule is triggered by a user.

public event Func<SocketGuild, AutoModRuleAction, AutoModActionExecutedData, Task> AutoModActionExecuted

Event Type

Func<SocketGuild, AutoModRuleAction, AutoModActionExecutedData, Task>

AutoModRuleCreated

Fired when an auto moderation rule is created.

public event Func<SocketAutoModRule, Task> AutoModRuleCreated

Event Type

Func<SocketAutoModRule, Task>

AutoModRuleDeleted

Fired when an auto moderation rule is deleted.

public event Func<SocketAutoModRule, Task> AutoModRuleDeleted

Event Type

Func<SocketAutoModRule, Task>

AutoModRuleUpdated

Fired when an auto moderation rule is modified.

public event Func<Cacheable<SocketAutoModRule, ulong>, SocketAutoModRule, Task> AutoModRuleUpdated

Event Type

Func<Cacheable<SocketAutoModRule, ulong>, SocketAutoModRule, Task>

AutocompleteExecuted

Fired when an autocomplete is used and its interaction is received.

public event Func<SocketAutocompleteInteraction, Task> AutocompleteExecuted

Event Type

Func<SocketAutocompleteInteraction, Task>

ButtonExecuted

Fired when a button is clicked and its interaction is received.

public event Func<SocketMessageComponent, Task> ButtonExecuted

Event Type

Func<SocketMessageComponent, Task>

ChannelCreated

Fired when a channel is created.

public event Func<SocketChannel, Task> ChannelCreated

Event Type

Func<SocketChannel, Task>

Examples

public void HookChannelCreated(BaseSocketClient client)
    => client.ChannelCreated += HandleChannelCreated;

public Task HandleChannelCreated(SocketChannel channel)
{
    if (channel is SocketGuildChannel guildChannel)
        Console.WriteLine($"A new channel '{guildChannel.Name}'({guildChannel.Id}, {guildChannel.GetType()})"
                          + $"has been created at {guildChannel.CreatedAt}.");
    return Task.CompletedTask;
}

Remarks

This event is fired when a generic channel has been created. The event handler must return a Task and accept a SocketChannel as its parameter.

The newly created channel is passed into the event handler parameter. The given channel type may include, but not limited to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category); see the derived classes of SocketChannel for more details.

ChannelDestroyed

Fired when a channel is destroyed.

public event Func<SocketChannel, Task> ChannelDestroyed

Event Type

Func<SocketChannel, Task>

Examples

public void HookChannelDestroyed(BaseSocketClient client)
    => client.ChannelDestroyed += HandleChannelDestroyed;

public Task HandleChannelDestroyed(SocketChannel channel)
{
    if (channel is SocketGuildChannel guildChannel)
        Console.WriteLine(
            $"A new channel '{guildChannel.Name}'({guildChannel.Id}, {guildChannel.GetType()}) has been deleted.");
    return Task.CompletedTask;
}

Remarks

This event is fired when a generic channel has been destroyed. The event handler must return a Task and accept a SocketChannel as its parameter.

The destroyed channel is passed into the event handler parameter. The given channel type may include, but not limited to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category); see the derived classes of SocketChannel for more details.

ChannelUpdated

Fired when a channel is updated.

public event Func<SocketChannel, SocketChannel, Task> ChannelUpdated

Event Type

Func<SocketChannel, SocketChannel, Task>

Examples

public void HookChannelUpdated(BaseSocketClient client)
    => client.ChannelUpdated += HandleChannelRename;

public Task HandleChannelRename(SocketChannel beforeChannel, SocketChannel afterChannel)
{
    if (beforeChannel is SocketGuildChannel beforeGuildChannel &&
        afterChannel is SocketGuildChannel afterGuildChannel)
        if (beforeGuildChannel.Name != afterGuildChannel.Name)
            Console.WriteLine(
                $"A channel ({beforeChannel.Id}) is renamed from {beforeGuildChannel.Name} to {afterGuildChannel.Name}.");
    return Task.CompletedTask;
}

Remarks

This event is fired when a generic channel has been updated. The event handler must return a Task and accept 2 SocketChannel as its parameters.

The original (prior to update) channel is passed into the first SocketChannel, while the updated channel is passed into the second. The given channel type may include, but not limited to, Private Channels (DM, Group), Guild Channels (Text, Voice, Category); see the derived classes of SocketChannel for more details.

CurrentUserUpdated

Fired when the connected account is updated.

public event Func<SocketSelfUser, SocketSelfUser, Task> CurrentUserUpdated

Event Type

Func<SocketSelfUser, SocketSelfUser, Task>

EntitlementCreated

Fired when a user subscribes to a SKU.

public event Func<SocketEntitlement, Task> EntitlementCreated

Event Type

Func<SocketEntitlement, Task>

EntitlementDeleted

Fired when a user's entitlement is deleted.

public event Func<Cacheable<SocketEntitlement, ulong>, Task> EntitlementDeleted

Event Type

Func<Cacheable<SocketEntitlement, ulong>, Task>

EntitlementUpdated

Fired when a subscription to a SKU is updated.

public event Func<Cacheable<SocketEntitlement, ulong>, SocketEntitlement, Task> EntitlementUpdated

Event Type

Func<Cacheable<SocketEntitlement, ulong>, SocketEntitlement, Task>

GuildAvailable

Fired when a guild becomes available.

public event Func<SocketGuild, Task> GuildAvailable

Event Type

Func<SocketGuild, Task>

GuildJoinRequestDeleted

Fired when a user leaves without agreeing to the member screening

public event Func<Cacheable<SocketGuildUser, ulong>, SocketGuild, Task> GuildJoinRequestDeleted

Event Type

Func<Cacheable<SocketGuildUser, ulong>, SocketGuild, Task>

GuildMemberUpdated

Fired when a guild member is updated.

public event Func<Cacheable<SocketGuildUser, ulong>, SocketGuildUser, Task> GuildMemberUpdated

Event Type

Func<Cacheable<SocketGuildUser, ulong>, SocketGuildUser, Task>

GuildMembersDownloaded

Fired when offline guild members are downloaded.

public event Func<SocketGuild, Task> GuildMembersDownloaded

Event Type

Func<SocketGuild, Task>

GuildScheduledEventCancelled

Fired when a guild event is cancelled.

public event Func<SocketGuildEvent, Task> GuildScheduledEventCancelled

Event Type

Func<SocketGuildEvent, Task>

GuildScheduledEventCompleted

Fired when a guild event is completed.

public event Func<SocketGuildEvent, Task> GuildScheduledEventCompleted

Event Type

Func<SocketGuildEvent, Task>

GuildScheduledEventCreated

Fired when a guild event is created.

public event Func<SocketGuildEvent, Task> GuildScheduledEventCreated

Event Type

Func<SocketGuildEvent, Task>

GuildScheduledEventStarted

Fired when a guild event is started.

public event Func<SocketGuildEvent, Task> GuildScheduledEventStarted

Event Type

Func<SocketGuildEvent, Task>

GuildScheduledEventUpdated

Fired when a guild event is updated.

public event Func<Cacheable<SocketGuildEvent, ulong>, SocketGuildEvent, Task> GuildScheduledEventUpdated

Event Type

Func<Cacheable<SocketGuildEvent, ulong>, SocketGuildEvent, Task>

GuildScheduledEventUserAdd

public event Func<Cacheable<SocketUser, RestUser, IUser, ulong>, SocketGuildEvent, Task> GuildScheduledEventUserAdd

Event Type

Func<Cacheable<SocketUser, RestUser, IUser, ulong>, SocketGuildEvent, Task>

GuildScheduledEventUserRemove

public event Func<Cacheable<SocketUser, RestUser, IUser, ulong>, SocketGuildEvent, Task> GuildScheduledEventUserRemove

Event Type

Func<Cacheable<SocketUser, RestUser, IUser, ulong>, SocketGuildEvent, Task>

GuildStickerCreated

Fired when a sticker in a guild is created.

public event Func<SocketCustomSticker, Task> GuildStickerCreated

Event Type

Func<SocketCustomSticker, Task>

GuildStickerDeleted

Fired when a sticker in a guild is deleted.

public event Func<SocketCustomSticker, Task> GuildStickerDeleted

Event Type

Func<SocketCustomSticker, Task>

GuildStickerUpdated

Fired when a sticker in a guild is updated.

public event Func<SocketCustomSticker, SocketCustomSticker, Task> GuildStickerUpdated

Event Type

Func<SocketCustomSticker, SocketCustomSticker, Task>

GuildUnavailable

Fired when a guild becomes unavailable.

public event Func<SocketGuild, Task> GuildUnavailable

Event Type

Func<SocketGuild, Task>

GuildUpdated

Fired when a guild is updated.

public event Func<SocketGuild, SocketGuild, Task> GuildUpdated

Event Type

Func<SocketGuild, SocketGuild, Task>

IntegrationCreated

Fired when an integration is created.

public event Func<IIntegration, Task> IntegrationCreated

Event Type

Func<IIntegration, Task>

IntegrationDeleted

Fired when an integration is deleted.

public event Func<IGuild, ulong, Optional<ulong>, Task> IntegrationDeleted

Event Type

Func<IGuild, ulong, Optional<ulong>, Task>

IntegrationUpdated

Fired when an integration is updated.

public event Func<IIntegration, Task> IntegrationUpdated

Event Type

Func<IIntegration, Task>

InteractionCreated

Fired when an Interaction is created. This event covers all types of interactions including but not limited to: buttons, select menus, slash commands, autocompletes.

public event Func<SocketInteraction, Task> InteractionCreated

Event Type

Func<SocketInteraction, Task>

Remarks

This event is fired when an interaction is created. The event handler must return a Task and accept a SocketInteraction as its parameter.

The interaction created will be passed into the SocketInteraction parameter.

InviteCreated

Fired when an invite is created.

public event Func<SocketInvite, Task> InviteCreated

Event Type

Func<SocketInvite, Task>

Remarks

This event is fired when an invite is created. The event handler must return a Task and accept a SocketInvite as its parameter.

The invite created will be passed into the SocketInvite parameter.

InviteDeleted

Fired when an invite is deleted.

public event Func<SocketGuildChannel, string, Task> InviteDeleted

Event Type

Func<SocketGuildChannel, string, Task>

Remarks

This event is fired when an invite is deleted. The event handler must return a Task and accept a SocketGuildChannel and string as its parameter.

The channel where this invite was created will be passed into the SocketGuildChannel parameter.

The code of the deleted invite will be passed into the string parameter.

JoinedGuild

Fired when the connected account joins a guild.

public event Func<SocketGuild, Task> JoinedGuild

Event Type

Func<SocketGuild, Task>

LeftGuild

Fired when the connected account leaves a guild.

public event Func<SocketGuild, Task> LeftGuild

Event Type

Func<SocketGuild, Task>

MessageCommandExecuted

Fired when a message command is used and its interaction is received.

public event Func<SocketMessageCommand, Task> MessageCommandExecuted

Event Type

Func<SocketMessageCommand, Task>

MessageDeleted

Fired when a message is deleted.

public event Func<Cacheable<IMessage, ulong>, Cacheable<IMessageChannel, ulong>, Task> MessageDeleted

Event Type

Func<Cacheable<IMessage, ulong>, Cacheable<IMessageChannel, ulong>, Task>

Examples

public void HookMessageDeleted(BaseSocketClient client)
    => client.MessageDeleted += HandleMessageDelete;

public async Task HandleMessageDelete(Cacheable<IMessage, ulong> cachedMessage, Cacheable<IMessageChannel, ulong> cachedChannel)
{
    // check if the message exists in cache; if not, we cannot report what was removed
    if (!cachedMessage.HasValue)
        return;
    // gets or downloads the channel if it's not in the cache
    IMessageChannel channel = await cachedChannel.GetOrDownloadAsync();
    var message = cachedMessage.Value;
    Console.WriteLine(
        $"A message ({message.Id}) from {message.Author} was removed from the channel {channel.Name} ({channel.Id}):"
        + Environment.NewLine
        + message.Content);
}

Remarks

This event is fired when a message is deleted. The event handler must return a Task and accept a Cacheable<TEntity, TId> and ISocketMessageChannel as its parameters.

important

It is not possible to retrieve the message via DownloadAsync(); the message cannot be retrieved by Discord after the message has been deleted.

If caching is enabled via DiscordSocketConfig, the Cacheable<TEntity, TId> entity will contain the deleted message; otherwise, in event that the message cannot be retrieved, the snowflake ID of the message is preserved in the ulong.

The source channel of the removed message will be passed into the ISocketMessageChannel parameter.

MessageReceived

Fired when a message is received.

public event Func<SocketMessage, Task> MessageReceived

Event Type

Func<SocketMessage, Task>

Examples

The example below checks if the newly received message contains the target user.

private readonly ulong[] _targetUserIds = { 168693960628371456, 53905483156684800 };
public void HookMessageReceived(BaseSocketClient client)
=> client.MessageReceived += HandleMessageReceived;
public Task HandleMessageReceived(SocketMessage message)
{
// check if the message is a user message as opposed to a system message (e.g. Clyde, pins, etc.)
if (!(message is SocketUserMessage userMessage))
return Task.CompletedTask;
// check if the message origin is a guild message channel
if (!(userMessage.Channel is SocketTextChannel textChannel))
return Task.CompletedTask;
// check if the target user was mentioned
var targetUsers = userMessage.MentionedUsers.Where(x => _targetUserIds.Contains(x.Id));
foreach (var targetUser in targetUsers)
Console.WriteLine(
$"{targetUser} was mentioned in the message '{message.Content}' by {message.Author} in {textChannel.Name}.");
return Task.CompletedTask;
}

Remarks

This event is fired when a message is received. The event handler must return a Task and accept a SocketMessage as its parameter.

The message that is sent to the client is passed into the event handler parameter as SocketMessage. This message may be a system message (i.e. SocketSystemMessage) or a user message (i.e. SocketUserMessage. See the derived classes of SocketMessage for more details.

MessageUpdated

Fired when a message is updated.

public event Func<Cacheable<IMessage, ulong>, SocketMessage, ISocketMessageChannel, Task> MessageUpdated

Event Type

Func<Cacheable<IMessage, ulong>, SocketMessage, ISocketMessageChannel, Task>

Remarks

This event is fired when a message is updated. The event handler must return a Task and accept a Cacheable<TEntity, TId>, SocketMessage, and ISocketMessageChannel as its parameters.

If caching is enabled via DiscordSocketConfig, the Cacheable<TEntity, TId> entity will contain the original message; otherwise, in event that the message cannot be retrieved, the snowflake ID of the message is preserved in the ulong.

The updated message will be passed into the SocketMessage parameter.

The source channel of the updated message will be passed into the ISocketMessageChannel parameter.

MessagesBulkDeleted

Fired when multiple messages are bulk deleted.

public event Func<IReadOnlyCollection<Cacheable<IMessage, ulong>>, Cacheable<IMessageChannel, ulong>, Task> MessagesBulkDeleted

Event Type

Func<IReadOnlyCollection<Cacheable<IMessage, ulong>>, Cacheable<IMessageChannel, ulong>, Task>

Remarks

note

The MessageDeleted event will not be fired for individual messages contained in this event.

This event is fired when multiple messages are bulk deleted. The event handler must return a Task and accept an IReadOnlyCollection<T> and ISocketMessageChannel as its parameters.

important

It is not possible to retrieve the message via DownloadAsync(); the message cannot be retrieved by Discord after the message has been deleted.

If caching is enabled via DiscordSocketConfig, the Cacheable<TEntity, TId> entity will contain the deleted message; otherwise, in event that the message cannot be retrieved, the snowflake ID of the message is preserved in the ulong.

The source channel of the removed message will be passed into the ISocketMessageChannel parameter.

ModalSubmitted

Fired when a modal is submitted.

public event Func<SocketModal, Task> ModalSubmitted

Event Type

Func<SocketModal, Task>

PollVoteAdded

Fired when a vote is added to a poll.

public event Func<Cacheable<IUser, ulong>, Cacheable<ISocketMessageChannel, IRestMessageChannel, IMessageChannel, ulong>, Cacheable<IUserMessage, ulong>, Cacheable<SocketGuild, RestGuild, IGuild, ulong>?, ulong, Task> PollVoteAdded

Event Type

Func<Cacheable<IUser, ulong>, Cacheable<ISocketMessageChannel, IRestMessageChannel, IMessageChannel, ulong>, Cacheable<IUserMessage, ulong>, Cacheable<SocketGuild, RestGuild, IGuild, ulong>?, ulong, Task>

PollVoteRemoved

Fired when a vote is removed from a poll.

public event Func<Cacheable<IUser, ulong>, Cacheable<ISocketMessageChannel, IRestMessageChannel, IMessageChannel, ulong>, Cacheable<IUserMessage, ulong>, Cacheable<SocketGuild, RestGuild, IGuild, ulong>?, ulong, Task> PollVoteRemoved

Event Type

Func<Cacheable<IUser, ulong>, Cacheable<ISocketMessageChannel, IRestMessageChannel, IMessageChannel, ulong>, Cacheable<IUserMessage, ulong>, Cacheable<SocketGuild, RestGuild, IGuild, ulong>?, ulong, Task>

PresenceUpdated

Fired when a users presence is updated.

public event Func<SocketUser, SocketPresence, SocketPresence, Task> PresenceUpdated

Event Type

Func<SocketUser, SocketPresence, SocketPresence, Task>

ReactionAdded

Fired when a reaction is added to a message.

public event Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, SocketReaction, Task> ReactionAdded

Event Type

Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, SocketReaction, Task>

Examples

public void HookReactionAdded(BaseSocketClient client)
    => client.ReactionAdded += HandleReactionAddedAsync;

public async Task HandleReactionAddedAsync(Cacheable<IUserMessage, ulong> cachedMessage,
    Cacheable<IMessageChannel, ulong> originChannel, SocketReaction reaction)
{
    var message = await cachedMessage.GetOrDownloadAsync();
    if (message != null && reaction.User.IsSpecified)
        Console.WriteLine($"{reaction.User.Value} just added a reaction '{reaction.Emote}' " +
                          $"to {message.Author}'s message ({message.Id}).");
}

Remarks

This event is fired when a reaction is added to a user message. The event handler must return a Task and accept a Cacheable<TEntity, TId>, an ISocketMessageChannel, and a SocketReaction as its parameter.

If caching is enabled via DiscordSocketConfig, the Cacheable<TEntity, TId> entity will contain the original message; otherwise, in event that the message cannot be retrieved, the snowflake ID of the message is preserved in the ulong.

The source channel of the reaction addition will be passed into the ISocketMessageChannel parameter.

The reaction that was added will be passed into the SocketReaction parameter.

note

When fetching the reaction from this event, a user may not be provided under User. Please see the documentation of the property for more information.

ReactionRemoved

Fired when a reaction is removed from a message.

public event Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, SocketReaction, Task> ReactionRemoved

Event Type

Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, SocketReaction, Task>

ReactionsCleared

Fired when all reactions to a message are cleared.

public event Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, Task> ReactionsCleared

Event Type

Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, Task>

ReactionsRemovedForEmote

Fired when all reactions to a message with a specific emote are removed.

public event Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, IEmote, Task> ReactionsRemovedForEmote

Event Type

Func<Cacheable<IUserMessage, ulong>, Cacheable<IMessageChannel, ulong>, IEmote, Task>

Remarks

This event is fired when all reactions to a message with a specific emote are removed. The event handler must return a Task and accept a ISocketMessageChannel and a IEmote as its parameters.

The channel where this message was sent will be passed into the ISocketMessageChannel parameter.

The emoji that all reactions had and were removed will be passed into the IEmote parameter.

RecipientAdded

Fired when a user joins a group channel.

public event Func<SocketGroupUser, Task> RecipientAdded

Event Type

Func<SocketGroupUser, Task>

RecipientRemoved

Fired when a user is removed from a group channel.

public event Func<SocketGroupUser, Task> RecipientRemoved

Event Type

Func<SocketGroupUser, Task>

RequestToSpeak

Fired when a user requests to speak within a stage channel.

public event Func<SocketStageChannel, SocketGuildUser, Task> RequestToSpeak

Event Type

Func<SocketStageChannel, SocketGuildUser, Task>

RoleCreated

Fired when a role is created.

public event Func<SocketRole, Task> RoleCreated

Event Type

Func<SocketRole, Task>

RoleDeleted

Fired when a role is deleted.

public event Func<SocketRole, Task> RoleDeleted

Event Type

Func<SocketRole, Task>

RoleUpdated

Fired when a role is updated.

public event Func<SocketRole, SocketRole, Task> RoleUpdated

Event Type

Func<SocketRole, SocketRole, Task>

SelectMenuExecuted

Fired when a select menu is used and its interaction is received.

public event Func<SocketMessageComponent, Task> SelectMenuExecuted

Event Type

Func<SocketMessageComponent, Task>

SlashCommandExecuted

Fired when a slash command is used and its interaction is received.

public event Func<SocketSlashCommand, Task> SlashCommandExecuted

Event Type

Func<SocketSlashCommand, Task>

SpeakerAdded

Fired when a speaker is added in a stage channel.

public event Func<SocketStageChannel, SocketGuildUser, Task> SpeakerAdded

Event Type

Func<SocketStageChannel, SocketGuildUser, Task>

SpeakerRemoved

Fired when a speaker is removed from a stage channel.

public event Func<SocketStageChannel, SocketGuildUser, Task> SpeakerRemoved

Event Type

Func<SocketStageChannel, SocketGuildUser, Task>

StageEnded

Fired when a stage ends.

public event Func<SocketStageChannel, Task> StageEnded

Event Type

Func<SocketStageChannel, Task>

StageStarted

Fired when a stage is started.

public event Func<SocketStageChannel, Task> StageStarted

Event Type

Func<SocketStageChannel, Task>

StageUpdated

Fired when a stage is updated.

public event Func<SocketStageChannel, SocketStageChannel, Task> StageUpdated

Event Type

Func<SocketStageChannel, SocketStageChannel, Task>

SubscriptionCreated

Fired when a user subscribes to a SKU.

public event Func<SocketSubscription, Task> SubscriptionCreated

Event Type

Func<SocketSubscription, Task>

SubscriptionDeleted

Fired when a user's subscription is deleted.

public event Func<Cacheable<SocketSubscription, ulong>, Task> SubscriptionDeleted

Event Type

Func<Cacheable<SocketSubscription, ulong>, Task>

SubscriptionUpdated

Fired when a subscription to a SKU is updated.

public event Func<Cacheable<SocketSubscription, ulong>, SocketSubscription, Task> SubscriptionUpdated

Event Type

Func<Cacheable<SocketSubscription, ulong>, SocketSubscription, Task>

ThreadCreated

Fired when a thread is created within a guild, or when the current user is added to a thread.

public event Func<SocketThreadChannel, Task> ThreadCreated

Event Type

Func<SocketThreadChannel, Task>

ThreadDeleted

Fired when a thread is deleted.

public event Func<Cacheable<SocketThreadChannel, ulong>, Task> ThreadDeleted

Event Type

Func<Cacheable<SocketThreadChannel, ulong>, Task>

ThreadMemberJoined

Fired when a user joins a thread

public event Func<SocketThreadUser, Task> ThreadMemberJoined

Event Type

Func<SocketThreadUser, Task>

ThreadMemberLeft

Fired when a user leaves a thread

public event Func<SocketThreadUser, Task> ThreadMemberLeft

Event Type

Func<SocketThreadUser, Task>

ThreadUpdated

Fired when a thread is updated within a guild.

public event Func<Cacheable<SocketThreadChannel, ulong>, SocketThreadChannel, Task> ThreadUpdated

Event Type

Func<Cacheable<SocketThreadChannel, ulong>, SocketThreadChannel, Task>

UserBanned

Fired when a user is banned from a guild.

public event Func<SocketUser, SocketGuild, Task> UserBanned

Event Type

Func<SocketUser, SocketGuild, Task>

UserCommandExecuted

Fired when a user command is used and its interaction is received.

public event Func<SocketUserCommand, Task> UserCommandExecuted

Event Type

Func<SocketUserCommand, Task>

UserIsTyping

Fired when a user starts typing.

public event Func<Cacheable<IUser, ulong>, Cacheable<IMessageChannel, ulong>, Task> UserIsTyping

Event Type

Func<Cacheable<IUser, ulong>, Cacheable<IMessageChannel, ulong>, Task>

UserJoined

Fired when a user joins a guild.

public event Func<SocketGuildUser, Task> UserJoined

Event Type

Func<SocketGuildUser, Task>

UserLeft

Fired when a user leaves a guild.

public event Func<SocketGuild, SocketUser, Task> UserLeft

Event Type

Func<SocketGuild, SocketUser, Task>

UserUnbanned

Fired when a user is unbanned from a guild.

public event Func<SocketUser, SocketGuild, Task> UserUnbanned

Event Type

Func<SocketUser, SocketGuild, Task>

UserUpdated

Fired when a user is updated.

public event Func<SocketUser, SocketUser, Task> UserUpdated

Event Type

Func<SocketUser, SocketUser, Task>

UserVoiceStateUpdated

Fired when a user joins, leaves, or moves voice channels.

public event Func<SocketUser, SocketVoiceState, SocketVoiceState, Task> UserVoiceStateUpdated

Event Type

Func<SocketUser, SocketVoiceState, SocketVoiceState, Task>

VoiceChannelStatusUpdated

Fired when status of a voice channel is updated.

public event Func<Cacheable<SocketVoiceChannel, ulong>, string, string, Task> VoiceChannelStatusUpdated

Event Type

Func<Cacheable<SocketVoiceChannel, ulong>, string, string, Task>

Remarks

The previous state of the channel is passed into the first parameter; the updated channel is passed into the second one.

VoiceServerUpdated

Fired when the bot connects to a Discord voice server.

public event Func<SocketVoiceServer, Task> VoiceServerUpdated

Event Type

Func<SocketVoiceServer, Task>

WebhooksUpdated

Fired when a webhook is modified, moved, or deleted. If the webhook was moved the channel represents the destination channel, not the source.

public event Func<SocketGuild, SocketChannel, Task> WebhooksUpdated

Event Type

Func<SocketGuild, SocketChannel, Task>