🎯 TikTokStalker

A lightweight, interactive CLI tool that monitors any TikTok user's activity and sends real-time updates to your messaging destinations — Discord (webhook or bot) and Telegram bots are supported out of the box.

Made with ❤️ by @k0shir0

✨ Features

🎬 New Video Alerts — Get notified when a monitored user posts a new TikTok.
👤 Follower Monitoring — Detects follower gains and drops.
📈 Stat Tracking — Periodic summary of follower count, total likes, and video count.
💬 Multiple Messaging Providers — Fan out alerts to Discord webhooks, Discord bots, and Telegram bots at the same time.
🗃️ Active Comment Scraping (opt-in) — Continuously collect every comment on every video of the monitored account into a local SQLite database.
🤖 Bot Commands (opt-in) — Ask the Discord or Telegram bot for comment analytics (/comments) or the whole database as a file (/dump). Restricted to one authorized user ID per platform.
🛠️ Interactive CLI Setup — Pick destinations, enter credentials, validate, and send a test message before anything is saved.
🔁 Persistent Config — Reuse your settings or reconfigure anytime.

📡 Supported Messaging Providers

Provider	Needs	Notes
Discord webhook	Webhook URL	The original integration. Server Settings → Integrations → Webhooks.
Discord bot	Bot token + channel ID	Bot must be in the server with permission to post in the channel.
Telegram bot	Bot token + chat ID	Create the bot with @BotFather; numeric chat ID (groups may be negative).

Alerts are delivered to every configured destination — if one provider is down or misconfigured, the others still receive their messages.

1. Discord webhook

In Discord: Server Settings → Integrations → Webhooks → New Webhook, then copy the URL.
During setup choose Discord webhook and paste the URL (input is hidden).

2. Discord bot

Create an app at the Discord Developer Portal, open the Bot tab and copy the token.
Invite the bot to your server (OAuth2 → URL Generator with the bot scope and Send Messages permission).
Enable Developer Mode in Discord, right-click the target channel → Copy Channel ID.
During setup choose Discord bot and provide both values.

3. Telegram bot

In Telegram, chat with @BotFather: send /newbot, follow the steps, copy the token.
Send your bot any message, then open https://api.telegram.org/bot<your-token>/getUpdates in a browser and copy result[0].message.chat.id. For a group, add the bot to the group first (group IDs are negative).

🗃️ Active Comment Scraping (opt-in)

Active Comment Scraping collects every comment on every video of the monitored account into a local SQLite database (comments.db by default). It is entirely optional — the default is disabled, and a disabled setup never touches comment endpoints or creates a database.

When enabled, it:

Discovers all videos of the monitored user.
Performs an initial scrape, video by video, printing progress (Videos discovered / processed / Comments collected / New comments).
Keeps itself up to date: new-video alerts trigger an immediate scrape of that video, and an incremental pass re-scrapes stale or newly found videos on an interval (default 30 minutes; recent videos refresh more often).
Deduplicates everything — rescraping updates likes/counts instead of inserting copies.

Per-video failures are isolated: one blocked or empty video never aborts the run.

🤖 Bot Commands (opt-in)

With Active Scraping enabled you can also enable command listeners for Discord and/or Telegram during setup. Commands are restricted to the single authorized user ID configured per platform (stable platform IDs — never usernames). Tokens and IDs can also come from *_BOT_TOKEN / *_USER_ID environment variables for the current run.

Command	What it does
`/dump`	Uploads your full comment database as a file (Discord attachment / Telegram document), with row counts in the caption.
`/dump <page>`	Shows the analytics summary as text instead of the file.
`/comments`	Analytics overview: totals, most-commented video, top commenter, most-liked comment.
`/comments <#index \| url \| id> [page]`	Browses one video's stored comments, best-liked first, 10 per page.
`/help`	Lists the commands.

All statistics are computed with SQL aggregation inside SQLite — responses stay fast regardless of database size.

Example `setup.json` additions

{
  "active_scraping": {
    "enabled": true,
    "db_path": "comments.db",
    "scrape_interval": 1800
  },
  "command_bots": {
    "discord": { "enabled": true, "bot_token": "...", "user_id": "123456789012345678", "channel_id": "222333444555666777" },
    "telegram": { "enabled": true, "bot_token": "...", "user_id": "98765432" }
  }
}

🔁 Upgrading from an older version? Old setup.json files keep working unchanged: missing sections default to disabled, and nothing new scrapes until you explicitly opt in via setup (R at startup) or by editing setup.json.

⚙️ Installation & Setup

1. Clone the repository

git clone https://github.com/k0shir0/TiktokStalker.git
cd TiktokStalker

2. Install dependencies

pip install -r requirements.txt
python -m playwright install

📦 Node.js is not required. The current TikTokApi (v7+) drives a real browser via Playwright, so you must run python -m playwright install once to download the browser engines.

3. Get an `ms_token` (required for TikTok)

TikTok now returns data only to requests carrying a valid msToken cookie:

Open tiktok.com in your browser (logged in works best).
Open DevTools → Application → Cookies → https://www.tiktok.com.
Copy the value of the msToken cookie.

Provide it either during the interactive setup, or via an environment variable:

export ms_token="paste-your-mstoken-here"     # macOS/Linux
setx ms_token "paste-your-mstoken-here"        # Windows (new shell)

⚠️ ms_token values expire. If TikTok starts returning empty responses, grab a fresh one.

🚀 Usage

python main.py

On first run the interactive setup walks you through:

The TikTok username to monitor (e.g., charlidamelio)
An optional ms_token (hidden input)
One or more messaging destinations — each with credential prompts, validation, and an optional test message so you can confirm delivery before saving

Your configuration is saved to setup.json. On future launches you'll be asked:

"Do you want to (C)ontinue with this setup, (M)anage messaging destinations, or (R)econfigure everything?"

C — continue with your saved configuration
M — add / edit / remove messaging destinations without touching anything else
R — reconfigure everything (e.g. to monitor a different user)

🔧 Configuration

Environment variables

Variable	Default	Description
`ms_token`	(none)	Your TikTok `msToken` cookie (required for TikTok to return data).
`POLL_INTERVAL`	`60`	Seconds between checks for new activity.
`STATS_HEARTBEAT`	`3600`	Seconds between periodic stat summaries (`0` = only post on change).
`TIKTOK_BROWSER`	`chromium`	Playwright browser engine (`chromium`, `webkit`, or `firefox`).
`TIKTOK_HEADLESS`	`true`	Set to `false` if TikTok is bot-blocking your requests.

Credential environment variables override the stored setup.json values for the current run (handy for CI/secrets managers):

Variable	Overrides
`DISCORD_WEBHOOK_URL`	Stored Discord webhook URL
`DISCORD_BOT_TOKEN`, `DISCORD_CHANNEL_ID`	Stored Discord bot credentials
`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`	Stored Telegram bot credentials
`DISCORD_BOT_TOKEN`, `DISCORD_USER_ID`, `DISCORD_COMMAND_CHANNEL_ID`	Command-bot credentials (`*_COMMAND_CHANNEL_ID` only affects the command listener)
`TELEGRAM_BOT_TOKEN`, `TELEGRAM_USER_ID`	Telegram command-bot credentials

Example `setup.json`

{
  "username": "charlidamelio",
  "ms_token": "optional-if-not-using-env-var",
  "messaging": [
    { "provider": "discord_webhook", "webhook_url": "https://discord.com/api/webhooks/..." },
    { "provider": "discord_bot", "bot_token": "...", "channel_id": "123456789012345678" },
    { "provider": "telegram_bot", "bot_token": "...", "chat_id": "-1001234567" }
  ]
}

This file is generated automatically after your first run and is git-ignored because it contains your credentials.

🔁 Upgrading from an older version? A setup.json that only has a top-level "webhook" value is migrated automatically to the new format on first run — no action needed.

Adding a new provider (developers)

Providers live in messaging/ and register themselves in messaging.PROVIDERS. Subclass MessagingProvider, define name/label/config_spec, implement send(), and the interactive setup, fan-out dispatch, validation, and secret redaction all pick it up automatically.

🔔 What Gets Sent?

🆕 New TikTok Posted — with caption and a direct link to the video.
➕ New Follower(s) / ➖ Lost Follower(s) — with the delta and new total.
📊 TikTok Stats — followers, total likes, and video count.

Messages render as rich embeds on Discord; Telegram receives HTML-formatted messages (bold title, escaped content, link previews disabled, auto-chunked at Telegram's 4096-character limit).

🧪 Testing

python -m pytest

The suite covers providers, config validation, formatting/escaping, fan-out, legacy migration, the monitor loop, the interactive setup flow, the comment database, the scraper, bot command handling, both command listeners, and end-to-end Active Scraping flows. All network access is mocked by default; an opt-in live smoke test runs against real platforms when you set TIKTOKSTALKER_LIVE_E2E=1 plus TELEGRAM_BOT_TOKEN_E2E + TELEGRAM_CHAT_ID_E2E and/or DISCORD_BOT_TOKEN_E2E + DISCORD_CHANNEL_ID_E2E.

The pre-existing offline script also still works:

python test_logic.py

🐛 Troubleshooting

TikTok returns empty responses / "they are detecting you're a bot": TikTok has strong anti-bot protection, especially from servers and datacenter IPs. Try, in order:

A fresh ms_token from a real browser session.
TIKTOK_HEADLESS=false (requires a desktop/display).
TIKTOK_BROWSER=webkit.
Running from a residential IP or via a residential proxy.

Discord webhook messages stop appearing: the webhook was likely deleted or the URL revoked — re-create it and update setup (choose M at startup).

Discord bot fails with 401: the token was reset in the Developer Portal — generate a new one and update your configuration.

Discord bot authenticated but nothing arrives: the bot lacks access to the channel or the Send Messages permission — check the channel ID and the bot's role permissions.

Telegram test message fails with "chat not found": you haven't sent the bot a message yet, or the chat ID is wrong (group IDs include a minus sign). Send any message to the bot first, then re-check getUpdates.

🔐 Disclaimer

TikTokStalker relies on the unofficial TikTokApi scraping library. You are responsible for ensuring your usage complies with TikTok's Terms of Service, Discord's community guidelines, and Telegram's terms.

📄 License

MIT License — use it freely, modify it responsibly.

🤝 Contributing

Pull requests welcome! Open issues or improvements via GitHub Issues.

Name		Name	Last commit message	Last commit date
messaging		messaging
tests		tests
.gitignore		.gitignore
README.md		README.md
bot_commands.py		bot_commands.py
database.py		database.py
main.py		main.py
pytest.ini		pytest.ini
requirements.txt		requirements.txt
scraper.py		scraper.py
setup_flow.py		setup_flow.py
test_logic.py		test_logic.py

Navigation Menu

Repository navigation

About

Repository files navigation

🎯 TikTokStalker

✨ Features

📡 Supported Messaging Providers

1. Discord webhook

2. Discord bot

3. Telegram bot

🗃️ Active Comment Scraping (opt-in)

🤖 Bot Commands (opt-in)

Example `setup.json` additions

⚙️ Installation & Setup

1. Clone the repository

2. Install dependencies

3. Get an `ms_token` (required for TikTok)

🚀 Usage

🔧 Configuration

Environment variables

Example `setup.json`

Adding a new provider (developers)

🔔 What Gets Sent?

🧪 Testing

🐛 Troubleshooting

🔐 Disclaimer

📄 License

🤝 Contributing

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎯 TikTokStalker

✨ Features

📡 Supported Messaging Providers

1. Discord webhook

2. Discord bot

3. Telegram bot

🗃️ Active Comment Scraping (opt-in)

🤖 Bot Commands (opt-in)

Example setup.json additions

⚙️ Installation & Setup

1. Clone the repository

2. Install dependencies

3. Get an ms_token (required for TikTok)

🚀 Usage

🔧 Configuration

Environment variables

Example setup.json

Adding a new provider (developers)

🔔 What Gets Sent?

🧪 Testing

🐛 Troubleshooting

🔐 Disclaimer

📄 License

🤝 Contributing

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Example `setup.json` additions

3. Get an `ms_token` (required for TikTok)

Example `setup.json`