grammY authentication and store bot
This service replaces the former JSON/Python bot with one grammY process and a
transactional SQLite database. It deliberately runs independently from
cmd/telesrv; a bot outage cannot stop MTProto.
Included functionality
- automatic persistent number and initial code on
/start; - delivery and storage of real login codes through authenticated
POST /code; - free replacement numbers and paid anonymous
+888numbers; - Premium, server Stars and collectible username purchases through Telegram Stars;
- arbitrary Stars invoices, payment deduplication and a durable sales journal;
- compensated refunds that revoke the exact Stars, Premium entitlement, collectible username or paid number before returning Telegram Stars;
- account target IDs and three recent recipients;
- daily bonuses, referrals and a weighted wheel;
- promo codes and button-based giveaways;
- support tickets;
- complete Russian and English localization for menus, keyboards, invoices, errors, login codes and Bot API command descriptions;
- per-user language and notification settings; broadcasts skip disabled and stale recipients;
- owner-only statistics, broadcasts, Stars/Premium/bonus grants, invoices, payment refunds, login-code access, support replies, sales and Stars-rate controls;
- optional required-channel membership gate.
The bot token and Admin API token must never be committed. .env.example
contains names and safe local defaults only.
Local run
Requirements: Node.js 22.13 or newer and a running gramsrv Admin API.
cd cmd/bots/grammystore
cp .env.example .env
nano .env
npm ci
npm test
npm start
Set BOT_PUBLIC_USERNAME so referral links are available before the first
getMe. OWNER_IDS accepts comma-separated Telegram IDs. Users set their
gramsrv account ID under Settings; Telegram IDs are not assumed to equal server
account IDs.
PRODUCT_NAME controls user-facing product text and defaults to Telesrv.
Deployment-specific branding belongs in the service environment, not in source.
DEFAULT_LANGUAGE is used until Telegram supplies or the user selects a
supported language. The selection is stored in SQLite and is not overwritten by
later updates from Telegram. Bot command descriptions are registered separately
for ru and en client locales.
Each paid fulfillment is snapshotted in the sales journal. Refunds are phased and idempotent: if Telegram is temporarily unavailable after the server-side product has been revoked, retrying the same transaction does not revoke it twice. Legacy Premium and anonymous-number purchases without exact fulfillment metadata fail safe and require manual review instead of touching unrelated account state.
Migrating the former Python bot
Never open the legacy database directly with the new service because its table names overlap but its columns are incompatible. Keep the old service stopped, copy its database, and create a separate destination:
npm run migrate:legacy -- /path/to/legacy.sqlite3 /path/to/new.sqlite3
The command refuses to overwrite its source or an existing destination. It preserves users, bonus balances, referrals, numbers, current login codes and support messages. Keep the legacy database backup for historical orders and broadcast drafts, which have no equivalent in the new Telegram Stars journal.
Login-code webhook
Configure gramsrv's code-delivery webhook for:
TELESRV_PHONE_CODE_DELIVERY_PROVIDER=webhook
TELESRV_OTP_WEBHOOK_URL=http://127.0.0.1:2800/v1/otp/deliveries
TELESRV_OTP_WEBHOOK_SECRET=<same value as CODE_WEBHOOK_SECRET>
gramsrv sends its version-1 JSON envelope and signs the exact request body as
X-Telesrv-Signature: sha256=<HMAC-SHA256(timestamp + "." + body)>. The bot
checks that signature, a five-minute timestamp window and Idempotency-Key.
For example, the body contains:
{"version":"1","delivery_id":"...","purpose":"login_sms","channel":"sms","recipient":"+79991234567","code":"12345","expires_at":"2026-08-09T12:00:00Z","expires_in":300}
The endpoint is loopback-only by default. It rejects requests without the
HMAC secret, stores each delivery idempotently and returns HTTP 202 immediately;
Telegram delivery then runs asynchronously for the number owner and explicitly
granted support viewers. A slow Bot API therefore cannot turn auth.sendCode
into a server-side timeout. /healthz is read-only.
Linux install
sudo useradd --system --home /var/lib/gramsrv-grammy-bot --shell /usr/sbin/nologin telesrv-bot || true
sudo install -d -o telesrv-bot -g telesrv-bot -m 0750 /opt/gramsrv-grammy-bot /var/lib/gramsrv-grammy-bot
sudo cp -a package.json package-lock.json src /opt/gramsrv-grammy-bot/
cd /opt/gramsrv-grammy-bot
sudo npm ci --omit=dev
sudo cp .env.example /etc/telesrv-grammy-bot.env
sudo chmod 0600 /etc/telesrv-grammy-bot.env
sudo cp deploy/telesrv-grammy-bot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now telesrv-grammy-bot
sudo journalctl -u telesrv-grammy-bot -f
Use BOT_DB_PATH=/var/lib/gramsrv-grammy-bot/bot.sqlite3 in the production env.
Back up the database with SQLite's online backup command or while the service is
stopped; include /etc/telesrv-grammy-bot.env in a separate encrypted secret
backup.
The systemd unit intentionally has no hosting-specific values. Do not deploy it until the local branch has been reviewed and merged.