Skip to content

Telegram integration

StockClaw can push FLASH and ALERT signals to your personal Telegram chat — grouped into at most two messages per pipeline run (all FLASH merged, all ALERT merged) so you don't get pinged per signal.

One-time setup

1. Start the bot

Open Telegram, tap @stockclaw_notify_bot, and hit Start (or send /start).

This step is not optional

Telegram does not allow bots to initiate conversations. Until you send the first message, the bot has no permission to DM you — pushes will silently fail with chat not found.

2. Get your chat id

Open @userinfobot and send /start. It replies with something like:

Id: 123456789
First: Kaitao

Copy the 123456789 (just the digits, no spaces).

Go to Settings → Telegram integration. Paste the chat id, optionally add your @username (cosmetic — shown in the "Linked as" row), click Link.

Your next pipeline run with a FLASH/ALERT signal will arrive in Telegram.

Group chats

Want the bot to post into a shared group (household portfolio, team channel)?

  1. Create the group (or use an existing one).
  2. Add @stockclaw_notify_bot as a member.
  3. Have any admin send /start@stockclaw_notify_bot in the group — same rule as DMs.
  4. The group's chat id is a negative number (e.g. -1001234567890). To find it, forward any group message to @userinfobot; it replies with the group's Forwarded from id.
  5. Paste that negative id into StockClaw. Works identically.

Two accounts, one chat

Nothing stops two StockClaw accounts from linking the same chat id — the "household shared chat" pattern. Both users' signals fan in to the same Telegram chat. If their watchlists overlap, the same news event may produce two signals (one per account) and land as two Telegram messages. If overlap is fine for you, you're done; if you want "who triggered this" labels, open an issue.

What the messages look like

Every batch message carries:

  • A header (⚡ StockClaw AI — FLASH or 🔔 — ALERT) and the signal count.
  • Per-signal block with the summary (EN + ZH), an affected-tickers bar-chart with impact % and link_type, the impact/confidence numbers, and the 5-agent breakdown with individual latencies.
  • The source URL.
  • The signal id (first 8 chars, for support / debug).

See the dashboard's signal card for a visual analogue — they're intentionally similar.

Settings → Telegram integration → Unlink. The telegram_chat_id on your user_settings row is nulled. Pushes stop immediately. Bot permission on Telegram stays — you can re-link later without re-starting the bot.

Troubleshooting

No messages arriving:

  • Check you've actually /start'd the bot (step 1).
  • Check Celery workers are running — pipeline tasks need a worker to consume them.
  • The signal urgency matters: DIGEST and FYI are dashboard-only, not Telegram. Only FLASH and ALERT push.
  • Look at your server's worker logs; search for [run_user_pipeline] user=<your id> — the delivery step prints chat_id and success.

"chat not found" in worker logs:

  • Your chat id is wrong, or the user / group hasn't /start'd the bot yet.

Bot replied but no signals:

  • You may have no tickers on your watchlist, or no news has produced FLASH/ALERT today. Try adding a popular ticker like NVDA and waiting two Beat cycles (~40 minutes).