Embeds

Rich cards with a title, fields, images and a footer, and the link previews Bafflux adds by itself.

An embed is a card under a message: a colored bar on the left, then an optional author, title, description, fields, thumbnail, large image and footer. The shape is the same as Discord's embed object, so existing embed builders work.

Bots and webhooks can send up to 10 embeds with a message. People can't send them; their messages get link previews instead.

The embed object

json

{
	"title": "Server status",
	"url": "https://status.example.com",
	"description": "All systems are **running**. See the [status page](https://status.example.com).",
	"color": 3065014,
	"timestamp": "2026-10-14T15:04:05Z",
	"author": { "name": "Status bot", "url": "https://example.com", "icon_url": "https://example.com/bot.png" },
	"thumbnail": { "url": "https://example.com/logo.png" },
	"fields": [
		{ "name": "API", "value": "Online", "inline": true },
		{ "name": "Gateway", "value": "42 ms", "inline": true },
		{ "name": "Notes", "value": "Fields without inline take the whole row." }
	],
	"image": { "url": "https://example.com/chart.png" },
	"footer": { "text": "Checked every minute", "icon_url": "https://example.com/clock.png" }
}

Field	Notes
`title`	Up to 256 characters. A link when `url` is set
`description`	Up to 4096 characters, with formatting and `[masked links](https://...)`
`url`	Where the title links to
`color`	The bar's color as a number, `0` to `16777215` (`0x2EC4B6` = `3065014`)
`timestamp`	ISO 8601. Shown in the footer in the reader's time, like "Today at 3:04 PM"
`author`	`name` (up to 256, required), optional `url` and `icon_url`
`thumbnail`	`{ url }`, shown at the top right, up to 80 px
`image`	`{ url }`, the large image under the fields, up to 400 x 300 px
`fields`	Up to 25. `name` (up to 256) and `value` (up to 1024) are required. Inline fields sit 3 to a row (2 with a thumbnail)
`footer`	`text` (up to 2048, required), optional `icon_url`

camelCase names (iconUrl) work too. Every URL must start with http:// or https://.

Limits

Up to 10 embeds per message.
Titles, descriptions, field names and values, footer texts and author names together can be up to 6000 characters across all of a message's embeds.
An embed needs at least one of: title, description, fields, image, thumbnail, author or footer.
A message with embeds may have empty content.

Breaking a rule answers 400 with the code invalid_embed and a message that names the field, like embeds[0].fields[2].value can be up to 1024 characters. A person's account sending embeds gets 403 embeds_not_allowed.

Embeds never ping anyone: <@id> in an embed shows the name, but only mentions in content notify people.

After a message is sent, Bafflux reads the size of each embed image in the background and adds width and height to image and thumbnail, so apps can keep the space for them while they load. The message gets a MESSAGE_UPDATE when that happens.

Sending embeds

Add embeds wherever you send a message:

Where	How
Messages	`POST /api/channels/{channelId}/messages` with `"embeds": [...]` (also inside `payload_json` with files)
Editing	`PATCH /api/channels/{channelId}/messages/{messageId}` with `"embeds"` replaces them; `[]` removes them. Leave `content` out to keep the text
Interactions	`embeds` in a `message` callback or a follow-up, ephemeral ones included
Webhooks	`embeds` next to `content`

bash

curl https://bafflux.com/api/channels/$CHANNEL_ID/messages \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"embeds": [{"title": "Deploy finished", "description": "**v1.4.2** is live", "color": 3065014}]}'

Link previews

When anyone sends or edits a message with http:// or https:// links, Bafflux fetches up to 3 of them in the background and adds a preview to the message, then sends MESSAGE_UPDATE with the new embeds:

Type	When	Shows
`link`	A web page	The site name (`provider.name`), title, description and image from its Open Graph or Twitter card tags, `<title>` and `<meta name="description">`. The page's `theme-color` becomes the bar color. A large image when the page asks for one (`twitter:card` `summary_large_image`), otherwise a thumbnail
`image`	A direct link to an image	Just the image, with its `width` and `height`. A message that is only that link shows only the image
`video`	A YouTube video	The title, channel (`author`), thumbnail and a `video.url` player the app loads when you click play

Previews come after the message's own embeds in embeds, and their url is the link as written. Rules:

Wrap a link in angle brackets to skip its preview: <https://example.com>. The brackets aren't shown.
Links inside code, code blocks and ||spoilers|| aren't previewed. Neither are links to Bafflux itself (invites already get their own card).
Only public addresses are fetched, with a few seconds' timeout and only the first 512 KB of the page. Pages that don't answer just get no preview.
Previews are cached for 30 minutes, so the same link in many messages is fetched once.
Editing keeps the previews of links that are still in the text and fetches new ones.

Published copies of announcements keep the original's embeds, previews included.

#The embed object

#Limits

#Sending embeds

#Link previews

The embed object

Limits

Sending embeds

Link previews