Sending Attachments

Attachments let you upload files directly to Discord. discord-luau supports sending them by providing the raw file content as a string.

Prerequisites

This guide uses the onMessage event. To match on message.content in your handler, add "MessageContent" to your intents - it is a privileged intent that must also be enabled in the Discord Developer Portal under your application’s Bot tab.

Adding an attachment to a message

Call :addAttachment(content, name) on a builders.message.message object, where content is the raw file data as a string and name is the filename that will appear in Discord.

local discord  = require("@self/../luau_packages/discord")
local classes  = require("@self/../luau_packages/classes")
local builders = require("@self/../luau_packages/builders")
local env      = require("@self/../.env")

local bot = discord.bot.new({
    token = env.DISCORD_BOT_TOKEN,
    intents = builders.intents.new({ "Guilds", "GuildMessages" }):build(),
    reconnect = true,
})

bot.onMessage:listen(function(message: classes.Message)
    if message.content ~= "!file" then
        return
    end

    message:replyAsync(
        builders.message.message.new()
            :addAttachment("Hello from discord-luau!", "hello.txt")
            :build()
    ):await()
end)

bot.onAllShardsReady:listenOnce(function()
    print(`Bot '{bot.user.username}' is online!`)
end)

bot:connectAsync():await()

Multiple attachments

Call :addAttachment() multiple times to include more than one file in a single message. Each call adds one file.

message:replyAsync(
    builders.message.message.new()
        :addAttachment("First file contents", "first.txt")
        :addAttachment("Second file contents", "second.txt")
        :build()
):await()

Combining attachments with text or embeds

Attachments, message content, and embeds can all be combined on the same message builder.

message:replyAsync(
    builders.message.message.new()
        :setContent("Here is your file:")
        :addAttachment("some,csv,data\n1,2,3", "data.csv")
        :build()
):await()

File content is a string

The content argument to :addAttachment() is always a plain Luau string. For binary formats, you would need to encode the data as a string first.

Full script

local discord  = require("@self/../luau_packages/discord")
local classes  = require("@self/../luau_packages/classes")
local builders = require("@self/../luau_packages/builders")
local env      = require("@self/../.env")

local bot = discord.bot.new({
    token = env.DISCORD_BOT_TOKEN,
    intents = builders.intents.new({ "Guilds", "GuildMessages" }):build(),
    reconnect = true,
})

bot.onMessage:listen(function(message: classes.Message)
    if message.content ~= "!file" then
        return
    end

    message:replyAsync(
        builders.message.message.new()
            :addAttachment("Hello from discord-luau!", "hello.txt")
            :build()
    ):await()
end)

bot.onAllShardsReady:listenOnce(function()
    print(`Bot '{bot.user.username}' is online!`)
end)

bot:connectAsync():await()

References

• Bot - the discord.bot class, gateway connection and event emitters
• Message builder - builders.message.message, constructs message payloads including attachments
• Message class - classes.Message, the object passed to onMessage handlers
• Intents builder - builders.intents, constructs the gateway intent bitfield
• Futures - the FutureLike async primitive returned by async calls