Building messages

DDBKitUtilities exposes a collection of utiltity builders for creating structured messages. This makes it a lot easier to format your message text or create complex messages with embeds, components, and buttons. This also makes it easier to use conditional logic in your messages to keep your code clean and readable. Remember to import the module before using it with import DDBKitUtilities.

You may receive errors when importing the module if you didn’t specify it as a dependency in your Package.swift file. Ensure your target has the module listed as a dependency, or just add everything like below.

.executableTarget(
  name: "MyNewBot",
  dependencies: [
    .product(name: "DDBKit", package: "DDBKit"),
    .product(name: "Database", package: "DDBKit"),
    .product(name: "DDBKitUtilities", package: "DDBKit"),
    .product(name: "DDBKitFoundation", package: "DDBKit"),
  ]
)

DDBKitUtilities adds methods to your GatewayManager (your bot instance) that wrap their respective DiscordClient methods. They accept Message types instead of the normal payloads as Message does the conversion under the hood.

You start off by instanciating a message with

Message {
  // a tumbleweed tumbles...
}

This is an empty message, but you can’t send empty messages. Also it’ll error due to ambiguity with different ways of initialising it. You can take this two different ways:

You can send purely text content
You can make a full message with embeds and all that

Sending text content can be made easier with this convenience initialiser.

Message {
  Text("hi mom")
}

This is the equivalent of using the component-based normal initialiser:

Message {
  MessageContent {
    Text("hi mom")
  }
}

You’ll need to use the normal initialiser to have anything else like embeds and components.

Message {
  MessageContent {
    Text("wish i was an embed :c")
  }
  MessageEmbed {
    Title("embed #1")
    Description("wagwan gs")
  }
  MessageEmbed {
    Title("embed #2")
    Description("gm")
  }
  MessageComponents {
    ActionRow {
      LinkButton(":3", url: "https://example.com")
    }
  }
}

MyNewBot Bot 05/11/2024

wish i was an embed :c

embed #1

wagwan gs

embed #2

As you can tell, the MessageComponents you can use generally start with the Message prefix, keep that in mind. The following components exist:

MessageContent *
MessageEmbed
MessageComponents *
MessageAttachment
MessagePoll *
MessageSticker

Items marked with * are singular, and only the last declared instance will be used if any.

MessageContent

This is the main content of the message, and either this or an embed is required in a message to be sent.

The following MessageContentComponent types exist:

Text
URL
Heading
Blockquote
Code
Codeblock
OrderedList
UnorderedList

We’ll go through the usage of each one.

`Text`

The most basic component, just text. It also has many modifiers to change it’s style.

Text("hi mom")
// hi mom\n

Text("hi mom")
  .bold()
// **hi mom**\n

Text("hi mom")
  .italic()
// *hi mom*\n

Text("hi mom")
  .strikethrough()
// ~~hi mom~~\n

Text("hi mom")
  .underlined()
// __hi mom__\n

Text("hi mom")
  .spoilered()
// ||hi mom||\n

You can chain these modifiers together if you’d like.

Sometimes, you may need to have many Text components on a single line sometimes, so use the grouped convenience initialiser.

Text {
  Text("hi")
    .bold()
  Text(" mom")
}
// **hi** mom\n

`URL`

URLs are just Text components with a URL inside them. This component lets you conveniently mask links or disable embeds (link previews).

URL("https://example.com")
  .disableEmbedding()
  .maskedWith {
    Text("click me")
      .bold()
  }
// [click me](<https://example.com>)<https://example.com>\n

`Heading`

Headings are single line, hence only one Text component is allowed.

Heading("wagwan") /// defaults to h1 (biggest), but you can use .large() modifier if you'd like lol
// # wagwan\n

Heading("wagwan")
  .medium()
// ## wagwan\n

Heading("wagwan")
  .small()
// ### wagwan\n

Or use the Text component convenience initialiser.

Heading {
  Text("wagwan")
    .bold()
}.medium()
// ## **wagwan**\n

`Blockquote`

Blockquotes can accept all MessageContentComponent types, though I wouldn’t recommend using another Blockquote in it.

Blockquote {
  Text("hi mom")
  Text("hi dad")
}
// > hi mom\n
// > hi dad\n

`Code`

Code is the inline form of codeblocks, and just takes a String type.

Code("print(\"hi mom\")")
// `print("hi mom")`\n

`Codeblock`

Codeblocks are cool, and can have a language specified.

Codeblock("swift", """
for i in 0..<10 {
  print(i)
}
""")
.language("swift")
// ```swift\n
// for i in 0..<10 {\n
//   print(i)\n
// }\n
// ```

`OrderedList` and `UnorderedList`

OrderedList can accept Text and UnorderedList components.

OrderedList {
  Text("gm")
  Text("gn")
}
// 1. gm\n
// 2. gn\n

And you can put lists inside lists.

OrderedList {
  Text("gm")
  Text("gn")
  UnorderedList {
    Text("hi mom")
    Text("hi dad")
    Text("hi brother")
    Text("hi sister")
  }
}
// 1. gm\n
// 2. gn\n
//   - hi mom\n
//   - hi dad\n
//   - hi brother\n
//   - hi sister\n

`MessageEmbed`

Embeds are cool, and can have a lot of stuff in them in a nice, formatted manner.

The following MessageEmbedComponent types exist:

Title
Description
Image
Thumbnail
Video
Field
Footer

The MessageEmbed component also has modifiers, which include:

func setKind(_ kind: Embed.Kind)
func setTimestamp(_ date: Date = .now)
func setColor(_ color: DiscordColor?)
func setURL(_ url: String)
func setProvider(_ name: String, url: String? = nil)
func setAuthor(_ name: String, url: String? = nil, icon_url: Embed.DynamicURL? = nil)

MessageEmbed - Components

`Title`

The title of the embed, which is a single line String type.

MessageEmbed {
  Title("wagwan")
}

MyNewBot Bot 05/11/2024

embed #1

wagwan gs