Interface IMessageChannel

Namespace: Discord

Assembly: Discord.Net.Core.dll

Represents a generic channel that can send and receive messages.

public interface IMessageChannel : IChannel, ISnowflakeEntity, IEntity<ulong>

Inherited Members: IChannel.Name

IChannel.GetUsersAsync(CacheMode, RequestOptions)

IChannel.GetUserAsync(ulong, CacheMode, RequestOptions)

ISnowflakeEntity.CreatedAt

IEntity<ulong>.Id

Extension Methods: ChannelExtensions.GetChannelType(IChannel)

Methods

DeleteMessageAsync(IMessage, RequestOptions)

Deletes a message based on the provided message in this channel.

Task DeleteMessageAsync(IMessage message, RequestOptions options = null)

Parameters

message IMessage: The message that would be removed.
options RequestOptions: The options to be used when sending the request.

Returns

Task: A task that represents the asynchronous removal operation.

DeleteMessageAsync(ulong, RequestOptions)

Deletes a message.

Task DeleteMessageAsync(ulong messageId, RequestOptions options = null)

Parameters

messageId ulong: The snowflake identifier of the message that would be removed.
options RequestOptions: The options to be used when sending the request.

Returns

Task: A task that represents the asynchronous removal operation.

EnterTypingState(RequestOptions)

Continuously broadcasts the "user is typing" message to all users in this channel until the returned object is disposed.

IDisposable EnterTypingState(RequestOptions options = null)

Parameters

options RequestOptions: The options to be used when sending the request.

Returns

IDisposable: A disposable object that, upon its disposal, will stop the client from broadcasting its typing state in this channel.

Examples

The following example keeps the client in the typing state until LongRunningAsync has finished.

using (channel.EnterTypingState())
    await LongRunningAsync();

GetMessageAsync(ulong, CacheMode, RequestOptions)

Gets a message from this message channel.

Task<IMessage> GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)

Parameters

id ulong: The snowflake identifier of the message.
mode CacheMode: The CacheMode that determines whether the object should be fetched from cache.
options RequestOptions: The options to be used when sending the request.

Returns

Task<IMessage>: A task that represents an asynchronous get operation for retrieving the message. The task result contains the retrieved message; null if no message is found with the specified identifier.

GetMessagesAsync(IMessage, Direction, int, CacheMode, RequestOptions)

Gets a collection of messages in this channel.

IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = 100, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)

Parameters

fromMessage IMessage: The starting message to get the messages from.
dir Direction: The direction of the messages to be gotten from.
limit int: The numbers of message to be gotten from.
mode CacheMode: The CacheMode that determines whether the object should be fetched from cache.
options RequestOptions: The options to be used when sending the request.

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>: Paged collection of messages.

Examples

The following example gets 5 message prior to a specific message, oldMessage.

var oldMessage = await channel.SendMessageAsync("boi");
var messagesFromMsg = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync();

Remarks

important

The returned collection is an asynchronous enumerable object; one must call FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) to access the individual messages as a collection.

warning

Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual rate limit, causing your bot to freeze!

This method will attempt to fetch the number of messages specified under limit around the message fromMessage depending on the dir. The library will attempt to split up the requests according to your limit and MaxMessagesPerBatch. In other words, should the user request 500 messages, and the MaxMessagesPerBatch constant is 100, the request will be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need of flattening.

GetMessagesAsync(int, CacheMode, RequestOptions)

Gets the last N messages from this message channel.

IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(int limit = 100, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)

Parameters

limit int: The numbers of message to be gotten from.
mode CacheMode: The CacheMode that determines whether the object should be fetched from cache.
options RequestOptions: The options to be used when sending the request.

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>: Paged collection of messages.

Examples

The following example downloads 300 messages and gets messages that belong to the user 53905483156684800.

var messages = await channel.GetMessagesAsync(300).FlattenAsync();
var userMessages = messages.Where(x => x.Author.Id == 53905483156684800);

Remarks

important

The returned collection is an asynchronous enumerable object; one must call FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) to access the individual messages as a collection.

warning

Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual rate limit, causing your bot to freeze!

This method will attempt to fetch the number of messages specified under limit. The library will attempt to split up the requests according to your limit and MaxMessagesPerBatch. In other words, should the user request 500 messages, and the MaxMessagesPerBatch constant is 100, the request will be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need of flattening.

GetMessagesAsync(ulong, Direction, int, CacheMode, RequestOptions)

Gets a collection of messages in this channel.

IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = 100, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null)

Parameters

fromMessageId ulong: The ID of the starting message to get the messages from.
dir Direction: The direction of the messages to be gotten from.
limit int: The numbers of message to be gotten from.
mode CacheMode: The CacheMode that determines whether the object should be fetched from cache.
options RequestOptions: The options to be used when sending the request.

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>: Paged collection of messages.

Examples

The following example gets 5 message prior to the message identifier 442012544660537354.

await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync();

The following example attempts to retrieve messageCount number of messages from the beginning of the channel and prints them to the console.

public async Task PrintFirstMessages(IMessageChannel channel, int messageCount)
{
    // Although the library does attempt to divide the messageCount by 100
    // to comply to Discord's maximum message limit per request, sending
    // too many could still cause the queue to clog up.
    // The purpose of this exception is to discourage users from sending
    // too many requests at once.
    if (messageCount > 1000)
        throw new InvalidOperationException("Too many messages requested.");
// Setting fromMessageId to 0 will make Discord
// default to the first message in channel.
var messages = await channel.GetMessagesAsync(
        0, Direction.After, messageCount)
    .FlattenAsync();

// Print message content
foreach (var message in messages)
    Console.WriteLine($"{message.Author} posted '{message.Content}' at {message.CreatedAt}.");

}

Remarks

important

The returned collection is an asynchronous enumerable object; one must call FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) to access the individual messages as a collection.

warning

Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual rate limit, causing your bot to freeze!

This method will attempt to fetch the number of messages specified under limit around the message fromMessageId depending on the dir. The library will attempt to split up the requests according to your limit and MaxMessagesPerBatch. In other words, should the user request 500 messages, and the MaxMessagesPerBatch constant is 100, the request will be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need of flattening.

GetPinnedMessagesAsync(RequestOptions)

Gets a collection of pinned messages in this channel.

Task<IReadOnlyCollection<IMessage>> GetPinnedMessagesAsync(RequestOptions options = null)

Parameters

options RequestOptions: The options to be used when sending the request.

Returns

Task<IReadOnlyCollection<IMessage>>: A task that represents the asynchronous get operation for retrieving pinned messages in this channel. The task result contains a collection of messages found in the pinned messages.

ModifyMessageAsync(ulong, Action<MessageProperties>, RequestOptions)

Modifies a message.

Task<IUserMessage> ModifyMessageAsync(ulong messageId, Action<MessageProperties> func, RequestOptions options = null)

Parameters

messageId ulong: The snowflake identifier of the message that would be changed.
func Action<MessageProperties>: A delegate containing the properties to modify the message with.
options RequestOptions: The options to be used when sending the request.

Returns

Task<IUserMessage>: A task that represents the asynchronous modification operation.

Remarks

This method modifies this message with the specified properties. To see an example of this method and what properties are available, please refer to MessageProperties.

SendFileAsync(FileAttachment, string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Sends a file to this message channel with an optional caption.

Task<IUserMessage> SendFileAsync(FileAttachment attachment, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null, MessageReference messageReference = null, MessageComponent components = null, ISticker[] stickers = null, Embed[] embeds = null, MessageFlags flags = MessageFlags.None, PollProperties poll = null)

Parameters

attachment FileAttachment: The attachment containing the file and description.
text string: The message to be sent.
isTTS bool: Whether the message should be read aloud by Discord or not.
embed Embed: The Rich Embed to be sent.
options RequestOptions: The options to be used when sending the request.
allowedMentions AllowedMentions: Specifies if notifications are sent for mentioned users and roles in the message text. If null, all mentioned roles and users will be notified.
messageReference MessageReference: The message references to be included. Used to reply to specific messages.
components MessageComponent: The message components to be included with this message. Used for interactions.
stickers ISticker[]: A collection of stickers to send with the file.
embeds Embed[]: A array of Embeds to send with this response. Max 10.
flags MessageFlags: A message flag to be applied to the sent message, only SuppressEmbeds and SuppressNotification is permitted.
poll PollProperties: A poll to send with the message.

Returns

Task<IUserMessage>: A task that represents an asynchronous send operation for delivering the message. The task result contains the sent message.

Remarks

This method sends a file as if you are uploading an attachment directly from your Discord client.

note

If you wish to upload an image and have it embedded in a Rich embed, you may upload the file and refer to the file with "attachment://filename.ext" in the ImageUrl. See the example section for its usage.

SendFileAsync(Stream, string, string, bool, Embed, RequestOptions, bool, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Sends a file to this message channel with an optional caption.

Task<IUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, bool isSpoiler = false, AllowedMentions allowedMentions = null, MessageReference messageReference = null, MessageComponent components = null, ISticker[] stickers = null, Embed[] embeds = null, MessageFlags flags = MessageFlags.None, PollProperties poll = null)

Parameters

stream Stream: The Stream of the file to be sent.
filename string: The name of the attachment.
text string: The message to be sent.
isTTS bool: Whether the message should be read aloud by Discord or not.
embed Embed: The Rich Embed to be sent.
options RequestOptions: The options to be used when sending the request.
isSpoiler bool: Whether the message attachment should be hidden as a spoiler.
allowedMentions AllowedMentions: Specifies if notifications are sent for mentioned users and roles in the message text. If null, all mentioned roles and users will be notified.
messageReference MessageReference: The message references to be included. Used to reply to specific messages.
components MessageComponent: The message components to be included with this message. Used for interactions.
stickers ISticker[]: A collection of stickers to send with the file.
embeds Embed[]: A array of Embeds to send with this response. Max 10.
flags MessageFlags: A message flag to be applied to the sent message, only SuppressEmbeds and SuppressNotification is permitted.
poll PollProperties: A poll to send with the message.

Returns

Task<IUserMessage>: A task that represents an asynchronous send operation for delivering the message. The task result contains the sent message.

Examples

The following example uploads a streamed image that will be called b1nzy.jpg embedded inside a rich embed to the channel.

using (var b1nzyStream = await httpClient.GetStreamAsync("https://example.com/b1nzy"))
    await channel.SendFileAsync(b1nzyStream, "b1nzy.jpg",
        embed: new EmbedBuilder { ImageUrl = "attachment://b1nzy.jpg" }.Build());

Remarks

This method sends a file as if you are uploading an attachment directly from your Discord client.

note

SendFileAsync(string, string, bool, Embed, RequestOptions, bool, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Sends a file to this message channel with an optional caption.

Task<IUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, bool isSpoiler = false, AllowedMentions allowedMentions = null, MessageReference messageReference = null, MessageComponent components = null, ISticker[] stickers = null, Embed[] embeds = null, MessageFlags flags = MessageFlags.None, PollProperties poll = null)

Parameters

filePath string: The file path of the file.
text string: The message to be sent.
isTTS bool: Whether the message should be read aloud by Discord or not.
embed Embed: The Rich Embed to be sent.
options RequestOptions: The options to be used when sending the request.
isSpoiler bool: Whether the message attachment should be hidden as a spoiler.
allowedMentions AllowedMentions: Specifies if notifications are sent for mentioned users and roles in the message text. If null, all mentioned roles and users will be notified.
messageReference MessageReference: The message references to be included. Used to reply to specific messages.
components MessageComponent: The message components to be included with this message. Used for interactions.
stickers ISticker[]: A collection of stickers to send with the file.
embeds Embed[]: A array of Embeds to send with this response. Max 10.
flags MessageFlags: A message flag to be applied to the sent message, only SuppressEmbeds and SuppressNotification is permitted.
poll PollProperties: A poll to send with the message.

Returns

Task<IUserMessage>: A task that represents an asynchronous send operation for delivering the message. The task result contains the sent message.

Examples

The following example uploads a local file called wumpus.txt along with the text good discord boi to the channel.

await channel.SendFileAsync("wumpus.txt", "good discord boi");

The following example uploads a local image called b1nzy.jpg embedded inside a rich embed to the channel.

await channel.SendFileAsync("b1nzy.jpg",
    embed: new EmbedBuilder { ImageUrl = "attachment://b1nzy.jpg" }.Build());

Remarks

This method sends a file as if you are uploading an attachment directly from your Discord client.

note

SendFilesAsync(IEnumerable<FileAttachment>, string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Sends a collection of files to this message channel.

Task<IUserMessage> SendFilesAsync(IEnumerable<FileAttachment> attachments, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null, MessageReference messageReference = null, MessageComponent components = null, ISticker[] stickers = null, Embed[] embeds = null, MessageFlags flags = MessageFlags.None, PollProperties poll = null)

Parameters

attachments IEnumerable<FileAttachment>: A collection of attachments to upload.
text string: The message to be sent.
isTTS bool: Whether the message should be read aloud by Discord or not.
embed Embed: The Rich Embed to be sent.
options RequestOptions: The options to be used when sending the request.
allowedMentions AllowedMentions: Specifies if notifications are sent for mentioned users and roles in the message text. If null, all mentioned roles and users will be notified.
messageReference MessageReference: The message references to be included. Used to reply to specific messages.
components MessageComponent: The message components to be included with this message. Used for interactions.
stickers ISticker[]: A collection of stickers to send with the file.
embeds Embed[]: A array of Embeds to send with this response. Max 10.
flags MessageFlags: A message flag to be applied to the sent message, only SuppressEmbeds and SuppressNotification is permitted.
poll PollProperties: A poll to send with the message.

Returns

Task<IUserMessage>: A task that represents an asynchronous send operation for delivering the message. The task result contains the sent message.

Remarks

This method sends files as if you are uploading attachments directly from your Discord client.

note

SendMessageAsync(string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Sends a message to this message channel.

Task<IUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null, AllowedMentions allowedMentions = null, MessageReference messageReference = null, MessageComponent components = null, ISticker[] stickers = null, Embed[] embeds = null, MessageFlags flags = MessageFlags.None, PollProperties poll = null)

Parameters

text string: The message to be sent.
isTTS bool: Determines whether the message should be read aloud by Discord or not.
embed Embed: The Rich Embed to be sent.
options RequestOptions: The options to be used when sending the request.
allowedMentions AllowedMentions: Specifies if notifications are sent for mentioned users and roles in the message text. If null, all mentioned roles and users will be notified.
messageReference MessageReference: The message references to be included. Used to reply to specific messages.
components MessageComponent: The message components to be included with this message. Used for interactions.
stickers ISticker[]: A collection of stickers to send with the message.
embeds Embed[]: A array of Embeds to send with this response. Max 10.
flags MessageFlags: A message flag to be applied to the sent message, only SuppressEmbeds and SuppressNotification is permitted.
poll PollProperties: A poll to send with the message.

Returns

Task<IUserMessage>: A task that represents an asynchronous send operation for delivering the message. The task result contains the sent message.

Examples

The following example sends a message with the current system time in RFC 1123 format to the channel and deletes itself after 5 seconds.

var message = await channel.SendMessageAsync(DateTimeOffset.UtcNow.ToString("R"));
await Task.Delay(TimeSpan.FromSeconds(5))
    .ContinueWith(x => message.DeleteAsync());

TriggerTypingAsync(RequestOptions)

Broadcasts the "user is typing" message to all users in this channel, lasting 10 seconds.

Task TriggerTypingAsync(RequestOptions options = null)

Parameters

options RequestOptions: The options to be used when sending the request.

Returns

Task: A task that represents the asynchronous operation that triggers the broadcast.

Table of Contents

Interface IMessageChannel

Methods

DeleteMessageAsync(IMessage, RequestOptions)

Parameters

Returns

DeleteMessageAsync(ulong, RequestOptions)

Parameters

Returns

EnterTypingState(RequestOptions)

Parameters

Returns

Examples

GetMessageAsync(ulong, CacheMode, RequestOptions)

Parameters

Returns

GetMessagesAsync(IMessage, Direction, int, CacheMode, RequestOptions)

Parameters

Returns

Examples

Remarks

important

warning

GetMessagesAsync(int, CacheMode, RequestOptions)

Parameters

Returns

Examples

Remarks

important

warning

GetMessagesAsync(ulong, Direction, int, CacheMode, RequestOptions)

Parameters

Returns

Examples

Remarks

important

warning

GetPinnedMessagesAsync(RequestOptions)

Parameters

Returns

ModifyMessageAsync(ulong, Action<MessageProperties>, RequestOptions)

Parameters

Returns

Remarks

SendFileAsync(FileAttachment, string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Parameters

Returns

Remarks

note

SendFileAsync(Stream, string, string, bool, Embed, RequestOptions, bool, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Parameters

Returns

Examples

Remarks

note

SendFileAsync(string, string, bool, Embed, RequestOptions, bool, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Parameters

Returns

Examples

Remarks

note

SendFilesAsync(IEnumerable<FileAttachment>, string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Parameters

Returns

Remarks

note

SendMessageAsync(string, bool, Embed, RequestOptions, AllowedMentions, MessageReference, MessageComponent, ISticker[], Embed[], MessageFlags, PollProperties)

Parameters

Returns

Examples

TriggerTypingAsync(RequestOptions)

Parameters

Returns