API Documentation

Complete guide to BotBroad Broadcasting API

No results found

Try adjusting your search terms

POST /api/broadcastapi

Main API endpoint for all BotBroad operations, including bot registration, user management, and broadcast message handling — all through a single unified request system. By using this api you agree to Developer Api Policy

Base URL
https://botbroad.alwaysdata.net/api/broadcastapi

Note: All API requests must be sent to this endpoint using POST method.

Required Headers
Header Value Description
Content-Type application/json Request content type
X-API-Key required Your API Key Authentication token
AUTH Authentication
API Key Authentication

All requests require an API key in the X-API-Key header. API keys are associated with admin accounts and can be generated from the BotBroad bot.

Test Authentication

POST /api/broadcastapi

Create a broadcast job to send a message (with optional media) to all registered users of a specific bot.

Request Parameters
Parameter Type Required Description
type string required Must be "broadcast"
bot_id integer required Bot ID to broadcast from
message string required Message text to broadcast (max 4096 chars, or 1024 if media attached)
media file optional Media file upload (jpg, png, gif, max 10MB). Use multipart/form-data.
file_id string (URL) optional Alternative to file upload: provide an existing media URL.
Request Example 
{
  "type": "broadcast",
  "bot_id": 987654321,
  "message": "Hello users! This is a broadcast message."
}
Response Example 
{
  "success": true,
  "jobId": 42,
  "status": "queued",
  "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
  "totalRecipients": 120,
  "estimatedTime": "12 seconds"
}
200 OK
Message Formatting

The message field supports rich text formatting with simple syntax:

Syntax Result
**bold** bold
_italic_ italic
__underline__ underline
~strikethrough~ strikethrough
`inline code` inline code 
```
code block
```
 
code block
[Google](https://google.com) Google

Example message:

Hello **World**!
This is _italic_ text and a [Google](https://google.com) link.
POST /api/broadcastapi

Check the status and progress of a broadcast job.

Request Parameters
Parameter Type Required Description
type string required Must be "job_status"
job_id integer required Job ID returned from the broadcast request
Request Example 
{
  "type": "job_status",
  "job_id": 123456789
}
Response Example 
{
  "success": true,
  "job": {
    "id": 123456789,
    "botId": 987654321,
    "botName": "MyBot",
    "message": "Hello users! This is a broadcast message.",
    "mediaType": "photo",
    "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
    "status": "completed",
    "createdAt": "2023-10-05T14:30:00Z",
    "updatedAt": "2023-10-05T14:32:15Z",
    "total": 1500
  },
  "progress": {
    "sent": 1488,
    "failed": 12,
    "total": 1500,
    "percentage": 99.2
  }
}
200 OK
POST /api/broadcastapi

Get detailed results for a broadcast job, including individual user delivery statuses.

Request Parameters
Parameter Type Required Description
type string required Must be "results"
job_id integer required Job ID returned from the broadcast request
page integer optional Page number for pagination (default: 1)
limit integer optional Number of results per page (default: 50, max: 100)
Request Example 
{
  "type": "results",
  "job_id": 42,
  "page": 1,
  "limit": 50
}
Response Example 
{
  "success": true,
  "job": {
    "id": 42,
    "botId": 987654321,
    "botName": "MyBot",
    "message": "Hello users! This is a broadcast message.",
    "mediaType": "photo",
    "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
    "status": "completed",
    "createdAt": "2023-10-05T14:30:00Z",
    "total": 1500
  },
  "progress": {
    "sent": 1488,
    "failed": 12,
    "total": 1500,
    "successRate": 99.2
  },
  "results": [
    {
      "userId": 123456789,
      "botId": 987654321,
      "status": "failed",
      "errorMessage": "Blocked by user",
      "firstName": "John",
      "username": "john_doe",
      "sentAt": "2023-10-05T14:31:00Z"
    },
    {
      "userId": 987654321,
      "botId": 987654321,
      "status": "sent",
      "firstName": "Alice",
      "username": "alice123",
      "sentAt": "2023-10-05T14:31:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1500,
    "pages": 30
  }
}
200 OK
POST /api/broadcastapi

Retrieve broadcast history across all bots owned by the authenticated admin. Supports pagination and returns individual delivery results for each broadcasted message.

Request Parameters
Parameter Type Required Description
type string required Must be "broadcast_history"
page integer optional Page number (default: 1)
limit integer optional Number of results per page (default: 100, max: 100)
Request Example 
{
  "type": "broadcast_history",
  "page": 1,
  "limit": 10
}
Response Example 
{
  "success": true,
  "results": [
    {
      "userId": 123456789,
      "botId": 987654321,
      "botName": "MyBot",
      "message": "Hello users! This is a broadcast message.",
      "mediaType": "photo",
      "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
      "status": "sent",
      "errorMessage": null,
      "sentAt": "2023-10-05T14:31:00Z"
    },
    {
      "userId": 223344556,
      "botId": 987654321,
      "botName": "MyBot",
      "message": "Hello users! This is a broadcast message.",
      "mediaType": "photo",
      "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
      "status": "failed",
      "errorMessage": "User blocked bot",
      "sentAt": "2023-10-05T14:31:02Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45,
    "pages": 5
  }
}
200 OK
POST /api/broadcastapi

Retrieve all broadcast results across all bots owned by the authenticated admin. Includes aggregate statistics and the full delivery history.

Request Parameters
Parameter Type Required Description
type string required Must be "all_results"
Request Example 
{
  "type": "all_results"
}
Response Example 
{
  "success": true,
  "adminId": 42,
  "adminUsername": "admin_user",
  "stats": {
    "totalBroadcasts": 45,
    "totalSent": 67032,
    "totalFailed": 540,
    "successRate": 99.2
  },
  "totalResults": 5,
  "results": [
    {
      "userId": 123456789,
      "botId": 987654321,
      "botName": "MyBot",
      "message": "Hello users! This is a broadcast message.",
      "mediaType": "photo",
      "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
      "status": "sent",
      "errorMessage": null,
      "sentAt": "2023-10-05T14:31:00Z"
    },
    {
      "userId": 223344556,
      "botId": 987654321,
      "botName": "MyBot",
      "message": "Hello users! This is a broadcast message.",
      "mediaType": "photo",
      "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
      "status": "failed",
      "errorMessage": "User blocked bot",
      "sentAt": "2023-10-05T14:31:02Z"
    }
  ]
}
200 OK
POST /api/broadcastapi

Get detailed information about the authenticated admin, including bot stats, user stats, broadcast stats, recent broadcasts, and rate limits.

Request Parameters
Parameter Type Required Description
type string required Must be "get_info"
Request Example 
{
  "type": "get_info"
}
Response Example 
{
  "success": true,
  "info": {
    "admin": {
      "username": "admin_user",
      "createdAt": "2023-01-15T10:30:00Z",
      "status": "active"
    },
    "botStats": {
      "totalBots": 3,
      "onlineBots": 2,
      "todayBroadcasts": 5
    },
    "userStats": {
      "totalUsers": 1520
    },
    "broadcastStats": {
      "totalBroadcasts": 45,
      "totalSent": 67032,
      "totalFailed": 540
    },
    "recentBroadcasts": [
      {
        "id": 42,
        "botId": 987654321,
        "botName": "MyBot",
        "message": "Hello users! This is a broadcast message.",
        "mediaType": "photo",
        "mediaUrl": "https://yourapp.com/assets/images/broadcast_abc.png",
        "status": "completed",
        "total": 1500,
        "sentCount": 1488,
        "failedCount": 12,
        "createdAt": "2023-10-05T14:30:00Z"
      }
    ],
    "rateLimits": {
      "broadcastsPerDay": 20,
      "requestsPer2Min": 200,
      "userRequestsPer5Min": 30
    }
  }
}
200 OK
POST /api/broadcastapi

Register a new bot in the system under the authenticated admin (or a specific admin if admin_id is provided).

Request Parameters
Parameter Type Required Description
type string required Must be "register_bot"
bot_token string required Telegram Bot Token (stored encrypted)
Request Example 
{
  "type": "register_bot",
  "bot_token": "4366158178:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
}
Response Example 
{
  "success": true,
  "message": "Bot registered successfully",
  "bot_id": 9006740544,
  "bot_name": "MyBotUsername"
}
200 OK
POST /api/broadcastapi

Register a Telegram user under a specific bot. If the user already exists, their details are updated.

Request Parameters
Parameter Type Required Description
type string required Must be "add_user"
bot_id integer required Bot ID the user belongs to
user_id integer required Telegram User ID
first_name string optional User’s first name
username string optional User’s Telegram username
language_code string optional Language code (e.g., en, ru)
Request Example 
{
  "type": "add_user",
  "bot_id": 987654321,
  "user_id": 123456789,
  "first_name": "John",
  "username": "john_doe",
  "language_code": "en"
}
Response Example 
{
  "success": true,
  "message": "User added to the bot successfully",
  "user_id": 123456789,
  "bot_id": 987654321
}
200 OK
POST /api/broadcastapi

Retrieve all currently active or pending broadcast jobs for the authenticated admin. Returns job details, progress, and broadcast metadata.

Request Parameters
Parameter Type Required Description
type string required Must be "ongoing_broadcasts"
Request Example 
{
  "type": "ongoing_broadcasts"
}
Response Example 
{
  "success": true,
  "message": "Active broadcasts retrieved successfully.",
  "totalActive": 2,
  "broadcasts": [
    {
      "jobId": 101,
      "botId": 987654321,
      "botName": "PromoBot",
      "status": "In_progress",
      "totalTargets": 250,
      "totalSent": 100,
      "progressPercent": 40.0,
      "messageText": "Weekly update!",
      "mediaUrl": "https://example.com/images/broadcast_1.png",
      "createdAt": "2025-10-06 08:12:45",
      "updatedAt": "2025-10-06 08:20:30"
    },
    {
      "jobId": 102,
      "botId": 123456789,
      "botName": "NewsBot",
      "status": "Pending",
      "totalTargets": 800,
      "totalSent": 0,
      "progressPercent": 0,
      "messageText": "Morning news broadcast",
      "mediaUrl": null,
      "createdAt": "2025-10-06 07:45:12",
      "updatedAt": "2025-10-06 07:45:12"
    }
  ]
}
200 OK 404 Not Found (no active broadcasts)
LIMIT Rate Limiting
Rate Limits

BotBroad API enforces strict rate limits to ensure fair usage and system stability. If limits are exceeded, requests will return 429 Too Many Requests.

Category Limit Window
Global Requests 200 requests per 2 minutes (per session)
Broadcast Operations 20 broadcasts per day (per bot)
User Additions 30 requests per 5 minutes (per user)
STATUS Status Codes
HTTP Status Codes
Code Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error