Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Messages and Embeds

Discord Embeds

Learn to build Discord embeds - title, description, fields, author, footer, images, colors and timestamps - with the official length limits enforced by a runnable embed builder and a paginated help example.

A plain message is a line of text. An embed is a card: a colored side bar, a title, a description, a grid of fields, an author line, a thumbnail or image, a footer and a timestamp. Embeds are how Discord bots show structured information: a user profile, a server status, a search result, a moderation log entry. They are part of the message JSON, so you send them with the same POST /channels/{id}/messages call, in an embeds array.

Anatomy of an embed

JSON
{
  "embeds": [{
    "title": "Server status",
    "description": "All systems operational.",
    "url": "https://example.com/status",
    "color": 5763719,
    "timestamp": "2025-01-15T18:30:00.000Z",
    "author": { "name": "StatusBot", "icon_url": "https://example.com/icon.png" },
    "thumbnail": { "url": "https://example.com/thumb.png" },
    "fields": [
      { "name": "API", "value": "OK", "inline": true },
      { "name": "Database", "value": "OK", "inline": true },
      { "name": "Notes", "value": "No incidents today." }
    ],
    "footer": { "text": "Updated automatically" }
  }]
}

All fields are optional, but an embed must have at least something to show. Images must be HTTPS URLs (or attachment://file.png referring to a file uploaded in the same message, see Files and Uploads).

Colors are a single integer: the RGB value as a number, so #57F287 (a pleasant green) is 0x57F287, which is 5763719. Timestamps are ISO 8601 strings.

Limits you must respect

Discord rejects the whole message with a 400 if any limit is exceeded, so enforce them before sending.

Part Limit
Title 256 characters
Description 4096 characters
Fields 25 per embed
Field name 256 characters
Field value 1024 characters
Footer text 2048 characters
Author name 256 characters
Embeds per message 10
Total characters of all embeds in one message 6000 (title, description, field names and values, footer text, author name)

The 6000 total is the one people forget. You can get the 400 error with every individual part well within its limit. The best protection is a small builder that counts as you add.

Node.js An embed builder that enforces the limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The fourth case is the sneaky one: a description of 4,000 characters and three fields of about 1,000 each are all individually valid, yet together they pass 6,000. This builder is the same idea as discord.js EmbedBuilder, which also validates input and exposes the same method names (setTitle, addFields, setFooter).

Fields and layout

Fields are laid out in a grid. Fields with inline: true sit side by side, up to three per row; a field with inline: false takes the full width. A common trick is to use a zero-width space (โ€‹) as a field name or value to create blank columns or spacers. Keep field values short; a field is meant for a label and a value, not a paragraph. Put long text in the description.

You can also attach up to 10 embeds to a message, each with its own color. Use that for grouped results, for example one embed per search hit, rather than stuffing everything into a single card.

Embeds on other messages: webhooks and edits

Embeds can be sent by webhooks (a webhook URL needs no bot) and edited later with PATCH /channels/{id}/messages/{id}. To remove an embed, patch with embeds: []. Links in the message content also create embeds automatically (link previews); suppress them with the message flag SUPPRESS_EMBEDS (1 << 2, which is 4).

A paginated list

Embeds shine for lists that are too long for one card. The pattern is a pure function that turns a list into pages, so a button handler (next in Buttons and Inline Keyboards) can show page n.

Node.js Paginating items into embed pages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Clamping the page number (safe) means a stale button that asks for page 99 returns the last page instead of an error. Because the function is pure, it is trivial to test.

Embeds are not for everything

Embeds do not show on some surfaces (notification previews show only content), and screen readers handle them less well than plain text. Put the essential message in content and use the embed for detail. Embeds also cannot be used to send "hidden" text: moderators and users can both inspect embed content.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How is an embed color expressed in the API?

    The color field is a decimal integer, for example 0x57F287 equals 5763719.
  2. 2. What is the total character limit across all embeds in one message?

    Titles, descriptions, field names and values, footer text and author names together may not exceed 6000 characters.
  3. 3. How many inline fields fit on one row?

    Inline fields share a row, at most three of them; non-inline fields take the whole width.
  4. 4. A button asks for page 99 of a 3-page list. What should the pagination function do?

    Clamping handles stale or malicious page values gracefully.

Summary

  • An embed is a JSON card inside embeds; up to 10 per message, each with title, description, fields, author, footer, images, color and timestamp.
  • Key limits: title 256, description 4096, 25 fields (name 256, value 1024), footer 2048, author 256, and 6000 characters in total.
  • Use a builder that validates as you add; count the total, not just the parts.
  • Fields are for short label/value pairs; inline fields form up to three columns.
  • Keep essential information in content too, and paginate long lists with pure functions.

Next: Buttons and Inline Keyboards