5 bot commands: /start, /status, /stats, /help, /unlink. Webhook + polling fallback. NOTIFICATION_TYPE_TO_PREF maps notification keys to Telegram preferences.

Telegram bot commands

The Wevion Telegram bot supports 5 commands verified in apps/backend/src/services/telegram-bot.service.ts: /start, /status, /stats, /help, /unlink. Delivery via webhook (POST /api/v1/telegram/webhook with secret-header verification) + polling fallback. NOTIFICATION_TYPE_TO_PREF maps selected notification keys to alert_* preference fields, with billing routed to the payment-issue preference.

Who is this for

Anyone using the Wevion Telegram bot. Reference for what each command does.

The 5 commands

/start

Purpose: initial setup / link conversation.

When you click a Wevion deep_link (see ntf-104) and open Telegram, the bot typically auto-starts. If not: send /start manually.

Bot responds with:

• Welcome message
• Confirmation of link to Wevion account (or prompt to use deep_link if no token)
• Brief command list

If already linked: bot confirms existing link with username + first_name from your Telegram profile.

/status

Purpose: check link status + account context.

Bot responds with:

• Linked: yes / no
• Linked Wevion user (your email or display name)
• Workspace / team you're linked to
• Active alert preferences summary

Useful to verify bot is working + you're seeing notifications for the right account.

/stats

Purpose: recent activity summary.

Bot responds with concise stats:

• Recent campaigns activity
• Recent rule executions
• Recent sync events
• Recent spend

Read-only digest of current account state. Lighter than the full digest (ntf-106).

/help

Purpose: command reference.

Bot responds with the list of commands + a brief description of each. Note: the /help output lists /stats, /status, /unlink, and /help — it does not list /start (which is used only during initial linking).

Useful as a refresher when you forget what's available.

/unlink

Purpose: remove the Telegram link from your Wevion account.

Bot confirms unlink:

• telegram_link.is_active = false (server-side)
• No more notifications sent to this Telegram chat
• You can re-link anytime via deep_link

Same effect as DELETE /api/v1/telegram/unlink API call.

Delivery: webhook + polling

The bot can receive Telegram updates two ways:

Switch configured at deployment level (admin task).

NOTIFICATION_TYPE_TO_PREF mapping

In telegram-bot.service.ts, the NOTIFICATION_TYPE_TO_PREF constant maps the current Telegram notification keys to the available alert_* fields in telegram_notification_pref:

(Note: notification types not present in this mapping fall back to enabled. isNotificationTypeEnabled(prefs, notificationType) returns true if the mapped toggle is enabled, true if no preference row exists, and true for unknown notification types.)

How isNotificationTypeEnabled works

When a notification needs to be sent via Telegram:

1. Backend lookups telegram_notification_pref row for the user
2. If no row exists: default true (notifications enabled by default)
3. If row exists: look up the mapped toggle for this notification type
4. Return toggle value (true = send, false = skip)

This means: opt-in by default. User must explicitly disable via PUT /api/v1/telegram/preferences.

Preference management via PUT /preferences

To customize toggles:

PUT /api/v1/telegram/preferencesBody:{  "alert_account_status": true,  "alert_spend_cap": true,  "alert_sync_completed": false,  "alert_sync_failed": true,  ...  "daily_digest_enabled": true,  "daily_digest_hour": 9,  "digest_timezone": "Europe/Rome"}

Partial update — only fields you provide are changed.

Bot blocking auto-recovery

If you block the bot in Telegram (or delete the chat):

• Next Wevion send fails with 403 from Telegram API
• Worker sets telegram_link.is_active = false
• No further sends attempted
• Status visible via GET /api/v1/telegram/status (linked=false)

To re-enable: unblock the bot in Telegram → unlink in Wevion (via UI or /unlink) → re-link via deep_link.

Multiple users, one bot

The same Wevion deployment uses one bot for all users. Each user has their own telegram_link row → their own chat → their own preferences.

The bot can serve thousands of users simultaneously (Telegram bot infrastructure handles it).

Bot also used for tracker (separate workflow)

The same bot infrastructure may also handle tracker postback callbacks (separate from notifications — see com-114 Telegram bot setup). The two workflows share the bot but are independent: setting up tracker doesn't enable notifications, and vice versa.

Common questions

Why doesn't /start auto-link me?

/start only confirms an existing link. To create a link: trigger from Wevion UI (/settings → Notifications → Connect Telegram) which generates a deep_link with a token.

Can the bot respond to natural language questions?

No. The bot is a fixed-command bot. For conversational AI: use Wavo inside Wevion (/chat — see ai-101).

Can I create custom commands?

No. The 5 commands are platform-fixed.

Can I forward bot messages to other Telegram chats?

You can forward manually (Telegram's standard forward). The bot can only send to its linked chat, not to groups (by default).

Bot in a group chat?

Currently: per-user link only (1:1 chat with the bot). Group chat support is not enabled.

Common issues

• Bot doesn't respond to /start: deployment's bot not configured (admin task — see com-114)
• Bot responds in wrong language: bot language is fixed at deployment level
• /status shows linked=false but you just connected: brief lag; try again in a few seconds
• /unlink doesn't work: send command directly to bot; if persistent, unlink via Wevion UI (DELETE /unlink)
• Receiving notifications for actions you didn't take: owner fan-out (you're an owner; team members' actions notify you)

FAQ

What commands does the Wevion Telegram bot support?

The Wevion Telegram bot supports five fixed commands: /start to set up or confirm the link, /status to check link status and account context, /stats for a recent activity summary, /help for the command reference, and /unlink to remove the link. You cannot create custom commands — the set is platform-fixed.

Are Telegram notifications on by default?

Yes, Telegram notifications are opt-in by default in Wevion. When a notification needs sending, isNotificationTypeEnabled checks your telegram_notification_pref row: if no row exists it defaults to true, and unknown notification types also default to true. To silence specific alerts, disable the mapped alert_* toggles via PUT /api/v1/telegram/preferences.

Can the Wevion Telegram bot answer natural-language questions?

No. The Wevion Telegram bot is a fixed-command bot that only understands its five commands — it cannot answer free-form questions. For conversational AI over your account data, use Wavo inside Wevion at /chat. The two are separate: the bot delivers notifications, while Wavo handles interactive questions and actions.

Can I add the Wevion bot to a group chat?

No. The Wevion bot supports per-user linking only — a 1:1 chat between you and the bot — and it can only send to its linked chat, not to groups. Group chat support isn't enabled. You can still manually forward individual bot messages to other chats using Telegram's standard forward feature.

Steps

1. Backend lookups telegramnotificationpref row for the user
2. If no row exists: default true (notifications enabled by default)
3. If row exists: look up the mapped toggle for this notification type
4. Return toggle value (true = send, false = skip)

Last updated: 2026-05-17

Related articles

• Connect Telegram for real-time alerts
• Telegram digest — daily and weekly reports
• Customize notification preferences