File uploads

This page covers sending files: building a file upload from a local path, a url or a received attachment, attaching it to a message builder, and reading the attachments of a sent message. You're assumed to have a bot named "my-bot" logged in and to know how to send a message.

How uploads work

A new file upload wraps a source into a local object, added to a message builder's attachments before it is sent. Four sources build one, chosen by the words after from:

on message received seen by "my-bot":
    if discord content of event-message is "!file-local":
        set {_f} to a new file upload from file "plugins/DiSky/logo.png"
        set {_m} to a new message with content "here's the logo" in event-channel
        add {_f} to attachments of {_m}
        await set {_sent} to the build result of {_m}

Nothing is read from disk or downloaded until the message carrying the upload is actually sent, except the local file's existence check and the image encoding above, which both have to happen now since there's nothing to defer.

Naming and spoilers

Every constructor takes an optional named (or with the name) and with spoiler. Left out, the name defaults to the source's own: the local file's or attachment's file name, the url's last path segment (or "file" if it has none), or image-<hex>.png for an image.

set {_f} to a new file upload from url "https://example.com/logo.png" named "banner.png" with spoiler true

with spoiler true and set spoiler of {_f} both work by prefixing the name with SPOILER_; setting it back to false strips the prefix again. Because the check looks at the current name, rename the file before setting spoiler, not after, or the rename overwrites the prefix. file description sets the alt text shown by screen readers and on hover; it has no readable side, only a setter.

set {_f} to a new file upload from file "plugins/DiSky/logo.png"
set file name of {_f} to "company-logo.png"
set spoiler of {_f} to true
set file description of {_f} to "the company logo"

Attaching to a message

attachments of a message builder takes set, add and remove; reading it back gives the names of the files added so far, and remove takes a name rather than the upload itself.

on message received seen by "my-bot":
    if discord content of event-message is "!file-list":
        set {_a} to a new file upload from file "plugins/DiSky/logo.png" named "a.png"
        set {_b} to a new file upload from file "plugins/DiSky/logo.png" named "b.png"
        set {_m} to a new message with content "one file" in event-channel
        set attachments of {_m} to {_a} and {_b}
        remove "a.png" from attachments of {_m}
        await set {_sent} to the build result of {_m}

A url or attachment source is only downloaded once the build result of runs, so a dead url fails there, not on the add line. reply with {_m} with reference event-message sends a builder's attachments the same way the build result of does. Media galleries and file displays (components v2) take file uploads too, the same way.

Reading attachments

discord attachments of a sent message returns its files as attachment, a read-only type with its own properties and conditions.

Four conditions describe what kind of file it is:

on message received seen by "my-bot":
    if discord content of event-message is "!file-echo":
        set {_att} to first element of discord attachments of event-message
        if {_att} is set:
            set {_f} to a new file upload from attachment {_att} named "echo-%file name of {_att}%"
            set {_m} to a new message with content "re-uploaded" in event-channel
            add {_f} to attachments of {_m}
            await set {_sent} to the build result of {_m}

Errors you may see