telegram-crawler/data/web/blogfork.telegram.org/api/premium.html
2023-03-20 11:08:32 +00:00

229 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>Telegram Premium</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="Telegram Premium is an optional subscription service that unlocks additional exclusive client-side and API-side features…">
<meta property="og:title" content="Telegram Premium">
<meta property="og:image" content="">
<meta property="og:description" content="Telegram Premium is an optional subscription service that unlocks additional exclusive client-side and API-side features…">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
<link href="/css/telegram.css?236" rel="stylesheet" media="screen">
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class="active"><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/premium" >Telegram Premium</a></li></ul></div>
<h1 id="dev_page_title">Telegram Premium</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>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 Telegrams <strong>sustainable monetization</strong> driven by our users, rather than advertisers or shareholders. This way, Telegram can remain independent and prioritize its users first. </p>
<blockquote>
<p>This page describes how should client apps handle Premium features: for a user-friendly overview of Telegram Premium features, see the <a href="https://telegram.org/faq_premium">Telegram Premium FAQ</a>.</p>
</blockquote>
<h3><a class="anchor" href="#telegram-premium-users" id="telegram-premium-users" name="telegram-premium-users"><i class="anchor-icon"></i></a>Telegram Premium users</h3>
<pre><code><a href='/constructor/inputUserSelf'>inputUserSelf</a>#f7c1b13f = <a href='/type/InputUser'>InputUser</a>;
<a href='/constructor/user'>user</a>#5d99adee flags:<a href='/type/%23'>#</a> self:flags.10?<a href='/constructor/true'>true</a> contact:flags.11?<a href='/constructor/true'>true</a> mutual_contact:flags.12?<a href='/constructor/true'>true</a> deleted:flags.13?<a href='/constructor/true'>true</a> bot:flags.14?<a href='/constructor/true'>true</a> bot_chat_history:flags.15?<a href='/constructor/true'>true</a> bot_nochats:flags.16?<a href='/constructor/true'>true</a> verified:flags.17?<a href='/constructor/true'>true</a> restricted:flags.18?<a href='/constructor/true'>true</a> min:flags.20?<a href='/constructor/true'>true</a> bot_inline_geo:flags.21?<a href='/constructor/true'>true</a> support:flags.23?<a href='/constructor/true'>true</a> scam:flags.24?<a href='/constructor/true'>true</a> apply_min_photo:flags.25?<a href='/constructor/true'>true</a> fake:flags.26?<a href='/constructor/true'>true</a> bot_attach_menu:flags.27?<a href='/constructor/true'>true</a> premium:flags.28?<a href='/constructor/true'>true</a> attach_menu_enabled:flags.29?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> access_hash:flags.0?<a href='/type/long'>long</a> first_name:flags.1?<a href='/type/string'>string</a> last_name:flags.2?<a href='/type/string'>string</a> username:flags.3?<a href='/type/string'>string</a> phone:flags.4?<a href='/type/string'>string</a> photo:flags.5?<a href='/type/UserProfilePhoto'>UserProfilePhoto</a> status:flags.6?<a href='/type/UserStatus'>UserStatus</a> bot_info_version:flags.14?<a href='/type/int'>int</a> restriction_reason:flags.18?<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/RestrictionReason'>RestrictionReason</a>&gt; bot_inline_placeholder:flags.19?<a href='/type/string'>string</a> lang_code:flags.22?<a href='/type/string'>string</a> emoji_status:flags.30?<a href='/type/EmojiStatus'>EmojiStatus</a> = <a href='/type/User'>User</a>;
<a href='/constructor/help.premiumPromo'>help.premiumPromo</a>#5334759c status_text:<a href='/type/string'>string</a> status_entities:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/MessageEntity'>MessageEntity</a>&gt; video_sections:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/string'>string</a>&gt; videos:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/Document'>Document</a>&gt; period_options:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/PremiumSubscriptionOption'>PremiumSubscriptionOption</a>&gt; users:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/User'>User</a>&gt; = <a href='/type/help.PremiumPromo'>help.PremiumPromo</a>;
---functions---
<a href='/method/users.getUsers'>users.getUsers</a>#d91a548 id:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/InputUser'>InputUser</a>&gt; = <a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/User'>User</a>&gt;;
<a href='/method/help.getPremiumPromo'>help.getPremiumPromo</a>#b81b93d4 = <a href='/type/help.PremiumPromo'>help.PremiumPromo</a>;</code></pre>
<p>Premium users will have the <code>premium</code> flag of the <a href="/constructor/user">user</a> set. </p>
<p>Use <a href="/method/users.getUsers">users.getUsers</a> with <a href="/constructor/inputUserSelf">inputUserSelf</a> to fetch info about the current subscription status of the current user.<br>
You can also directly use <a href="/method/help.getPremiumPromo">help.getPremiumPromo</a>, as it will return info about the current user in the <code>users</code> field. </p>
<h3><a class="anchor" href="#telegram-premium-features" id="telegram-premium-features" name="telegram-premium-features"><i class="anchor-icon"></i></a>Telegram Premium features</h3>
<p>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. </p>
<h4><a class="anchor" href="#promo-page" id="promo-page" name="promo-page"><i class="anchor-icon"></i></a>Promo page</h4>
<pre><code><a href='/constructor/help.premiumPromo'>help.premiumPromo</a>#5334759c status_text:<a href='/type/string'>string</a> status_entities:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/MessageEntity'>MessageEntity</a>&gt; video_sections:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/string'>string</a>&gt; videos:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/Document'>Document</a>&gt; period_options:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/PremiumSubscriptionOption'>PremiumSubscriptionOption</a>&gt; users:<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/User'>User</a>&gt; = <a href='/type/help.PremiumPromo'>help.PremiumPromo</a>;
---functions---
<a href='/method/help.getPremiumPromo'>help.getPremiumPromo</a>#b81b93d4 = <a href='/type/help.PremiumPromo'>help.PremiumPromo</a>;
<a href='/method/help.getAppConfig'>help.getAppConfig</a>#98914110 = <a href='/type/JSONValue'>JSONValue</a>;</code></pre>
<p>Clients should show a Telegram Premium button in the settings.<br>
Clicking on this button in the settings, clicking on the <a href="#badge">badge</a> of a Premium user or hitting one of the Premium limits listed below should open a Telegram Premium modal. </p>
<p>Call <a href="/method/help.getPremiumPromo">help.getPremiumPromo</a> and <a href="/method/help.getAppConfig">help.getAppConfig</a> to fetch info on how to build the premium modal. </p>
<p><a href="/method/help.getAppConfig">help.getAppConfig</a> will return a list of Premium feature identifiers in the <a href="/api/config#premium-promo-order"><code>premium_promo_order</code> appConfig field</a>: the modal should contain a row for each returned feature, ordered as specified in the returned array. </p>
<p>Possible feature identifiers:</p>
<ul>
<li><code>double_limits</code> - Clicking on this entry should open a secondary popup with a list of the <a href="#premium-limits">improved Premium limits »</a>.</li>
<li><code>more_upload</code> - Premium users can upload bigger files, as specified by the <a href="/api/config#upload-max-fileparts-default">upload_max_fileparts_default</a> vs <a href="/api/config#upload-max-fileparts-premium">upload_max_fileparts_premium</a> config keys.</li>
<li><code>faster_download</code> - Premium users have no download speed limits.</li>
<li><code>voice_to_text</code> - Premium users can <a href="/api/transcribe">transcribe voice messages</a>.</li>
<li><code>no_ads</code> - Premium users see no <a href="/api/sponsored-messages">sponsored messages</a>.</li>
<li><code>unique_reactions</code> - Premium users have access to more <a href="/api/reactions">message reactions</a>.</li>
<li><code>premium_stickers</code> - Premium users have access to premium <a href="/api/stickers">stickersets</a>.</li>
<li><code>animated_emoji</code> - Premium users can send custom <a href="/api/custom-emoji">animated emojis</a>.</li>
<li><code>advanced_chat_management</code> - Premium users can <a href="/api/folders">reorder the default folder</a>, auto-archive and hide new chats from non-contacts.</li>
<li><code>profile_badge</code> - Premium users have a <a href="#badge">badge</a> next to their name, showing that they are helping support Telegram.</li>
<li><code>animated_userpics</code> - <a href="/api/files#animated-profile-pictures">Animated profile pictures</a> of Premium users will play in-chat and when browsing the dialog list.</li>
<li><code>app_icons</code> - Premium users can change the default icon of the Telegram app.</li>
<li><code>infinite_reactions</code> - Premium users can use <a href="/api/custom-emoji">custom emojis</a> when <a href="/api/reactions">reacting to messages</a>.</li>
<li><code>emoji_status</code> - Premium users can set a <a href="/api/emoji-status">status emoji</a>.</li>
</ul>
<p>The <a href="/constructor/help.premiumPromo">help.premiumPromo</a> constructor returned by <a href="/method/help.getPremiumPromo">help.getPremiumPromo</a> contains various info about the subscription, as described in the <a href="/constructor/help.premiumPromo">constructor page</a>.</p>
<h4><a class="anchor" href="#premium-limits" id="premium-limits" name="premium-limits"><i class="anchor-icon"></i></a>Premium limits</h4>
<p>What follows is a list of <a href="/api/config#client-configuration">appConfig integer config parameters</a>. </p>
<p>Note that whenever config keys end with a <code>*</code> in the following list, the <code>*</code> should be replaced with <code>premium</code> or <code>default</code>, to fetch the appropriate limit value for Premium and non-Premium users.</p>
<ul>
<li><code>reactions_user_max_*</code> - The maximum number of <a href="/api/reactions">reactions</a> that can be added to a single message by the user.</li>
<li><code>channels_limit_*</code> - The maximum number of <a href="/api/channel">channels and supergroups</a> a user may join.</li>
<li><code>saved_gifs_limit_*</code> - The maximum number of GIFs a user may save.</li>
<li><code>stickers_faved_limit_*</code> - The maximum number of stickers a user may <a href="/api/stickers#favorite-stickersets">add to favorites</a>.</li>
<li><code>dialog_filters_limit_*</code> - The maximum number of <a href="/api/folders">folders</a> a user may create.</li>
<li><code>dialog_filters_chats_*</code> - The maximum number of chats a user may add to a <a href="/api/folders">folder</a>.</li>
<li><code>dialogs_pinned_limit_*</code> - The maximum number of chats a user may pin.</li>
<li><code>dialogs_folder_pinned_limit_*</code> - The maximum number of chats a user may pin in a folder.</li>
<li><code>channels_public_limit_*</code> - The maximum number of public <a href="/api/channel">channels or supergroups</a> a user may create.</li>
<li><code>caption_length_limit_*</code> - The maximum UTF-8 length of media captions.</li>
<li><code>about_length_limit_*</code> - The maximum UTF-8 length of user bios.</li>
</ul>
<h4><a class="anchor" href="#badge" id="badge" name="badge"><i class="anchor-icon"></i></a>Badge</h4>
<p>Users with a Telegram Premium subscription (<a href="/constructor/user">user</a>.<code>premium</code> is set) should have a Telegram Premium badge next to their name. </p>
<h4><a class="anchor" href="#animated-profile-pictures" id="animated-profile-pictures" name="animated-profile-pictures"><i class="anchor-icon"></i></a>Animated profile pictures</h4>
<p>The <a href="/api/files#animated-profile-pictures">animated profile pictures</a> of Premium users should play inside of chats and dialog lists, and not just when opening the profile page.</p>
<h4><a class="anchor" href="#sticker-suggestions" id="sticker-suggestions" name="sticker-suggestions"><i class="anchor-icon"></i></a>Sticker suggestions</h4>
<p>The suggested sticker selection logic is slightly different for Premium users, see <a href="/api/stickers#sticker-suggestions">here for more info »</a>.</p>
<h3><a class="anchor" href="#subscribing-to-telegram-premium" id="subscribing-to-telegram-premium" name="subscribing-to-telegram-premium"><i class="anchor-icon"></i></a>Subscribing to Telegram Premium</h3>
<p>Here's how to activate a Telegram Premium subscription, when the user clicks on the subscribe button:</p>
<ul>
<li>If the <code>premium_bot_username</code> field is set, call <a href="/method/messages.startBot">messages.startBot</a>, specifying the following parameters:<ul>
<li><code>peer</code> and <code>bot</code>: The bot mentioned in <code>premium_bot_username</code></li>
<li><code>start_param</code>: One of the following values:<ul>
<li>If the user clicks on the subscribe button when viewing the promo page for a specific Premium feature, provide the feature identifier.</li>
<li>If the user clicks on the subscribe button after hitting a limit that Telegram Premium raises, provide <code>double_limits</code></li>
<li>If the user clicks on the subscribe button from the Telegram Premium button in the settings, provide <code>settings</code></li>
<li>If the user clicks on the subscribe button from the Telegram Premium star in a profile page, provide <code>profile</code>
Then, when the user clicks on the subscribe button in the sent invoice, follow the <a href="/api/payments">usual payment flow for message invoices</a>. </li>
</ul>
</li>
</ul>
</li>
<li>Otherwise, if the <code>premium_invoice_slug</code> field is set, handle the payment as you would handle a <code>t.me/$premium_invoice_slug</code> <a href="/api/links#invoice-links">invoice deep link</a>.</li>
</ul>
<p>There is also a store-based subscription flow based on <a href="/method/payments.assignAppStoreTransaction">payments.assignAppStoreTransaction</a>/<a href="/method/payments.assignPlayMarketTransaction">payments.assignPlayMarketTransaction</a>, but it's currently not available to third-party apps (unlike the flow described above, which can be used by all clients).</p>
<h3><a class="anchor" href="#gifting-telegram-premium" id="gifting-telegram-premium" name="gifting-telegram-premium"><i class="anchor-icon"></i></a>Gifting Telegram Premium</h3>
<pre><code><a href='/constructor/userFull'>userFull</a>#c4b1fc3f flags:<a href='/type/%23'>#</a> blocked:flags.0?<a href='/constructor/true'>true</a> phone_calls_available:flags.4?<a href='/constructor/true'>true</a> phone_calls_private:flags.5?<a href='/constructor/true'>true</a> can_pin_message:flags.7?<a href='/constructor/true'>true</a> has_scheduled:flags.12?<a href='/constructor/true'>true</a> video_calls_available:flags.13?<a href='/constructor/true'>true</a> voice_messages_forbidden:flags.20?<a href='/constructor/true'>true</a> id:<a href='/type/long'>long</a> about:flags.1?<a href='/type/string'>string</a> settings:<a href='/type/PeerSettings'>PeerSettings</a> profile_photo:flags.2?<a href='/type/Photo'>Photo</a> notify_settings:<a href='/type/PeerNotifySettings'>PeerNotifySettings</a> bot_info:flags.3?<a href='/type/BotInfo'>BotInfo</a> pinned_msg_id:flags.6?<a href='/type/int'>int</a> common_chats_count:<a href='/type/int'>int</a> folder_id:flags.11?<a href='/type/int'>int</a> ttl_period:flags.14?<a href='/type/int'>int</a> theme_emoticon:flags.15?<a href='/type/string'>string</a> private_forward_name:flags.16?<a href='/type/string'>string</a> bot_group_admin_rights:flags.17?<a href='/type/ChatAdminRights'>ChatAdminRights</a> bot_broadcast_admin_rights:flags.18?<a href='/type/ChatAdminRights'>ChatAdminRights</a> premium_gifts:flags.19?<a href='/type/Vector%20t'>Vector</a>&lt;<a href='/type/PremiumGiftOption'>PremiumGiftOption</a>&gt; = <a href='/type/UserFull'>UserFull</a>;
<a href='/constructor/premiumGiftOption'>premiumGiftOption</a>#74c34319 flags:<a href='/type/%23'>#</a> months:<a href='/type/int'>int</a> currency:<a href='/type/string'>string</a> amount:<a href='/type/long'>long</a> bot_url:<a href='/type/string'>string</a> store_product:flags.0?<a href='/type/string'>string</a> = <a href='/type/PremiumGiftOption'>PremiumGiftOption</a>;
<a href='/constructor/messageActionGiftPremium'>messageActionGiftPremium</a>#aba0f5c6 currency:<a href='/type/string'>string</a> amount:<a href='/type/long'>long</a> months:<a href='/type/int'>int</a> = <a href='/type/MessageAction'>MessageAction</a>;
<a href='/constructor/inputStickerSetPremiumGifts'>inputStickerSetPremiumGifts</a>#c88b3b02 = <a href='/type/InputStickerSet'>InputStickerSet</a>;
---functions---
<a href='/method/users.getFullUser'>users.getFullUser</a>#b60f5918 id:<a href='/type/InputUser'>InputUser</a> = <a href='/type/users.UserFull'>users.UserFull</a>;</code></pre>
<p>If after calling <a href="/method/users.getFullUser">users.getFullUser</a> the resulting <a href="/constructor/userFull">userFull</a> constructor has one or more <a href="/constructor/premiumGiftOption">premiumGiftOptions</a> in the <code>premium_gifts</code> field, we can gift a non-recurring Telegram Premium subscription to this user. </p>
<p>The <a href="/constructor/premiumGiftOption">premiumGiftOption</a> 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 <a href="/api/links">deep link</a> contained in the <code>bot_url</code> field. </p>
<p>Once the payment is successfully processed, the user to which the gift was sent will automatically receive a <a href="/constructor/messageService">messageService</a> from the user that sent the gift, containing a <a href="/constructor/messageActionGiftPremium">messageActionGiftPremium</a> constructor with further info about the price and duration of the gifted Telegram Premium subscription.<br>
Clients should display this message, along with a sticker from the <a href="/constructor/inputStickerSetPremiumGifts">inputStickerSetPremiumGifts</a> <a href="/api/stickers">stickerset</a>: here's an <a href="https://telegram.org/blog/custom-emoji#gifting-telegram-premium">example</a>. </p>
<h3><a class="anchor" href="#blocked-telegram-premium" id="blocked-telegram-premium" name="blocked-telegram-premium"><i class="anchor-icon"></i></a>Blocked Telegram Premium</h3>
<p>If the <code>premium_purchase_blocked</code> <a href="/api/config#client-configuration">app configuration parameter</a> is set, the user can't purchase a Premium account, and all Telegram Premium features must be hidden (like the <a href="#badge">badges</a> of Premium users, Telegram Premium purchase buttons, and so on). </p></div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
<li><a href="//telegram.org/privacy">Privacy</a></li>
<li><a href="//telegram.org/press">Press</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
<script src="/js/main.js?47"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>