Connect Telegram for real-time alerts

POST /api/v1/telegram/link generates a one-time link token + Telegram deep_link. Click deep_link → opens Telegram → user starts bot → bot verifies token → telegram_link row created (user_id + chat_id unique). Notifications fan out to direct user AND owner (with "Team: [memberName]" prefix). Bot blocking detection: 403 from bot → is_active=false automatically.

Who is this for

Anyone wanting real-time alerts in Telegram (instant, mobile-friendly). Especially: on-call mediabuyers, agency owners monitoring multiple clients.

Prerequisites

• Telegram account

• Wevion account (any role with mediabuyer+ permission)

• Smartphone or desktop Telegram app

The Wevion workspace's Telegram bot must be configured at the deployment level (admin task — see com-114 Telegram bot setup). If your workspace's bot isn't connected: admin needs to set it up first.

How to connect

Step 1: Trigger the link flow

In Wevion UI: /settings → Notifications → Telegram → click Connect Telegram.

Or via API: POST /api/v1/telegram/link returns:

{
  "link_token": "...",
  "deep_link": "https://t.me/yourbot?start=...",
  "expires_at": "..."
}

Step 2: Open the deep_link

Click the deep_link OR copy to a device with Telegram installed.

Opens Telegram → conversation with Wevion's bot → bot shows greeting.

Step 3: Send /start to the bot

If the bot doesn't auto-respond: send /start.

Bot verifies the link token → creates telegram_link row:

• user_id (unique per Wevion user)

• chat_id (unique per Telegram chat)

• username + first_name (from Telegram)

• linked_at (timestamp)

• is_active (true)

Step 4: Verify connection

GET /api/v1/telegram/status returns:

{
  "linked": true,
  "username": "your_telegram_username",
  "first_name": "Your Name",
  "linked_at": "...",
  "is_active": true
}

UI shows green badge "Telegram Connected".

Step 5: Test it

POST /api/v1/telegram/test sends a test message.

Or via UI: /settings → Notifications → Telegram → Send Test.

Test message arrives instantly in Telegram. If it doesn't: see troubleshooting below.

What you'll receive

Per the 13 verified alert toggles in telegram_notification_pref:

Plus digest if enabled (see ntf-106 digest).

Configure via PUT /api/v1/telegram/preferences:

{
  "alert_spend_cap": true,
  "alert_sync_completed": false,
  "daily_digest_enabled": true,
  "daily_digest_hour": 9,
  "digest_timezone": "Europe/Rome"
}

Severity icons

Each Telegram message starts with a severity icon (send-telegram-notification.worker.ts):

Owner fan-out

If you're a team member (e.g. mediabuyer) with user.owner_id set:

• Direct notifications go to you

• AND to your owner (with "Team: [your name]" prefix)

This lets owners stay informed of team activity. Owners can disable via their own preferences.

Bot blocking detection

If you block the Wevion bot in Telegram (or revoke conversation):

• Wevion's next send fails with status 403 or "bot was blocked"

• Worker automatically sets telegram_link.is_active = false

• No further Telegram notifications sent

To re-enable: unlink + re-link via the connect flow.

Disconnect Telegram

DELETE /api/v1/telegram/unlink removes the link.

Or send /unlink to the bot directly (see ntf-105 commands).

After unlink:

• telegram_link.is_active = false

• No more Telegram notifications

• Link token expired

• You can re-link anytime

Same bot for tracker callbacks

Note: the same Telegram bot may also handle tracker postback callbacks (see com-114 Telegram bot setup). The notification side + tracker side are separate workflows on the same bot infrastructure. Linking for notifications doesn't affect tracker setup or vice versa.

Privacy

When linked, Telegram bot sees:

• Your chat_id + username + first_name (from Telegram)

• Notification content delivered to you

• Your /start /status /stats /help /unlink commands

Bot does NOT see your other Telegram conversations.

Wevion does NOT send personal info to Telegram beyond what's in the notification message itself.

Common issues

• Deep_link expires before I can click: link tokens have a TTL (typically 10 min). Re-trigger link if expired.

• Bot didn't respond to /start: check workspace's bot is configured (admin → com-114)

• Test message didn't arrive: bot may be blocked; check is_active via GET /status; unlink + re-link

• Notifications stopped after working initially: bot blocked / chat archived; same fix (unlink + re-link)

• Owner getting my notifications: by design — owner fan-out. Owner can disable in their own preferences.

• Notifications too noisy: disable specific alert_* toggles via PUT /preferences or use the UI

Related

• Telegram bot commands — /start, /status, /stats, /help, /unlink

• Telegram digest — daily + weekly summary

• Telegram bot setup (admin) — workspace-level config