Telegram Premium

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.

Telegram Premium users

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 features

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.

Promo page

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:

The help.premiumPromo constructor returned by help.getPremiumPromo contains various info about the subscription, as described in the constructor page.

Premium limits

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.

Badge

Users with a Telegram Premium subscription (user.premium is set) should have a Telegram Premium badge next to their name.

Animated profile pictures

The animated profile pictures of Premium users should play inside of chats and dialog lists, and not just when opening the profile page.

Sticker suggestions

The suggested sticker selection logic is slightly different for Premium users, see here for more info ».

Subscribing to Telegram Premium

Here's how to activate a Telegram Premium subscription, when the user clicks on the subscribe button:

  • If the premium_bot_username field is set, call messages.startBot, specifying the following parameters:
    • peer and bot: The bot mentioned in premium_bot_username
    • start_param: One of the following values:
      • If the user clicks on the subscribe button when viewing the promo page for a specific Premium feature, provide the feature identifier.
      • If the user clicks on the subscribe button after hitting a limit that Telegram Premium raises, provide double_limits
      • If the user clicks on the subscribe button from the Telegram Premium button in the settings, provide settings
      • If the user clicks on the subscribe button from the Telegram Premium star in a profile page, provide profile Then, when the user clicks on the subscribe button in the sent invoice, follow the usual payment flow for message invoices.
  • Otherwise, if the 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).

Gifting Telegram Premium

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#979d2376 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 can_view_revenue:flags2.9?true bot_can_manage_emoji_status:flags2.10?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 stargifts_count:flags2.8?int starref_program:flags2.11?StarRefProgram = UserFull;

premiumGiftOption#74c34319 flags:# months:int currency:string amount:long bot_url:string store_product:flags.0?string = PremiumGiftOption;

messageActionGiftPremium#6c6274fa flags:# currency:string amount:long months:int crypto_currency:flags.0?string crypto_amount:flags.0?long message:flags.1?TextWithEntities = 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.

Blocked Telegram Premium

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).

Telegram
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
About
Mobile Apps
Desktop Apps
Platform
About
Blog
Press
Moderation