Telegram Chat Data and Stars
Everything Telegram's Bot API lets a bot know about the channel or group it publishes to, through the bot you connected to the profile (your token from @BotFather).
- Authentication: API Key —
Authorization: Apikey <YOUR_API_KEY> - Every endpoint takes the profile in
user.
The Bot API has no views, reach or channel statistics for bots: Message carries no view
count and there is no statistics method. What it does report, and what Upload-Post returns:
subscribers/members (getChatMemberCount), the chat details (getChat), administrators,
boosts and reactions per post. Reactions and the chat-wide list of boosts only reach a bot as
live updates, so they need update receiving enabled for the bot, and the bot must be an
administrator of the chat. Reactions on channel posts are anonymous counts.
Receiving the bot's updates (Telegram: updates, DMs and Business) is not
generally available yet. Until it is, reaction counts stay at 0, the boosts list without user_id
is empty, and post analytics answer post_metrics_error. Subscribers, chat details,
administrators, getUserChatBoosts and the Stars endpoints work now.
Chat details
- Method:
GET - Endpoint:
/api/uploadposts/telegram/chat-info
| Parameter | Type | Required | Description |
|---|---|---|---|
user | string | Yes | Profile username with Telegram connected. |
include_administrators | boolean | No | Default true. Adds the chat administrators (getChatAdministrators). |
return_bots | boolean | No | Also list other bots that are administrators. |
curl 'https://api.upload-post.com/api/uploadposts/telegram/chat-info?user=my-channel' \
-H 'Authorization: Apikey YOUR_API_KEY'
{
"success": true,
"chat": { "id": -1001234567890, "type": "channel", "title": "My Channel", "username": "mychannel",
"description": "News", "linked_chat_id": -1009876543210 },
"member_count": 4321,
"url": "https://t.me/mychannel",
"bot_membership": { "status": "administrator", "can_post_messages": true },
"administrators": [ { "status": "creator", "user": { "id": 111, "first_name": "Ana" } } ],
"boosts_active": 3,
"reactions_total": 812,
"posts_with_reactions": 40,
"views_available": false
}
chat is Telegram's ChatFullInfo as returned.
bot_membership is the bot's own ChatMember
with its rights. Answers are cached for 5 minutes.
Analytics and post analytics
telegram works in Get Analytics (/api/analytics/<profile>?platforms=telegram):
followers (subscribers or members; in a private chat with the bot, the person and the bot), engagement / likes (reactions counted on the posts the bot
received updates for), boosts_active, title, username, url and views_available: false.
If Telegram does not return the member count in time, the telegram section comes back with
success: false, partial: true, error and the chat data that did arrive (no follower fields). The rest of
the analytics response is not delayed.
Post analytics for a Telegram post (its post_id is the message id) returns
reactions (one entry per emoji, custom emoji or paid reaction), reactions_total, likes and
engagement. While no reaction update has arrived for that post, it returns post_metrics_error
explaining why (Telegram reports no views).
Boosts
- Method:
GET - Endpoint:
/api/uploadposts/telegram/boosts
| Parameter | Type | Required | Description |
|---|---|---|---|
user | string | Yes | Profile username. |
user_id | integer | No | A Telegram user id: returns the boosts that user added, live from Telegram (getUserChatBoosts, bot must be an administrator). |
Without user_id the answer is the list of active boosts received as updates (source: "updates"):
Telegram has no method that lists every boost of a chat.
Telegram Stars balance
- Method:
GET - Endpoint:
/api/uploadposts/telegram/stars
Returns the bot's balance (getMyStarBalance):
{"success": true, "amount": 250, "nanostar_amount": 0, "balance": {...}}.
Telegram Stars transactions
- Method:
GET - Endpoint:
/api/uploadposts/telegram/stars/transactions
| Parameter | Type | Required | Description |
|---|---|---|---|
user | string | Yes | Profile username. |
offset | integer | No | Transactions to skip. |
limit | integer | No | 1-100, default 100. |
Returns Telegram's StarTransaction list in
chronological order, plus next_offset (null on the last page). For a payment from a buyer, the
transaction id is the telegram_payment_charge_id you need for a
refund.
Errors
All errors are {"success": false, "error": "...", "error_code": "..."}:
| Status | error_code | Meaning |
|---|---|---|
| 400 | user_required, validation_error, telegram_not_connected, telegram_bad_request | Missing/invalid parameter, no bot on the profile, or Telegram rejected the request (telegram_error has Telegram's text). |
| 401 | telegram_reconnect_required | The bot token was revoked or regenerated in @BotFather. Reconnect Telegram. |
| 403 | telegram_not_enough_rights | The bot is not an administrator, or lacks a right. |
| 404 | profile_not_found, telegram_chat_not_found | Unknown profile, or Telegram cannot find the chat. |
| 429 | telegram_rate_limited | Telegram's limit for your bot; wait retry_after seconds. |
| 502 | telegram_unreachable, telegram_api_error | Telegram could not be reached or failed. Safe to retry (read-only). |