Managing messages

This page covers what you can do to a message that already exists: change it, pin it, publish it, forward it, delete it, and read its properties. You're assumed to have a bot named "my-bot" logged in and to know how to send a message.

How a message is managed

Every effect on this page takes a message, and a message comes from one of four places: the event you're in (event-message), the build result of a message builder, a fetch by id, or the pinned messages of a channel. The last two are retrieve-only reads and need await (see cache and await); the effects themselves never take it, since each one waits for Discord's answer before the next line runs.

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"

The builder gives back the message the bot just sent, which is the one message the bot can always edit. The other two sources look like this:

await set {_msg} to message with id "1234567890" in event-channel
await set {_pins::*} to pinned messages of event-channel

message with id fetches one message from a channel, pinned messages of every pinned message of it; both fail with a readable error when the id is wrong or the channel is not visible to the bot.

Editing

edit replaces what a message shows. It accepts a text, an embed or a component, and it is not a patch: the new payload replaces the content, the embeds, the components and the attachments of the message at once. Editing with a text removes the embeds the message had, editing with an embed empties its text. Only messages sent by the bot itself can be edited; every other one is refused before the request leaves.

on message received seen by "my-bot":
    if discord content of event-message is "!edit-embed":
        set {_m} to a new message with content "will get an embed" in event-channel
        await set {_sent} to the build result of {_m}
        set {_e} to a new discord embed
        set description of {_e} to "edited into an embed"
        edit {_sent} with {_e}

edit ... with and edit ... to show are the same effect. To keep both a text and an embed after the edit, pass a message builder that carries both, as described on the sending messages page.

Pinning and publishing

pin adds a message to its channel's pins and unpin removes it; a channel holds up to 50 pinned messages. Pinning a message that is not the bot's needs the Manage Messages permission.

on message received seen by "my-bot":
    if discord content of event-message is "!pin":
        pin event-message
    if discord content of event-message is "!unpin":
        unpin event-message

is pinned reads the snapshot you hold, not Discord: right after pin event-message, event-message is pinned is still false. Fetch the message again with message with id when you need the fresh flag.

publish (or crosspost) pushes a message to every guild following its channel. It only works on a message posted in an announcement channel; anywhere else Discord refuses it with a readable error in the console.

on message received seen by "my-bot":
    if discord content of event-message is "!publish":
        publish event-message

Forwarding and deleting

forward sends a copy of a message to another channel; the copy carries Discord's forwarded marker and is forwarded is true on it. destroy deletes one message, and purge deletes a list of them in as few requests as possible.

on message received seen by "my-bot":
    if discord content of event-message is "!forward":
        forward event-message to event-channel
    if discord content of event-message is "!delete":
        destroy event-message

on message received seen by "my-bot":
    if discord content of event-message is "!purge":
        set {_m} to a new message with content "temporary" in event-channel
        await set {_first} to the build result of {_m}
        await set {_second} to the build result of {_m}
        purge {_first} and {_second}

purge groups the messages per channel and uses Discord's bulk-delete endpoint, which takes 2 to 100 messages at a time and only accepts messages younger than two weeks. Larger lists are split into batches of 100, a single message falls back to a plain delete, and messages older than two weeks are deleted one by one; you never have to filter the list yourself. Deleting messages written by someone else, one at a time or in bulk, needs Manage Messages.

Other effects

show typing status in makes the bot is typing... indicator appear in a channel for 10 seconds, or until the bot posts there; it takes the channel, not a message. suppress the embeds of hides the link previews Discord generated for a message. end the poll of closes the poll a message carries; polls are covered on the polls page.

on message received seen by "my-bot":
    if discord content of event-message is "!typing":
        show typing status in event-channel
    if discord content of event-message is "!no-previews":
        suppress the embeds of event-message

Reading a message

A message's properties are read with <property> of <message>. The ones that overlap with a Skript name carry a discord prefix: Skript picks the first registered syntax whose pattern matches, and an untyped variable such as {_msg} satisfies any slot, so a same-shaped Skript or addon syntax would silently win over DiSky's. discord content, discord author, discord attachments and discord components avoid that; write them with the prefix always.

on message received seen by "my-bot":
    if discord content of event-message is "!info":
        reply with "by %discord author of event-message%: %jump url of event-message%"
        reply with "%size of mentioned users of event-message% user(s) mentioned"

Ten conditions describe the state of a message. They all read the snapshot you hold, and Skript negates each of them with is not (if event-message is not pinned:).

on message received seen by "my-bot":
    if event-message is from a dm:
        stop
    if event-message has a poll:
        reply with "%poll question of poll of event-message%"

Errors you may see