Skip to content
maxylevPublic

About

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.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

gra — Instagram → Telegram bridge daemon

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.

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 instagram crate (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

Install

cargo install gra

or 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

Quick start

  1. Create a bot with @BotFather and copy its token.

  2. Create gra.toml (see gra.toml.example for every option):

    bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    db_path   = "gra.db"
    allowed_user_ids = [11111111]   # recommended: only you can use the bot
  3. Run gra and message your bot: /start, /login (cookies, optional), /add natgeo.

New posts and stories are then delivered automatically.

Bot commands

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_check posts 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.

Configuration

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.

gra doctor

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

docker build -t gra:local .
docker run -d --name gra -v "$PWD/data:/data" -e GRA_BOT_TOKEN="123456:..." gra:local

The 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.

Development

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 --nocapture

Pushing a v* tag publishes the crate to crates.io and a multi-arch image to GHCR (requires the CARGO_REGISTRY_TOKEN secret).

Architecture

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.

Security

  • Cookies are stored in your SQLite database and sent only to Instagram. Restrict a public bot with allowed_user_ids and 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).

License

MIT

About

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.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages