The Discord embed object, field by field

Embeds are the standard way bots present structured information, and most embed problems are layout problems rather than API problems.

The anatomy

Fields and the three-column grid

Fields with inline: true pack up to three across. Fewer than three in a row leaves the row ragged rather than stretching to fill, so a set of four inline fields renders three-then-one, not two-and-two.

This is the single most common source of “the layout looks wrong on my phone”: narrow viewports reduce the effective column count, and a design tuned to three columns collapses. Designs that survive both are usually two inline fields per conceptual row, or none at all.

The combined budget

Each property has its own ceiling, and there is also a combined limit across the whole embed. An embed whose title, description, field names, field values and footer are each individually legal can still be rejected because their total exceeds the overall budget. The error names the embed rather than the offending field, which makes it look like a structural problem when it is a length problem.

Anything generated from user input — a ticket transcript summary, a log entry with a message quote — needs truncation applied to the total, not per field, or it will work in testing and fail on the first long input.

Colour is an integer

color takes a decimal integer, so #5865F2 is sent as 5793266. Passing the string fails validation. Passing 0 is legal and renders as no accent bar rather than black, which is occasionally what you want and more often an accident from an uninitialised variable.

What embeds cannot do

There is no arbitrary image placement: exactly one image at the bottom and one thumbnail at the top right. There is no table, no column control beyond the inline grid, and no font control. Layouts that need more than this are usually better served by several embeds in one message, or by components alongside the embed.