@antisubmissivist/clawrich

Send real tables, interactive checklists, collapsible details, math, and custom emoji to Telegram 鈥?via the new Bot API 10.1 sendRichMessage method.

Pure Node.js SDK. Zero framework lock-in. Optional OpenClaw plugin integration.

Which install is right for me?

Three install paths for three audiences 鈥?pick the one that matches you:

馃挕 Same code, three doors. The npm tarball and the ClawHub plugin share the same src/ and lib/ 鈥?the npm one is the SDK, the ClawHub one wires it as an OpenClaw tool. You don't need both.

Why

Telegram Bot API 10.1 (2026-06-11) added sendRichMessage 鈥?a new endpoint that natively renders real <table>, <checklist>, <details>, <math>, and custom emoji in any chat. No more <pre> hacks for tables, no more "list a task list of strings" 鈥?actual interactive, native Telegram elements.

clawrich wraps this in a clean, framework-agnostic Node.js SDK:

• 鉁?Pure Node 鈥?works in any Node.js 鈮?18 project
• 鉁?Zero dependencies (only typebox for the OpenClaw plugin shim)
• 鉁?TypeScript-first 鈥?full type definitions included
• 鉁?Three usage styles 鈥?SDK function call, OpenClaw plugin tool, or CLI
• 鉁?No HTML escaping headaches 鈥?pass structured spec, get native output

Install (Node SDK)

npm install @antisubmissivist/clawrich

That's it. You now have a working sendRichMessage wrapper.

Quick start (Node SDK)

import { sendRichMessage } from 'clawrich';

const result = await sendRichMessage({
  token: process.env.TG_BOT_TOKEN,        // get from @BotFather
  chat_id: 123456789,                      // or @username
  rich_spec: {
    heading: 'Sprint Status',
    summary: 'Driver App shipped. Portal QA in progress.',
    table: {
      columns: ['Task', 'Owner', 'Status'],
      rows: [
        ['Driver App release', 'Alex', '鉁?Done'],
        ['Portal QA', 'Sam', '馃煛 In progress'],
        ['Route optimizer', 'Luke', '馃敶 Blocked']
      ]
    },
    list: [
      { text: 'Review PR', done: true },
      { text: 'Run staging smoke test', done: false },
      { text: 'Send release note', done: false }
    ],
    details: [
      {
        summary: '鈿狅笍 Risks',
        blocks: [
          'QA may slip if staging data is stale.',
          'Route optimizer dependency needs confirmation.'
        ]
      }
    ]
  }
});

console.log(result.message_id);

Or use raw HTML / Markdown

// Pass raw HTML
await sendRichMessage({
  token, chat_id,
  html: '<b>bold</b> <i>italic</i> <table>...</table>'
});

// Or raw Markdown
await sendRichMessage({
  token, chat_id,
  markdown: '**bold** _italic_ | A | B |\n|-|-|\n| 1 | 2 |'
});

Build the payload without sending

import { buildRichMessage } from 'clawrich';

const rich = buildRichMessage({
  heading: 'Title',
  table: { columns: ['A', 'B'], rows: [['1', '2']] }
});

console.log(rich.html);
// 鈫?'<h2>Title</h2>\n<table>...</table>'

CLI

# Dry-run (print payload, don't send)
node node_modules/clawrich/bin/send.js --chat_id 12345 \
  --json examples/sprint-status.json --dry-run

# Real send
node node_modules/clawrich/bin/send.js --chat_id 12345 \
  --json examples/sprint-status.json

Or install globally and use clawrich-send:

npm install -g clawrich
clawrich-send --chat_id 12345 --json sprint.json

OpenClaw plugin (optional)

If you use OpenClaw and want the same capability as a native tool, the package also exports an OpenClaw plugin:

# Install alongside OpenClaw
npm install clawrich
openclaw plugins validate clawrich   # should say "Plugin clawrich is valid"

Your agent will then be able to call the telegram_rich_send tool directly.

Note: The OpenClaw plugin shim uses typebox and openclaw/plugin-sdk as peer deps. If you don't use OpenClaw, you can ignore them 鈥?they're marked as peerDependenciesMeta.optional: true.

API reference

sendRichMessage(params)

Returns Promise<{ ok: true, message_id, date, chat, ... }>.

RichMessageSpec (structured form)

interface RichMessageSpec {
  heading?: string;
  heading_level?: 1 | 2 | 3 | 4 | 5 | 6;  // default 2
  summary?: string;
  table?: { columns: string[]; rows: string[][] };
  list?: { text: string; done?: boolean }[];
  checklist?: { text: string; done?: boolean }[];
  details?: { summary: string; blocks: string[] }[];
  paragraphs?: string[];
  quotes?: string[];
  divider?: boolean;
}

Supported rich elements

Reference: https://core.telegram.org/bots/api#rich-message-formatting-options

Environment

• Node.js 鈮?18 (uses native fetch)
• Telegram Bot API 鈮?10.1 (2026-06-11)
• No transpilation, no bundler needed

Testing

git clone https://github.com/Antisubmissivist/clawrich.git
cd clawrich
npm install
npm test

Tests use Node's built-in node:test runner 鈥?no test framework dependency.

License

MIT 漏 2026 Antisubmissivist 鈥?see LICENSE

Acknowledgments

• Built for the OpenClaw ecosystem
• Powered by Telegram Bot API 10.1
• Inspired by every bot developer who's ever wanted to send a real table