Quick Start

Get Started in Minutes

This guide will walk you through setting up and deploying your Telegram Subscription Manager bot as quickly as possible.

Prerequisites: Make sure you have Node.js 18+, a Telegram account, MongoDB Atlas account, and Paystack account ready.

Setup Process

Create Your Telegram Bot

Open Telegram and message @BotFather:

Send /newbot command
Choose a name for your bot (e.g., “VIP Subscription Bot”)
Choose a username (must end in “bot”, e.g., “myvipchannel_bot”)
Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Keep your bot token secure! Never commit it to version control or share it publicly.

Configure Bot Commands

In BotFather, send /setcommands, select your bot, and 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

Get Your Channel ID

You need to get the ID of your private Telegram channel:

Forward any message from your channel to @userinfobot
The bot will reply with channel details
Copy the channel ID (format: -100xxxxxxxxxx)
Add your bot as an administrator to the channel
Grant these permissions:
- ✅ Invite users via link
- ✅ Restrict members (ban/unban)

Without admin permissions, the bot cannot create invite links or remove expired users.

Clone and Install

Get the project code and install dependencies:

# Clone the repository
git clone <your-repo-url>
cd telegram-subscription-manager

# Install dependencies
npm install

Configure Environment Variables

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

.env.local

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
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

# Cron Security (generate a random string)
CRON_SECRET=your_random_secret_string_here

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

Where to get these values

TELEGRAM_BOT_TOKEN: From BotFather (Step 1)
TELEGRAM_CHANNEL_ID: From userinfobot (Step 3)
PAYSTACK_SECRET_KEY: From Paystack Dashboard → Settings → API Keys
DATABASE_URL: From MongoDB Atlas → Database → Connect → Application
CRON_SECRET: Generate a random string (e.g., use openssl rand -hex 32 in terminal)

Setup MongoDB Database

Initialize your database schema:

# Generate Prisma client
npx prisma generate

# Push schema to MongoDB (creates collections)
npx prisma db push

MongoDB doesn’t use migrations like SQL databases. The db push command creates or updates collections based on your schema.

Run Locally

Start the development server:

npm run dev

Your bot should now be running at http://localhost:3000.

The bot won’t respond yet because Telegram doesn’t know your local server’s URL. Continue to the next step.

Setup Webhook (Development)

For local testing, use ngrok to create a public URL:

# Install ngrok (or use npx)
npx ngrok http 3000

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

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

Or visit this URL in your browser:

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"}

Test Your Bot

Open Telegram and message your bot:

Send /start - You should see the welcome message with plan details
Send /pay - Provide an email and receive payment buttons
Click a payment button - Complete a test transaction on Paystack
Send /verify_basic <reference> - The bot should verify and send an invite link

Use Paystack test mode initially. Test cards are available in the Paystack documentation.

Deploy to Production

Vercel
Other Platforms

Deploy to Vercel (Recommended)

Push to GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-github-repo-url>
git push -u origin main

Import to Vercel

Go to vercel.com and sign in
Click “Add New” → “Project”
Import your GitHub repository
Click “Deploy”

Add Environment Variables

In Vercel dashboard:

Go to your project → Settings → Environment Variables
Add all variables from your .env.local file
Update NEXT_PUBLIC_APP_URL to your Vercel domain (e.g., https://your-bot.vercel.app)
Redeploy the project

Configure Cron Job

Create vercel.json in your project root:

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/remove-expired",
      "schedule": "0 * * * *"
    }
  ]
}

This runs the expiry check every hour at minute 0.

Update Webhook URL

Set your production webhook URL:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-bot.vercel.app/api/telegram/webhook"

Vercel automatically handles SSL certificates, so your webhook URL will be HTTPS (required by Telegram).

Deploy to Other Platforms

The bot can be deployed to any platform that supports Next.js:

Railway: Easy deployment with automatic HTTPS
Render: Free tier available with build commands
DigitalOcean App Platform: Managed hosting with scaling
AWS Amplify: Full AWS integration

General Requirements:

Node.js 18+ runtime
Support for Next.js 16
Environment variable configuration
HTTPS endpoint for webhook
Cron job or scheduled task support for /api/cron/remove-expired

Make sure your platform supports scheduled tasks for the auto-removal cron job. Without it, expired users won’t be automatically removed.

Verification Checklist

Before going live, verify everything works:

Bot Functionality

/start shows welcome message with all plans
/pay collects email and shows payment buttons
Payment links open correctly in browser
Test payments are processed by Paystack
/verify_basic verifies payment and sends invite link
Invite links allow joining the channel
/status shows correct subscription details
/help displays help information

Admin Features

Set your admin user ID in src/lib/config.ts (line 52)
Test /broadcast sends messages to all users
Test /botstats shows user statistics
Test /checkuser looks up user subscriptions

Security

Environment variables are not committed to git
.env.local is in .gitignore
Paystack webhook signature verification is enabled
Cron endpoint is protected with CRON_SECRET
Bot token is kept secret

Subscription Expiry

Cron job is configured to run hourly
Test that expired subscriptions are detected
Users are removed from channel when expired
Expiry notifications are sent to users

Common Issues

Bot doesn't respond to commands

Possible causes:

Webhook URL is incorrect or not set
Server is not running or unreachable
Bot token is invalid
Environment variables not loaded

Solutions:

Check webhook status: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo
Verify server is running and accessible
Check server logs for errors
Confirm environment variables are set correctly

Invite links don't work

Possible causes:

Bot is not an admin in the channel
Bot lacks “Invite users” permission
User is banned from the channel

Solutions:

Verify bot is admin with correct permissions
Try unbanning the user manually first
Check channel ID is correct (must start with -100)

Payment verification fails

Possible causes:

Paystack secret key is incorrect
Transaction reference is invalid
Payment status is not “success”
Payment amount doesn’t match plan

Solutions:

Verify Paystack secret key is correct
Check payment status in Paystack dashboard
Ensure reference is copied correctly
Check payment amount matches expected plan amount

Cron job not running

Possible causes:

Cron not configured on hosting platform
CRON_SECRET mismatch
Endpoint returns error

Solutions:

Verify vercel.json cron configuration
Check Vercel cron logs in dashboard
Manually test endpoint: curl -H "Authorization: Bearer <CRON_SECRET>" https://your-bot.vercel.app/api/cron/remove-expired

Next Steps

Customize Plans

Learn how to modify pricing and features

Setup Premium Features

Configure the MT5 Auto Copier integration

API Reference

Explore webhook endpoints and integrations

Troubleshooting

Detailed solutions for common problems

InstallationComplete installation guide with prerequisites and detailed configuration

⌘I

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Get Started in Minutes
Setup Process
Deploy to Production
Verification Checklist
Common Issues
Next Steps

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Features

Configuration

Deployment

Admin Guide

Get Started in Minutes

Setup Process

Deploy to Production

Deploy to Vercel (Recommended)

Deploy to Other Platforms

Verification Checklist

Common Issues

Next Steps

Customize Plans

Setup Premium Features

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Admin Guide

​Get Started in Minutes

​Setup Process

​Deploy to Production

​Deploy to Vercel (Recommended)

​Deploy to Other Platforms

​Verification Checklist

​Common Issues

​Next Steps

Customize Plans

Setup Premium Features

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started in Minutes

Setup Process

Deploy to Production

Deploy to Vercel (Recommended)

Deploy to Other Platforms

Verification Checklist

Common Issues

Next Steps