Docs · Setup

Pair the Telegram bot in 5 minutes

One-time setup in @BotFather. Paste one token into Railway, and every manager on this StockPilot deployment can connect their personal Telegram in one tap from /settings. No webhook config — StockPilot installs that itself on the next boot.

1

Open @BotFather in Telegram

On your phone or desktop, open Telegram and search for @BotFather. It's the official Telegram account (blue checkmark) that creates and configures bots. Open the chat and tap Startif you haven't before.

2

Send /newbot and pick a name

Send /newbot. BotFather asks for two things in order:

  • Display name — what managers see in their Telegram chat list. e.g. Northside StockPilot.
  • Username — must be unique across Telegram and end in bot. e.g. northside_stockpilot_bot.

BotFather replies with a token that looks like 1234567890:AAH-ZxQ_secret_string_here. Copy the whole thing — that's the only secret you need.

Treat the token like a password. Anyone with it can read and send every message your bot ever handles.

3

Paste it into Railway

Open your StockPilot service on Railway → Variables tab → + New Variable:

  • TELEGRAM_BOT_TOKEN=paste the token from BotFather

Railway redeploys automatically — about 60 seconds. On the next boot StockPilot calls Telegram's setWebhook for you, pointing at:

Webhook URL (auto-installed)

https://stockpilot-app-production-2a53.up.railway.app/api/bot/telegram

You don't paste this anywhere — it's here so you know what to look for in getWebhookInfo if you ever need to debug.

4

Click Connect Telegram in /settings

Sign in as a manager and open /settings. The Telegram row says “Tap Connect — Telegram opens and links automatically” and the button is live. Tap it. Telegram opens, your bot is already there with a Start button, tap that once.

The /settings row flips to Connected. From this point your phone gets push notifications for low-stock drafts, supplier replies, and morning briefs — and one-tap approval works from the lock screen.
5

(Optional) Skip the app switch with one-tap login

By default, clicking Connect Telegram opens t.me/your_botand asks the manager to tap Start. It's 5 seconds and works on every device, but it does switch them out of the browser.

If you want the smoother flow — manager stays in their browser, approves a one-tap consent screen, lands back on /settings already paired — register a Telegram OAuth app and add two more variables:

  • TELEGRAM_LOGIN_CLIENT_ID
  • TELEGRAM_LOGIN_CLIENT_SECRET

Telegram's OAuth registration uses oauth.telegram.org as the issuer. The redirect URI to register on the OAuth app is:

OAuth redirect URI

https://stockpilot-app-production-2a53.up.railway.app/api/bot/telegram/oidc/callback

Once both variables are set, isTelegramOneTapReady() flips on and Connect Telegram silently switches to the OIDC flow. The plain BotFather flow keeps working as the fallback.

6

If something looks off

Connect Telegram says “credentials missing” — the env var didn't take. Hard-refresh /api/health; if env.okis true and Telegram still complains, double-check there's no whitespace around TELEGRAM_BOT_TOKEN in Railway.

Webhook didn't install — call GET https://api.telegram.org/bot<TOKEN>/getWebhookInfo. You should see your https://stockpilot-app-production-2a53.up.railway.app/api/bot/telegramas the URL. If it's blank or wrong, click Connect Telegram once — that re-runs ensureTelegramWebhook with a clearer error path than boot does.

Manager taps Start and nothing pairs — the connect token expires after 15 minutes. Click Connect Telegram again to mint a fresh one.

← Back to Settings