Installation

Prerequisites

Before installing the Telegram Subscription Manager, ensure you have the following:

Node.js 18 or higher

The bot requires Node.js 18+ for modern JavaScript features and Next.js 16 compatibility.Check your version:

node --version

Install/Update Node.js:

Download from nodejs.org
Or use nvm for version management

MongoDB Atlas Account

MongoDB is used to store subscriptions, user data, and MT5 configurations.Setup Steps:

Create free account at mongodb.com/cloud/atlas
Create a new cluster (M0 free tier is sufficient for most use cases)
Create a database user with read/write permissions
Whitelist IP address 0.0.0.0/0 (allows connections from Vercel)
Get your connection string (format: mongodb+srv://username:[email protected]/database)

Keep your database credentials secure. Use a strong password and never commit it to version control.

Paystack Account

Paystack processes payments from Nigerian users.Setup Steps:

Sign up at paystack.com
Complete business verification (required for live mode)
Go to Settings → API Keys
Copy your Secret Key (starts with sk_live_ or sk_test_)

Start with test mode (sk_test_) during development. Switch to live mode (sk_live_) when ready for production.

Telegram Account

You’ll need a Telegram account to create and manage your bot.What you’ll do:

Create a bot via @BotFather
Create a private channel for VIP members
Configure bot commands and permissions

MetaCopier Account (Optional)

Required only if you plan to offer Premium plan with MT5 Auto Copier.Setup Steps:

Sign up at metacopier.com
Get your API credentials
Configure master trading account
Add credentials to environment variables

The bot works perfectly without MetaCopier for Basic, Bi-Weekly, and Monthly plans. Premium features require MetaCopier integration.

Installation Steps

1. Telegram Bot Setup

Create Bot with BotFather

Open Telegram and search for @BotFather:

Send /newbot command
Provide a display name (e.g., “VIP Signals Bot”)
Provide a username ending in “bot” (e.g., “vipsignals_bot”)
Save the bot token provided (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

You: /newbot
BotFather: Alright, a new bot. How are we going to call it?
You: VIP Signals Bot
BotFather: Good. Now let's choose a username for your bot.
You: vipsignals_bot
BotFather: Done! Your token is 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Configure Bot Commands

Tell BotFather about your bot’s commands. Send /setcommands to BotFather, select your bot, then paste:

start - Welcome message and payment instructions
pay - Get payment link for subscription
verify_basic - Verify Basic plan payment (7 days)
verify_biweekly - Verify Bi-Weekly plan payment (14 days)
verify_monthly - Verify Monthly plan payment (30 days)
verify_premium - Verify Premium plan payment (14 days + copier)
verify_promo - Verify promo code payment
status - Check subscription status
mt5setup - Setup MT5 Auto Copier (Premium only)
settings - Configure copier settings (Premium only)
mystats - View copier statistics (Premium only)
help - Show help and instructions

This enables auto-complete when users type / in the chat.

Create Private Channel

Create a private Telegram channel for your VIP members:

Open Telegram and create a new channel
Set it to Private
Name it (e.g., “VIP Signals Channel”)
Add some initial content

Get Channel ID

You need the numeric ID of your channel:

Forward any message from your channel to @userinfobot
The bot will reply with details including the channel ID
Copy the ID (format: -100xxxxxxxxxx)

Channel IDs always start with -100 for supergroups and channels.

Add Bot as Channel Admin

Your bot needs admin permissions to manage the channel:

Open your private channel
Go to channel settings → Administrators
Click “Add Administrator”
Search for your bot by username
Grant these permissions:
- ✅ Invite users via link (required for sending invite links)
- ✅ Restrict members (required for banning expired users)
Save changes

Without these permissions, the bot cannot add or remove users automatically.

2. Project Setup

Clone Repository

Get the source code:

git clone <your-repository-url>
cd telegram-subscription-manager

Install Dependencies

Install all required npm packages:

npm install

This installs:

Next.js 16 (framework)
Prisma (database ORM)
React 19 (UI library)
TypeScript (type safety)

Configure Environment Variables

Create a .env.local file in the project root:

.env.local

# ===========================
# Telegram Configuration
# ===========================
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHANNEL_ID=-100xxxxxxxxxx

# ===========================
# Paystack Configuration
# ===========================
PAYSTACK_SECRET_KEY=sk_test_your_paystack_secret_key

# ===========================
# Database Configuration
# ===========================
DATABASE_URL=mongodb+srv://username:[email protected]/vipbot?retryWrites=true&w=majority

# ===========================
# Security
# ===========================
# Generate a random string for cron job authentication
CRON_SECRET=your_random_secret_string_here

# ===========================
# Application
# ===========================
NEXT_PUBLIC_APP_URL=http://localhost:3000

# ===========================
# MetaCopier (Optional - Premium only)
# ===========================
# METACOPIER_API_KEY=your_metacopier_api_key
# METACOPIER_MASTER_ACCOUNT_ID=your_master_account_id

How to generate CRON_SECRET

Generate a secure random string using one of these methods:Using OpenSSL (Mac/Linux):

openssl rand -hex 32

Using Node.js:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Using online generator: Visit random.org and generate a 64-character string.

Never commit .env.local to version control. It’s already in .gitignore by default.

Initialize Database

Setup your MongoDB database with Prisma:

# Generate Prisma Client
npx prisma generate

# Push database schema (creates collections)
npx prisma db push

This creates the following collections in MongoDB:

Subscription - Stores all user subscriptions
User - Tracks all bot users
Mt5Setup - Stores MT5 account configurations (Premium)
ConversationState - Manages multi-step user flows
PromoCode - Manages promotional codes

MongoDB uses db push instead of migrations. Changes to prisma/schema.prisma can be applied with npx prisma db push.

Verify Installation

Check that everything is set up correctly:

# Start development server
npm run dev

You should see:

▲ Next.js 16.1.6
- Local:        http://localhost:3000
- Ready in 2.3s

3. Configure Subscription Plans

Customize plans to match your business model by editing src/lib/config.ts:

src/lib/config.ts

export const PLANS = {
  basic: {
    name: 'Basic VIP',
    amountKobo: 500000,  // ₦5,000 (amount in kobo)
    durationDays: 7,
    hasCopierAccess: false
  },
  biweekly: {
    name: 'Bi-Weekly VIP',
    amountKobo: 1000000,  // ₦10,000
    durationDays: 14,
    hasCopierAccess: false
  },
  monthly: {
    name: 'Monthly VIP',
    amountKobo: 1500000,  // ₦15,000
    durationDays: 30,
    hasCopierAccess: false
  },
  premium: {
    name: 'Premium VIP + Copier',
    amountKobo: 2200000,  // ₦22,000
    durationDays: 14,
    hasCopierAccess: true
  },
  promo: {
    name: 'Promo VIP',
    amountKobo: 300000,  // ₦3,000
    durationDays: 7,
    hasCopierAccess: false
  }
} as const

Paystack amounts are in kobo (smallest currency unit). ₦1,000 = 100,000 kobo.

4. Configure Bank Details (Optional)

If you want to display bank account information in messages:

src/lib/config.ts

export const BANK_DETAILS = {
  bankName: 'YOUR BANK NAME',
  accountNumber: '0123456789',
  accountName: 'Your Account Name'
}

5. Set Admin User ID

Set your Telegram user ID to access admin commands:

src/lib/config.ts

// Get your user ID from @userinfobot
export const ADMIN_ID = 123456789

Admin-only commands:

/broadcast - Send message to all users
/broadcast_active - Send to active subscribers only
/broadcast_premium - Send to premium users only
/broadcast_promo - Send promo offer with payment button
/botstats - View bot statistics
/checkuser <id|username> - Look up specific user

Development Setup

Local Testing with ngrok

For local development, use ngrok to expose your localhost to the internet:

Install ngrok

npm install -g ngrok
# or use npx (no installation needed)

Start Your Server

npm run dev

Create Tunnel

In a new terminal:

ngrok http 3000

Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

Set Webhook

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://abc123.ngrok.io/api/telegram/webhook"

You should see:

{"ok":true,"result":true,"description":"Webhook was set"}

ngrok URLs change every time you restart. You’ll need to reset the webhook each time.

Database Management

Use Prisma Studio to view and edit your database:

npx prisma studio

This opens a web interface at http://localhost:5555 where you can:

View all subscriptions
Manually edit user data
Delete test records
Check MT5 configurations

Troubleshooting

Error: Cannot find module 'prisma'

Solution:

npm install
npx prisma generate

MongoDB connection timeout

Possible causes:

Database URL is incorrect
IP address not whitelisted
Database user doesn’t have permissions

Solution:

Check your connection string format
Add 0.0.0.0/0 to MongoDB Atlas Network Access
Verify database user has read/write permissions

Bot not responding to commands

Possible causes:

Webhook not set
Server not running
Bot token invalid

Solution:

Check webhook status:

curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Verify server is running: npm run dev
Check server logs for errors
Confirm TELEGRAM_BOT_TOKEN is correct

Invite links return 'error creating invite link'

Possible causes:

Bot is not an admin in the channel
Bot lacks required permissions
Channel ID is incorrect

Solution:

Verify bot is an administrator in the channel
Check bot has “Invite users via link” permission
Confirm channel ID starts with -100
Test manually creating invite link in Telegram

Payment verification always fails

Possible causes:

Paystack secret key is wrong
Using test key in production or vice versa
Reference format is invalid

Solution:

Verify PAYSTACK_SECRET_KEY is correct
Check you’re using the right key for your environment (test vs live)
Test with Paystack test cards in test mode
Check Paystack dashboard for transaction status

TypeScript errors during build

Solution:

# Delete node_modules and reinstall
rm -rf node_modules
npm install

# Regenerate Prisma client
npx prisma generate

# Rebuild
npm run build

Next Steps

Now that installation is complete:

Quick Start

Follow the quick start guide to deploy

Deployment Guide

Deploy to production with Vercel

API Reference

Explore all webhook endpoints

Configuration

Configure environment variables and settings

Get Started

Core Features

Configuration

Deployment

Admin Guide

Prerequisites

Installation Steps

1. Telegram Bot Setup

2. Project Setup

3. Configure Subscription Plans

4. Configure Bank Details (Optional)

5. Set Admin User ID

Development Setup

Local Testing with ngrok

Database Management

Troubleshooting

Next Steps

Quick Start

Deployment Guide

API Reference

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Admin Guide

​Prerequisites

​Installation Steps

​1. Telegram Bot Setup

​2. Project Setup

​3. Configure Subscription Plans

​4. Configure Bank Details (Optional)

​5. Set Admin User ID

​Development Setup

​Local Testing with ngrok

​Database Management

​Troubleshooting

​Next Steps

Quick Start

Deployment Guide

API Reference

Configuration

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

1. Telegram Bot Setup

2. Project Setup

3. Configure Subscription Plans

4. Configure Bank Details (Optional)

5. Set Admin User ID

Development Setup

Local Testing with ngrok

Database Management

Troubleshooting

Next Steps