Sending Files

Sending files in Discord requires two things to be present in your request: the binary file data (sent as multipart form fields) and the attachment metadata (sent as JSON). The AttachmentBuilder class handles both for you.

The AttachmentBuilder

Use AttachmentBuilder to describe a file you want to send. It accepts any Buffer, Uint8Array, string, or Stream as the file data.

import { AttachmentBuilder } from "honocord";

const attachment = new AttachmentBuilder(Buffer.from("Hello, world!"), {
  name: "hello.txt",
  description: "A simple text file",
});

Use the fluent builder methods to configure the attachment:

Method	Description
.setName(name)	Sets the filename shown in Discord
.setDescription(desc)	Sets the alt-text / description
.setContentType(type)	Overrides the MIME type (e.g. "application/json")
.setSpoiler(true)	Prefixes the filename with SPOILER_

Sending with a Reply

Pass your AttachmentBuilder instance(s) directly into the files field of any response method. reply, editReply, followUp, and update all accept it.

Single file

await ctx.reply({
  content: "Here is your file!",
  files: [
    new AttachmentBuilder(Buffer.from(data), { name: "output.txt" }),
  ],
});

Multiple files

await ctx.reply({
  content: "Here are your files!",
  files: [
    new AttachmentBuilder(Buffer.from(dataA), { name: "file-a.txt" }),
    new AttachmentBuilder(Buffer.from(dataB), { name: "file-b.txt" }),
  ],
});

Referencing Files in Embeds

Once a file is attached, you can reference it inside an embed using the attachment://filename URI scheme. This is useful for embed thumbnails or images.

await ctx.reply({
  embeds: [
    {
      title: "Preview",
      image: { url: "attachment://chart.png" },
    },
  ],
  files: [new AttachmentBuilder(imageBuffer, { name: "chart.png" })],
});

Caution

The filename in attachment:// must exactly match the name set on the AttachmentBuilder, including the file extension.

Marking Files as Spoilers

Call .setSpoiler() to hide the file behind a spoiler warning in Discord. This prefixes the filename with SPOILER_ automatically.

const attachment = new AttachmentBuilder(imageBuffer, { name: "surprise.png" }).setSpoiler();

// attachment name is now "SPOILER_surprise.png"

Note

You can toggle the spoiler off again by calling .setSpoiler(false).

Using the REST Client Directly

Since v2.0.0 you can use the re-exported REST class (from @discordjs/rest) to send messages with attachments. If you need to post a message directly via the REST client rather than through an interaction method, use AttachmentBuilder.resolve() to split your builders into the files and attachments arrays that the REST client expects.

1. Build your attachments as normal.

   const builders = [
     new AttachmentBuilder(Buffer.from(data), { name: "report.txt" }),
   ];

2. Resolve them into the two separate arrays.

   const { files, attachments } = AttachmentBuilder.resolve(builders);

3. Pass files as a top-level REST option and attachments inside body.

   await rest.post(`/channels/${channelId}/messages`, {
     body: {
       content: "Here is your report!",
       attachments,
     },
     files,
   });

Caution

Do not place files inside body. The files array must be a top-level option on the REST call so the client can build the correct multipart/form-data request. Putting it inside body will serialize it as JSON and the binary data will never be uploaded.

Using an API instance

Since v2.0.0 you can also use the API class to send messages with attachments. This class is re-exported from @discordjs/core/http-only and provides a higher-level interface over the REST client.

import { REST, API, AttachmentBuilder } from "honocord";

const rest = new REST().setToken("your-bot-token");
const api = new API(rest);

await api.channels.createMessage(channelId, {
  content: "Here is your file!",
  ...new AttachmentBuilder(Buffer.from(data), { name: "report.txt" }).resolve(),
});

Demo View an example of using AttachmentBuilder in a real implementation, along with other Honocord features.