Table of Contents

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:

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:

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;