Skip to main content

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.
What Telegram does and does not report

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.

Not generally available yet

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
ParameterTypeRequiredDescription
userstringYesProfile username with Telegram connected.
include_administratorsbooleanNoDefault true. Adds the chat administrators (getChatAdministrators).
return_botsbooleanNoAlso 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
ParameterTypeRequiredDescription
userstringYesProfile username.
user_idintegerNoA 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
ParameterTypeRequiredDescription
userstringYesProfile username.
offsetintegerNoTransactions to skip.
limitintegerNo1-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": "..."}:

Statuserror_codeMeaning
400user_required, validation_error, telegram_not_connected, telegram_bad_requestMissing/invalid parameter, no bot on the profile, or Telegram rejected the request (telegram_error has Telegram's text).
401telegram_reconnect_requiredThe bot token was revoked or regenerated in @BotFather. Reconnect Telegram.
403telegram_not_enough_rightsThe bot is not an administrator, or lacks a right.
404profile_not_found, telegram_chat_not_foundUnknown profile, or Telegram cannot find the chat.
429telegram_rate_limitedTelegram's limit for your bot; wait retry_after seconds.
502telegram_unreachable, telegram_api_errorTelegram could not be reached or failed. Safe to retry (read-only).