@nitra/telegram

Мінімальний хелпер для надсилання повідомлень і документів у Telegram.

Встановлення

bun add @nitra/telegram

Налаштування

Потрібні змінні середовища (перевіряються при імпорті через @nitra/check-env):

| Змінна | Опис | | -------------------- | ----------------------------------------------------------------------- | | TELEGRAM_BOT_TOKEN | токен бота (обов'язково) | | TELEGRAM_CHAT_ID | id чату/каналу (опційно; можна передати через params.chat_id) | | TELEGRAM_THREAD_ID | id топіка в супергрупі (опційно; можна передати через params.message_thread_id) |

Формат за замовчуванням

Дефолтний parse_mode — MarkdownV2. Telegram вимагає екранувати спецсимволи _ * [ ] ( ) ~ \ > # + - = | { } . !— для динамічного контенту (тексти помилок, змінні) використовуйтеescapeMarkdownV2()`:

import { sendMessage, escapeMarkdownV2 } from '@nitra/telegram'

await sendMessage(`*Помилка:* ${escapeMarkdownV2(err.message)}`)

Якщо розмітка все одно невалідна, повідомлення не губиться — бібліотека один раз повторює запит без розмітки (plain text).

API

sendMessage(text, params?)

// MarkdownV2 (дефолт)
await sendMessage('*жирний* текст')

// HTML
await sendMessage('<b>жирний</b>', { parse_mode: 'HTML' })

// без розмітки (plain text)
await sendMessage('будь-який текст', { parse_mode: '' })

// без звуку
await sendMessage('тихо', { disable_notification: true })

// у топік супергрупи
await sendMessage('повідомлення в топік', { message_thread_id: 123 })

params:

| Поле | Тип | За замовчуванням | Опис | | ---------------------- | -------------------------------- | -------------------- | --------------------------------------- | | chat_id | string \| number | TELEGRAM_CHAT_ID | id чату; override для env змінної | | parse_mode | 'MarkdownV2' \| 'HTML' \| '' | 'MarkdownV2' | формат розмітки; ''/null — вимкнути | | message_thread_id | number | TELEGRAM_THREAD_ID | id топіка; override для env змінної | | disable_notification | boolean | — | надіслати без звуку |

У робочі години (08:00–18:00) сповіщення зі звуком; поза ними — автоматично тихо. Повідомлення довші за 4096 символів обрізаються.

sendDocument(document, params?)

await sendDocument(Buffer.from(csv), {
  filename: 'report.csv',
  contentType: 'text/csv',
  caption: `*Звіт:* ${escapeMarkdownV2('users_2026.csv')}`
})

// у топік супергрупи
await sendDocument(Buffer.from(csv), {
  filename: 'report.csv',
  contentType: 'text/csv',
  message_thread_id: 123
})

params: chat_id, filename, contentType, caption, parse_mode (дефолт MarkdownV2, лише для caption), message_thread_id, disable_notification. Як і в sendMessage, невалідна розмітка caption не блокує відправку — повтор без розмітки.

escapeMarkdownV2(text)

Екранує всі зарезервовані символи MarkdownV2. Застосовуйте до динамічних частин (не до всього повідомлення — інакше зникне навмисна розмітка).

escapeMarkdownV2('a_b.c!') // → 'a\\_b\\.c\\!'

DEFAULT_PARSE_MODE

Константа з дефолтним форматом ('MarkdownV2').