MessageBuilder class final

A builder for constructing Discord messages using message components v2.

The MessageBuilder provides a fluent API for composing messages with TextDisplay, interactive elements Button, SelectMenu, media AttachedFile, MediaGallery, and layout components Section, Container, Separator using Discord's message components v2 specification.

Usage

Create a builder and add components using the cascade operator or method chaining:

final builder = MessageBuilder()
  ..addText('# Welcome to our server!')
  ..addSeparator()
  ..addText('Please read the rules before posting.')
  ..addButtons([
    MessageButton.primary('accept_rules', label: 'Accept Rules'),
    MessageButton.secondary('learn_more', label: 'Learn More'),
  ]);

builder.addText("-# PS: Dont forget to have fun!");

// Send the message
await channel.send(builder);

Features

Text & Formatting: Add markdown-formatted text and separators
Interactive Components: Buttons and select menus for user interaction
Media: Attach files and create image galleries
Layout: Organize content with sections and containers
Composition: Combine multiple builders or copy existing ones

Examples

Simple text message

final message = MessageBuilder.text('Hello, world!');

Message with buttons

final builder = MessageBuilder()
  ..addText('Choose an option:')
  ..addButtons([
    MessageButton.primary('option_1', label: 'Option 1'),
    MessageButton.secondary('option_2', label: 'Option 2'),
    MessageButton.danger('cancel', label: 'Cancel'),
  ]);

Message with file attachments

// Using MediaItem
final mediaFromFile = MediaItem.fromFile(File('assets/logo.png'), 'logo.png');
final mediaFromNetwork = MediaItem.fromNetwork('https://example.com/image.jpg');

final builder = MessageBuilder()
  ..addText('Check out these images:')
  ..addFile(await AttachedFile.fromMediaItem(mediaFromFile))
  ..addFile(await AttachedFile.fromMediaItem(mediaFromNetwork));

// Or use the convenience factory
final builder2 = MessageBuilder()
  ..addText('Another way:')
  ..addFile(AttachedFile.fromFile(File('assets/logo.png'), 'logo.png'))
  ..addFile(await AttachedFile.fromNetwork('https://example.com/image.jpg', 'image.jpg));

Using containers for visual grouping

final container = MessageBuilder()
  ..addText('This is inside a container')
  ..addText('With multiple lines')
  ..addText('And even interactive components')
  ..addButton(MessageButton.primary('click_me', label: 'Click Me!'));

final builder = MessageBuilder()
  ..addText('Main message')
  ..addContainer(
    builder: container,
    color: Color.blue,
    spoiler: false,
  );

Constructors

MessageBuilder(): Creates an empty MessageBuilder.
MessageBuilder.text(String text): Creates a MessageBuilder with initial text content.
factory

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

addButton(Button button) → void: Adds a single button to the message.
addButtons(List<Button> buttons) → void: Adds multiple buttons in a single row.
addContainer({required MessageBuilder builder, Color? color, bool? spoiler}) → void: Adds a container with nested content.
addFile(AttachedFile file) → void: Attaches a file to the message.
addGallery(List<MediaItem> items) → void: Adds a media gallery to the message.
addSection({required MessageBuilder builder, Button? button, Thumbnail? thumbnail}) → void: Adds a section to the message.
addSelectMenu(SelectMenu menu) → void: Adds a select menu (dropdown) to the message.
addSeparator({bool show = true, SeparatorSize spacing = SeparatorSize.small}) → void: Adds a visual separator between content sections.
addText(String text) → void: Adds text content to the message.
appendFrom(MessageBuilder builder) → void: Appends all components from another builder to the end of this one.
build() → List<Map<String, dynamic>>: Converts the builder to a JSON representation for the Discord API.
copy() → MessageBuilder: Creates a copy of this builder with all its components.
copyWith(MessageBuilder builder) → MessageBuilder: Creates a new builder combining this builder's components with another's.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
prependFrom(MessageBuilder builder) → void: Prepends all components from another builder to the beginning of this one.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited