Telegram Bot

Overview

MysticX has a Telegram bot (@MysticXAliceBot) that provides the full AI tarot reading experience inside Telegram. The bot runs as a standalone process using grammY with long polling.

Commands

Command	Description
/start	Welcome message with quick actions
/draw	Quick one-card draw
/daily	Card of the day (static)
/reading	Full AI reading with spread picker and question prompt
/spread	Static card draw (no AI interpretation)
/spreads	List all available spreads
/connect	Link Telegram account to MysticX web account
/disconnect	Unlink Telegram account

Shortcut Syntax

Power users can combine command and question:

/reading love-deep Is this the right person for me?

Architecture

The bot does NOT use BullMQ. Instead, it makes internal HTTP calls to the Next.js API:

Telegram Bot (grammY long-poll)
       │
       ▼
POST /api/v1/internal/readings/create
       │  (protected by INTERNAL_API_KEY header)
       ▼
Next.js Server
       │  → Creates reading
       │  → Calls Gemini directly
       │  → Returns structured reading
       ▼
Bot formats and sends section-by-section

This simplifies the async flow since Telegram has its own delivery mechanism.

Reading Flow

1. User sends /reading or taps inline button
2. Bot shows inline keyboard spread picker (13 spreads in 7 rows)
3. User selects a spread
4. Bot prompts for a question
5. Bot calls internal API to create reading
6. Bot sends reading progressively, section by section:
   • Card images
   • Summary
   • Per-card interpretations
   • Practical advice
   • Luck enhancement tips
7. Complete reading delivered in ~10-30 seconds

Account Linking

Users can link their Telegram account to their MysticX web account to enable:

• Follow-up chat messages
• Reading history sync
• Credit-based features

Linking flow:

1. User clicks /connect in Telegram
2. Bot generates a deep link: t.me/MysticXAliceBot?start=link_{code}
3. User visits the link and authenticates on the web
4. TelegramLink record created, associating Telegram ID with user ID

Unlinked users can still do readings but cannot use follow-ups.

Configuration

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from @BotFather
TELEGRAM_BOT_ENABLED	Set to false to disable (default: true)
INTERNAL_API_KEY	Shared secret for bot-to-API authentication

Deployment

The bot runs as a PM2 process (mysticx-telegram-bot) with:

• Single instance (fork mode)
• 256 MB memory limit
• Auto-restart on crashes
• Separate log files: logs/telegram-bot-*.log