Discord Bot DSL Documentation

Developed for Hayden Bradley (K25072606) for 7CCSMMDD Model-driven Engineering

GitHub Repository: https://github.com/6ccs3mde-7ccsmmdd-classroom-2024-25/coursework-EggsLeggs

Introduction

This documentation covers the Discord Bot DSL, a language for defining Discord bots declaratively.

There are 3 top-level block: bot, event and action. These let you define the core settings for your bot, the events it should listen for and the actions it should perform.

Use the sidebar to browse blocks and event/action types. Each page links to the relevant fields, arguments and properties for that block.

Top-level blocks

The top-level blocks are the core building blocks of the Discord Bot DSL.

• bot - core bot settings (token, intents)
• event - event handlers
• action - reusable actions

Properties and dot-path notation

Most fields support dot-path notation to access properties of context variables.

For example, the `user_id` field in the `send_dm` action can be set to the user ID of the member who triggered the event by using the `member.user.id` path expression.

The available properties depend on the event type and/or arguments. You can find the available properties for an event type in the sidebar.

Example

bot {
    token = "your_token_here"
    intents = ["Guilds", "GuildMessages", "MessageContent", "GuildMembers"]
}

action "send_dm" "welcomeDm" {
    user_id = member.user.id
    content = "Welcome to the server!"
}

action "add_role" "memberRole" {
    role_id = "0123456789012345678"
    user_id = member.user.id
}
event "guildMemberAdd" "welcomeFlow" {
    actions = [action.send_dm.welcomeDm, action.add_role.memberRole]
}

This example shows a bot with a token and intents, and a welcome flow event that sends a welcome message and adds a role to the user when they join the server.

Defines the core settings for your Discord bot, including its token and the gateway intents it subscribes to.

Fields

Field	Type	Required	Description
token	string	optional	Your bot's secret token from the Discord Developer Portal. Keep this private - anyone with your token can control your bot. If this isn't provided, the generator will make a .env.example file. ↗
intents	string[]	required	The gateway intents your bot needs. Only declare the intents you actually use - some require explicit approval for verified bots. ↗

Possible Intents:

Guilds GuildMembers GuildModeration GuildExpressions GuildIntegrations GuildWebhooks GuildInvites GuildVoiceStates GuildPresences GuildMessages GuildMessageReactions GuildMessageTyping DirectMessages DirectMessageReactions DirectMessageTyping MessageContent GuildScheduledEvents AutoModerationConfiguration AutoModerationExecution GuildMessagePolls DirectMessagePolls

Example

bot {
  token "your-token-here"
  intents ["GuildMessages", "MessageContent"]
}

Runs when something happens in your Discord server, or defines a slash command when the event type is "command".

Event Types

Event blocks have a type, which determines the type of event it is. The type may provide additional fields and/or properties for actions.

• ready
• guildMemberAdd
• guildMemberRemove
• guildMemberUpdate
• messageCreate
• command

Fields

Shared Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Command-only Fields

These fields are only available for command events. See the command event type for more information.

Field	Type	Required	Description
description	string	optional	A short explanation shown in Discord's command picker when a user types /. Must be 1-100 characters.
arguments	string	optional	The inputs a user provides when running the command. For example, a /greet command might have a user argument for /greet @Alice.

Example

action "send_message" "pingReply" {
  channel_id = interaction.channelId
  content = "Pong!"
}

event "command" "ping" {
  description = "Ping the bot"
  action = action.send_message.pingReply
}

Fired once when the bot connects to Discord and is ready to receive events.

Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Example

action "send_message" "logReady" {
  channel_id = "000000000000000000"
  content = "Bot is online!"
}

event "ready" "onReady" {
  action = action.send_message.logReady
}

Context Variables

No context variables.

Fired when a new member joins the guild. Requires the GuildMembers privileged intent.

Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Example

action "send_message" "welcome" {
  channel_id = "000000000000000000"
  content = "Welcome to the server!"
}

event "guildMemberAdd" "onJoin" {
  action = action.send_message.welcome
}

Context Variables

Fired when a member leaves or is removed from the guild. Requires the GuildMembers privileged intent.

Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Example

action "send_message" "goodbye" {
  channel_id = "000000000000000000"
  content = "A member has left the server."
}

event "guildMemberRemove" "onLeave" {
  action = action.send_message.goodbye
}

Context Variables

Fired when a member's roles, nickname, or other properties change. Exposes before and after context variables to compare the member state. Requires the GuildMembers privileged intent.

Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Example

action "send_message" "notifyUpdate" {
  channel_id = "000000000000000000"
  content = "A member's profile was updated."
}

event "guildMemberUpdate" "onUpdate" {
  action = action.send_message.notifyUpdate
}

Context Variables

Fired when a message is sent in any channel the bot can see. Requires the GuildMessages and MessageContent intents.

Fields

Field	Type	Required	Description
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

Example

action "send_message" "echo" {
  channel_id = message.channel.id
  content = "You said something!"
}

event "messageCreate" "onMessage" {
  action = action.send_message.echo
}

Context Variables

A slash command registered with Discord. Supports description, arguments, and action references.

Fields

Field	Type	Required	Description
description	string	optional	A short explanation shown in Discord's command picker when a user types /. Must be 1-100 characters. ↗
arguments	string	optional	The inputs a user provides when running the command. For example, a /greet command might have a user argument for /greet @Alice. ↗
action	string	optional	A single action reference or inline action block this event executes when triggered. Use actions (plural) for multiple. You can only use one of action or actions.
actions	string[]	optional	An array of action references this event executes when triggered. References use the form action.<type>.<name>. You can only use one of action or actions.

arg

Defines a single argument for a slash command, including its name, type, description, and whether it is required.

Field	Type	Required	Description
type	string	required	The argument type: String, Integer, Boolean, User, Channel, Role, or Number. ↗
description	string	required	A short explanation of this argument shown to users in Discord's command picker.
required	string	optional	Whether this argument must be provided. Defaults to false. Required arguments must appear before optional ones.

Argument Types

Type	Description
String	String - A text value. Shown to users as a text input field.
Integer	Integer - A whole number, e.g. 5 or 100. Shown as a number input.
Boolean	Boolean - A true/false value. Shown as a toggle.
User	User - A Discord user, selected from a mention or user picker.
Channel	Channel - A Discord channel, selected from a channel picker.
Role	Role - A Discord role, selected from a role picker.
Number	Number - A decimal number, e.g. 3.14.

Example

action "send_message" "greet" {
  channel_id = interaction.channelId
  content = "Hello!"
}

event "command" "greet" {
  description = "Greet a user"
  arguments {
    arg "user" {
      type = User
      description = "The user to greet"
      required = true
    }
  }
  action = action.send_message.greet
}

Context Variables

Defines a reusable action that can be referenced by event handlers. Actions have a specific type and a set of fields for that type.

Action Types

Action blocks have a type, which determines the type of action it is. The type may provide additional fields and/or properties for actions.

• send_message
• send_dm
• add_role
• remove_role

Sends a message to a text channel.

Fields

Field	Type	Required	Description
channel_id	snowflake	optional	The channel to send the message in. Defaults to the channel where the event occurred. Defaults: messageCreate → message.channel.id command → interaction.channelId
content	template	required	The message text. Supports ${arg} interpolation in command contexts.

Example

action "send_message" "pingReply" {
  channel_id = interaction.channelId
  content = "Pong!"
}

event "command" "ping" {
  description = "Ping the bot"
  action = action.send_message.pingReply
}

Sends a direct message to a user.

Fields

Field	Type	Required	Description
user_id	snowflake	optional	The user to DM. Defaults to the user who triggered the event. Defaults: guildMemberAdd → member.user.id guildMemberRemove → member.user.id guildMemberUpdate → after.user.id messageCreate → message.author.id command → interaction.user.id
content	template	required	The DM text. Supports ${arg} interpolation in command contexts.

Example

action "send_dm" "welcome" {
  user_id = member.user.id
  content = "Welcome to the server!"
}

event "guildMemberAdd" "onJoin" {
  action = action.send_dm.welcome
}

Adds a role to a guild member.

Fields

Field	Type	Required	Description
role_id	snowflake	required	The ID of the role to add.
user_id	snowflake	optional	The member to receive the role. Defaults to the user who triggered the event. Defaults: guildMemberAdd → member.user.id guildMemberUpdate → after.user.id command → interaction.user.id
guild_id	snowflake	optional	The guild in which to add the role. Defaults to the guild where the event occurred. Defaults: guildMemberAdd → member.guild.id guildMemberUpdate → after.guild.id messageCreate → message.guild.id command → interaction.guild.id

Example

action "add_role" "giveMember" {
  role_id = "000000000000000001"
  user_id = member.user.id
  guild_id = member.guild.id
}

event "guildMemberAdd" "onJoin" {
  action = action.add_role.giveMember
}

Removes a role from a guild member.

Fields

Field	Type	Required	Description
role_id	snowflake	required	The ID of the role to remove.
user_id	snowflake	optional	The member to remove the role from. Defaults to the user who triggered the event. Defaults: guildMemberAdd → member.user.id guildMemberUpdate → after.user.id command → interaction.user.id
guild_id	snowflake	optional	The guild context. Defaults to the guild where the event occurred. Defaults: guildMemberAdd → member.guild.id guildMemberUpdate → after.guild.id messageCreate → message.guild.id command → interaction.guild.id

Example

action "remove_role" "stripMember" {
  role_id = "000000000000000001"
  user_id = interaction.user.id
  guild_id = interaction.guild.id
}

event "command" "kick" {
  description = "Remove the member role from a user"
  action = action.remove_role.stripMember
}