Skip to content

Message Entities

Rich text formatting, mentions, links, attachments, and system events — all expressed as entity spans within message text.

How Entities Work #

Every message has a plain text field plus an optional entities array. Each entity marks a span of the text with a type discriminator and offset/length. Extra fields are present only when relevant for the entity type — all other fields are null.

Base fields (all entities)

Field Type
type string
offset number
length number

Example — bold + mention

// "Hello **world**!" with bold on "world"
{
  "text": "Hello world!",
  "entities": [
    {
      "type": "bold",
      "offset": 6,
      "length": 5
    }
  ]
}

// Mention entity — only userId is populated
{
  "type": "mention",
  "offset": 0,
  "length": 6,
  "userId": "d3b07384-..."
}

Formatting #

Entity Type Extra Fields
"bold" —
"italic" —
"underline" colour : number?
"strikethrough" —
"spoiler" —
"monospace" —
"capitalized" —
"fraction" numerator : number? , denominator : number?
"ordinal" —

Mentions #

Entity Type Extra Fields
"mention" userId : string?
"mentionEveryone" —
"mentionRole" archetypeId : string?

Links #

Entity Type Extra Fields
"url" domain : string , path : string
"email" email : string
"hashTag" hashtag : string

Content #

Entity Type Extra Fields
"quote" quotedUserId : string?
"attachment" fileName : string , fileSize : number , contentType : string , width? : number , height? : number , thumbHash? : string , url? : string

System #

Entity Type Extra Fields
"systemCallStarted" callerId : string? , callId : string?
"systemCallEnded" callerId : string? , callId : string? , durationSeconds : number?
"systemCallTimeout" callerId : string? , callId : string?
"systemUserJoined" userId : string? , inviterId? : string

Stickers & Custom Emoji #

Messages from people can carry two more entity types, which V1 of the Bot API does not expose:

Entity Type What it marks
"sticker" A message that is one sticker: empty text and this entity alone.
"customEmoji" Exactly one :name: in the text, drawn as the space's custom emoji of that name.

Bots cannot send them today. A request whose entities holds either type is refused with 400.

Nor do bots receive them. In messageCreate, messageEdit and message history these entities are left out: a custom emoji stays in the text as its :name:, and a sticker message arrives with empty text and no entities.

Bots can read and add to a space's packs through IExpressions — see Stickers & Custom Emoji.

Notes

  • Entities can overlap — for example, bold and italic on the same span.
  • System entities (systemCall*, systemUserJoined) are created by the server. Bots cannot send system entities.
  • Attachment entities contain file metadata (fileName, fileSize, contentType) and the download url. The message's attachments list describes the same files with their fileId; bots send files through it, not as entities — see Files & Attachments.
  • Entity objects are flattened — all possible extra fields exist on the same type, but only the fields relevant to the entity's type are non-null.