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

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

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). No internal file IDs are exposed.
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.