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.
contexts	string[]	optional	An array of InteractionContextType values that determine where this command can be used. Valid values are Guild, BotDM, and PrivateChannel. When omitted, Discord applies its default context rules.
arguments	block	optional	A block of arg definitions for 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, ${args.user}!"
}

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_dm" "goodbye" {
  user_id = ctx.member.user.id
  content = "Sorry to see you go!"
}

event "guildMemberRemove" "onLeave" {
  action = action.send_dm.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 = "Member ${ctx.after.user.username} 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 = ctx.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. ↗
contexts	string[]	optional	An array of InteractionContextType values that determine where this command can be used. Valid values are Guild, BotDM, and PrivateChannel. When omitted, Discord applies its default context rules. ↗
arguments	block	optional	A block of arg definitions for 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 = ctx.interaction.channelId
  content = "Hello, ${args.user}!"
}

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
• call_webhook
• ban_member
• kick_member
• timeout_member

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.
content	template	required	The message text. Supports ${args.*} and ${ctx.*} interpolation in command contexts.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

channel_id

• messageCreate → ctx.message.channel.id
• command → ctx.interaction.channelId

Example

action "send_message" "pingReply" {
  channel_id = ctx.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.
content	template	required	The DM text. Supports ${args.*} and ${ctx.*} interpolation in command contexts.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberRemove → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• messageCreate → ctx.message.author.id
• command → ctx.interaction.user.id

Example

action "send_dm" "welcome" {
  user_id = ctx.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.
guild_id	snowflake	optional	The guild in which to add the role. Defaults to the guild where the event occurred.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• command → ctx.interaction.user.id

guild_id

• guildMemberAdd → ctx.member.guild.id
• guildMemberUpdate → ctx.after.guild.id
• messageCreate → ctx.message.guild.id
• command → ctx.interaction.guild.id

Example

action "add_role" "giveMember" {
  role_id = "000000000000000001"
  user_id = ctx.member.user.id
  guild_id = ctx.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.
guild_id	snowflake	optional	The guild context. Defaults to the guild where the event occurred.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• command → ctx.interaction.user.id

guild_id

• guildMemberAdd → ctx.member.guild.id
• guildMemberUpdate → ctx.after.guild.id
• messageCreate → ctx.message.guild.id
• command → ctx.interaction.guild.id

Example

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

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

Makes an HTTP request to an external URL.

Fields

Field	Type	Required	Description
url	template	required	The URL to send the request to. Supports ${args.*} and ${ctx.*} interpolation.
method	string	optional	The HTTP method to use. One of GET, POST, PUT, PATCH, or DELETE. Defaults to "POST".
body	template	optional	The request body. Supports ${args.*} and ${ctx.*} interpolation.
headers	headers	optional	HTTP headers to include with the request.

Example

action "call_webhook" "notifySlack" {
  url = "https://hooks.example.com/services/..."
  method = "POST"
  body = "{'text': '${ctx.member.user.username} just joined!'}"
  headers = {
    "Content-Type" = "application/json"
  }
}

event "guildMemberAdd" "onJoin" {
  action = action.call_webhook.notifySlack
}

Bans a member from the guild.

Fields

Field	Type	Required	Description
user_id	snowflake	optional	The member to ban. Defaults to the user who triggered the event.
guild_id	snowflake	optional	The guild to ban from. Defaults to the guild where the event occurred.
reason	template	optional	The reason for the ban, shown in the audit log. Supports ${args.*} and ${ctx.*} interpolation.
delete_message_days	string	optional	Number of days of messages to delete from the banned user (0-7). Defaults to 0.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberRemove → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• messageCreate → ctx.message.author.id
• command → ctx.interaction.user.id

guild_id

• guildMemberAdd → ctx.member.guild.id
• guildMemberUpdate → ctx.after.guild.id
• messageCreate → ctx.message.guild.id
• command → ctx.interaction.guild.id

Example

action "ban_member" "banUser" {
  user_id = ctx.interaction.user.id
  reason = "Violated server rules"
  delete_message_days = "1"
}

event "command" "ban" {
  description = "Ban a user from the server"
  action = action.ban_member.banUser
}

Kicks a member from the guild.

Fields

Field	Type	Required	Description
user_id	snowflake	optional	The member to kick. Defaults to the user who triggered the event.
guild_id	snowflake	optional	The guild to kick from. Defaults to the guild where the event occurred.
reason	template	optional	The reason for the kick, shown in the audit log. Supports ${args.*} and ${ctx.*} interpolation.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberRemove → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• messageCreate → ctx.message.author.id
• command → ctx.interaction.user.id

guild_id

• guildMemberAdd → ctx.member.guild.id
• guildMemberUpdate → ctx.after.guild.id
• messageCreate → ctx.message.guild.id
• command → ctx.interaction.guild.id

Example

action "kick_member" "kickUser" {
  user_id = ctx.interaction.user.id
  reason = "Spamming in chat"
}

event "command" "kick" {
  description = "Kick a user from the server"
  action = action.kick_member.kickUser
}

Times out a member, preventing them from sending messages for a set duration.

Fields

Field	Type	Required	Description
user_id	snowflake	optional	The member to time out. Defaults to the user who triggered the event.
guild_id	snowflake	optional	The guild context. Defaults to the guild where the event occurred.
duration	string	required	How long to time out the member. Accepts "30s", "10m", "1h", "1d", or "1w" (maximum 28 days).
reason	template	optional	The reason for the timeout, shown in the audit log. Supports ${args.*} and ${ctx.*} interpolation.

Smart defaults

When an optional field is omitted, the generator uses the following context paths depending on how the action is triggered.

user_id

• guildMemberAdd → ctx.member.user.id
• guildMemberRemove → ctx.member.user.id
• guildMemberUpdate → ctx.after.user.id
• messageCreate → ctx.message.author.id
• command → ctx.interaction.user.id

guild_id

• guildMemberAdd → ctx.member.guild.id
• guildMemberUpdate → ctx.after.guild.id
• messageCreate → ctx.message.guild.id
• command → ctx.interaction.guild.id

Example

action "timeout_member" "muteUser" {
  user_id = ctx.interaction.user.id
  duration = "1h"
  reason = "Cooldown period"
}

event "command" "mute" {
  description = "Temporarily mute a user"
  action = action.timeout_member.muteUser
}

A Discord user account.

Properties

Property	Type	Description
.id	Snowflake	The user's unique ID.
.username	string	The user's username.
.displayName	string	The user's global display name.

A Discord server.

Properties

Property	Type	Description
.id	Snowflake	The guild's unique ID.
.name	string	The guild's name.

A user's membership record within a specific guild.

Properties

Property	Type	Description
.user	User	The underlying Discord user.
.guild	Guild	The guild this membership belongs to.
.displayName	string	The member's display name (server nickname, falling back to global display name).
.roles	RoleManager	The member's assigned roles.

Any channel that supports sending text messages.

Properties

Property	Type	Description
.id	Snowflake	The channel's unique ID.
.name	string	The channel's name.

A Discord channel.

Properties

Property	Type	Description
.id	Snowflake	The channel's unique ID.
.name	string	The channel's name.

A Discord role in a guild.

Properties

Property	Type	Description
.id	Snowflake	The role's unique ID.
.name	string	The role's name.

Manages the roles assigned to a guild member.

No directly accessible properties.