Skip to main content
The Telegram Subscription Manager requires several environment variables to function properly. These variables configure your bot’s connection to Telegram, Paystack payment gateway, database, and security settings.

​
Required Variables

​
TELEGRAM_BOT_TOKEN
string
required
Your Telegram bot token from BotFather.Format: 123456:ABC-DEF...How to get it:
  1. Open Telegram and search for @BotFather
  2. Send /newbot command
  3. Follow prompts to name your bot
  4. Copy the bot token provided
​
TELEGRAM_CHANNEL_ID
string
required
The ID of your private Telegram channel where users will be added.Format: -100xxxxxxxxxxHow to get it:
  1. Forward a message from your private channel to @userinfobot
  2. Copy the channel ID from the response
  3. Add your bot as an administrator to the channel with these permissions:
    • ✅ Invite users via link
    • ✅ Restrict members
​
PAYSTACK_SECRET_KEY
string
required
Your Paystack API secret key for payment verification.Format: sk_live_... or sk_test_...How to get it:
  1. Log in to Paystack Dashboard
  2. Go to Settings → API Keys
  3. Copy your Secret Key
Never commit your secret key to version control. Always use environment variables.
​
DATABASE_URL
string
required
MongoDB connection string for storing user subscriptions and payment records.Format: mongodb+srv://username:[email protected]/databaseHow to set it up:
  1. Create a free account at MongoDB Atlas
  2. Create a new cluster (M0 free tier works)
  3. Create a database user
  4. Whitelist IP 0.0.0.0/0 (required for Vercel)
  5. Copy the connection string and replace <username> and <password> with your credentials
​
CRON_SECRET
string
required
A secret key used to authenticate cron job requests for removing expired users.How to generate:
openssl rand -base64 32
This prevents unauthorized access to your cron endpoint at /api/cron/remove-expired.
​
NEXT_PUBLIC_APP_URL
string
required
The public URL where your application is deployed.Examples:
  • Development: http://localhost:3000
  • Production: https://your-domain.vercel.app
This variable is prefixed with NEXT_PUBLIC_ which means it’s accessible on the client side.

​
Setting Up Locally

  1. Create environment file: 
    cp .env.example .env.local
  2. Edit .env.local with your credentials: 
    # Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHANNEL_ID=your_channel_id

# Paystack Configuration
PAYSTACK_SECRET_KEY=sk_live_your_paystack_secret_key

# Database Configuration
DATABASE_URL=mongodb+srv://username:[email protected]/database

# Cron Security
CRON_SECRET=generate_a_random_secret_string_here

# Application Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
  3. Initialize the database: 
    npx prisma generate
npx prisma db push

​
Deploying to Vercel

When deploying to Vercel, you need to add all environment variables to your project settings:
  1. Go to your project in Vercel Dashboard
  2. Navigate to Settings → Environment Variables
  3. Add each variable listed above
  4. Deploy your application
# After deploying, set your webhook URL
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.vercel.app/api/telegram/webhook"

​
Testing Environment

For testing, you can use Paystack’s test mode:
  1. Get test API keys from Paystack dashboard (starts with sk_test_)
  2. Use PAYSTACK_SECRET_KEY=sk_test_... in your .env.local
  3. Make test payments using Paystack’s test payment page
  4. Verify with test transaction references
Always use test keys in development and live keys only in production.

​
Security Best Practices

  • Never commit .env.local to version control (add it to .gitignore)
  • Use strong secrets for CRON_SECRET in production
  • Enable HTTPS on your production domain
  • Monitor logs for suspicious webhook activity
  • Rotate keys regularly if you suspect they’ve been compromised

​
Troubleshooting

​
Bot Not Responding

  • Verify TELEGRAM_BOT_TOKEN is correct
  • Check that webhook is set to the correct URL
  • Ensure all environment variables are loaded in Vercel

​
Payment Verification Failing

  • Confirm PAYSTACK_SECRET_KEY is correct and matches the environment (test vs live)
  • Verify transaction references are from the same Paystack account
  • Check that payment status is “success”

​
Database Connection Issues

  • Ensure DATABASE_URL is correctly formatted
  • Verify IP whitelist includes 0.0.0.0/0 in MongoDB Atlas
  • Check database user credentials are correct

​
Cron Job Not Running

  • Verify CRON_SECRET matches in both code and Vercel environment variables
  • Check Vercel cron logs for errors
  • Ensure the endpoint returns 200 status

Build docs developers (and LLMs) love

Get started for freeTalk to us