Ghabilee Telegram Relay

Thin HTTP service that lives on a foreign VPS and forwards ops alerts to Telegram Bot API. The Iran-hosted Nest backend calls this relay instead of api.telegram.org directly (which is often unreachable from inside Iran).

Repo: https://git.ghabilee.ir/AliSaZa/telegrambot.git

Why

• Core product (Jibit, Kavenegar, Postgres) stays in Iran.
• Only Telegram delivery needs outbound access to api.telegram.org.
• Failures here must not break user flows (backend already treats most alerts as best-effort).

API

GET /health

Liveness for Docker/load balancers. No auth.

POST /v1/send

Auth header (required):

X-Ghabilee-Telegram-Relay-Secret: <RELAY_SECRET>

Body (JSON):

Field	Type	Required	Notes
text	string	yes	1–4096 chars (Telegram limit)
chatId	string	no	Override default chat from env
messageThreadId	number | null	no	Forum topic; null = no topic; omit = env default
disableWebPagePreview	boolean	no	Default true

Success:

{ "ok": true, "messageId": 123 }

Errors: 401 unauthorized, 400 validation, 502 Telegram API failure.

Example

curl -sS -X POST "https://relay.example.com/v1/send" \
  -H "Content-Type: application/json" \
  -H "X-Ghabilee-Telegram-Relay-Secret: $RELAY_SECRET" \
  -d '{"text":"hello from relay","messageThreadId":8}'

Local run

cp .env.example .env
# fill TELEGRAM_BOT_TOKEN, chat ids, RELAY_SECRET (≥32 chars)

npm install
npm run dev

Tests / typecheck:

npm test
npm run typecheck

Docker

cp .env.example .env
docker compose up -d --build

Env

See .env.example. Production needs:

• RELAY_SECRET (≥32)
• TELEGRAM_BOT_TOKEN
• TELEGRAM_GROUP_CHAT_ID (preferred) or TELEGRAM_CHAT_ID
• optional TELEGRAM_GROUP_THREAD_ID (ops forum topic)

Backend integration (next step)

In ghabilee-backend OpsAlertsService.sendTelegram, when TELEGRAM_RELAY_URL is set, POST to {TELEGRAM_RELAY_URL}/v1/send with the shared secret instead of calling Telegram directly. Keep a direct-Telegram fallback for local/dev if useful.

Security notes

• Do not put the secret in query strings (access logs).
• Expose only HTTPS on the foreign VPS (Caddy/Nginx + Let’s Encrypt).
• Firewall: ideally allow only the Iran VPS egress IP to hit /v1/send.