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 and offset/length.

Base fields (all entities)

Field Type

type string

offset number

length number

version number

Example

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

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" fileId : string , 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 reference uploaded files. Use the file upload endpoint to get a fileId before sending.
The version field is for forward compatibility. Always send 1.