telegram-html

Convert Telegram Bot API message entities into HTML, or hast, and vice versa.

Installation

# Bun
bun add telegram-html

# Deno
deno add npm:telegram-html

# pnpm
pnpm add telegram-html

# npm
npm install telegram-html

Usage

Convert Telegram Message to hast

function messageToHast(message: Message, options?: MessageToHastOptions): Root;

This function converts Telegram message into hast. It returns hast Root and accepts two arguments:

• message (required)

  The Telegram message to process.

• options (optional)

  Configuration for the conversion. It has three options:

  • withClass (optional, boolean, default: true)

    Adds a class attribute to the generated HTML tags.

    By default, classes are prefixed with tg- (e.g., tg-bold, tg-custom-emoji). If set to false, classes are removed. Some entities (like hashtags) will become plain text because they cannot be styled without classes.

  • classPrefix (optional, string, default: tg-)

    The prefix used for the HTML class names.

  • preserveEntityData (optional, boolean, default: false)

    Preserve original Telegram entity data in the HTML.

    Set this to true if you need to convert the HTML back to Telegram entities later.

    Note: This increases the HTML size.

Example:

messageToHast(
  {
    entities: [{ length: 9, offset: 8, type: "bold" }],
    text: "This is bold text",
  },
  { preserveEntityData: true },
);

Convert Telegram Message to HTML

function messageToHtml(message: Message, options?: MessageToHtmlOptions): string;

This function converts a Telegram message into a semantic HTML string. It returns HTML string and accepts two arguments:

• message (required)

  The Telegram message to process.

• options (optional)

  Same options as messageToHast.

Example:

messageToHtml(
  {
    entities: [{ length: 9, offset: 8, type: "bold" }],
    text: "This is bold text",
  },
  { preserveEntityData: true },
);

Convert hast to Telegram Message

function hastToMessage(hast: Root, options?: HastToMessageOptions): Message;

Converts hast into a Telegram message. It returns Telegram message and accepts two arguments:

• hast (required)

  The hast to process.

• options (optional)

  Configuration for the conversion. It has two options:

  • classPrefix (optional, string, default: tg-)

    The prefix used to identify Telegram entities.

    By default, elements with a class name starting with tg- are identified as [Telegram entities]0tg-entities. For example, an element with the class tg-custom-emoji will be converted into a custom_emoji entity type.

    Change this option if you are using a different prefix, such as telegram-.

• skipAutoEntities (optional, boolean, default to true)

  Skip entities that the Telegram server detects automatically.

  When true (the default), entities like hashtags, URLs, emails, etc. are skipped. Telegram parses these on its own, so sending them is not needed and only adds extra size.

  Set to false to include all entities.

Example:

hastToMessage(
  {
    type: "root",
    children: [
      { type: "text", value: "This is " },
      {
        type: "element",
        tagName: "b",
        properties: { className: ["telegram-bold"] },
        children: [{ type: "text", value: "bold text" }],
      },
    ],
  },
  { classPrefix: "telegram-", skipAutoEntities: false },
);

Convert HTML to Telegram Message

function htmlToMessage(html: string, options?: HtmlToMessageOptions): Message;

This function converts HTML into Telegram message. It returns Telegram message and provides two parameters:

• html (required)

  The HTML string to process.

• options (optional)

  The configuration option. It has the exact same options as hastToMessage.

Example:

htmlToMessage("This is <b>bold text</b>", { skipAutoEntities: false });

FAQ

How to convert a Telegram Message into Markdown and vice versa?

telegram-html does not provide a way to convert Telegram Message into Markdown. However, since HTML is widely supported, you can use messageToHtml to convert the Telegram Message into HTML first, then convert HTML to Markdown using third-party package and vice versa.

How to modify the output?

telegram-html provides conversion to hast. That way, it brings you the flexibility to modify them.

After you are done, you can convert them into HTML using toHtml or into a Telegram message using hastToMessage.

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

License

MIT