https://github.com/jellydn/sky-alert
Real-time flight monitoring Telegram bot. Track flights, get instant alerts on delays, gate changes, boarding, and more.
https://github.com/jellydn/sky-alert
bot flight telegrambot
Last synced: 18 days ago
JSON representation
Real-time flight monitoring Telegram bot. Track flights, get instant alerts on delays, gate changes, boarding, and more.
- Host: GitHub
- URL: https://github.com/jellydn/sky-alert
- Owner: jellydn
- License: mit
- Created: 2026-02-19T03:53:01.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T01:19:38.000Z (2 months ago)
- Last Synced: 2026-05-19T14:56:27.461Z (about 1 month ago)
- Topics: bot, flight, telegrambot
- Language: TypeScript
- Homepage:
- Size: 192 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Welcome to SkyAlert 👋
[](https://github.com/jellydn/sky-alert/blob/main/LICENSE)
[](https://twitter.com/jellydn)
> Real-time flight monitoring Telegram bot. Track flights, get instant alerts on delays, gate changes, boarding, and more.
## Features
- **Track flights** by flight number, natural language, or route (e.g., `DAD to SIN today`)
- **Real-time alerts** — check-in open, delays, gate changes, boarding, departure, landing, cancellation
- **Adaptive polling** — every 15 min (far), 5 min (near), 1 min (imminent)
- **Multi-user** — multiple users can track the same flight with deduplicated API calls
- **Auto-cleanup** — expired flights are deactivated and removed automatically
- **Live refresh fallback** — FlightStats-first enrichment, then FlightAware as secondary fallback when data is still low-signal
## Tech Stack
- **TypeScript** + [grammY](https://grammy.dev/) (Telegram Bot framework)
- **SQLite** (via better-sqlite3 or Drizzle)
- **[Aviationstack API](https://aviationstack.com/)** for flight data
## Install
```bash
# Install dependencies
bun install
# Configure environment
cp .env.example .env
# Set BOT_TOKEN and AVIATIONSTACK_API_KEY in .env
```
## Usage
```bash
# Run the bot
bun run start
```
## Deployment
Ready to deploy your bot? Check out the [**Hosting Guide**](HOSTING.md) for detailed instructions on deploying to:
- **Fly.io** (recommended) — with persistent SQLite volume
- **Render** — simple deployment with disk storage
- **Railway** — easy setup with volume support
The guide covers environment variables, database persistence, and troubleshooting.
## Develop
```bash
# Run in development mode
bun run dev
# Type-check
bun run typecheck
# Lint
bun run lint
```
### Justfile shortcuts
```bash
just dev
just db-generate
just db-migrate
just db-studio
```
Note: `drizzle-kit` SQLite commands rely on `better-sqlite3` at dev time for DB connectivity.
## Environment Variables
| Variable | Description |
| ----------------------- | ------------------------------------------------------------ |
| `BOT_TOKEN` | Telegram bot token from [@BotFather](https://t.me/BotFather) |
| `AVIATIONSTACK_API_KEY` | API key from [aviationstack.com](https://aviationstack.com/) |
## Bot Commands
| Command | Description |
| ------------------------- | ------------------------------------- |
| `/start` | Welcome message |
| `/track AA123 2026-03-15` | Track a flight |
| `/flights` | List all tracked flights |
| `/status AA123` | View current flight status + timeline |
| `/remove AA123` | Stop tracking a flight |
| `/help` | Show available commands |
The bot also understands natural language:
- `Track my flight GA851 tomorrow`
- `DAD to SIN today`
## Architecture
```
┌─────────────────────────────────┐
│ Telegram Bot │
│ (grammY – long polling) │
├─────────────────────────────────┤
│ Message Parser / Router │
│ (commands + natural language) │
├──────────┬──────────────────────┤
│ Flight │ Background Worker │
│ Service │ (adaptive polling) │
├──────────┴──────────────────────┤
│ SQLite Database │
│ flights | tracked_flights | │
│ status_changes │
└─────────────────────────────────┘
│
▼
Aviationstack API
│
▼ (fallback when needed)
FlightStats parser + FlightAware parser
```
## Status Refresh, Timeout, and Fallback Rules
### Refresh timing
- `/status` refreshes flight data when either condition is true:
- Data is stale (`>= 15 minutes` since last poll)
- Data is low-signal (`scheduled`/empty status and no delay)
- Polling worker interval by time-to-departure:
- `> 3h`: every `15 minutes`
- `<= 3h`: every `5 minutes`
- `<= 1h`: every `1 minute`
### Caching
- Aviationstack response cache TTL: `15 minutes`
- Live refresh paths (`/status`, polling worker) bypass cache to force fresh provider data
### Selection timeout
- Multi-result flight selection (route or ambiguous number) expires after `5 minutes`
- If expired, user must search/select again
### Fallback behavior
- Primary source is Aviationstack
- Fallback is triggered only when Aviationstack is low-signal:
- Status is `scheduled` or empty, and delay is missing/non-positive
- Fallback order:
- 1) FlightStats (status, delay, estimated departure/arrival, terminal, gate)
- 2) FlightAware only if status/delay are still low-signal after FlightStats
- `/status` display prefers live fallback estimated times over derived `scheduled + delay`
- `/status` also shows arrival terminal/gate when available from fallback data
- FlightAware fallback tries multiple identifiers (`ICAO`, `IATA`, user input), e.g. `TGW315` then `TR315`
### Known limitations
- If both providers return no delay signal, bot will remain on scheduled/on-time data
- FlightAware fallback is HTML/bootstrap parsing, not an official FlightAware API
## Author
👤 **Huynh Duc Dung**
- Website: https://productsway.com/
- Twitter: [@jellydn](https://twitter.com/jellydn)
- Github: [@jellydn](https://github.com/jellydn)
## Show your support
Give a ⭐️ if this project helped you!
[](https://ko-fi.com/dunghd)
[](https://paypal.me/dunghd)
[](https://www.buymeacoffee.com/dunghd)
## License
MIT © [Huynh Duc Dung](https://productsway.com/)