telegram-send-message-cli

Typed Node.js utility that exposes a sendMessage command-line tool and programmatic helper for sending Telegram notifications from scripts, CI jobs, or local workflows.

Installation

npm install -g telegram-send-message-cli

You can also add it to a project:

npm install --save-dev telegram-send-message-cli

The package ships pre-built JavaScript and TypeScript declaration files for Node.js 18 and newer.

Configuration

The CLI needs a Telegram bot token and target chat identifier. Provide them through environment variables or CLI flags.

export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="123456789"

These variables are read by default. They can also be passed explicitly:

sendMessage "Task done" --token "$TELEGRAM_BOT_TOKEN" --chat-id "$TELEGRAM_CHAT_ID"

Optional flags:

• --parse-mode <MODE> – pass MarkdownV2, HTML, etc.
• --disable-notification – send a silent notification.
• --credentials-url <URL> – download TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID from a remote shell file.
• -v|--version – show package version.
• -h|--help – show usage information.

Usage

Send a message directly:

sendMessage "Build completed"

Pipe from another command:

cat build.log | sendMessage --parse-mode MarkdownV2

Loading credentials from a Gist

If you store your Telegram credentials in a private GitHub Gist (or any HTTPS-accessible shell snippet), point the CLI to it:

export TELEGRAM_CREDENTIALS_URL="https://gist.githubusercontent.com/.../telegram_credentials.sh"
sendMessage "Deploy finished"

The file should contain assignments such as:

TELEGRAM_BOT_TOKEN=123:abc
TELEGRAM_CHAT_ID=456

You can also pass the URL explicitly with --credentials-url.

Programmatic API

The module exports an async sendMessage helper. Example:

import { sendMessage } from 'telegram-send-message-cli';

await sendMessage({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  chatId: process.env.TELEGRAM_CHAT_ID!,
  text: 'Task finished ✅',
  parseMode: 'MarkdownV2',
});

The helper throws SendMessageError when the request fails or Telegram returns ok: false.

Development

Clone the repository and install dependencies:

npm install

Available scripts:

• npm run lint – TypeScript type-checking
• npm test – runs Vitest unit tests
• npm run build – emits compiled files to dist/

Publishing is automated through the Publish Package GitHub workflow. Pushing to main with a new version in package.json will run lint, tests, build, and publish to npm when the version is not already released.

The workflow sends a Telegram notification on completion, sourcing credentials via the same TELEGRAM_CREDENTIALS_URL mechanism. Update the gist referenced in .github/workflows/publish.yml to rotate secrets without modifying the repository.

Troubleshooting

• Ensure the bot token has access to the specified chat. For private chats you might need to initiate a conversation with the bot first.
• Telegram limits the rate of messages; watch for retry_after hints in error responses printed by the CLI.
• Add TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID to your shell startup files so they are available in every session.

License

MIT