telegram-html

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

Installation

telegram-html is available on both npm.com and JSR.io.

Using npm

# npm
npm install telegram-html

# pnpm
pnpm add telegram-html

# Bun
bun add telegram-html

# Deno
deno add npm:telegram-html

Using JSR

# npm - JSR
npx jsr add @qz/telegram-html

# pnpm - JSR
pnpm i jsr:@qz/telegram-html

# Bun - JSR
bunx jsr add @qz/telegram-html

# Deno - JSR
deno add jsr:@qz/telegram-html

Usage

Convert Telegram Message to HTML

Example

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

Output

This is <b class="tg-bold">bold text</b>

API

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.

Convert Telegram Message to hast

Example

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

Output

Note: Some irrelevant properties like position and data have been omitted to keep it short.

{
  "type": "root",
  "children": [
    {
      "type": "text",
      "value": "This is "
    },
    {
      "type": "element",
      "tagName": "b",
      "properties": {
        "className": ["tg-bold"]
      },
      "children": [
        {
          "type": "text",
          "value": "bold text"
        }
      ]
    }
  ]
}

API

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 entity later.

    Note: This increases the HTML size.

Convert HTML to Telegram Message

Example

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

Output

{
  "text": "This is bold text",
  "entities": [{ "type": "bold", "offset": 8, "length": 9 }]
}

API

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.

Convert hast to Telegram Message

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 },
);

Output

{
  "text": "This is bold text",
  "entities": [{ "type": "bold", "offset": 8, "length": 9 }]
}

API

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 entity.

    By default, elements with a class name starting with tg- are identified as Telegram entity. 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.

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 the hast into HTML using toHtml, or into a Telegram message using hastToMessage.

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

License

MIT