Telegram Userbot on Railway — Full Setup Guide

What You're Building

A Telethon userbot — a script that logs in as your Telegram account (not a bot created via @BotFather), watches specific public channels you've joined, filters messages by keyword, and forwards matches to a destination chat. This approach works on any public channel without needing admin access.

---

Step 1 — Get Telegram API Credentials

1. Go to my.telegram.org and log in with your phone number.
2. Navigate to API Development Tools.
3. Create a new app (name and description don't matter).
4. Copy your api_id and api_hash — save them somewhere secure.

---

Step 2 — Get the Code

Clone this repository directly — no need to create files manually:

git clone https://github.com/kommissarfx/telegram-userbot.git
cd telegram-userbot

This gives you all three required files (main.py, Procfile, requirements.txt) instantly.

If you want your own copy on GitHub (recommended for Railway deployment), push it to a new private repo:

git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
git push -u origin main

Then connect your repo to Railway as described in Step 4.

---

Step 3 — Generate a StringSession (One-Time)

You need a StringSession — a string that represents your authenticated Telegram login so the bot can act as you on the server without needing your password each time.

Do this once using Replit (no local install needed):

1. Go to replit.com, create a free account, and start a new Python Repl.
2. In the Shell, run: pip install telethon
3. Create and run this script:

from telethon.sync import TelegramClient
from telethon.sessions import StringSession

api_id = int(input("API_ID: ").strip())
api_hash = input("API_HASH: ").strip()

with TelegramClient(StringSession(), api_id, api_hash) as client:
    print(">> Sending login code to your Telegram...")
    print("STRING_SESSION:", client.session.save())

4. Enter your api_id and api_hash when prompted.
5. Telegram will send a login code to your account — enter it.
6. Copy the long string printed after STRING_SESSION: — this is your session key. Treat it like a password.
7. You can delete the Repl afterwards.

---

Step 4 — Deploy to Railway

1. Go to railway.app and sign in (use "Continue with GitHub").
2. Click New Project → Deploy from GitHub Repo.
3. Select your telegram-userbot repo.
4. Railway will detect the Procfile and set the service type to Worker automatically. Confirm this is the case (not "Web Service").

---

Step 5 — Set Environment Variables

In Railway, go to your service → Variables tab, and add the following:

Variable	Value
API_ID	Your numeric API ID from my.telegram.org
API_HASH	Your API hash string
STRING_SESSION	The long session string from Step 3
KEYWORDS	Pipe-separated terms, e.g. Київ|Kyiv|Киев|дрон|Shahed|тривог
CHANNELS	Comma-separated channel IDs to watch, e.g. 1223955273,1641260594
FORWARD_TO	Destination chat ID or me for Saved Messages
WEBHOOK_URL	(Optional — leave blank if not needed)

Note on KEYWORDS: Always set a meaningful value. If left empty, the regex matches everything and the bot will forward every single message from all monitored channels to your destination chat. The code has a default fallback of Київ|Kyiv|Киев if the variable is not set at all.

Note on CHANNELS: If left empty, the bot watches all channels you've joined. It's recommended to list specific channel IDs to reduce noise.

Note on WEBHOOK_URL: Only needed if you want to trigger an external service (e.g. an iOS Shortcut via Pushcut) when an alert fires. Leave blank for Telegram-only forwarding.

---

Step 6 — Deploy and Verify

1. Click Deploy in Railway.
2. Wait for the build to finish and the worker to start.
3. Open the Logs tab — you should see: Userbot running. Watching channels: [...]
4. To test: send (or find) a message containing one of your keywords in a monitored channel.
5. Check your destination chat — the message should appear with a 🚨 prefix.

---

Step 7 — Mute the Original Channels

In Telegram, mute all the noisy source channels. Keep your destination chat (Saved Messages or your alerts chat) unmuted. From now on, you'll only receive notifications for messages that match your keywords.

---

Step 8 — Ongoing Maintenance

• Refine keywords anytime by updating KEYWORDS in Railway Variables (no redeploy needed, just restart the service).
• Check logs occasionally for errors.
• If the session expires (rare): repeat Step 3 to generate a new STRING_SESSION and update the variable in Railway.
• Free tier note: Railway's free plan covers ~750 hours/month per service — enough to run one small bot 24/7. Add a payment card to avoid interruptions if credits run low.