Telegram Premium is an optional subscription service that unlocks additional exclusive client-side and API-side features, while helping support the development of the app. It is a part of Telegram’s sustainable monetization – driven by our users, rather than advertisers or shareholders. This way, Telegram can remain independent and prioritize its users first.
This page describes how should client apps handle Premium features: for a user-friendly overview of Telegram Premium features, see the Telegram Premium FAQ.
inputUserSelf#f7c1b13f = InputUser;
user#83314fca flags:# self:flags.10?true contact:flags.11?true mutual_contact:flags.12?true deleted:flags.13?true bot:flags.14?true bot_chat_history:flags.15?true bot_nochats:flags.16?true verified:flags.17?true restricted:flags.18?true min:flags.20?true bot_inline_geo:flags.21?true support:flags.23?true scam:flags.24?true apply_min_photo:flags.25?true fake:flags.26?true bot_attach_menu:flags.27?true premium:flags.28?true attach_menu_enabled:flags.29?true flags2:# bot_can_edit:flags2.1?true close_friend:flags2.2?true stories_hidden:flags2.3?true stories_unavailable:flags2.4?true contact_require_premium:flags2.10?true bot_business:flags2.11?true bot_has_main_app:flags2.13?true id:long access_hash:flags.0?long first_name:flags.1?string last_name:flags.2?string username:flags.3?string phone:flags.4?string photo:flags.5?UserProfilePhoto status:flags.6?UserStatus bot_info_version:flags.14?int restriction_reason:flags.18?Vector<RestrictionReason> bot_inline_placeholder:flags.19?string lang_code:flags.22?string emoji_status:flags.30?EmojiStatus usernames:flags2.0?Vector<Username> stories_max_id:flags2.5?int color:flags2.8?PeerColor profile_color:flags2.9?PeerColor bot_active_users:flags2.12?int = User;
help.premiumPromo#5334759c status_text:string status_entities:Vector<MessageEntity> video_sections:Vector<string> videos:Vector<Document> period_options:Vector<PremiumSubscriptionOption> users:Vector<User> = help.PremiumPromo;
---functions---
users.getUsers#d91a548 id:Vector<InputUser> = Vector<User>;
help.getPremiumPromo#b81b93d4 = help.PremiumPromo;Premium users will have the premium flag of the user set.
Use users.getUsers with inputUserSelf to fetch info about the current subscription status of the current user.
You can also directly use help.getPremiumPromo, as it will return info about the current user in the users field.
Telegram Premium offers a set of additional features and raised limits: clients should be aware of the current subscription status to accordingly modify client behavior.
help.premiumPromo#5334759c status_text:string status_entities:Vector<MessageEntity> video_sections:Vector<string> videos:Vector<Document> period_options:Vector<PremiumSubscriptionOption> users:Vector<User> = help.PremiumPromo;
---functions---
help.getPremiumPromo#b81b93d4 = help.PremiumPromo;
help.getAppConfig#61e3f854 hash:int = help.AppConfig;Clients should show a Telegram Premium button in the settings.
Clicking on this button in the settings, clicking on the badge of a Premium user or hitting one of the Premium limits listed below should open a Telegram Premium modal.
Call help.getPremiumPromo and help.getAppConfig to fetch info on how to build the premium modal.
help.getAppConfig will return a list of Premium feature identifiers in the premium_promo_order appConfig field: the modal should contain a row for each returned feature, ordered as specified in the returned array.
Possible feature identifiers:
stories - Premium users have various Story-related improvements:
story_caption_length_limit_* » config keys.stories_suggested_reactions_limit_* » config keys.See the stories documentation » for more information on stories.
double_limits - Clicking on this entry should open a secondary popup with a list of the improved Premium limits ».
business - Premium users currently have access to Telegram Business features ».
last_seen - Premium users can view the last seen and message read times of other users even they can't view the last seen or read time for the current user.
message_privacy - Premium users can disallow incoming voice and video note messages in private chats using inputPrivacyKeyVoiceMessages and restrict incoming messages from non-contacts.
more_upload - Premium users can upload bigger files, as specified by the upload_max_fileparts_default vs upload_max_fileparts_premium config keys.
faster_download - Premium users have no download speed limits (i.e. they can't receive FLOOD_PREMIUM_WAIT_X errors when downloading files, see here » for more info).
wallpapers - Premium users can set custom chat wallpapers both for them and the other user in the chat.
peer_colors - Premium users can choose a custom color and background emoji for their profile background and messages.
voice_to_text - Premium users can transcribe voice messages without limits.
translations - Premium users can enable real-time chat translation.
no_ads - Premium users see no sponsored messages.
unique_reactions - Premium users have access to more message reactions.
premium_stickers - Premium users have access to premium stickersets.
animated_emoji - Premium users can send custom animated emojis.
advanced_chat_management - Premium users can reorder the default folder, auto-archive and hide new chats from non-contacts.
profile_badge - Premium users have a badge next to their name, showing that they are helping support Telegram.
animated_userpics - Animated profile pictures of Premium users will play in-chat and when browsing the dialog list.
app_icons - Premium users can change the default icon of the Telegram app.
infinite_reactions - Premium users can use custom emojis when reacting to messages.
emoji_status - Premium users can set a status emoji.
saved_tags - Premium users can use saved message tags.
effects - Premium users can use message effects.
channel_boost - Premium users can boost chats and channels.
forum_topic_icon - Premium users can set a custom emoji as a forum topic icon
The help.premiumPromo constructor returned by help.getPremiumPromo contains various info about the subscription, as described in the constructor page.
What follows is a list of appConfig integer config parameters.
Note that whenever config keys end with a * in the following list, the * should be replaced with premium or default, to fetch the appropriate limit value for Premium and non-Premium users.
reactions_user_max_* - The maximum number of reactions that can be added to a single message by the user.channels_limit_* - The maximum number of channels and supergroups a user may join.saved_gifs_limit_* - The maximum number of GIFs a user may save.stickers_faved_limit_* - The maximum number of stickers a user may add to favorites.dialog_filters_limit_* - The maximum number of folders a user may create.dialog_filters_chats_* - The maximum number of chats a user may add to a folder.dialogs_pinned_limit_* - The maximum number of chats a user may pin.dialogs_folder_pinned_limit_* - The maximum number of chats a user may pin in a folder.channels_public_limit_* - The maximum number of public channels or supergroups a user may create.caption_length_limit_* - The maximum UTF-8 length of media captions.about_length_limit_* - The maximum UTF-8 length of user bios.chatlist_invites_limit_* - Maximum number of per-folder chat folder deep links » that can be created.chatlists_joined_limit_* - Maximum number of shareable folders a user may have. recommended_channels_limit_* - The maximum number of similar channels that can be recommended by channels.getChannelRecommendations» to users.saved_dialogs_pinned_limit_* - Maximum number of pinned dialogs in saved messages.Users with a Telegram Premium subscription (user.premium is set) should have a Telegram Premium badge next to their name.
The animated profile pictures of Premium users should play inside of chats and dialog lists, and not just when opening the profile page.
The suggested sticker selection logic is slightly different for Premium users, see here for more info ».
Here's how to activate a Telegram Premium subscription, when the user clicks on the subscribe button:
premium_bot_username field is set, call messages.startBot, specifying the following parameters:peer and bot: The bot mentioned in premium_bot_usernamestart_param: One of the following values:double_limitssettingsprofile
Then, when the user clicks on the subscribe button in the sent invoice, follow the usual payment flow for message invoices. premium_invoice_slug field is set, handle the payment as you would handle a t.me/$premium_invoice_slug invoice deep link.There is also a store-based subscription flow based on payments.assignAppStoreTransaction/payments.assignPlayMarketTransaction, but it's currently not available to third-party apps (unlike the flow described above, which can be used by all clients).
Note: to gift a Premium subscriptions to multiple friends, the alternative payment flow described here » (inputStorePaymentPremiumGiftCode without setting boost_peer) must be used, instead.
userFull#cc997720 flags:# blocked:flags.0?true phone_calls_available:flags.4?true phone_calls_private:flags.5?true can_pin_message:flags.7?true has_scheduled:flags.12?true video_calls_available:flags.13?true voice_messages_forbidden:flags.20?true translations_disabled:flags.23?true stories_pinned_available:flags.26?true blocked_my_stories_from:flags.27?true wallpaper_overridden:flags.28?true contact_require_premium:flags.29?true read_dates_private:flags.30?true flags2:# sponsored_enabled:flags2.7?true id:long about:flags.1?string settings:PeerSettings personal_photo:flags.21?Photo profile_photo:flags.2?Photo fallback_photo:flags.22?Photo notify_settings:PeerNotifySettings bot_info:flags.3?BotInfo pinned_msg_id:flags.6?int common_chats_count:int folder_id:flags.11?int ttl_period:flags.14?int theme_emoticon:flags.15?string private_forward_name:flags.16?string bot_group_admin_rights:flags.17?ChatAdminRights bot_broadcast_admin_rights:flags.18?ChatAdminRights premium_gifts:flags.19?Vector<PremiumGiftOption> wallpaper:flags.24?WallPaper stories:flags.25?PeerStories business_work_hours:flags2.0?BusinessWorkHours business_location:flags2.1?BusinessLocation business_greeting_message:flags2.2?BusinessGreetingMessage business_away_message:flags2.3?BusinessAwayMessage business_intro:flags2.4?BusinessIntro birthday:flags2.5?Birthday personal_channel_id:flags2.6?long personal_channel_message:flags2.6?int = UserFull;
premiumGiftOption#74c34319 flags:# months:int currency:string amount:long bot_url:string store_product:flags.0?string = PremiumGiftOption;
messageActionGiftPremium#c83d6aec flags:# currency:string amount:long months:int crypto_currency:flags.0?string crypto_amount:flags.0?long = MessageAction;
inputStickerSetPremiumGifts#c88b3b02 = InputStickerSet;
---functions---
users.getFullUser#b60f5918 id:InputUser = users.UserFull;If after calling users.getFullUser the resulting userFull constructor has one or more premiumGiftOptions in the premium_gifts field, we can gift a non-recurring Telegram Premium subscription to this user.
The premiumGiftOption constructors contain an ordered list of Premium gift offers with discounts over the base price, according to the subscription duration: to process the gift payment open the deep link contained in the bot_url field.
Once the payment is successfully processed, the user to which the gift was sent will automatically receive a messageService from the user that sent the gift, containing a messageActionGiftPremium constructor with further info about the price and duration of the gifted Telegram Premium subscription.
Clients should display this message, along with a sticker from the inputStickerSetPremiumGifts stickerset: here's an example.
Note that if the premium_gift_attach_menu_icon app configuration parameter is true, a gift icon should be shown in the attachment menu in private chats with users, offering the current user to gift a Telegram Premium subscription to the other user in the chat.
If the premium_gift_text_field_icon parameter is also set, a gift icon should be shown in the text bar in private chats with users (ie like the / icon in chats with bots), offering the current user to gift a Telegram Premium subscription to the other user in the chat. Can only be true if premium_gift_attach_menu_icon is also true.
Note that even if the premium_gifts field is not set, we can still gift one (or more!) Premium subscriptions using the alternative payment flow described here » (inputStorePaymentPremiumGiftCode without setting boost_peer).
Gifting a Telegram Premium subscription to another user will create boosts_per_sent_gift boost slots » for us, and one boost slot for the destination user.
If the premium_purchase_blocked app configuration parameter is set, the user can't purchase a Premium account, and all Telegram Premium features must be hidden (like the badges of Premium users, Telegram Premium purchase buttons, and so on).