POST /api/v1/telegram/link → deep_link → open in Telegram → bot verifies token. Owner fan-out. Bot blocking auto-deactivates.

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:

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

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 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 are single-use and expire after 24 hours. 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

FAQ

How do I connect Telegram to Wevion?

In Wevion go to /settings → Notifications → Telegram and click Connect Telegram, which calls POST /api/v1/telegram/link to generate a one-time token and a Telegram deep_link. Open the deep_link, send /start to the bot, and it verifies the token and creates your telegram_link row. A green "Telegram Connected" badge confirms it.

What happens if I block the Wevion bot?

If you block Wevion's bot or revoke the conversation, the next send fails with status 403, and the worker automatically sets telegram_link.is_active = false, stopping all further Telegram notifications. To re-enable them, unblock the bot in Telegram, then unlink and re-link through the connect flow in /settings → Notifications → Telegram.

Why is my owner receiving my notifications?

That's owner fan-out, by design in Wevion. If you're a team member with user.owner_id set, your direct notifications also go to your owner, prefixed with "Team: [your name]", so owners stay informed of team activity. Owners who don't want this can disable it through their own notification preferences.

How do I disconnect Telegram?

Call DELETE /api/v1/telegram/unlink, use /settings → Notifications → Telegram in Wevion, or send /unlink directly to the bot. After unlinking, telegram_link.is_active becomes false, no further Telegram notifications are sent, and the link token expires. You can re-link anytime through the standard deep_link connect flow.

Related articles

• Telegram bot commands
• Telegram digest — daily and weekly reports
• Connect Telegram for notifications