Track Instagram accounts from a Telegram bot: new posts & stories are downloaded and delivered straight to your chat, and follower/following/post counts are recorded over time for statistics.
- Multi-user: many Telegram chats, many accounts per chat, fully isolated.
- Each user manages named Instagram cookie sets in the bot (
/login,/cookies) — needed for stories, private profiles and the following list. - Per-account check interval, delivery toggles and cookie choice, all in the bot.
- SQLite storage; plain path or
file:URI. - Server-side settings come from TOML, environment variables and CLI flags.
- Scraping via the
instagramcrate (wreq with Chrome TLS emulation); a minimal Telegram client on the same stack.
Unofficial, not affiliated with Instagram or Meta. Use only to archive and watch content you are allowed to access, and respect Instagram's Terms of Use and rate limits.
Full documentation: maxylev.github.io/gra
cargo install graor run the Docker image:
docker run -d --name gra -v "$PWD/data:/data" -e GRA_BOT_TOKEN="<TOKEN>" \
--restart unless-stopped ghcr.io/maxylev/gra:latest-
Create a bot with @BotFather and copy its token.
-
Create
gra.toml(seegra.toml.examplefor every option):bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" db_path = "gra.db" allowed_user_ids = [11111111] # recommended: only you can use the bot
-
Run
graand message your bot:/start,/login(cookies, optional),/add natgeo.
New posts and stories are then delivered automatically.
| Command | What it does |
|---|---|
/start |
Main menu |
/accounts |
Tracked accounts (tap one for stats, settings, pause, remove) |
/add |
Track an account: /add name, @name, a profile or t.me link |
/remove |
Stop tracking an account |
/stats |
Followers / following / posts with deltas and trend charts |
/settings |
Per-account interval (5m → 1d), posts/stories/videos/stats toggles, cookie set |
/defaults |
Interval and toggles for accounts you add later |
/login |
Add cookies: k=v; … string, cookies.txt file, or a browser cookie table |
/cookies |
Cookie sets: choose the default ⭐, rename, delete |
/whoami |
Your configuration |
/cancel |
Abort the current input step |
Behaviour:
- Only new content is delivered (no backfill), oldest first, at most
max_send_per_checkposts per check — the rest follow on the next check. - Stories need cookies of an Instagram account that can see them.
- Cookies per account: Auto (your ⭐ default set, else the server's 🌐 set, else anonymous), None (anonymous), or a specific set.
- With videos off (or media too large for Telegram), the caption and link are delivered instead of the file.
- Statistics store one row per change of the counters.
- A failing account is reported once when it starts failing, then retried on its normal interval.
Precedence: defaults ← config file ← environment ← CLI flags. The config
file is --config/GRA_CONFIG, else ./gra.toml if it exists; unknown keys
are rejected.
| Key | Default | Description |
|---|---|---|
bot_token |
— | Telegram bot token (GRA_BOT_TOKEN, --bot-token) |
db_path |
gra.db |
SQLite path or file: URI (GRA_DB_PATH, --db-path) |
tick_secs |
15 |
How often due accounts are looked up (GRA_TICK_SECS) |
ig_delay_ms |
1200 |
Pause between paginated Instagram requests |
http_timeout_secs |
60 |
Timeout for Instagram requests |
max_concurrent_checks |
2 |
Accounts checked in parallel |
log_level |
info |
Tracing filter, e.g. gra=debug,info (GRA_LOG_LEVEL; RUST_LOG wins) |
log_file |
none | Log file rotated daily, 7 kept (GRA_LOG_FILE) |
allowed_user_ids |
[] |
Telegram user allowlist; empty = everyone (GRA_ALLOWED_USER_IDS=1,2) |
default_interval_secs |
1800 |
Interval for new users' accounts (≥ 60) |
default_send_posts / _stories / _videos |
true |
New users' delivery defaults |
default_track_stats |
true |
New users' stats default |
max_send_per_check |
5 |
Posts delivered per account per check |
media_group_size |
10 |
Items per Telegram album (2-10) |
max_follow_list |
60 |
Entries loaded from your following list |
tg_base_url |
https://api.telegram.org |
Bot API base (e.g. a local Bot API server) |
ig_base_url |
https://www.instagram.com |
Instagram base (tests) |
cookie_sets |
[] |
Server-owner 🌐 cookie sets: name, cookies (or file:<path>), ua |
Global cookie sets are synced on startup: changed sets are updated and sets removed from the config are deleted.
Check cookies and/or a profile without starting the daemon (exit code 1 on failure):
gra doctor --cookies file:./cookies.txt --username natgeo
gra doctor --cookies "sessionid=...; csrftoken=...; ds_user_id=..." --user-agent "Mozilla/5.0 ..."docker build -t gra:local .
docker run -d --name gra -v "$PWD/data:/data" -e GRA_BOT_TOKEN="123456:..." gra:localThe image runs as uid 10001 with the database at /data/gra.db; make a
mounted host directory writable with chown -R 10001 data. To use a config
file, mount it and point GRA_CONFIG at it.
cargo test # unit + wiremock end-to-end tests, no network
cargo clippy --all-targets -- -D warnings
cargo fmt --check
GRA_LIVE_COOKIES='file:./cookies.txt' cargo test --test live -- --ignored --nocapturePushing a v* tag publishes the crate to crates.io and a multi-arch image to
GHCR (requires the CARGO_REGISTRY_TOKEN secret).
| Module | Responsibility |
|---|---|
bot |
Long polling, per-chat ordered handling, commands, typed callbacks, input flows, views |
poller |
Scheduler: profile + stats → new posts → new stories → download → deliver |
ig |
Instagram session, following list, size-capped downloads, cookie parsing |
tg |
Bot API client with retries, flood-control handling and multipart uploads |
db |
SQLite schema (users, cookie_sets, accounts, stats, delivered) |
config |
CLI / env / TOML merging and validation |
state |
Expiring per-chat conversation state |
render |
HTML message builders |
The database schema is versioned; databases created by earlier releases are
rejected with a clear error — start with a fresh db_path.
- Cookies are stored in your SQLite database and sent only to Instagram.
Restrict a public bot with
allowed_user_idsand protect the database file. - The bot token never appears in logs or error messages.
- Everything users can trigger is checked for ownership (accounts, cookie sets) and validated (intervals, usernames, file sizes).
MIT
