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 mapping translates the 22 notification types to 13 alert preference toggles in telegram_notification_pref.

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 full list of available commands + brief description of each.

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 each of the 22 notification types to one of the 13 alert toggles in telegram_notification_pref:

(Note: some notification types share toggles for grouping. isNotificationTypeEnabled(prefs, notificationType) returns true if the mapped toggle is enabled, true if no preference row exists.)

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/preferences
Body:
{
  "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)

Related

• Connect Telegram — initial setup

• Telegram digest — daily + weekly summaries

• Customize notifications — full preference management