Sending messages

This page covers the three ways to put a message on Discord: post, reply with, and the message builder. You're assumed to have a bot named "my-bot" logged in and to know the builder contract and the three await rules.

How sending works

post sends a text, an embed or a component to a channel you name. reply with sends the same kinds of content, but picks its channel for you: the one the current event happened in. Neither hands you back the message it sent; for that, build one first (see below).

on message received seen by "my-bot":
    if discord content of event-message is "!post":
        post "plain text from DiSky" to event-channel

on message received seen by "my-bot":
    if discord content of event-message is "!reply":
        reply with "replied in the event channel"

In a message event, reply with posts to event-channel, exactly like the example above; in an interaction event it answers the interaction instead, and hidden makes that answer ephemeral (only the user who triggered it sees it, and it does nothing outside interactions). Add a reference to link the reply to a message, the way Discord's own reply feature does:

reply with "replied with a reference" with reference event-message

Posting to a channel

post and dispatch are the same effect under two names; pick whichever reads better. It accepts a text, an embed, a component or a poll, and posts to any message channel you hand it, not only event-channel:

on message received seen by "my-bot":
    if discord content of event-message is "!echo":
        set {_target} to event-channel
        post "posted from a variable" to {_target}
        dispatch "same effect, different name" in {_target}

Building a message

a new message with content %string% in %messagechannel% and a new message with embed %embedbuilder% in %messagechannel% create a message builder: it follows the same contract as every other builder, so nothing is sent until you read the build result of it, which requires await. What comes back is a real, already-sent message: edit it, pin it, or read any of its properties.

on message received seen by "my-bot":
    if discord content of event-message is "!edit":
        set {_m} to a new message with content "before" in event-channel
        await set {_sent} to the build result of {_m}
        edit {_sent} to show "after"

reply with {_m} also accepts a message builder, as a shortcut: it resends the builder's content, embeds, attachments and poll through the event's channel or interaction, without ever building it through the build result of, so you never get a message back. It ignores the builder's own channel, and it does not carry over tts, suppressed notifications or the builder's own referenced message; use with reference on reply with itself for that.

set {_m} to a new message with content "reply from a builder" in event-channel
reply with {_m} with reference event-message

Options

Every property below is write-only on the builder: read it back on the sent message instead.

on message received seen by "my-bot":
    if discord content of event-message is "!new-message":
        set {_m} to a new message with content "built, then sent" in event-channel
        set tts of {_m} to false
        set suppressed embeds of {_m} to false
        set suppressed notifications of {_m} to true
        await set {_sent} to the build result of {_m}

Replying to a message

referenced message, mention replied user and fail on invalid reply are the builder's own way to reply, alongside content or embed, instead of through reply with ... with reference. mention replied user only matters once a referenced message is set: it decides whether the referenced message's author gets pinged. fail on invalid reply decides what happens when that message no longer exists by the time the builder sends: false (the default) sends the message anyway, without the reply link; true fails the build instead.

on message received seen by "my-bot":
    if discord content of event-message is "!reply-ref":
        set {_m} to a new message with content "this is a reply" in event-channel
        set referenced message of {_m} to event-message
        set mention replied user of {_m} to false
        set fail on invalid reply of {_m} to false
        await set {_sent} to the build result of {_m}

Errors you may see