Messages

A message is one post in a channel, with its text, attachments, embeds, stickers and reactions. Categories, link channels, forum channels and media channels don't have messages of their own.

Access and history

A private channel returns 404 UNKNOWN_CHANNEL when you're not a recipient. A guild channel needs VIEW_CHANNEL, and in a thread you also need access to the parent and to a private thread, as Thread permissions describes.

In a guild channel without READ_MESSAGE_HISTORY, you only see messages created after the guild's message history cutoff, and nothing when the guild has no cutoff. In an age-restricted channel, the routes that read, send, edit or delete messages return 403 NSFW_CONTENT_AGE_RESTRICTED until the account passes the age check.

Routes that need MANAGE_MESSAGES also follow the guild's MFA level for elevated permissions.

Message object

Structure

Field	Type	Description
id	snowflake	The ID of the message
channel_id	snowflake	The ID of the channel
author1	partial user object	The user who sent the message
webhook_id?	snowflake	The ID of the webhook that sent the message
type	integer	Message type
flags	integer	Message flags
content	string	The text of the message, empty when it only has media
timestamp	ISO8601 timestamp	When the message was created
edited_timestamp	?ISO8601 timestamp	When the message was last edited
pinned	boolean	Whether the message is pinned
mention_everyone	boolean	Whether the message mentions everyone
tts	boolean	Whether the create request asked for text-to-speech
mentions	array[partial user object]	The users the message mentions
mention_roles	array[snowflake]	The IDs of the roles the message mentions
mention_channels?	array[channel mention object]	The channels the content links to
users?2	array[partial user object]	Users referred to in the message who weren't mentioned
embeds	array[embed object]	The embeds, empty while SUPPRESS_EMBEDS is set
attachments	array[message attachment object]	The files attached to the message
stickers	array[sticker item object]	The stickers sent with the message
reactions?	array[reaction object]	The reactions on the message
message_reference?	message reference object	The message this one replies to, forwards or copies
message_snapshots?	array[message snapshot object]	Copies of a forwarded message
nonce?3	string	The nonce from the create request
call?	message call object	The call a CALL message records
referenced_message?4	?message object	The message a reply points to
thread?	thread object	The thread started from this message

¹ For a webhook message, Fluxer builds the author from the webhook, with bot set to true

² A user is in mentions or in users, never both. Resolve the IDs in a snapshot's mentions against this array

³ Only in the create response and its Message Create event

⁴ Absent when the message isn't a reply, and null when the message it replies to is gone

Example

{
  "id": "1501320000000000000",
  "channel_id": "1501314428688998182",
  "author": {
    "id": "1501314428688990000",
    "username": "ada",
    "discriminator": "0001",
    "avatar": "a1b2c3d4e5f60718293a4b5c6d7e8f90"
  },
  "type": 0,
  "flags": 0,
  "content": "shipping it",
  "timestamp": "2026-08-31T09:14:02.000Z",
  "edited_timestamp": null,
  "pinned": false,
  "mention_everyone": false,
  "tts": false,
  "mentions": [],
  "mention_roles": [],
  "embeds": [],
  "attachments": [],
  "stickers": []
}

Message types

Value	Name	Description
0	DEFAULT	Ordinary message
1	RECIPIENT_ADD	Someone was added to a group DM or thread
2	RECIPIENT_REMOVE	Someone was removed from a group DM or thread
3	CALL	A call in a private channel
4	CHANNEL_NAME_CHANGE	A group DM or thread was renamed
5	CHANNEL_ICON_CHANGE	A group DM icon was changed
6	CHANNEL_PINNED_MESSAGE	A message was pinned
7	USER_JOIN	A member joined
12	CHANNEL_FOLLOW_ADD	The channel started following an announcement channel
18	THREAD_CREATED	A thread was created from the channel
19	REPLY	A reply to another message
21	THREAD_STARTER_MESSAGE	The first message of a thread started from a message

You can only edit, pin or reply to DEFAULT and REPLY messages. Thread messages describes the thread types.

Message flags

Value	Name	Description
1 << 0	CROSSPOSTED	The message was published to following channels
1 << 1	IS_CROSSPOST	The message is a copy from a followed announcement channel
1 << 2	SUPPRESS_EMBEDS	Embeds are hidden
1 << 3	SOURCE_MESSAGE_DELETED	The published message this copy came from was deleted
1 << 5	HAS_THREAD	A thread was started from this message
1 << 8	FAILED_TO_MENTION_SOME_ROLES_IN_THREAD	Some members of a mentioned role weren't added to the thread
1 << 12	SUPPRESS_NOTIFICATIONS	The message sends no mention notifications
1 << 13	VOICE_MESSAGE	The message is a voice message

You can set SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS and VOICE_MESSAGE. Fluxer ignores any other bit you send and sets the rest itself.

Message attachment object

Structure

Field	Type	Description
id	snowflake	The ID of the attachment
filename	string	The filename
title	?string	The display title
description	?string	The alt text
content_type	string	The media type Fluxer detected
content_hash	?string	The hash of the file
size	integer	The size in bytes
url	?string	The signed URL, or null once the attachment has expired
proxy_url	?string	The same URL as url
width?	integer	The width in pixels
height?	integer	The height in pixels
placeholder?	string	An encoded placeholder image
flags	integer	Attachment flags
nsfw?	boolean	Whether media inspection marked the file as explicit
duration?	integer	The audio or video length in seconds
waveform?	string	The base64 voice waveform
expires_at	?ISO8601 timestamp	When the attachment expires, or null if it doesn't
expired?	boolean	Present and true once the attachment has expired

Signed attachment URLs

When the instance has attachment URL secrets, Fluxer adds these query parameters to url and proxy_url.

Field	Type	Description
ex	string	When the URL expires, as Unix seconds in 8 hex digits
is	string	When the URL was issued, as Unix seconds in 8 hex digits
hm	string	The signature, as 64 hex digits
uc	string	dp on a data package URL, absent otherwise

A URL is valid for 24 hours from is. Keep the four parameters as they are, and add others such as a transformation if you need them. When ex is less than an hour away, get a new URL from Refresh attachment URLs or fetch the message again. An expired or changed URL returns 404 from the Media Proxy.

Data package attachment URLs

A data harvest archive links each attachment with uc=dp and ex=0. These URLs don't expire and work until the instance removes the secret that signed them.

Example

{
  "id": "1501320000000000001",
  "filename": "diagram.png",
  "title": null,
  "description": "Sequence diagram",
  "content_type": "image/png",
  "content_hash": "9f86d081884c7d659a2feaa0c55ad015",
  "size": 18422,
  "url": "https://media.example.com/attachments/1501314428688998182/1501320000000000001/diagram.png?ex=69fba4b5&is=69fa5335&hm=5586be3ae70411fe6582431649e2f28abc6c201e4f12a4f43a3256b72b90d3de",
  "proxy_url": "https://media.example.com/attachments/1501314428688998182/1501320000000000001/diagram.png?ex=69fba4b5&is=69fa5335&hm=5586be3ae70411fe6582431649e2f28abc6c201e4f12a4f43a3256b72b90d3de",
  "width": 1280,
  "height": 720,
  "flags": 0,
  "expires_at": null
}

Attachment flags

Value	Name	Description
1 << 3	IS_SPOILER	The attachment is a spoiler
1 << 4	CONTAINS_EXPLICIT_MEDIA	The attachment has explicit media
1 << 5	IS_ANIMATED	The attachment is animated

Emoji object

Structure

Field	Type	Description
id?	snowflake	The ID of a custom emoji
name	string	The custom emoji name, or the Unicode emoji itself
animated?	boolean	Whether the custom emoji is animated

Reaction object

Structure

Field	Type	Description
emoji	emoji object	The emoji
count	integer	How many users reacted with it
me?	boolean	Present and true when you reacted with it

A message can have up to max_reactions_per_message different emoji (default 30), and each up to max_users_per_message_reaction users (default 1,000,000).

Message reference object

Structure

Field	Type	Description
channel_id	snowflake	The ID of the referenced channel
message_id?	snowflake	The ID of the referenced message
guild_id?	snowflake	The ID of the referenced guild
type	integer	Message reference type

Message reference types

Value	Name	Description
0	DEFAULT	A reply, a published copy's source or a thread
1	FORWARD	A forward, with the content in message_snapshots

Message reference input object

Structure

Field	Type	Description
message_id	snowflake	The ID of the message to reply to or forward
channel_id?	snowflake	The ID of its channel, required for a forward
guild_id?	snowflake	The ID of its guild
type?	integer	Message reference type (default DEFAULT)
attachment_ids?	array[snowflake]	The attachments to forward (at most 10)
embed_indices?	array[integer]	The embeds to forward (at most 10)

A forward copies all the source's media unless you pick some with attachment_ids or embed_indices.

Message snapshot object

A snapshot is a copy of a forwarded message. It doesn't change when the source is edited or deleted.

Structure

Field	Type	Description
content?	string	The text
timestamp	ISO8601 timestamp	When the source was created
edited_timestamp?	ISO8601 timestamp	When the source was last edited
mentions?	array[snowflake]	The IDs of mentioned users
mention_roles?	array[snowflake]	The IDs of mentioned roles
mention_channels?	array[channel mention object]	The mentioned channels
embeds?	array[embed object]	The embeds
attachments?	array[message attachment object]	The attachments
stickers?	array[sticker item object]	The stickers
type	integer	The source's message type
flags	integer	The source's message flags

Message call object

Structure

Field	Type	Description
participants	array[snowflake]	The IDs of the users in the call
ended_timestamp	?ISO8601 timestamp	When the call ended, or null while it's ongoing

Channel mention object

Structure

Field	Type	Description
id	snowflake	The ID of the channel
name	string	The channel name
type	integer	Channel type

Sticker item object

Structure

Field	Type	Description
id	snowflake	The ID of the sticker
name	string	The sticker name
animated	boolean	Whether the sticker is animated

Embed object

An embed is a link preview Fluxer builds, or a rich embed you send.

Structure

Field	Type	Description
type	string	Embed type
title?	string	The title
description?	string	The description
url?	string	The link
timestamp?	ISO8601 timestamp	The timestamp
color?	integer	The color
author?	embed author object	The author
provider?1	embed provider object	The site the link is from
thumbnail?	embed media object	The thumbnail
image?	embed media object	The main image
video?1	embed media object	The video
audio?1	embed media object	The audio
footer?	embed footer object	The footer
fields?	array[embed field object]	The fields
nsfw?	boolean	Whether the embed has explicit media
html?1	string	Sanitized oEmbed markup
html_width?1	integer	The width of the oEmbed markup in pixels
html_height?1	integer	The height of the oEmbed markup in pixels
children?1	array[embed object]	At most one nested embed

¹ Only on link previews, and you can't send it

Example

{
  "type": "rich",
  "title": "Release 2.4.0",
  "url": "https://example.com/releases/2.4.0",
  "color": 5793266,
  "footer": {"text": "example.com"},
  "fields": [{"name": "Platform", "value": "Desktop", "inline": true}]
}

Embed types

Value	Description
rich	A rich embed, and the type of every embed you send
link	A link preview with no media
image	An image preview
video	A video preview
audio	An audio preview
gifv	A looping video preview
article	An article preview
bluesky	A Bluesky post preview

Embed author object

Structure

Field	Type	Description
name	string	The author name
url?	string	The author link
icon_url?	string	The icon URL
proxy_icon_url?	string	The icon URL through the Media Proxy

Embed media object

Structure

Field	Type	Description
url	string	The media URL
proxy_url	string	The media URL through the Media Proxy
width?	integer	The width in pixels
height?	integer	The height in pixels
duration?	integer	The length in seconds
description?	string	The alt text
content_type?	string	The media type
content_hash?	string	The content hash
placeholder?	string	An encoded placeholder image
flags?	integer	CONTAINS_EXPLICIT_MEDIA and IS_ANIMATED from attachment flags

Fluxer signs every embed URL that points to an attachment on this instance, the same way as attachment URLs.

Embed footer object

Structure

Field	Type	Description
text	string	The footer text
icon_url?	string	The icon URL
proxy_icon_url?	string	The icon URL through the Media Proxy

Embed field object

Structure

Field	Type	Description
name	string	The field name
value	string	The field value
inline	boolean	Whether the field shows inline

Embed provider object

Structure

Field	Type	Description
name	string	The provider name
url?	string	The provider URL

Allowed mentions object

An allowed mentions object picks which mentions in the text notify anyone.

Structure

Field	Type	Description
parse?1	array[string]	Allowed mention parse values
users?	array[snowflake]	The users who can be mentioned (at most 100)
roles?	array[snowflake]	The roles that can be mentioned (at most 100)
replied_user?	boolean	Whether a reply mentions the author of the message it replies to (default true)

¹ Leaving out the whole object allows every value. Sending users or roles without parse allows none of them. You can't send parse together with users or roles

Caution

Sending allowed_mentions as {} turns off every mention, including @everyone and @here.

Allowed mention parse values

Value	Description
users	User mentions
roles	Role mentions
everyone	@everyone and @here

Message attachment input objects

Each entry in a message's attachments array is one of these.

Pre-uploaded attachment object

Structure

Field	Type	Description
id	integer | integer string	The attachment's position
filename	string	The filename
upload_filename	string	The upload key from Request attachment upload URLs
file_size	integer	The size in bytes
content_type	string	The media type (1-255 characters)
title?	?string	The display title (1-1,024 characters)
description?	?string	The alt text (1-4,096 characters)
duration?1	?integer	The voice message length in seconds
waveform?1	?string	The base64 voice waveform (1-4,096 characters)
flags?	integer	Attachment flags (default 0)

¹ Required for a voice message

Direct multipart attachment metadata object

Structure

Field	Type	Description
id	integer | integer string	The index of the files[N] field
filename	string	The filename
content_type?	string	The media type (1-255 characters)
title?	?string	The display title (1-1,024 characters)
description?	?string	The alt text (1-4,096 characters)
flags?	integer	Attachment flags (default 0)
duration?1	?integer	The voice message length in seconds
waveform?1	?string	The base64 voice waveform (1-4,096 characters)

¹ Required for a voice message

Existing attachment reference object

Use this in Modify message to keep an attachment and change its title or description. When you edit someone else's message, sending filename, duration or waveform returns INVALID_FORM_BODY with CANNOT_EDIT_ATTACHMENT_METADATA.

Structure

Field	Type	Description
id	snowflake | integer	The ID of the attachment, or its position in the message
title?	?string	A new display title (1-1,024 characters)
description?	?string	New alt text (1-4,096 characters)
flags?	integer	Ignored
filename?	string	Ignored
duration?	?integer	Ignored
waveform?	?string	Ignored

Rich embed input objects

A message can have up to max_embeds_per_message embeds (default 10).

Rich embed object

Structure

Field	Type	Description
url?	?string	The link (1-2,048 characters)
title?	?string	The title (at most 256 characters)
color?	?integer	The color
timestamp?	?ISO8601 timestamp	The timestamp
description?	?string	The description (1-4,096 characters)
author?	?embed author input object	The author
image?	?embed media input object	The main image
thumbnail?	?embed media input object	The thumbnail
footer?	?embed footer input object	The footer
fields?	?array[embed field input object]	The fields (at most 25)

Embed author input object

Structure

Field	Type	Description
name	string	The author name (1-256 characters)
url?	?string	The author link (1-2,048 characters)
icon_url?	?string	The icon URL (1-2,048 characters)

Embed media input object

Structure

Field	Type	Description
url1	string	The media URL (1-2,048 characters)
description?	?string	The alt text (1-4,096 characters)

¹ An http or https URL. In image and thumbnail, it can also be attachment://<filename> for a png, jpg, jpeg, webp or gif file in the same request

Embed footer input object

Structure

Field	Type	Description
text	string	The footer text (1-2,048 characters)
icon_url?	?string	The icon URL (1-2,048 characters)

Embed field input object

Structure

Field	Type	Description
name	string	The field name (1-256 characters)
value	string	The field value (at most 1,024 characters)
inline?	boolean	Whether the field shows inline (default false)

Attachment upload objects

To upload a file before you send the message:

1. Get upload URLs from Request attachment upload URLs.
2. PUT the file to upload_url, or each part to its own URL for a file over 10 MiB, then call Complete attachment upload.
3. Send the upload_filename in a pre-uploaded attachment.

The upload only works for a message in the same channel, which in a forum or media channel is the first message of a post from Start thread.

Attachment upload request item object

Structure

Field	Type	Description
id	integer	Your position for the attachment (0-2,147,483,647)
filename	string	The filename
file_size	integer	The size in bytes
content_type	string	The media type (1-255 characters)

Singlepart attachment upload object

Returned for a file of 10 MiB or less.

Structure

Field	Type	Description
id	integer	The id from the request
filename	string	The filename from the request
upload_filename	string	The upload key to send with the message
file_size	integer	The size from the request
content_type	string	The media type Fluxer derived from filename
upload_mode	string	Always singlepart
upload_url	string	The URL to PUT the whole file to

Multipart attachment upload object

Returned for a file over 10 MiB.

Structure

Field	Type	Description
id	integer	The id from the request
filename	string	The filename from the request
upload_filename	string	The upload key to send with the message
file_size	integer	The size from the request
content_type	string	The media type Fluxer derived from filename
upload_mode	string	Always multipart
upload_id	string	The ID of the multipart upload
part_size	integer	The size of every part except the last, in bytes
parts	array[attachment upload part object]	The parts in order

Each part except the last must be exactly part_size bytes, and all parts together must add up to file_size.

Attachment upload part object

Structure

Field	Type	Description
part_number	integer	The part number, starting at 1
upload_url	string	The URL to PUT this part to

Multipart upload completion item object

Structure

Field	Type	Description
upload_filename	string	The upload key
upload_id	string	The ID of the multipart upload

Refreshed attachment URL object

Structure

Field	Type	Description
original	string	The URL you sent
refreshed	string	The URL with a new signature

refreshed is the same as original when the URL isn't an attachment URL of this instance.

Channel pin object

Structure

Field	Type	Description
message	message object	The pinned message, without referenced_message and reactions
pinned_at	ISO8601 timestamp	When the message was pinned

Channel pins page object

Structure

Field	Type	Description
items	array[channel pin object]	The pins, newest first
has_more	boolean	Whether there are older pins

To get the next page, set before to the pinned_at of the last item. Skip messages you already have, because two pins can share a timestamp.

Reaction users page object

Structure

Field	Type	Description
items	array[partial user object]	The users, by ascending ID
has_more	boolean	Whether there's another page
next_after	?snowflake	The after value for the next page

Bulk message request object

Structure

Field	Type	Description
channel_id	snowflake	The ID of the channel
limit	integer	The number of messages to return (1-50)
before?	snowflake	Get messages before this message ID
after?	snowflake	Get messages after this message ID
around?	snowflake	Get messages around this message ID

Bulk message channel object

Structure

Field	Type	Description
channel_id	snowflake	The ID of the channel
messages	array[message object]	The messages, newest first

Crosspost source object

Structure

Field	Type	Description
guild	crosspost source guild object	The guild the message was published from

Crosspost source guild object

Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The guild name
icon	?string	The guild icon hash
banner	?string	The guild banner hash
description	?string	The discovery description, or null when the guild isn't in discovery
features	array of strings	VERIFIED, PARTNERED and DISCOVERABLE from guild features
badge_ids	array[snowflake]	The custom badges of the guild. Look them up with List guild badges
approximate_member_count	?integer	About how many members the guild has
approximate_presence_count	?integer	About how many members are online
discoverable	boolean	Whether you can join through Join discovery guild

List channel messages

GET/v1/channels/{channel_id}/messagesBot

Returns messages from a channel, newest first. A page can have fewer than limit messages when some are older than your history cutoff.

Query parameters

Field	Type	Description
limit?	integer	The number of messages to return (1-100, default 50)
before?	snowflake	Get messages before this message ID
after?	snowflake	Get messages after this message ID
around?	snowflake	Get messages around this message ID, ignoring before and after

Response

Status	Body	Condition
200	array[message object]	The messages were returned
400	error response	INVALID_CHANNEL_TYPE for a forum or media channel

The rate limit is 100 requests per 10 seconds, on the channel:messages:read::channel_id bucket.

List messages from multiple channels

POST/v1/channels/messages/bulk

Returns messages from up to 25 channels in one request. Each channel needs the same access as List channel messages, and one channel you can't see fails the whole request. Bots can't use this route.

JSON body

Field	Type	Description
requests	array[bulk message request object]	1-25 channels, with limit adding up to at most 250

Response body

Field	Type	Description
channels	array[bulk message channel object]	One result for each request, in the same order

Response

Status	Body	Condition
200	response body	The messages were returned

The rate limit is 20 requests per 10 seconds, on the channel:messages:bulk_read bucket.

Get message

GET/v1/channels/{channel_id}/messages/{message_id}Bot

Returns one message, or 404 UNKNOWN_MESSAGE when it's older than your history cutoff.

Response

Status	Body	Condition
200	message object	The message was returned

The rate limit is 100 requests per 10 seconds, on the channel:message:read::channel_id bucket.

Request attachment upload URLs

POST/v1/channels/{channel_id}/attachmentsBot

Returns upload URLs for 1 to 10 files, as described in Attachment upload objects. In a guild channel you need SEND_MESSAGES and ATTACH_FILES.

Each file can be up to the max_attachment_file_size limit, which defaults to 524288000 bytes (500 MiB), or 26214400 bytes (25 MiB) without premium on an instance with premium tiers. Bots get at most 52428800 bytes (50 MiB).

JSON body

Field	Type	Description
attachments	array[attachment upload request item object]	The files to upload (1-10)

Response body

Field	Type	Description
attachments	array[singlepart or multipart attachment upload object]	One upload for each file, in request order

Response

Status	Body	Condition
200	response body	The upload URLs were returned
400	error response	FILE_SIZE_TOO_LARGE when a file is over the size limit
400	error response	CANNOT_SEND_MESSAGES_IN_NON_TEXT_CHANNEL when the channel has no messages
403	error response	COMMUNICATION_DISABLED when you're timed out
403	error response	FEATURE_TEMPORARILY_DISABLED when the instance has turned off uploads

The rate limit is 10 requests per 10 seconds, on the channel:attachment:upload::channel_id bucket.

Complete attachment upload

POST/v1/channels/{channel_id}/attachments/completeBot

Finishes 1 to 10 multipart uploads after you've uploaded every part. If completion fails, Fluxer discards the upload and you have to start again.

JSON body

Field	Type	Description
uploads	array[multipart upload completion item object]	The uploads to finish (1-10)

Response body

Field	Type	Description
uploads	array[object]	One object with upload_filename for each upload

Response

Status	Body	Condition
200	response body	The uploads were finished
400	error response	INVALID_FORM_BODY with UPLOADED_ATTACHMENT_NOT_FOUND for an unknown upload
400	error response	INVALID_FORM_BODY with NO_UPLOADED_PARTS_TO_FINALIZE when no part was uploaded
400	error response	FILE_SIZE_TOO_LARGE when the uploaded file is over the size limit

The rate limit is 10 requests per 10 seconds, on the channel:attachment:upload::channel_id bucket.

Refresh attachment URLs

POST/v1/attachments/refresh-urlsBot

Signs 1 to 50 attachment URLs again. A refreshed URL is valid until its ex, which is 12 to 24 hours away. Check ex on each URL, because it isn't always a full day. OAuth2 tokens can't use this route.

JSON body

Field	Type	Description
attachment_urls	array[string]	The URLs to sign (1-50, each at most 2,048 characters)

Response body

Field	Type	Description
refreshed_urls	array[refreshed attachment URL object]	One result for each URL, in request order

Response

Status	Body	Condition
200	response body	The URLs were signed

The rate limit is 60 requests per 10 seconds, on the attachment:refresh_urls bucket.

Create message

POST/v1/channels/{channel_id}/messagesBot

Sends a message and returns it, and Fluxer sends Message Create. In a guild channel you need SEND_MESSAGES, or SEND_MESSAGES_IN_THREADS in a thread. Embeds need EMBED_LINKS, files need ATTACH_FILES and @everyone needs MENTION_EVERYONE.

A message needs text, an embed, an attachment, a meme or a sticker. Text can be up to the max_message_length limit, and bots and webhooks always get at least 4,000 characters.

JSON body

Field	Type	Description
nonce?1	string | integer	Your ID for the message (up to 32 characters, or a non-negative integer)
content?	?string	The text
embeds?	array[rich embed object]	The embeds
attachments?	array[pre-uploaded attachment object]	The attachments (default limit 10)
message_reference?	?message reference input object	The message to reply to or forward
allowed_mentions?	?allowed mentions object	Which mentions notify anyone
flags?	integer	Message flags (default 0)
favorite_meme_id?	?snowflake	A saved meme to attach
sticker_ids?	?array[snowflake]	The stickers (at most 3)
tts?	boolean	Whether to use text-to-speech, which needs SEND_TTS_MESSAGES

¹ Fluxer remembers a nonce for 5 minutes, and sending it again in the same channel returns the first message. Reuse the nonce when you retry a send. Reusing it in a different channel within that time returns 404 UNKNOWN_MESSAGE

A forward has only message_reference, with type 1 and channel_id.

Multipart body

Send files as multipart/form-data, with the JSON body in payload_json. In payload_json, attachments uses the direct multipart attachment metadata object.

Field	Type	Description
payload_json?	string	The JSON body
files[N]?	binary	A file, where N starts at 0
content?	string	Replaces content in payload_json
nonce?	string	Replaces nonce in payload_json
tts?	string	Replaces tts in payload_json (true or false)
flags?	string	Replaces flags in payload_json
favorite_meme_id?	string	Replaces favorite_meme_id in payload_json
sticker_ids?	string	Replaces sticker_ids in payload_json, once for each sticker

These field codes come back in a 400 INVALID_FORM_BODY.

Condition	Field code
A files[N] index is over the attachment limit	FILE_INDEX_EXCEEDS_MAXIMUM
Two fields use the same index	DUPLICATE_FILE_INDEX
There are more files than the attachment limit	TOO_MANY_FILES
An attachments entry with a filename has no matching file	NO_FILE_FOR_ATTACHMENT_METADATA

Voice messages

A message with the VOICE_MESSAGE flag has one audio attachment with duration and waveform, and nothing else. It can be up to max_voice_message_duration seconds long (default 1200).

Condition	Field code
The message has text	VOICE_MESSAGES_CANNOT_HAVE_CONTENT
The message doesn't have exactly one attachment	VOICE_MESSAGES_REQUIRE_SINGLE_ATTACHMENT
The attachment has no waveform	VOICE_MESSAGES_ATTACHMENT_WAVEFORM_REQUIRED
The attachment has no duration	VOICE_MESSAGES_ATTACHMENT_DURATION_REQUIRED
The recording is too long	VOICE_MESSAGES_DURATION_EXCEEDS_LIMIT

Response

Status	Body	Condition
200	message object	The message was sent
400	error response	CANNOT_SEND_EMPTY_MESSAGE when the message has nothing in it
400	error response	CANNOT_SEND_MESSAGES_TO_USER when the recipient's DM settings block you
400	error response	SLOWMODE_RATE_LIMITED with retry_after when slowmode is on
400	error response	THREAD_LOCKED or MAX_ACTIVE_THREADS in a thread
403	error response	COMMUNICATION_DISABLED when you're timed out
403	error response	NEW_CONVERSATIONS_LIMITED when you can't start new DMs
403	error response	ACCOUNT_LIMITED when your account is limited
403	error response	UNCLAIMED_ACCOUNT_CANNOT_SEND_MESSAGES outside personal notes

The rate limit is 20 requests per 10 seconds, on the channel:message:create::channel_id bucket.

Modify message

PATCH/v1/channels/{channel_id}/messages/{message_id}Bot

Edits a message and returns it, and Fluxer sends Message Update. The author can change any field. Someone else with MANAGE_MESSAGES can only change SUPPRESS_EMBEDS and the title and alt text of existing attachments. The author of a published message can edit it 3 times in a row, then once every 20 minutes.

The body works like Create message, including multipart. Fields you leave out stay the same.

JSON body

Field	Type	Description
content?	?string	The new text
embeds?1	array[rich embed object]	The embeds
allowed_mentions?	?allowed mentions object	Which mentions notify anyone
flags?	integer	Message flags
attachments?1	array[pre-uploaded attachment object | existing attachment reference object]	The attachments to keep and add
message_snapshots?	array	Not accepted, and returns 403 MISSING_PERMISSIONS

¹ Replaces the whole list, so include every existing item you want to keep

Response

Status	Body	Condition
200	message object	The message was edited
400	error response	CANNOT_MODIFY_SYSTEM_WEBHOOK for a system message
400	error response	INVALID_FORM_BODY with MESSAGES_WITH_SNAPSHOTS_CANNOT_BE_EDITED for a forwarded message
400	error response	THREAD_ARCHIVED or THREAD_LOCKED in a thread
403	error response	CANNOT_EDIT_OTHER_USER_MESSAGE when you can't edit someone else's message
429	error response	PUBLISHED_MESSAGE_EDIT_RATE_LIMITED for a published message

The rate limit is 20 requests per 10 seconds, on the channel:message:update::channel_id bucket.

Crosspost message

POST/v1/channels/{channel_id}/messages/{message_id}/crosspostBot

Publishes a message in an announcement channel to every channel that follows it, and returns the message with the CROSSPOSTED flag. You need SEND_MESSAGES, and MANAGE_MESSAGES for someone else's message. Only a DEFAULT message that isn't a forward can be published, and only once. Announcement channels describes the copies.

Each announcement channel can publish 10 messages in a row, then one every 6 minutes.

Response

Status	Body	Condition
200	message object	The message was published
400	error response	ANNOUNCEMENT_CHANNEL_REQUIRED for another channel type
400	error response	MESSAGE_NOT_CROSSPOSTABLE for a message that can't be published
400	error response	MESSAGE_ALREADY_CROSSPOSTED when it's already published
403	error response	CONTENT_BLOCKED when the message matches an instance blocklist
429	error response	MESSAGE_CROSSPOST_RATE_LIMITED when the channel has published too many

The rate limit is 5 requests per 5 seconds, on the channel:message:crosspost::channel_id bucket.

Get message crosspost source

GET/v1/channels/{channel_id}/messages/{message_id}/crosspost-sourceBot

Returns the guild a published copy came from, for a message with IS_CROSSPOST or a CHANNEL_FOLLOW_ADD message. You don't need to be a member of that guild.

Response

Status	Body	Condition
200	crosspost source object	The guild was returned
404	error response	UNKNOWN_MESSAGE for any other message
404	error response	UNKNOWN_GUILD when the guild was deleted

The rate limit is 20 requests per 10 seconds, on the channel:message:crosspost_source::channel_id bucket.

Clear channel read state

DELETE/v1/channels/{channel_id}/messages/ackBot

This route is deprecated, and it returns 204 without changing anything.

Response

Status	Body	Condition
204	empty	Always

The rate limit is 40 requests per 10 seconds, on the channel:read_state:delete::channel_id bucket.

Delete message

DELETE/v1/channels/{channel_id}/messages/{message_id}BotAudit reason

Deletes a message and its attachments, and Fluxer sends Message Delete. You can delete your own messages, and someone else's message in a guild needs MANAGE_MESSAGES. Only DEFAULT, REPLY, CHANNEL_PINNED_MESSAGE, USER_JOIN, CHANNEL_FOLLOW_ADD and THREAD_CREATED messages can be deleted. In a guild, every delete adds a MESSAGE_DELETE audit log entry.

Deleting a published message replaces each copy with [Original message deleted] and sets SOURCE_MESSAGE_DELETED.

Response

Status	Body	Condition
204	empty	The message was deleted

The rate limit is 20 requests per 10 seconds, on the channel:message:delete::channel_id bucket.

Delete message attachment

DELETE/v1/channels/{channel_id}/messages/{message_id}/attachments/{attachment_id}Bot

Deletes one attachment from your own message, and Fluxer sends Message Update. When it's the last thing in the message, Fluxer deletes the whole message and sends Message Delete instead.

Response

Status	Body	Condition
204	empty	The attachment was deleted

The rate limit is 20 requests per 10 seconds, on the channel:message:delete::channel_id bucket.

Bulk delete messages

POST/v1/channels/{channel_id}/messages/bulk-deleteBotAudit reasonMFA

Deletes up to 100 messages of any age in a guild channel and skips IDs that match nothing. You need MANAGE_MESSAGES. Fluxer sends one Message Delete Bulk and adds one MESSAGE_BULK_DELETE audit log entry.

JSON body

Field	Type	Description
message_ids?	array[snowflake]	The messages to delete (1-100)
messages?	array[snowflake]	Another name for message_ids

Response

Status	Body	Condition
204	empty	The messages were deleted
400	error response	INVALID_FORM_BODY with MESSAGE_IDS_CANNOT_BE_EMPTY when the list is empty
400	error response	CANNOT_EXECUTE_ON_DM in a private channel

The rate limit is 10 requests per 10 seconds, on the channel:message:bulk_delete::channel_id bucket.

Purge personal notes

POST/v1/channels/{channel_id}/messages/purgeBot

Deletes every message in your personal notes channel and can't be undone. Fluxer sends Message Delete Bulk for every 100 messages.

Response body

Field	Type	Description
deleted_count	integer	The number of messages deleted

Response

Status	Body	Condition
200	response body	The messages were deleted
400	error response	INVALID_CHANNEL_TYPE for any other channel

The rate limit is 2 requests per minute, on the channel:message:purge::channel_id bucket.

Bulk delete own messages

POST/v1/channels/{channel_id}/messages/bulk-delete-mineBotMFA

Deletes every message you sent in a channel and its threads, and can't be undone. For a thread, only that thread is cleared. You need sudo mode, from the X-Fluxer-Sudo-Mode-JWT header or the fields in the JSON body. Fluxer sends Message Delete Bulk for every 100 messages.

JSON body

Field	Type	Description
password?	string	Your password, when you have no MFA
mfa_method?	string	totp, webauthn or email_code
mfa_code?	string	The authenticator code (1-32 characters)
webauthn_response?	WebAuthn assertion object	The WebAuthn assertion
webauthn_challenge?	string	The challenge for the assertion
email_code_ticket?	string	The ticket from send a sudo email code (1-128 characters)
email_code?	string	The 6-digit code from the email

Response

Status	Body	Condition
202	empty	The messages were deleted
403	error response	SUDO_MODE_REQUIRED when you're not in sudo mode

The rate limit is 10 requests per 10 seconds, on the channel:message:bulk_delete::channel_id bucket.

List pinned messages

GET/v1/channels/{channel_id}/messages/pinsBot

Returns a page of pinned messages, newest pin first.

Query parameters

Field	Type	Description
limit?	integer	The number of pins to return (1-50, default 50)
before?	ISO8601 timestamp	Get pins pinned before this time

Response

Status	Body	Condition
200	channel pins page object	The pins were returned
400	error response	INVALID_CHANNEL_TYPE for a forum or media channel

The rate limit is 20 requests per 10 seconds, on the channel:pins::channel_id bucket.

Pin message

PUT/v1/channels/{channel_id}/pins/{message_id}BotAudit reason

Pins a DEFAULT or REPLY message. In a guild you need PIN_MESSAGES, and Fluxer adds a MESSAGE_PIN audit log entry. Fluxer posts a CHANNEL_PINNED_MESSAGE message and sends Message Update, Channel Pins Update and Message Create.

Response

Status	Body	Condition
204	empty	The message is pinned
400	error response	CANNOT_MODIFY_SYSTEM_WEBHOOK for a system message
400	error response	CANNOT_SEND_MESSAGES_TO_USER when the recipient's DM settings block you

The rate limit is 20 requests per 10 seconds, on the channel:pins::channel_id bucket.

Unpin message

DELETE/v1/channels/{channel_id}/pins/{message_id}BotAudit reason

Unpins a message, with the same permissions as Pin message. Fluxer sends Message Update and Channel Pins Update, and in a guild adds a MESSAGE_UNPIN audit log entry.

Response

Status	Body	Condition
204	empty	The message isn't pinned
400	error response	CANNOT_MODIFY_SYSTEM_WEBHOOK for a system message

The rate limit is 20 requests per 10 seconds, on the channel:pins::channel_id bucket.

Acknowledge pins

POST/v1/channels/{channel_id}/pins/ackBot

Marks the channel's pins as seen, and Fluxer sends Channel Pins ACK to your sessions.

Response

Status	Body	Condition
204	empty	The pins were acknowledged
400	error response	INVALID_CHANNEL_TYPE for a forum or media channel

The rate limit is 20 requests per 10 seconds, on the channel:pins::channel_id bucket.

Reaction emoji path value

The {emoji} path value is URL-encoded and 1-64 characters long. Use name:id for a custom emoji and the emoji itself for a Unicode emoji.

List reaction users unpaged

GET/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}Bot

Returns the users who reacted with an emoji, as a plain array. The X-Has-More and X-Next-After headers have the paging values that List reaction users returns in the body.

Query parameters

Field	Type	Description
limit?	integer	The number of users to return (1-100, default 25)
after?	snowflake	Get users after this user ID

Response

Status	Body	Condition
200	array[partial user object]	The users were returned

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

List reaction users

GET/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/usersBot

Returns a page of the users who reacted with an emoji.

Query parameters

Field	Type	Description
limit?	integer	The number of users to return (1-100, default 25)
after?	snowflake	Get users after this user ID

Response

Status	Body	Condition
200	reaction users page object	The users were returned

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Add own reaction

PUT/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@meBot

Adds your reaction, and Fluxer sends Message Reaction Add. In a guild, adding a new emoji needs ADD_REACTIONS, and a custom emoji also needs USE_EXTERNAL_EMOJIS. Using another guild's emoji needs the feature_global_expressions limit. Your account needs a verified email.

Query parameters

Field	Type	Description
session_id?	string	Your Gateway session ID (1-64 characters)

Response

Status	Body	Condition
204	empty	The reaction was added
400	error response	MAX_REACTIONS when the message has too many reactions
400	error response	INVALID_FORM_BODY with NOT_A_VALID_UNICODE_EMOJI or CUSTOM_EMOJI_NOT_FOUND for a bad emoji
400	error response	INVALID_FORM_BODY with CUSTOM_EMOJIS_REQUIRE_PREMIUM_OUTSIDE_SOURCE for another guild's emoji
403	error response	REACTION_EMAIL_VERIFICATION_REQUIRED when your email isn't verified
403	error response	UNCLAIMED_ACCOUNT_CANNOT_ADD_REACTIONS outside personal notes
403	error response	COMMUNICATION_DISABLED when you're timed out

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Remove own reaction

DELETE/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@meBot

Removes your reaction, and Fluxer sends Message Reaction Remove.

Query parameters

Field	Type	Description
session_id?	string	Your Gateway session ID (1-64 characters)

Response

Status	Body	Condition
204	empty	The reaction was removed

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Remove another user's reaction

DELETE/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/{target_id}Bot

Removes the reaction of the user target_id, and Fluxer sends Message Reaction Remove. Unless target_id is you, this only works in a guild channel and needs MANAGE_MESSAGES.

Query parameters

Field	Type	Description
session_id?	string	Your Gateway session ID (1-64 characters)

Response

Status	Body	Condition
204	empty	The reaction was removed

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Remove all reactions for emoji

DELETE/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}Bot

Removes every reaction with one emoji, and Fluxer sends Message Reaction Remove Emoji. This only works in a guild channel, where you need MANAGE_MESSAGES. A private channel returns 403 MISSING_PERMISSIONS.

Response

Status	Body	Condition
204	empty	The reactions were removed

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Remove all reactions

DELETE/v1/channels/{channel_id}/messages/{message_id}/reactionsBot

Removes every reaction from a message, and Fluxer sends Message Reaction Remove All. This only works in a guild channel, where you need MANAGE_MESSAGES. A private channel returns 403 MISSING_PERMISSIONS.

Response

Status	Body	Condition
204	empty	The reactions were removed

The rate limit is 30 requests per 10 seconds, on the channel:reactions::channel_id bucket.

Indicate typing

POST/v1/channels/{channel_id}/typingBot

Shows that you're typing, and Fluxer sends Typing Start. In a guild channel you need SEND_MESSAGES, or SEND_MESSAGES_IN_THREADS in a thread.

Response body

Field	Type	Description
message_send_cooldown_ms?1	integer	Milliseconds until slowmode lets you send a message
thread_create_cooldown_ms?1	integer	Milliseconds until slowmode lets you create a thread

¹ The schema does not declare this body

Fluxer only returns this body during a slowmode cooldown, and only to a session with the channel_threads client capability.

Response

Status	Body	Condition
200	response body	You're typing and slowmode is counting down
204	empty	You're typing
400	error response	INVALID_CHANNEL_TYPE for a forum or media channel

The rate limit is 20 requests per 10 seconds, on the channel:typing::channel_id bucket.

Acknowledge message

POST/v1/channels/{channel_id}/messages/{message_id}/ack

Marks a channel as read up to a message, and Fluxer sends Message ACK to your sessions. Bots can't use this route.

JSON body

Field	Type	Description
mention_count?	integer	The number of unread mentions left (default 0)
manual?	boolean	Whether to move the read marker back to this message (default false)

Setting manual to true marks the messages after message_id unread.

Response

Status	Body	Condition
204	empty	The message was acknowledged

The rate limit is 100 requests per 10 seconds, on the channel:message:ack::channel_id bucket.