The Telegram platform side-service, split into two binaries that share the bot token, so Telegram egress lives off the main host while game login does not depend on it. See docs/ARCHITECTURE.md §1/§3/§10/§12/§13.

cmd/validator (home) — verifies Mini App initData and Login Widget data by HMAC (the bot token is the secret) and never calls the Bot API. It serves the validation gRPC API the gateway calls during Telegram auth, on the trusted internal network with no VPN. Because it needs no Telegram reachability, game login stays up even when the bot or the bot-link is down.
cmd/bot (remote) — runs the Bot API long-poll (Mini App launch, /start deep-links, the /support info reply) and sendMessage, the only component reaching the Telegram Bot API. It holds no inbound port: it dials the gateway over a reverse mTLS bot-link and executes the send commands the gateway pushes, so its egress can run on a host with native Telegram access (a VPN sidecar in the test contour, a separate host in prod).

Both hold the same token. One bot owns the exclusive getUpdates long-poll (TELEGRAM_OWNS_UPDATES, exactly one per token, else Telegram returns 409); the design leaves seams (a gateway bot registry, the owns_updates flag, per-command ids) for running several bots later, not built yet.

Validator

ValidateInitData validates initData against the token and returns only the Telegram user identity (no per-bot service language, no supported-languages set); ValidateLoginWidget verifies Telegram Login Widget web sign-in data — HMAC under SHA-256(bot_token), distinct from initData (internal/loginwidget) — for attaching a Telegram identity to an account from a browser. Both map a rejection to gRPC InvalidArgument.

Bot

Send commands. The gateway pushes Notify (out-of-app push: your_turn, game_over, nudge, match_found, and the invitation / friend_request notify sub-kinds), SendToUser and SendToGameChannel (operator broadcasts) down the bot-link. The bot renders the message in the command's language (the recipient's interface language; operator-chosen for broadcasts) with a Mini App launch button and sends it. It replies with an Ack per command (delivered mirrors the former connector semantics — false when the kind is not rendered out-of-app or the user never started the bot).
Bot chat. /start <payload> (and the chat menu button) reply with a localized welcome and a Mini App launch button; a deep-link payload routes the launch to a game / invitation / friend code. The welcome is Russian or English by the sender's reported Telegram language (Message.from.language_code, which the Bot API carries on the message itself — no separate user-update event — English fallback) and links the game channel and discussion chat by their public @username, resolved once at startup from TELEGRAM_GAME_CHANNEL_ID / TELEGRAM_CHAT_ID via getChat (a chat that is unset, private, or unreadable degrades that link to a generic noun — "the channel" / "our chat" — rather than a dangling "@"). This is otherwise self-contained — the bot never calls back into the game, so /start onboarding works even when the game is down.
Support command. /support replies with a fixed support-desk info message — the operators' working hours and what to include (a description and, when possible, screenshots). Like /start it answers only in a private chat and is Russian or English by the sender's reported language, and it is listed in the bot's command menu (localized, Russian/English). It is a dedicated command handler, so it intercepts /support before the support relay below — the command line itself is not forwarded to operators, while the user's following description still is.
Moderated-chat gating. When TELEGRAM_CHAT_ID names a channel's linked discussion group, the bot gates who may write there. The group allows sending by default (a human setting) and the bot only restricts — Telegram intersects the chat default with each user's permission, so a per-user grant cannot exceed a deny-by-default group, and the gate must mute the ineligible rather than grant the eligible. On a chat_member event the bot asks the gateway (ResolveChatEligibility) and mutes a member who is not registered or is admin-suspended or chat_muted, un-mutes an eligible one it had muted, and leaves an already-allowed eligible member untouched (it acts only when the state differs, so it is idempotent and skips its own change). When an operator blocks/unblocks an account, toggles its chat_muted role, or a user first registers, the gateway pushes a ChatGate command and the bot applies it — but only to a member currently in the chat (it probes one user with getChatMember, since bots cannot list members). The bot must be an administrator there with the "Ban users" right (the Bot API can_restrict_members), and it subscribes to chat_member updates, which Telegram delivers only to a chat admin. The bot also removes the automatic pin Telegram places on every channel post auto-forwarded into this linked chat (the Message.is_automatic_forward marker): it unpins only that one message (unpinChatMessage by id), so a pin set by a human admin — or by the bot for another message — is never touched. This needs the pin-messages right (can_pin_messages) in addition to "Ban users"; a startup self-check warns when it is missing.
Support relay (optional). When TELEGRAM_SUPPORT_CHAT_ID names a private forum supergroup, the bot runs a direct support channel for users who message it. A user's first non-/start message opens a dedicated forum topic whose first message is an info card (the name is a tappable profile mention via a text_mention entity — which also stops a name starting with / from rendering as a command — plus @username, language, premium, id) with a Block/Unblock toggle and a Clear button; each message is then copied into that topic (copyMessage, so any content — text, media, voice, files — carries over). Any administrator of the support chat who writes in a user's topic has it copied back to that user; the bot's own posts and non-admins are ignored (the loop guard). Block drops a user's incoming messages (the topic stays); Clear deletes the relayed messages, keeping the info card; a topic the operators delete is reopened on the next message. State (user→topic map, block list, relayed ids) is a JSON file under TELEGRAM_SUPPORT_STATE_DIR on a persistent volume — the bot host has no database. The bot must be an administrator in the group with the manage-topics and delete-messages rights. The relay is bot-local (no backend, no bot-link) and a forwarded message gets no automatic reply (the /support command above aside).
Promo bot (optional). When TELEGRAM_PROMO_BOT_TOKEN is set, the container also runs a second, standalone bot whose only job is to answer /start with a localized message and a button that opens the main bot's Mini App. The button is a URL to the main bot's direct link (TELEGRAM_BOT_LINK, the same link the UI uses) with ?startapp — a web_app button would launch under the promo bot's identity (its token would sign the initData), which the main bot's validator rejects. It is fully self-contained: no bot-link, no gateway, no game. Its ?startapp payload (TELEGRAM_PROMO_START_PARAM, default verudit_ru-scrabble_en) is a variant-seed deep link the backend decodes to seed a brand-new user's variant preferences (English Scrabble alongside the default Erudit). The message body also renders the bot's @username as that same deep link (an HTML text_link), so tapping the mention — not just the button — opens the seeded Mini App rather than the bot profile.
Rate limiting. Outbound sends are throttled (TELEGRAM_SEND_RATE_PER_SECOND, default 25) to respect the Bot API flood limits.
Payments (Telegram Stars). When TELEGRAM_STARS_OUTBOX_DIR is set (default /data), the bot handles the Stars rail. Only the bot reaches Telegram, so it mints the invoice on a CreateInvoice bot-link command (createInvoiceLink, XTR — the link goes back to the Mini App for WebApp.openInvoice); it gates each pre_checkout_query through the bot-link (ValidatePreCheckout, backed by the backend intake — declining an already-paid reusable invoice before the charge); and it records each successful_payment in a durable SQLite outbox (internal/outbox, stars.db on the writable volume) before forwarding it over the bot-link (ForwardPayment). The outbox is re-driven on startup and every 30 s, so a gateway or backend outage never loses a paid order; crediting is idempotent on telegram_payment_charge_id. The rail stays inert until a chip pack carries an XTR price (seeded in the admin).

The send commands address a recipient by the identity external_id (as in the backend identities table), so a future VK / MAX bot reuses them; only the validator's initData parsing is Telegram-specific.

gRPC contracts

pkg/proto/telegram/v1, service Telegram — served by the validator (ValidateInitData, ValidateLoginWidget). Its Notify / SendToUser / SendToGameChannel request shapes are reused as bot-link command payloads; the gateway also implements SendToUser / SendToGameChannel as the backend's admin relay.
pkg/proto/botlink/v1, service BotLink — the reverse bidi stream the bot dials on the gateway (Hello / Command / Ack), carrying a ChatGateCommand (set a user's chat write access) and a CreateInvoiceCommand (mint a Stars invoice link, returned in the Ack result), plus unary ResolveChatEligibility (the bot's join-time query), ValidatePreCheckout and ForwardPayment (the Stars rail) over the same mTLS channel. Generated Go is committed under pkg.

Deep-link scheme

Shared verbatim with the UI (ui/src/lib/deeplink.ts). A Mini App start parameter is a one-character kind prefix plus a value:

Parameter	Destination
`g<game uuid>`	open that game
`i<invitation uuid>`	open that invitation
`f<6-digit code>`	redeem that friend code
empty / unknown	the lobby

The bot turns a /start <payload> or a notification target into a launch-button URL <MiniAppURL>?startapp=<payload>.

Configuration

Shared:

Env var	Default	Meaning
`TELEGRAM_BOT_TOKEN`	— (required)	the bot's API token + initData HMAC secret
`TELEGRAM_LOG_LEVEL`	`info`	zap log level
`TELEGRAM_SERVICE_NAME`	per binary	OpenTelemetry `service.name` (validator: `scrabble-telegram-validator`, bot: `scrabble-telegram-bot`)
`TELEGRAM_OTEL_TRACES_EXPORTER`	`none`	`none`, `stdout` or `otlp` (gRPC; endpoint from `OTEL_EXPORTER_OTLP_*`)
`TELEGRAM_OTEL_METRICS_EXPORTER`	`none`	`none`, `stdout` or `otlp`

Validator (cmd/validator):

Env var	Default	Meaning
`TELEGRAM_VALIDATOR_GRPC_ADDR`	`:9091`	validator gRPC listen address (the gateway dials it)

Bot (cmd/bot):

Env var	Default	Meaning
`TELEGRAM_MINIAPP_URL`	— (required)	Mini App HTTPS origin (BotFather-registered)
`TELEGRAM_GATEWAY_ADDR`	— (required)	the gateway bot-link endpoint to dial
`TELEGRAM_BOTLINK_SERVER_NAME`	— (required)	the gateway certificate's expected SNI / CN
`TELEGRAM_BOTLINK_TLS_CERT` / `_KEY` / `_CA`	— (required)	the bot client cert, its key, and the CA that signs the gateway server cert
`TELEGRAM_GAME_CHANNEL_ID`	—	the bot's game channel chat id for `SendToGameChannel`
`TELEGRAM_CHAT_ID`	—	the moderated discussion chat id (a channel's linked group); empty disables chat gating
`TELEGRAM_SUPPORT_CHAT_ID`	—	the support relay's forum supergroup id (topic per user); empty disables the relay
`TELEGRAM_SUPPORT_STATE_DIR`	`/data`	directory for the support relay's JSON state (a writable volume)
`TELEGRAM_STARS_OUTBOX_DIR`	`/data`	directory for the Telegram Stars payment outbox (`stars.db`, a writable volume); empty disables the Stars rail
`TELEGRAM_PROMO_BOT_TOKEN`	—	the optional standalone promo bot's token; empty disables it
`TELEGRAM_BOT_USERNAME`	—	the main bot's @username without the @ (promo message); required when the promo bot runs
`TELEGRAM_BOT_LINK`	—	the main bot's Mini App link for the promo button (the UI's `VITE_TELEGRAM_LINK`); required when the promo bot runs
`TELEGRAM_PROMO_START_PARAM`	`verudit_ru-scrabble_en`	the promo button's `startapp` payload — a variant-seed deep link the backend decodes to seed a brand-new user's variant preferences; empty forwards the user's own `/start` payload
`TELEGRAM_OWNS_UPDATES`	`true`	run the exclusive `getUpdates` long-poll (one bot per token)
`TELEGRAM_SEND_RATE_PER_SECOND`	`25`	outbound Bot API send cap (0 disables)
`TELEGRAM_INSTANCE_ID`	hostname	bot identity reported to the gateway
`TELEGRAM_BOTLINK_RECONNECT_DELAY`	`2s`	pause before re-dialing after the stream ends
`TELEGRAM_API_BASE_URL`	`https://api.telegram.org`	Bot API host override (mock / self-hosted)
`TELEGRAM_TEST_ENV`	`false`	route to the Bot API test environment (`/bot<token>/test/METHOD`)

Build, test, run

go build ./platform/telegram/...
go test ./platform/telegram/...          # unit tests use an httptest fake Bot API + an in-process bot-link
go run ./platform/telegram/cmd/validator # needs TELEGRAM_BOT_TOKEN
go run ./platform/telegram/cmd/bot       # needs the bot env above + mTLS cert files

Deploy

platform/telegram/Dockerfile builds both binaries on distroless nonroot with two targets, validator and bot. In the test contour (deploy/docker-compose.yml) the validator runs on the internal network (no VPN); the bot keeps a VPN sidecar for Telegram egress and dials the gateway bot-link by its internal name. The bot-link mTLS material is generated by deploy/gen-certs.sh. In prod the bot runs on a separate host with native Telegram access and dials the gateway's published bot-link port with PROD_ certificates in production.

A real end-to-end Telegram smoke needs a BotFather bot, its token, a public HTTPS Mini App origin, and the bot container; the unit tests cover the wire format, templates, deep-links, the validator handlers and the bot-link client/executor without a live bot.