The Telegram Bot API Methods That Actually Matter, Grouped by Job

The Telegram Bot API Methods That Actually Matter, Grouped by Job

The official reference lists every method alphabetically, which is correct and unhelpful when you are trying to build a specific thing.

This groups the methods by what you are actually doing, with the parameter limits and behaviours that cause real bugs. Quoted text below is verbatim from Telegram's documentation; unquoted figures come from the Bot API reference, the Bot FAQ or the Telegram Stars terms, and anything that is our own inference is marked as such.

Selling access to a channel

createChatSubscriptionInviteLink — a recurring paid subscription link.

• subscription_period — "The number of seconds the subscription will be active for before the next payment. Currently, it must always be 2592000 (30 days)." 30-day billing only today; the docs hedge with "Currently", so re-check before designing around annual plans.
• subscription_price — 1–10,000 Stars. At roughly $0.0133 net per Star, that caps you near $133/month per subscriber.
• Requires the can_invite_users admin right.

editChatSubscriptionInviteLink — takes chat_id, invite_link, and name. That is all.

You cannot change the price of an existing subscription link. To sell at a new price, create a new link. The Bot API documents only that editChatSubscriptionInviteLink takes chat_id, invite_link and name — it says nothing about what happens to users already subscribed through the old link, so verify that on a test channel before you build pricing around it. See tiered access.

Managing invite links

createChatInviteLink

• member_limit — 1–99,999: "The maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-99999". Not total uses, and it counts only members who joined through that link — remove one of those and the slot frees up, re-arming the link.
• expire_date — Unix timestamp.
• creates_join_request — "If True, member_limit can't be specified." Mutually exclusive.

revokeChatInviteLink — "If the primary link is revoked, a new link is automatically generated." Revoking your primary link invalidates every published copy of it. Revoke the links you created for a purpose; leave the primary alone.

Footgun: revoke a member's link when you remove them, or that link works again. See invite link leaks.

Approving members

approveChatJoinRequest / declineChatJoinRequest — both need can_invite_users.

The ChatJoinRequest object is more useful than most people realise:

• bio — the user's profile bio, before you admit them. The cheapest spam signal available.
• user_chat_id — and this: "The bot can use this identifier for 5 minutes to send messages until the join request is processed, assuming no other administrator contacted the user."

A five-minute private channel to a prospective member who is not yet in your group. See join requests.

Removing and restricting

banChatMember

• until_date — "If user is banned for more than 366 days or less than 30 seconds from the current time they are considered to be banned forever. Applied for supergroups and channels only." Both ends are traps. A duration that rounds under 30 seconds is a permanent ban; the docs state the rule but not what the API returns, so do not rely on an error to catch it — clamp the duration in your own code. In a basic group until_date is not applied at all.
• revoke_messages — "Pass True to delete all messages from the chat for the user that is being removed. If False, the user will be able to see messages in the group that were sent before the user was removed. Always True for supergroups and channels." In a supergroup or channel the parameter is inert; passing False only changes anything in a basic group.

unbanChatMember

• "if the user is a member of the chat they will also be removed from the chat"

Always pass only_if_banned=True. Without it, unbanning an active member kicks them. A cleanup job over past removals will silently eject paying subscribers.

restrictChatMember — takes a ChatPermissions object. This is how you mute new accounts for their first 24–48 hours, which is the defence that actually matches modern join-raid attacks. Bot API 10.0 added can_react_to_messages as a separately restrictable permission.

Ticketing with forum topics

A supergroup with topics enabled is a ticket system. The primitives:

message_thread_id is Optional on Message — "Unique identifier of a message thread or forum topic to which the message belongs; for supergroups and private chats only" — so it is absent on messages outside a thread; treat absence as the General topic rather than indexing blind. To route a reply into a topic you pass message_thread_id yourself on the send method. Ticket status reaches you as service messages, not as your own calls: forum_topic_closed and forum_topic_reopened are Optional fields on Message (ForumTopicClosed / ForumTopicReopened, both "Currently holds no information" — the topic is identified by the message's message_thread_id). Count those for reopen rate; counting your closeForumTopic / reopenForumTopic calls misses every close a human admin performs in the Telegram app. deleteForumTopic is your erasure primitive — though it only touches the Telegram side, not your database.

Receiving updates

setWebhook

• url — HTTPS only
• Ports: "Ports currently supported for webhooks: 443, 80, 88, 8443." Those four against api.telegram.org; a self-hosted local Bot API server can "Use any port for the webhook."
• secret_token — arrives as an X-Telegram-Bot-Api-Secret-Token header. Set it; otherwise your endpoint is open to anyone who learns the URL
• max_connections — 1–100, default 40
• allowed_updates — receive only what you handle, but note it is also an opt-in: an empty list gives you "all update types except chat_member, message_reaction, and message_reaction_count", and a list you set once will silently exclude any type Telegram adds later
• certificate — for self-signed, as an InputFile; "sending a String will not work"

getUpdates — long polling.

• limit 1–100 (default 100)
• timeout — "Defaults to 0, i.e. usual short polling. Should be positive, short polling should be used for testing purposes only." Always set it positive.

getWebhookInfo — pending update count and last delivery error. The first thing to call when updates stop. See debugging webhook failures.

deleteWebhook — required before switching back to polling; they are mutually exclusive.

Payments

refundStarPayment — refund a Stars purchase. It takes user_id and telegram_payment_charge_id (the value on SuccessfulPayment), so store both at purchase time.

Your bot must also handle /paysupport — a documented requirement for bots taking Stars payments, not a suggestion.

Delivery limits

Not a method, but it governs everything you send:

allow_paid_broadcast on send methods enables the higher rate at 0.1 Stars per message above the free 30/sec. The two official sources disagree on the gate: the Bot FAQ says "a bot must have at least 100,000 Stars on its balance and at least 100,000 monthly active users", while the Bot API page's Paid Broadcasts section says "In order to use this feature, a bot must have at least 10,000 Stars on its balance" and states no user requirement. Confirm in @BotFather before planning around either number.

On 429 the error response's parameters object (ResponseParameters) normally carries retry_after — "Optional. In case of exceeding flood control, the number of seconds left to wait before the request can be repeated". Read it as parameters.retry_after, wait that long, and fall back to your own bounded backoff when it is absent. The same object carries migrate_to_chat_id when a group has been upgraded to a supergroup. See error handling.

Useful fields people miss

invite_link on ChatMemberUpdated is easy to miss. Issue a separate link per traffic source and you get join attribution — but you must be an administrator and pass "chat_member" explicitly in allowed_updates, because it is not in the default set. invite_link is itself Optional, present "for joining by invite link events only", so joins by search, chat-folder link or an approved join request arrive without it.

The five that cause the most bugs

1. unbanChatMember without only_if_banned — removes active members
2. banChatMember with until_date under 30 seconds — permanent ban, silently
3. member_limit read as total uses rather than simultaneous members
4. editChatSubscriptionInviteLink assumed to change price — it cannot
5. getUpdates left at timeout=0 — short polling, explicitly for testing only

Every parameter, limit and quoted behaviour verified directly against Telegram's Bot API documentation and Bot FAQ, September 2026. The /paysupport obligation is from the Telegram Stars terms. The ~$0.0133 net per Star figure is Telegram's payout rate, not a number published in the Bot API docs or the FAQ, and is approximate.