Последняя версияLatest: 0.6.06.170103

Стабильная версияStable: -

Установка

Install

Последняя:

Latest:

curl -fsSL https://packages.novij.tech/services/telegram/install.sh | sudo bash -s -- telegram.example.com --enable-tls

Стабильная:

Stable:

curl -fsSL https://packages.novij.tech/services/telegram/install.sh | sudo env NOVIJ_PACKAGE_CHANNEL=stable bash -s -- telegram.example.com --enable-tls

Релизы

Releases

latest

stable

Релизов пока нет.
No releases yet.

Команды

Commands

novij-telegram setup <domain> --enable-tls [--wallet-id id]: Настраивает PostgreSQL, Redis, web proxy, systemd и service wallet.Configures PostgreSQL, Redis, web proxy, systemd, and the service wallet.
novij-telegram config-check: Проверяет конфигурацию и обязательные переменные окружения.Validates configuration and required environment variables.
novij-telegram queue-status: Показывает состояние очередей отправки.Shows send queue status.
novij-telegram prices: Показывает текущие цены, лимиты и шаблоны сообщений.Shows current prices, limits, and message templates.
novij-telegram wallet: Показывает wallet id сервиса.Shows the service wallet id.
novij-telegram relay-check: Проверяет доступность Relay API.Checks Relay API availability.
novij-telegram bot-test <bot_id>: Проверяет Telegram bot token без отправки сообщения пользователю.Checks a Telegram bot token without sending a user message.
novij-telegram webhook-sync [bot_id|common] [--drop-pending]: Синхронизирует Telegram webhook для общего или проектного бота.Synchronizes the Telegram webhook for the common or project bot.
novij-telegram service-registry:status: Показывает состояние Service Registry и локальной регистрации.Shows Service Registry and local registration status.
novij-telegram service-registry:register|update|verify: Регистрирует, обновляет и проверяет запись сервиса в Service Registry.Registers, updates, and verifies the service entry in Service Registry.
novij-telegram cleanup: Запускает очистку просроченных payload, connect codes и audit данных.Cleans expired payloads, connect codes, and audit data.
novij-telegram update --check [--channel stable]: Проверяет свежий пакет на package-сервере.Checks the package site for a newer package.
sudo novij-telegram update [--force] [--dry-run] [--channel stable]: Скачивает, проверяет SHA256 и устанавливает свежий .deb.Downloads, verifies SHA256, and installs a newer .deb.
novij-telegram version: Показывает версию и build metadata.Shows version and build metadata.

Частые сценарии

Common Scenarios

1. Что закрывает сервис1. What the service covers

Novij Telegram Service ставится как отдельный backend с API, worker и scheduler. Он принимает заявки от проектов, хранит временный payload в зашифрованном виде, отправляет сообщения через Telegram Bot API и связывает отправку с wallet/Relay flow Novij Protocol.

Novij Telegram Service runs as a standalone backend with API, worker, and scheduler processes. It accepts project requests, stores temporary payloads encrypted, sends messages through Telegram Bot API, and ties delivery to the Novij Protocol wallet/Relay flow.

`send`	шаблонные сообщения: `text_message`, `nrsv_reminder`, `server_alert_basic`, `test_message`.template messages: `text_message`, `nrsv_reminder`, `server_alert_basic`, `test_message`.
`reminders`	отложенные nRSV-напоминания, которые scheduler переносит в очередь отправки в нужный момент.scheduled nRSV reminders that the scheduler moves into the send queue when due.
`alerts`	live alert-карточки для мониторинга: create/upsert/update, кнопки действий и отдельные details-сообщения.live alert cards for monitoring: create/upsert/update, action buttons, and separate details messages.
`commands`	интерактивные Telegram-команды: manifest интеграции, polling executor, ack и reply обратно в исходный chat.interactive Telegram commands: integration manifest, polling executor, ack, and reply back to the source chat.
`connect`	одноразовые deep-link коды, webhook бота и привязка зашифрованного `chat_id` к публичной ссылке пользователя.one-time deep-link codes, bot webhook, and encrypted `chat_id` binding to the user's public reference.
`registry`	well-known endpoints для Service Registry и CLI-команды регистрации/проверки сервиса.well-known endpoints for Service Registry plus CLI commands for service registration and verification.

2. Установка сервиса на домен2. Install service for a domain

Инсталлятор поднимает PostgreSQL, Redis, systemd-процессы API/worker/scheduler, web proxy и service wallet. После установки проверьте конфиг и public health endpoint.

The installer sets up PostgreSQL, Redis, API/worker/scheduler systemd processes, web proxy, and service wallet. After install, validate config and the public health endpoint.

curl -fsSL https://packages.novij.tech/services/telegram/install.sh | sudo bash -s -- telegram.example.com --enable-tls
sudo novij-telegram config-check
curl -fsS https://telegram.example.com/api/v1/health

3. Только установка пакета3. Package-only install

Используйте этот режим, если proxy/TLS/домен настраиваются отдельно.

Use this mode when proxy, TLS, and domain setup are managed separately.

curl -fsSL https://packages.novij.tech/services/telegram/install.sh | sudo bash -s -- --package-only
sudo novij-telegram setup telegram.example.com --enable-tls

4. Проверка конфигурации и API4. Configuration and API checks

Быстрая smoke-проверка показывает состояние env, systemd, публичных endpoint и OpenAPI-схемы.

A quick smoke check verifies env, systemd, public endpoints, and the OpenAPI schema.

sudo novij-telegram config-check
systemctl status novij-telegram-api.service
systemctl status novij-telegram-worker.service
systemctl status novij-telegram-scheduler.service
curl -fsS https://telegram.example.com/api/v1/version
curl -fsS https://telegram.example.com/api/v1/settings
curl -fsS https://telegram.example.com/openapi.json

5. Интеграция проекта и Telegram Connect5. Project integration and Telegram Connect

Проект регистрирует интеграцию, создаёт одноразовый connect code и отдаёт пользователю Telegram deep-link. Webhook привяжет chat к recipient_ref, а /stop отключит получателя.

A project registers an integration, creates a one-time connect code, and gives the user a Telegram deep link. The webhook binds the chat to recipient_ref, while /stop disables the recipient.

curl -fsS -X POST https://telegram.example.com/api/v1/integrations \
  -H 'content-type: application/json' \
  -d '{"project_id":"project_123","owner_wallet_id":"OWNER_WALLET_ID","bot_mode":"custom","custom_bot_token":"BOT_TOKEN","payment_mode":"dsr","default_reminder_minutes":30}'

curl -fsS -X POST https://telegram.example.com/api/v1/telegram/connect-codes \
  -H 'content-type: application/json' \
  -d '{"project_id":"project_123","integration_id":"int_telegram_123","public_user_ref":"user:42"}'

6. DSR-отправка и nRSV-напоминание6. DSR send and nRSV reminder

Для платных шаблонов клиент передаёт подтверждённую Relay-транзакцию в service wallet. Сервис проверяет receiver, sender, memo/payment_code, сумму и idempotency key, затем ставит отправку в очередь.

For paid templates, the client passes a confirmed Relay transaction to the service wallet. The service verifies receiver, sender, memo/payment_code, amount, and idempotency key, then queues delivery.

curl -fsS -X POST https://telegram.example.com/api/v1/send \
  -H 'content-type: application/json' \
  -d '{"project_id":"project_123","integration_id":"int_telegram_123","recipient_ref":"user:42","template":"text_message","template_vars":{"text":"Hello from Novij"},"payment_mode":"dsr","tx_hash":"TX_HASH","payer_wallet_id":"PAYER_WALLET_ID","payment_code":"PAYMENT_CODE","idempotency_key":"project_123:user_42:hello_001"}'

curl -fsS -X POST https://telegram.example.com/api/v1/reminders \
  -H 'content-type: application/json' \
  -d '{"project_id":"project_123","integration_id":"int_telegram_123","recipient_ref":"user:42","template":"nrsv_reminder","template_vars":{"minutes_before":30,"service_title":"Visit","starts_at_local":"2026-06-01 12:30"},"send_at":"2026-06-01T09:00:00.000Z","payment_mode":"dsr","tx_hash":"TX_HASH","payer_wallet_id":"PAYER_WALLET_ID","payment_code":"PAYMENT_CODE","idempotency_key":"project_123:user_42:reminder_001"}'

7. Live alerts для мониторинга7. Live alerts for monitoring

Monitoring Agent может создавать или обновлять одну Telegram-карточку по внешнему incident id, добавлять кнопки действий и забирать пользовательские действия через poll/ack endpoint.

Monitoring Agent can create or update one Telegram card by external incident id, attach action buttons, and collect user actions through poll/ack endpoints.

POST /api/v1/alerts/upsert
PATCH /api/v1/alerts/send_01hxyz
POST /api/v1/alerts/send_01hxyz/reply
GET /api/v1/alerts/actions/poll?project_id=project_123&integration_id=int_telegram_123
POST /api/v1/alerts/actions/ack

8. Интерактивные команды из Telegram8. Interactive commands from Telegram

Интеграция публикует manifest команд, а исполнитель забирает pending requests через polling и отправляет результат обратно в исходный chat.

An integration publishes a command manifest, while an executor polls pending requests and replies back into the source chat.

POST /api/v1/integrations/int_telegram_123/commands/manifest
GET /api/v1/commands/poll?project_id=project_123&integration_id=int_telegram_123&executor_key=monitoring-agent
POST /api/v1/commands/ack
POST /api/v1/commands/cmd_01hxyz/reply

9. Telegram bot и webhook9. Telegram bot and webhook

Проверяйте токен без отправки сообщений пользователю, затем синхронизируйте webhook на публичный HTTPS URL сервиса.

Validate the token without sending a user message, then synchronize the webhook to the public HTTPS URL of the service.

novij-telegram bot-test <bot_id>
sudo novij-telegram webhook-sync common --drop-pending
novij-telegram prices

10. Wallet, Relay и Service Registry10. Wallet, Relay, and Service Registry

Сервис должен знать свой wallet id, видеть Relay API и поддерживать registry-запись с публичными well-known endpoint.

The service must know its wallet id, reach Relay API, and maintain a registry entry with public well-known endpoints.

novij-telegram wallet
novij-telegram relay-check
novij-telegram service-registry:status
sudo novij-telegram service-registry:update
novij-telegram service-registry:verify
curl -fsS https://telegram.example.com/.well-known/novij/service-health

11. Очереди, логи и обслуживание11. Queues, logs, and maintenance

Worker обрабатывает очередь telegram-send, scheduler переносит due-reminders, cleanup удаляет просроченные payload, connect codes и audit-данные.

The worker processes the telegram-send queue, scheduler moves due reminders, and cleanup removes expired payloads, connect codes, and audit data.

novij-telegram queue-status
novij-telegram cleanup
journalctl -u novij-telegram-worker.service -n 100 --no-pager
journalctl -u novij-telegram-scheduler.service -n 100 --no-pager

12. Безопасность и приватность сообщений12. Message security and privacy

`secrets`	Bot token, `chat_id` и временный payload хранятся как AES-256-GCM ciphertext.Bot token, `chat_id`, and temporary payload are stored as AES-256-GCM ciphertext.
`logs`	Текст сообщений, template vars, email, phone, name, bot token и исходный `chat_id` не пишутся в логи/audit.Message text, template vars, email, phone, name, bot token, and raw `chat_id` are not written to logs/audit.
`auth`	Admin/API действия могут требовать wallet signature через `REQUIRE_SIGNATURES=true` и/или внутренний API key.Admin/API actions can require a wallet signature through `REQUIRE_SIGNATURES=true` and/or an internal API key.
`webhook`	Telegram webhook проверяет secret token из заголовка или query-параметра.Telegram webhook validates the secret token from a header or query parameter.

13. Обновление сервиса13. Service updates

novij-telegram update --check
sudo novij-telegram update
sudo novij-telegram update --channel stable