Render API reference

Render an arbitrary RichText node sequence to `{ text, entities }`. Internal: shared by {@link toEntities} and the RichBlock lowering in `./richmessage`.

entitiesForNodes(nodes: readonly RichTextNode[]): EntitiesPayload

The DEFAULT renderer. Lowers a validated `MessageText`/`CaptionText` to the Bot API `{ text, entities }` payload with UTF-16 code-unit offsets.

toEntities(message: MessageText | CaptionText): EntitiesPayload

Render a validated message/caption to Telegram's supported HTML subset.

toHtml(message: MessageText | CaptionText): string

RENDER FALLBACK ONLY — see the file header. Render a validated message/caption to Telegram MarkdownV2 wire text with all reserved characters escaped.

toMarkdownV2(message: MessageText | CaptionText): string

Capability-flagged partial renderer for the Bot API 10.1 block subset. The `capability` token is a REQUIRED parameter — omitting it is a type error.

toRichMessage(nodes: readonly RichBlockNode[], capability: RichMessageCapability): RenderRichMessageResult

Presence of a `pre` block's language tag, as a DU (no `.optional()`).

type EntityLanguage = | { readonly kind: "known"; readonly value: string }
  | { readonly kind: "unknown" }

The Bot API `MessageEntity` union, as produced by {@link toEntities}.

type MessageEntity = SimpleEntity | PreEntity | TextLinkEntity | TextMentionEntity

Entity types that carry no extra fields beyond `offset`/`length`.

type SimpleEntityType = | "bold"
  | "italic"
  | "underline"
  | "strikethrough"
  | "code"
  | "blockquote"
  | "expandable_blockquote"
  | "spoiler"
  | "mention"

type LoweredBlock = LoweredHeading | LoweredMath | LoweredTable | LoweredCollapsible

type RenderRichMessageResult = | { readonly kind: "ok"; readonly value: RichMessagePayload }
  | { readonly kind: "unsupported-node"; readonly nodeKind: string }

The default render payload: the plain text plus its formatting entities.

interface EntitiesPayload

text: string

entities: readonly MessageEntity[]

A `pre` (code block) entity, optionally carrying a language tag.

interface PreEntity

type: "pre"

offset: number

length: number

language: EntityLanguage

A formatting entity with no type-specific payload.

interface SimpleEntity

type: SimpleEntityType

offset: number

length: number

A `text_link` entity — inline text linking to `url`.

interface TextLinkEntity

type: "text_link"

offset: number

length: number

url: string

A `text_mention` entity — a mention of a user by numeric id.

interface TextMentionEntity

type: "text_mention"

offset: number

length: number

user: { readonly id: number; }

interface LoweredCollapsible

kind: "collapsible"

summary: EntitiesPayload

blocks: readonly LoweredBlock[]

interface LoweredHeading

kind: "heading"

level: 1 | 2 | 3 | 4

content: EntitiesPayload

interface LoweredMath

kind: "math"

latex: string

interface LoweredTable

kind: "table"

header: readonly EntitiesPayload[]

rows: readonly (readonly EntitiesPayload[])[]

The capability token gating access to the 10.1 rich-message surface.

interface RichMessageCapability

kind: "rich-message-10-1"

The successfully-lowered 10.1 rich message.

interface RichMessagePayload

blocks: readonly LoweredBlock[]

const EntitiesPayloadSchema: z.ZodType<EntitiesPayload, z.ZodTypeDef, EntitiesPayload>

const MessageEntitySchema: z.ZodType<MessageEntity, z.ZodTypeDef, MessageEntity>