Skip to main content
POST
/
api
/
admin
/
broadcast
Broadcast Messages
curl --request POST \
  --url https://api.example.com/api/admin/broadcast
{
  "success": true,
  "message": "<string>",
  "stats": {
    "stats.total": 123,
    "stats.successful": 123,
    "stats.failed": 123,
    "stats.failedUsers": [
      {}
    ]
  }
}

​
Overview

The broadcast endpoint allows administrators to send messages to all users or specific segments based on plan type and subscription status. This is useful for marketing campaigns, announcements, and user engagement.
This is a privileged endpoint that requires ADMIN_SECRET authentication. Unauthorized access is logged and blocked.

​
Authentication

This endpoint requires Bearer token authentication using the ADMIN_SECRET environment variable. 
Authorization: Bearer YOUR_ADMIN_SECRET

​
Request Body

​
message
string
required
The message to broadcast to users. Supports HTML formatting for rich text messages.
​
planType
string
Filter recipients by subscription plan type. If not specified or set to all, messages will be sent to all users.Options:
  • basic - Basic plan subscribers (7 days)
  • monthly - Monthly plan subscribers (30 days)
  • premium - Premium plan subscribers (14 days + Copier)
  • all - All users (default)
​
activeOnly
boolean
default:"false"
When set to true, only users with active (non-expired) subscriptions will receive the message. When false, all users matching the plan type criteria will receive the message.

​
Response

​
success
boolean
Indicates whether the broadcast operation completed successfully.
​
message
string
A human-readable message describing the result.
​
stats
object
Detailed statistics about the broadcast operation.
​
stats.total
number
Total number of users targeted for the broadcast.
​
stats.successful
number
Number of messages successfully delivered.
​
stats.failed
number
Number of messages that failed to deliver.
​
stats.failedUsers
array
List of usernames or user IDs for failed deliveries.

​
Rate Limiting

The endpoint implements automatic rate limiting with a 100ms delay between messages to comply with Telegram’s API limits (20 messages per second).

​
Examples

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 this week!"
  }'

​
Response Examples

{
  "success": true,
  "message": "Broadcast sent successfully",
  "stats": {
    "total": 150,
    "successful": 148,
    "failed": 2,
    "failedUsers": ["user123", "987654321"]
  }
}

​
Get Broadcast Stats

You can retrieve subscriber statistics by sending a GET request to the same endpoint: 
curl -X GET https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET"

​
Stats Response

{
  "info": "Broadcast API - Send messages to all users",
  "usage": {
    "method": "POST",
    "headers": {
      "Authorization": "Bearer YOUR_ADMIN_SECRET"
    },
    "body": {
      "message": "Your message here (supports HTML formatting)",
      "planType": "basic | monthly | premium | all (optional, default: all)",
      "activeOnly": "true | false (optional, default: false)"
    }
  },
  "stats": {
    "totalUniqueUsers": 250,
    "totalSubscribers": [
      { "planType": "basic", "_count": { "telegramUserId": 80 } },
      { "planType": "monthly", "_count": { "telegramUserId": 120 } },
      { "planType": "premium", "_count": { "telegramUserId": 50 } }
    ],
    "activeSubscribers": [
      { "planType": "basic", "_count": { "telegramUserId": 60 } },
      { "planType": "monthly", "_count": { "telegramUserId": 95 } },
      { "planType": "premium", "_count": { "telegramUserId": 45 } }
    ]
  }
}

​
Security Considerations

Critical Security Measures:
  • The ADMIN_SECRET must be kept secure and never committed to version control
  • Invalid authentication attempts are logged for security monitoring
  • Failed deliveries are tracked and reported for audit purposes
  • Ensure the secret is sufficiently long and randomly generated

​
Error Handling

The endpoint implements comprehensive error handling:
  • 401 Unauthorized: Missing or invalid Authorization header format
  • 403 Forbidden: Invalid ADMIN_SECRET token (logged for security)
  • 400 Bad Request: Missing required message field
  • 500 Internal Server Error: Database or Telegram API failures

​
Implementation Details

Database Queries:The endpoint uses Prisma to query subscriptions with these criteria:
  • Distinct telegramUserId to avoid duplicate messages
  • Optional filtering by planType
  • Optional filtering by expiresAt > NOW() and isRemoved = false for active users
Source: src/app/api/admin/broadcast/route.ts:36-58

​
Testing

For testing purposes, you can use the GET endpoint to retrieve current statistics before sending a broadcast. This helps validate your targeting criteria. 
# Step 1: Check stats
curl -X GET https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET"

# Step 2: Send targeted broadcast
curl -X POST https://your-domain.com/api/admin/broadcast \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "Test message", "planType": "premium", "activeOnly": true}'

Build docs developers (and LLMs) love

Get started for freeTalk to us