Connect Telegram for notifications

Open /connect/telegram to get your unique 6-digit auth code. Open the Wevion Telegram bot, send /start [code]. 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 6-digit auth code (e.g. 847291) — valid 5 minutes, 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 847291

(Replace 847291 with your actual code shown in 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 (forced-on, cannot disable)

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 fresh 6-digit code

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 valid 6-digit code (5-min 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

• 6-digit code expired (>5 min): refresh /connect/telegram for a new code

• 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.

Related

• Telegram bot commands reference — all commands

• Set up notifications and Telegram alerts — user-facing intro

• Notification center — bell + all channels overview