Pair Telegram bot at /connect/telegram with a one-time deep-link token. Real-time alerts for rules, spend, errors. Cross-link to gs-115.

Connect Telegram for notifications

Open /connect/telegram to get your unique deep-link token. Open the Wevion Telegram bot, send /start [token]. Pairing complete — real-time alerts now arrive on Telegram. Endpoints verified vs apps/backend/src/routes/api/telegram.route.ts: link, unlink, status, preferences, webhook.

Who is this for

Anyone who wants real-time alerts on their phone for rule firings, spend thresholds, sync errors, security events. Most useful for active mediabuyers monitoring campaigns outside of business hours.

Why Telegram over email

Telegram excels at real-time + interactive. Email lags (batch / scheduled). In-app requires you to be in Wevion.

Telegram bot capabilities

Beyond receiving notifications, the Wevion Telegram bot supports interactive commands (see com-115):

• /start [code] — pair your account
• /status — current state of account + workspace
• /stats — quick performance snapshot
• /help — list commands
• /unlink — unpair

The bot speaks Italian by default (apps/backend/src/services/telegram-bot.service.ts).

Before you start

• A Telegram account (free, install Telegram app on phone or desktop)
• 2 minutes for setup

How to pair

Step 1: Open the Wevion Telegram connector

In sidebar click Connect → Telegram or visit /connect/telegram. The page shows:

• Your one-time Telegram link token in the bot deep link — currently a 32-character hex token valid for 24 hours, regeneratable
• A link to open the Wevion bot in Telegram (clickable from desktop)

Step 2: Open the bot

Click the Open the Wevion bot link. Telegram opens (or installs if not present). You see the bot's profile + chat window.

Step 3: Send /start with your code

In the bot chat, send:

/start <token-from-wevion>

(Use the token/deep link generated by Wevion.)

Step 4: Bot confirms pairing

Bot replies with a welcome message confirming your Wevion account is now linked to this Telegram chat. Pairing saved server-side per-user.

Behind the scenes:

• POST /api/v1/telegram/link validates the code
• handleStartCommand in telegram-bot.service.ts processes the command
• User's Telegram chat ID stored linked to user_session ID

Step 5: Configure notification preferences

Back in Wevion /connect/telegram:

• Page now shows Connected badge
• Toggle per-event preferences (rule firings, spend alerts, sync errors, etc.)
• Test alert button to verify delivery

For per-event detail see team-116 customize notifications — same preferences cover Telegram channel.

What Telegram alerts cover

By default:

• Rule firings: pause/scale/notify actions
• Spend alerts: thresholds you set
• Sync errors: ad platform connection issues
• Token expiry warnings: 7 days before expected
• Security events: login from new device, 2FA changes, API key created — where the current event catalog exposes them. These follow your notification preferences like other events; Wevion does not guarantee they are forced-on for the Telegram channel.

Per-event toggle at /settings/personal/notifications (cross-cluster — see team-116).

Bot endpoints (technical reference)

Verified vs apps/backend/src/routes/api/telegram.route.ts:

Delivery infrastructure

Wevion's bot delivery via apps/backend/src/lib/telegram-delivery-v2.ts + apps/backend/src/services/channels/telegram-delivery-v2.service.ts:

• Async via SQS worker (apps/backend/src/sqs/workers/telegram/send-telegram-notification.worker.ts)
• Retry on failure with exponential backoff
• Rate-limit aware (Telegram has per-bot limits)
• Per-user circuit breaker (if a user's chat keeps failing, skip after N retries)

Plugin reference

apps/backend/src/plugins/external/13.telegram.ts registers the Telegram bot plugin at startup. Requires TELEGRAM_BOT_TOKEN env var.

Multiple Telegram pairings

Each Wevion user can pair with ONE Telegram chat. To switch (e.g. new phone):

1. Unpair via /unlink bot command OR /connect/telegram → Unlink button
2. Pair again with new Telegram account using a fresh link token

Group chats

Pairing currently supports 1:1 user → bot chats. Group chats not supported (the bot won't accept commands in groups, and notifications go to your personal chat).

For team notifications: each teammate pairs individually + notification preferences are per-user.

Bot language

Bot messages default to Italian (codebase setup). Other languages on roadmap. If you need English bot interaction, contact support.

Security

• Pairing requires a valid 32-character hex token (24h expiry, single-use)
• Webhook from Telegram verified via secret token
• Chat ID stored encrypted at rest
• Unlink immediately revokes the bot's permission to send to that chat
• Audit log records pair / unpair events (admin view)

What you'll see

After successful pair:

• /connect/telegram shows Connected badge with your Telegram username
• Bot welcome message in your Telegram chat
• Notification preferences page (/settings/personal/notifications) shows Telegram toggles enabled
• First test notification arrives within seconds of preference change

Common issues

• Link token expired (>24h): refresh /connect/telegram for a new token
• Bot doesn't reply to /start: bot may be temporarily offline. Wait 1 min. Persistent: contact support with your Telegram username.
• Code accepted but no welcome message: check Telegram app notification settings; sometimes bot messages are filtered.
• Receiving too many notifications: tune at /settings/personal/notifications (team-116).
• Stopped receiving notifications: check /connect/telegram → Status. If shows Disconnected, repair.
• Bot replies in Italian and I want English: not currently configurable; contact support for roadmap info.

Cross-reference

This is the integration-side view of Telegram (PRD-14 commerce/tracker cluster).

The user-side view is at gs-115 set up notifications (PRD-10 onboarding cluster).

Both link to bot commands reference: com-115.

FAQ

How do I pair Telegram with Wevion?

Open /connect/telegram to get your one-time deep-link token, then click Open the Wevion bot and, in the bot chat, send /start followed by your token. The bot replies with a welcome message confirming your Wevion account is linked to that Telegram chat, and pairing is saved server-side per user. The whole flow takes about 2 minutes.

What alerts does the Wevion Telegram bot send?

By default the bot sends rule firings (pause, scale, notify actions), spend alerts for thresholds you set, sync errors for ad platform connection issues, token expiry warnings 7 days ahead, and security events. You can toggle each event type at /settings/personal/notifications, the same preferences that cover the Telegram channel.

Can I pair Telegram with a group chat in Wevion?

No. Pairing currently supports only 1:1 user-to-bot chats; the bot will not accept commands in groups, and notifications go to your personal chat. For team notifications, each teammate pairs individually, since notification preferences are per user.

What language does the Wevion Telegram bot speak?

The bot messages default to Italian, per the codebase setup, with other languages on the roadmap. If you need English bot interaction, contact support. This applies to the bot's replies and notifications, while your in-app Wevion experience follows your own language settings.

How do I switch my Telegram pairing to a new phone?

Each Wevion user can pair with one Telegram chat, so to switch, first unpair using the /unlink bot command or the Unlink button at /connect/telegram, then pair again from your new Telegram account using a fresh link token. Unlinking immediately revokes the bot's permission to send to the old chat.

Related articles

• Telegram bot commands reference
• Set up notifications and Telegram alerts
• Notification center — staying informed