Telegram Bot Setup

Overview

Setting up your Telegram bot is the first step in deploying the Subscription Manager. This guide covers creating your bot, configuring commands, setting up your private channel, and getting the necessary credentials.

Prerequisites

A Telegram account
Telegram app (mobile or desktop)
A private Telegram channel (or create one during setup)

Create Your Bot

Open BotFather

Open Telegram and search for @BotFather or click here
Start a conversation by clicking “Start” or sending /start

BotFather is Telegram’s official bot for creating and managing bots.

Create New Bot

Send the /newbot command to BotFather.BotFather will ask you two questions:1. Choose a name for your bot:

VIP Subscription Bot

This is the display name users will see.2. Choose a username for your bot:

myvip_subscription_bot

Username requirements:

Must end with bot (e.g., my_bot or MyBot)
Must be unique across all Telegram
Can only contain letters, numbers, and underscores

Save Bot Token

BotFather will respond with your bot token:

Done! Congratulations on your new bot. You will find it at t.me/myvip_subscription_bot. 
You can now add a description, about section and profile picture for your bot.

Use this token to access the HTTP API:
123456789:ABCdefGhIJKlmNoPQRstuVWXyz1234567890

Keep your token secure and store it safely, it can be used by anyone to control your bot.

Copy and save this token securely - you’ll need it for your environment variables.

Never share your bot token publicly! Anyone with this token can control your bot.

Configure Bot Commands

Set up bot commands so users can see available commands in the Telegram menu.

Open Command Editor

In your conversation with BotFather, send:

/setcommands

BotFather will show a list of your bots. Click on the bot you just created.

Set Commands

Copy and paste the following command list:

start - Welcome message and payment instructions
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 your current subscription status
help - Show help and payment instructions

BotFather will confirm:

Success! Command list updated. /help

Users can now see these commands by typing / in the chat with your bot.

Create Private Channel

Your bot will manage access to a private Telegram channel where subscribers receive content.

Create Channel

Open Telegram
Click the menu (☰) → “New Channel”
Enter channel name (e.g., “VIP Signals Channel”)
Add a description
Click “Create”

Make Channel Private

When asked to choose channel type:

Select “Private Channel”
Optionally set a custom invite link (not required)
Click “Save”

The channel MUST be private! Public channels won’t work with this bot system.

Get Channel ID

To get your channel ID, you need to forward a message to a special bot:

Post a message in your private channel (any message works)
Forward that message to @userinfobot
The bot will reply with information including the channel ID

Look for a line like:

Chat: -1001234567890

Or:

"chat": {
  "id": -1001234567890,
  "title": "VIP Signals Channel",
  "type": "channel"
}

Save this channel ID - it will be your TELEGRAM_CHANNEL_ID environment variable.

Channel IDs always start with -100 and are negative numbers.

Add Bot as Administrator

Your bot needs admin permissions to manage channel members:

Go to your private channel
Click channel name → “Administrators”
Click “Add Administrator”
Search for your bot by username (e.g., @myvip_subscription_bot)
Select your bot

Required Permissions:

Essential Permissions (Required)

✅ Invite users via link - Allows bot to create invite links
✅ Restrict members - Allows bot to ban/unban users

Optional Permissions (Recommended to Disable)

❌ Change channel info
❌ Post messages
❌ Edit messages
❌ Delete messages
❌ Add new administrators

Click “Done” to save

Without proper permissions, the bot cannot create invite links or manage expired subscriptions!

Configuration Variables

You now have two critical values for your environment configuration:

TELEGRAM_BOT_TOKEN

The token you received from BotFather:

123456789:ABCdefGhIJKlmNoPQRstuVWXyz1234567890

Add to your .env.local:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRstuVWXyz1234567890

TELEGRAM_CHANNEL_ID

The channel ID from @userinfobot:

-1001234567890

Add to your .env.local:

TELEGRAM_CHANNEL_ID=-1001234567890

These variables will also be added to your Vercel deployment settings.

Set Webhook (After Deployment)

The webhook connects Telegram to your deployed application. You’ll set this up after deploying to Vercel.

Skip this section for now and return after completing the Vercel deployment.

Once deployed, set your webhook:

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

Replace:

<YOUR_BOT_TOKEN> with your actual bot token
your-app.vercel.app with your Vercel deployment URL

Expected Response:

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

Verify Webhook

Check webhook status:

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

Successful Response:

{
  "ok": true,
  "result": {
    "url": "https://your-app.vercel.app/api/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "max_connections": 40
  }
}

If pending_update_count is 0, your webhook is working correctly!

Test Your Bot

Verify everything is working:

Start Conversation

Open Telegram
Search for your bot by username (e.g., @myvip_subscription_bot)
Click “Start” or send /start

Verify Response

Your bot should respond with a welcome message showing:

Available subscription plans
Prices and durations
Payment instructions
Bank account details

If the bot doesn’t respond:

Check webhook is set correctly
Verify environment variables in Vercel
Check Vercel function logs for errors

Test Commands

Try each command:

/help - Should show payment instructions
/status - Should show “No active subscription”
Type / to see all available commands in the menu

Customization Options

Change Bot Profile Picture

Send /setuserpic to BotFather
Select your bot
Upload an image (square images work best)

Set Bot Description

This appears when users first open your bot:

Send /setdescription to BotFather
Select your bot
Enter description:

Welcome to VIP Subscription Manager! 

Get access to premium trading signals with flexible subscription plans. Pay with Paystack and get instant access to our exclusive VIP channel.

Set About Text

This appears in the bot’s profile:

Send /setabouttext to BotFather
Select your bot
Enter about text:

Automated subscription management bot for VIP channel access. Secure payments via Paystack.

Troubleshooting

Bot Not Responding to Commands

Possible causes:

Webhook not set:

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

If url is empty, set the webhook.

Wrong webhook URL: Verify URL matches your Vercel deployment.
Vercel deployment issues: Check Vercel function logs for errors.
Environment variables missing: Verify TELEGRAM_BOT_TOKEN is set in Vercel.

Cannot Create Invite Links

Solution: Check bot permissions in channel:

Go to channel → Administrators
Click on your bot
Ensure “Invite users via link” is enabled
Ensure “Restrict members” is enabled

Test permissions: Try manually creating an invite link through the bot:

If it works, permissions are correct
If it fails with “not enough rights”, add the permissions

Channel ID Not Working

Verify channel ID format:

Must be a negative number
Must start with -100
Example: -1001234567890

Get channel ID alternative method:

Make your bot an admin first
Send a test message from bot to channel
Check the API response for the chat ID

Users Getting 'User Not Found' Errors

This happens when trying to remove users who:

Have never joined the channel
Already left the channel
Blocked the bot

Solution: The app handles this gracefully - no action needed. The error is logged but doesn’t affect functionality.

Security Best Practices

Protect Your Bot Token:

Never commit .env.local to Git
Never share bot token publicly
Regenerate token if compromised (use /revoke in BotFather)

Rate Limiting: The bot includes built-in rate limiting (4 failed attempts = 1 hour block) to prevent abuse.

Next Steps

Now that your Telegram bot is configured, proceed with:

Paystack Setup

Configure payment processing

Database Setup

Set up MongoDB and Prisma

Get Started

Core Features

Configuration

Deployment

Admin Guide

Overview

Prerequisites

Create Your Bot

Configure Bot Commands

Create Private Channel

Configuration Variables

TELEGRAM_BOT_TOKEN

TELEGRAM_CHANNEL_ID

Set Webhook (After Deployment)

Verify Webhook

Test Your Bot

Customization Options

Change Bot Profile Picture

Set Bot Description

Set About Text

Troubleshooting

Security Best Practices

Next Steps

Paystack Setup

Database Setup

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Admin Guide

​Overview

​Prerequisites

​Create Your Bot

​Configure Bot Commands

​Create Private Channel

​Configuration Variables

​TELEGRAM_BOT_TOKEN

​TELEGRAM_CHANNEL_ID

​Set Webhook (After Deployment)

​Verify Webhook

​Test Your Bot

​Customization Options

​Change Bot Profile Picture

​Set Bot Description

​Set About Text

​Troubleshooting

​Security Best Practices

​Next Steps

Paystack Setup

Database Setup

Build docs developers (and LLMs) love

Overview

Prerequisites

Create Your Bot

Configure Bot Commands

Create Private Channel

Configuration Variables

TELEGRAM_BOT_TOKEN

TELEGRAM_CHANNEL_ID

Set Webhook (After Deployment)

Verify Webhook

Test Your Bot

Customization Options

Change Bot Profile Picture

Set Bot Description

Set About Text

Troubleshooting

Security Best Practices

Next Steps