Skip to main content
As an admin, you can send broadcast messages to users through multiple methods: Telegram bot commands, API endpoints, or command-line scripts.

​
Broadcasting Methods

1

Using Telegram Bot Commands

The easiest way to broadcast messages directly from your Telegram client.Available commands:
  • /broadcast - Send 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
2

Using the Broadcast Script

Run broadcasts from your terminal with the Node.js script.
# Send to all users
node scripts/broadcast.mjs "🎉 Special offer! Get 20% off this week!"

# Send only to monthly plan users
node scripts/broadcast.mjs "📅 Monthly members exclusive deal!" --plan=monthly

# Send only to active premium subscribers
node scripts/broadcast.mjs "👑 Premium-only announcement!" --plan=premium --active-only
3

Using the API Endpoint

Make HTTP requests to the broadcast API for programmatic access.
curl -X POST https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "Your message here"}'

​
Bot Commands Reference

​
Send to Everyone

/broadcast Your message here
Sends your message to ALL users who have ever interacted with the bot. This includes:
  • Active subscribers
  • Expired subscribers
  • Users who just clicked /start
Use this sparingly to avoid spamming users who haven’t subscribed.

​
Send to Active Subscribers

/broadcast_active Your message here
Sends only to users with active, non-expired subscriptions. Best for:
  • Feature announcements
  • Trading signals updates
  • Engagement campaigns
This is the recommended default for most announcements.

​
Send to Premium Users

/broadcast_premium Your message here
Targets only premium plan subscribers, ideal for:
  • Auto Copier updates
  • Premium-exclusive features
  • Upsell opportunities to premium users

​
Send Promo Broadcast

/broadcast_promo
Sends a special promotional offer (₦3,000 for 7 days) to ALL users with a payment button. Each broadcast:
  • Creates FRESH payment links
  • Links expire after 48 hours
  • Includes “Verify Promo Payment” button
Promo links work ONCE only. After expiry, you need to send a new broadcast with fresh links.

​
API Endpoint Usage

​
Authentication

All broadcast API requests require the ADMIN_SECRET token: 
Authorization: Bearer YOUR_ADMIN_SECRET
IMPORTANT: Never expose ADMIN_SECRET in frontend code or public repositories. Store it securely in environment variables.

​
Send Broadcast (POST)

Endpoint: /api/admin/broadcast Request Body: 
{
  "message": "Your message here (supports HTML)",
  "planType": "basic | biweekly | monthly | premium | all",
  "activeOnly": true | false
}
Parameters:
ParameterTypeDefaultDescription
messagestringrequiredMessage content (HTML supported)
planTypestring"all"Target specific plan or all users
activeOnlybooleanfalseOnly send to active subscribers
Example Requests: 
curl -X POST https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "🎉 Special offer! 20% off all plans!"}'
Response: 
{
  "success": true,
  "message": "Broadcast sent successfully",
  "stats": {
    "total": 150,
    "successful": 142,
    "failed": 8,
    "failedUsers": ["user123", "user456"]
  }
}

​
Get Stats (GET)

Endpoint: /api/admin/broadcast Returns subscriber statistics before broadcasting: 
curl https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET"
Response: 
{
  "stats": {
    "totalUniqueUsers": 245,
    "totalSubscribers": [
      {"planType": "basic", "_count": {"telegramUserId": 50}},
      {"planType": "monthly", "_count": {"telegramUserId": 80}},
      {"planType": "premium", "_count": {"telegramUserId": 30}}
    ],
    "activeSubscribers": [
      {"planType": "basic", "_count": {"telegramUserId": 20}},
      {"planType": "monthly", "_count": {"telegramUserId": 45}},
      {"planType": "premium", "_count": {"telegramUserId": 15}}
    ]
  }
}

​
Message Formatting

Telegram supports HTML formatting in broadcast messages: 
<b>Bold text</b>
<i>Italic text</i>
<code>Code</code>
<a href="https://example.com">Link</a>
<pre>Preformatted text</pre>

​
Example Messages

🎉 <b>Flash Sale!</b>

Get 20% off all plans this weekend!

Use code: WEEKEND20

Valid until Sunday midnight.

👑 <b>Upgrade to Premium!</b>

━━━━━━━━━━━━━━━━━━━

Get access to our exclusive Auto Copier Bot!

💎 Perfect for:
• Busy traders
• Passive income seekers
• Automated trading

📈 85% of our premium members see results within 2 weeks!

Upgrade now: /pay

🆕 <b>New Feature Alert!</b>

We're excited to announce daily market analysis!

📊 What you'll get:
• Pre-market analysis
• Trade setups
• Risk management tips
• And much more!

Already included in your subscription.

​
Best Practices

1

Keep Messages Short

Under 200 characters gets the best engagement. Users scan quickly on mobile.
2

Use Emojis

Makes messages more engaging and easier to scan. Don’t overdo it.
3

Include Call-to-Action

Tell users what to do next: /pay, click link, check channel, etc.
4

Time It Right

Send during trading hours (market open) for best results. Avoid late nights.
5

Don't Spam

Limit to 1-2 messages per day maximum. Quality over quantity.
6

Test First

Send to yourself using /checkuser YOUR_ID before broadcasting to everyone.

​
Rate Limiting

Telegram enforces strict rate limits:
  • 20 messages per second to different users
  • 1 message per second to the same user
The broadcast system automatically adds a 100ms delay between messages to stay within limits.
For large broadcasts (1000+ users), expect ~2-3 minutes for completion.

​
Troubleshooting

Problem: API returns 401 UnauthorizedSolutions:
  • Check that ADMIN_SECRET is set correctly in .env
  • Verify you’re using Bearer token format in Authorization header
  • Ensure no extra spaces in the token
Problem: API returns 403 ForbiddenSolutions:
  • ADMIN_SECRET doesn’t match server value
  • Check environment variable is set in production (Vercel)
  • Verify deployment has latest environment variables
Problem: Not all messages delivered successfullyThis is normal:
  • Users may have blocked the bot
  • Users may have deleted their Telegram account
  • Users may have cleared chat history
  • Expect 5-10% failure rate
What to do:
  • Review failedUsers array in response
  • Consider removing consistently failing users from database
Problem: Broadcast commands don’t respondSolutions:
  • Verify you’re logged in as admin (check ADMIN_ID in config)
  • Ensure bot is running and webhook is active
  • Check bot logs for errors
  • Try /botstats to confirm admin access

​
Security Considerations

Production Deployment:
  1. Set ADMIN_SECRET in Vercel environment variables
  2. Use your production URL, not localhost
  3. Never commit ADMIN_SECRET to git
  4. Rotate secret if exposed
  5. Use HTTPS only for API calls

Build docs developers (and LLMs) love

Get started for freeTalk to us