alisaza 54a8dcb283 Add initial Telegram relay service for Iran→foreign delivery.

Thin Hono API so the Iran-hosted backend can POST ops alerts here and this VPS calls Telegram Bot API.

2026-09-13 13:38:36 +03:30

2.4 KiB

Raw Blame History

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.

2.4 KiB Raw Blame History Unescape Escape