Sending Messages
This guide demonstrates how to send messages to a channel.
Different types of message properties are available because various endpoints support different options. However, all these types implement IMessageProperties, which defines the properties supported by all endpoints. This guide will cover the properties defined in IMessageProperties.
Types of Message Properties
The following message properties types are available:
- MessageProperties - Can be used with RestClient.SendMessageAsync to send messages to channels.
- InteractionMessageProperties - Used for sending messages in response to interactions. Refer to Responding to Interactions for more information.
- ReplyMessageProperties - Can be used with RestMessage.ReplyAsync to reply to messages.
- WebhookMessageProperties - Can be used with RestClient.ExecuteWebhookAsync to send messages via webhooks.
- ForumGuildThreadMessageProperties - Can be used with RestClient.CreateForumGuildThreadAsync to create forum posts.
All the RestClient methods mentioned above have their equivalent methods in appropriate objects, such as TextChannel and WebhookClient.
Using IMessageProperties
If you need to build an API that supports creating messages for multiple endpoints, you can utilize the IMessageProperties interface. This allows you to define the properties common to all message properties types in a straightforward manner.
static T CreateMessage<T>() where T : IMessageProperties, new()
{
return new()
{
Content = "Hello, World!",
Components = [],
};
}
You can view sample usages of this method below:
message = CreateMessage<MessageProperties>();
message = CreateMessage<InteractionMessageProperties>();
Defining the Content
The content refers to the main text of the message.
message.Content = "Hello, World!";
All message properties types support an implicit conversion from a string. However, note that this does not apply to IMessageProperties, as it is an interface.
MessageProperties message = "Hello, World!";
Adding Embeds
Embeds are rich content elements that can be attached to a message. They support titles, descriptions, images, and more. A message can include up to 10 embeds.
message.Embeds = [embed];
Customizing Embeds
You can customize embeds by specifying properties such as the title, description, color, and image.
embed = new()
{
Title = "Welcome to the Baking Club!",
Description = "Join us for delicious recipes and baking tips!",
Url = "https://example.com",
Timestamp = DateTimeOffset.UtcNow,
Color = new(0xFFA500),
Footer = new()
{
Text = "Happy Baking!",
IconUrl = "https://example.com/images/baking-icon.png",
},
Image = "https://example.com/images/cake.jpg",
Thumbnail = "https://example.com/images/rolling-pin.png",
Author = new()
{
Name = "Baking Club",
Url = "https://example.com",
IconUrl = "https://example.com/images/club-logo.png",
},
Fields =
[
new()
{
Name = "Today's Special Recipe",
Value = "Chocolate Lava Cake",
},
new()
{
Name = "Next Meetup",
Value = "Sunday, 4 PM",
Inline = true,
},
new()
{
Name = "Location",
Value = "123 Baker's Street",
Inline = true,
},
new()
{
Name = "Membership Fee",
Value = "Free for the first month!",
Inline = true,
},
],
};
Managing Allowed Mentions
Allowed mentions define which users and roles can be mentioned within the message.
To allow all mentions, use AllowedMentionsProperties.All.
message.AllowedMentions = AllowedMentionsProperties.All;
To disable all mentions, use AllowedMentionsProperties.None.
message.AllowedMentions = AllowedMentionsProperties.None;
You can also define custom allowed mentions.
message.AllowedMentions = new()
{
Everyone = true, // Allow @everyone and @here
ReplyMention = true, // Allow reply mention
AllowedRoles = [988888771187581010], // Allow specific roles
AllowedUsers = [265546281693347841], // Allow specific users
};
Attaching Files
Attachments are files that can be added to a message. A message can contain up to 10 attachments.
message.Attachments = [attachment];
Customizing Attachments
Attachments are files that can be added to a message, with up to 10 attachments per message. All attachment types support any readable stream, such as file streams. Below are examples of how you can create and customize attachments.
Standard Attachments
This is an example of a standard attachment. The following code creates an attachment with the content "Hello!".
attachment = new AttachmentProperties("hello.txt", new MemoryStream("Hello!"u8.ToArray()));
Base64-Encoded Attachments
You can create an attachment with base64 encoding. The following example demonstrates an attachment that will display "Hello, base64!" in the chat.
attachment = new Base64AttachmentProperties("hello.txt", new MemoryStream("SGVsbG8sIGJhc2U2NCE="u8.ToArray()));
Quoted-Printable Attachments
Quoted-printable encoding is another supported format. The following example creates an attachment that will display "Różowy means pink" in the chat.
attachment = new QuotedPrintableAttachmentProperties("polish.txt",
new MemoryStream("R=C3=B3=C5=BCowy means pink"u8.ToArray()));
Google Cloud Attachments
Warning
Discord does not offer any stability guarantees for this feature so it can break without notice.
Discord supports uploading attachments directly to Google Cloud Platform. This example creates an attachment uploaded directly to Google Cloud Platform with the content "Hello, Google!".
// Create a bucket with a file named "hello.txt"
var buckets = await textChannel.CreateGoogleCloudPlatformStorageBucketsAsync([new("hello.txt")]);
var bucket = buckets[0];
// Upload the file content to the bucket
var response = await httpClient.PutAsync(bucket.UploadUrl, new StringContent("Hello, Google!"));
response.EnsureSuccessStatusCode();
attachment = new GoogleCloudPlatformAttachmentProperties("hello.txt", bucket.UploadFileName);
Adding Titles and Descriptions
You can enhance your attachments by adding titles and descriptions. Use the AttachmentProperties.Title
and AttachmentProperties.Description
properties to set these values. Here's an example:
attachment.Title = "Hello, World!";
attachment.Description = "This is a file named hello.txt";
Adding Components
Components are interactive elements that can be attached to a message. These include buttons, select menus, and more. A message can contain up to 5 components, including action rows and select menus.
message.Components = [component];
Action Rows
Action rows contain buttons, and each can have up to 5 buttons. Available button types include:
- ButtonProperties, which triggers an interaction when clicked.
- LinkButtonProperties, which opens a URL when clicked.
- PremiumButtonProperties, which prompts the user to pay when clicked.
component = new ActionRowProperties
{
new ButtonProperties("welcome", "Welcome", new("👋"), ButtonStyle.Primary),
new ButtonProperties("hug", new EmojiProperties(356377264209920002), ButtonStyle.Success),
new ButtonProperties("goodbye", "Goodbye", ButtonStyle.Secondary)
{
Disabled = true,
},
new LinkButtonProperties("https://netcord.dev", "Learn More"),
new PremiumButtonProperties(1271914991536312372),
};
Select Menus
Select menus are dropdown menus containing up to 25 options. They support various types, such as strings, channels, and users.
String Menus
String menus allow you to include any string options. Each option in the menu can be customized with additional properties, such as setting a default selection, adding an emoji, or providing a description for better context.
component = new StringMenuProperties("animal")
{
new("Dog", "dog")
{
Default = true,
Emoji = new("🐶"),
Description = "A loyal companion",
},
new("Cat", "cat")
{
Emoji = new("🐱"),
Description = "A curious feline",
},
new("Bird", "bird")
{
Emoji = new("🐦"),
Description = "A chirpy flyer",
},
};
Channel Menus
Channel menus include channels as options, and support filtering by channel type and the ability to specify default channels.
component = new ChannelMenuProperties("channel")
{
DefaultValues = [1124777547687788626],
ChannelTypes = [ChannelType.ForumGuildChannel, ChannelType.PublicGuildThread],
};
Mentionable Menus
Mentionable menus include users and roles as options, and support specifying default users and roles.
component = new MentionableMenuProperties("mentionable")
{
DefaultValues =
[
new(803324257194082314, MentionableValueType.User),
],
};
Role Menus
Role menus contain roles as options, and support specifying default roles.
component = new RoleMenuProperties("role")
{
DefaultValues = [803169206115237908],
};
User Menus
User menus allow selecting users as options, and support specifying default users.
component = new UserMenuProperties("user")
{
DefaultValues = [233590074724319233],
};
Specifying Additional Properties
Additionally, all select menus allow you to specify a placeholder, set a minimum and maximum number of selectable options, and disable the select menu if necessary.
component.Placeholder = "Select 2-5 animals";
component.MinValues = 2;
component.MaxValues = 5;
component.Disabled = true;
Configuring Flags
Flags control how a message behaves. You can combine multiple flags using the bitwise OR operator.
For example, this configuration specifies that no embeds from URLs should be displayed, and the message should be silent (not triggering push or desktop notifications).
message.Flags = MessageFlags.SuppressEmbeds | MessageFlags.SuppressNotifications;