Telegram Bot Widgets

The Chat module includes a Telegram bot that provides live-updating widgets — pinned messages in Telegram chats that automatically refresh with real-time data from the platform. Widgets work in both private and group Telegram chats.

How Widgets Work

1. User sends a command (e.g., /mybalance) to the Telegram bot
2. Bot creates a pinned message with current data
3. Message auto-refreshes at configured intervals (1–5 minutes)
4. Widget persists for up to 40 hours, then automatically recreates

Each widget is a self-contained mini-dashboard inside Telegram — no need to open a browser or PWA.

Built-in Widgets

User Widgets

Available to any user who has linked their Telegram account:

Command	Name	Description	Refresh
/menu	Menu	List of all available widgets (filtered by permissions)	Static
/rates	Rates	Currency exchange rates with base currency toggle (EUR/USD/BTC)	5 min
/mybalance	My Balance	Personal wallet balances across all currencies	5 min
/myorders	My Orders	Recent transactions with alerts for new activity	3 min

Admin Widgets

Available only to users with specific permissions (scopes) assigned in AuthProxy:

Command	Name	Required Scope	Description	Refresh
/health	Health	chat.admin	Module availability monitoring (AuthProxy, TrexWallet, CRM, Core, Chat)	1 min
/orders	Orders	chat.sensitive	All TrexWallet transactions (system-wide monitoring)	2 min
/users	Users	chat.sensitive	CRM activity (registrations, updates, status changes)	3 min

The Menu Widget

The /menu command shows a personalized list of available widgets:

• My widgets section — user widgets available to everyone
• Admin widgets section — only shown if the user has the required scopes

Widgets the user doesn't have access to are not displayed.

Widget Controls

Every widget includes standard control buttons:

Button	Action	Who Can Use
Stop	Stop and delete the widget	Creator only
Refresh	Force immediate data refresh	Anyone
Snapshot	Send current data as a separate message (for sharing)	Anyone
Recreate	Move widget to the top of the chat (new pinned message)	Creator only

Scope-Based Authorization

Widget access is controlled through AuthProxy scopes:

Scope	Grants Access To
chat.admin	Bot management, health monitoring, system settings
chat.sensitive	Viewing all transactions, user data, CRM activity
chat.wallet.ops	Wallet operations (transfers, swaps) via widget actions

Authorization flow: Telegram ID → CRM lookup → AuthProxy scope check. Results are cached for 10 minutes.

Creating Custom Widgets

Custom widgets are registered through the Chat module extension mechanism and can be limited by scope. Users without the required scope cannot create or operate admin widgets.

Widget Lifecycle

sequenceDiagram
    participant User as Telegram User
    participant Bot as Chat Bot
    participant DB as Database

    User->>Bot: /mybalance
    Bot->>Bot: Check scope (if admin widget)
    Bot->>User: Send pinned message (placeholder)
    Bot->>DB: Persist widget record
    loop Every RefreshInterval
        Bot->>Bot: BuildContent() + BuildKeyboard()
        Bot->>User: EditMessageText (update pinned message)
    end
    Note over Bot: After 40 hours
    Bot->>User: Recreate (new pinned message)
    Bot->>DB: Update record

Configuration

The Telegram bot token is configured in the Chat module's appsettings.json:

{
  "TelegramBot": "bot_token_from_botfather"
}

To set up the bot:

1. Create a bot via @BotFather in Telegram
2. Use /setdomain to set the bot's allowed domain
3. Add the bot token to the Chat module configuration
4. Bot automatically starts and registers all discovered widgets

Related

• Chat Module — full Chat module documentation
• Chat Calls — WebRTC audio/video calls
• AuthProxy — OAuth Providers — Telegram as auth method