<metaproperty="description"content="Telegram channel administrators may launch giveaways to randomly distribute Telegram Premium subscriptions and other gifts among their followers, in exchange for boosts.">
<metaproperty="og:title"content="Giveaways">
<metaproperty="og:image"content="">
<metaproperty="og:description"content="Telegram channel administrators may launch giveaways to randomly distribute Telegram Premium subscriptions and other gifts among their followers, in exchange for boosts.">
<p>Telegram <ahref="/api/channel">channel</a> administrators may launch giveaways to randomly distribute <ahref="/api/premium">Telegram Premium</a> subscriptions and other gifts among their followers, in exchange for <ahref="/api/boost">boosts</a>.</p>
<p>This functionality should only be enabled if the <ahref="/api/config#giveaway-gifts-purchase-available">giveaway_gifts_purchase_available</a> config value is set to true. </p>
<p>Note that the flow described below can also be used to gift a Premium subscriptions to multiple friends, and is different from the <ahref="/api/premium#gifting-telegram-premium">old gift flow</a>, which allowed gifting only one subscription with some extra limitations, not present in this flow. </p>
<p>Note that <ahref="/api/links#premium-multigift-links">premium multigift links</a> lead to a page that uses the new gift flow described below. </p>
<p>First of all, invoke <ahref="/method/payments.getPremiumGiftCodeOptions">payments.getPremiumGiftCodeOptions</a> to obtain a list of <ahref="/constructor/premiumGiftCodeOption">premiumGiftCodeOption</a> constructors, containing a list of giveaway options that may be chosen by the admin, indicating the number and duration of the of <ahref="/api/premium">Telegram Premium</a> subscriptions that will be gifted in the giveaway, along with their price (<code>amount</code>) in the specified <code>currency</code> (see the <ahref="/constructor/premiumGiftCodeOption">constructor page »</a> for more info on these fields). </p>
<p>Once the admin has chosen a specific gift code option, invoke <ahref="/method/payments.getPaymentForm">payments.getPaymentForm</a>, passing an <ahref="/constructor/inputInvoicePremiumGiftCode">inputInvoicePremiumGiftCode</a>, with the chosen <ahref="/constructor/premiumGiftCodeOption">premiumGiftCodeOption</a> in <code>option</code> and a <code>purpose</code> containing either:</p>
<ul>
<li><ahref="/constructor/inputStorePaymentPremiumGiveaway">inputStorePaymentPremiumGiveaway</a> to create a giveaway, where Telegram will randomly select <code>option.users</code> subscribers to the channel specified in <code>purpose.boost_peer</code> (only new subscribers starting from the giveaway creation date if the <code>purpose.only_new_subscribers</code> field is set).<br>
Additional channels that the user must join to participate to the giveaway can be specified in <code>additional_peers</code>.<br>
The set of users that can participate to the giveaway can be restricted by passing an explicit whitelist of up to <ahref="/api/config#giveaway-countries-max">giveaway_countries_max</a> countries, specified as two-letter ISO 3166-1 alpha-2 country codes in <code>countries_iso2</code>.<br>
The end date of the giveaway must be specified in <code>until_date</code>, and it must be at most <ahref="/api/config#giveaway-period-max">giveaway_period_max</a> seconds in the future; at that date, Telegram will randomly choose <code>option.users</code> subscribers according to the conditions specified above, and send them a Telegram Premium giftcode as a <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a> constructor, that should be used client-side to generate a <ahref="/api/links#premium-giftcode-links">giftcode link</a>.<br>
The channel specified in <code>boost_peer</code> will receive <ahref="/api/config#giveaway-boosts-per-premium">giveaway_boosts_per_premium</a><ahref="/api/boost">boosts</a> from each user, that cannot be reassigned to another channel for the duration of the gifted subscription. </li>
<li>or <ahref="/constructor/inputStorePaymentPremiumGiftCode">inputStorePaymentPremiumGiftCode</a>, to gift <ahref="/api/premium">Telegram Premium</a> subscriptions only to some specific subscribers (<code>purpose.users</code>, max <ahref="/api/config#giveaway-add-peers-max">giveaway_add_peers_max</a> users) of the channel specified in <code>purpose.boost_peer</code>, which will receive <ahref="/api/config#giveaway-boosts-per-premium">giveaway_boosts_per_premium</a><ahref="/api/boost">boosts</a> from each user, that cannot be reassigned to another channel for the duration of the gifted subscription.<br>
Users may also use this method to simply gift subscriptions to contacts by <strong>not</strong> setting the <code>boost_peer</code> field: in this case, gifting a <ahref="/api/premium">Telegram Premium</a> subscription to another user will create <ahref="/api/config#boosts-per-sent-gift">boosts_per_sent_gift</a><ahref="/api/boost">boost slots »</a> for us, and one boost slot for the destination user. </li>
</ul>
<p>Then, follow the <ahref="/api/payments#22-getting-invoice-info-about-the-product">invoice payment flow as described in the payments documentation »</a>. </p>
<p>More alternative payment flows are also available:</p>
<ul>
<li>The Premium Bot flow, by contacting <ahref="/api/config#premium-bot-username">premium_bot_username</a>, and following the inline keyboard payment flow for giveaways (the final keyboard with the prices will contain buttons with <ahref="/api/links#invoice-links">invoice deep links »</a> that should be used to make the payment).</li>
<li>Payment via <ahref="https://fragment.com">Fragment</a>, which also allows making larger purchases.</li>
<li>The store-based subscription flow based on <ahref="/method/payments.assignAppStoreTransaction">payments.assignAppStoreTransaction</a>/<ahref="/method/payments.assignPlayMarketTransaction">payments.assignPlayMarketTransaction</a>, currently not available to third-party apps. </li>
</ul>
<p>Then:</p>
<ul>
<li>
<p>If the payment was made using the <ahref="/method/payments.getPaymentForm">payments.getPaymentForm</a> or <ahref="/method/payments.assignAppStoreTransaction">payments.assignAppStoreTransaction</a>/<ahref="/method/payments.assignPlayMarketTransaction">payments.assignPlayMarketTransaction</a> payment flows, the giveaway will launch as soon as the payment is complete.</p>
</li>
<li>
<p>Otherwise, if the <ahref="/api/config#premium-bot-username">Premium bot</a> or <ahref="https://fragment.com">Fragment</a> flows were used, once the payment for the giveaway is made, invoke <ahref="/method/premium.getBoostsStatus">premium.getBoostsStatus</a>, passing to <code>peer</code> the ID of the channel that we selected when paying for the giveaway, to obtain a <ahref="/constructor/prepaidGiveaway">prepaidGiveaway</a> constructor in <ahref="/constructor/premium.boostsStatus">premium.boostsStatus</a>.<code>prepaid_giveaways</code>, containing info about the prepaid giveaway. </p>
<p>To actually launch the giveaway for the Fragment and bot flows, invoke <ahref="/method/payments.launchPrepaidGiveaway">payments.launchPrepaidGiveaway</a>, passing <ahref="/constructor/prepaidGiveaway">prepaidGiveaway</a>.<code>id</code> to <code>giveaway_id</code>, the ID of the channel to <code>peer</code> and giveaway settings in <code>purpose</code> (populated as specified above). </p>
</li>
</ul>
<p>Finally:</p>
<ul>
<li>
<p>If the payment succeeds and we're launching a giveaway using <ahref="/constructor/inputStorePaymentPremiumGiveaway">inputStorePaymentPremiumGiveaway</a>: a <ahref="/constructor/messageActionGiveawayLaunch">messageActionGiveawayLaunch</a> service message and a media message containing a <ahref="/constructor/messageMediaGiveaway">messageMediaGiveaway</a> will be sent to the channel. </p>
<p>Once the giveaway is over, a <ahref="/constructor/messageActionGiveawayResults">messageActionGiveawayResults</a> will be sent to the channel and the winners will automatically receive a <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a> service message from Telegram's service user, containing the <code>slug</code> that can be used to generate a <ahref="/api/links#premium-giftcode-links">giftcode link</a> to redeem the Premium subscription.<br>
The <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a>.<code>via_giveaway</code> flag will be set. </p>
</li>
<li>
<p>If the payment succeeds and we're simply gifting some subscriptions to specific users <ahref="/constructor/inputStorePaymentPremiumGiftCode">inputStorePaymentPremiumGiftCode</a>: the specified users will automatically receive a <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a> service message from Telegram's service user, containing the <code>slug</code> that can be used to generate a <ahref="/api/links#premium-giftcode-links">giftcode link</a> to redeem the Premium subscription.<br>
The <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a>.<code>via_giveaway</code> flag will not be set. </p>
<p>Note that if the payment was made on behalf of the user (i.e. if <code>boost_peer</code> was <strong>not</strong> set), then the users to which the gift was sent will instead receive a <ahref="/constructor/messageService">messageService</a> from the user that sent the gift, containing a <ahref="/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 <ahref="/constructor/inputStickerSetPremiumGifts">inputStickerSetPremiumGifts</a><ahref="/api/stickers">stickerset</a>: here's an <ahref="https://telegram.org/blog/custom-emoji#gifting-telegram-premium">example</a>. </p>
</li>
</ul>
<p>The <ahref="/constructor/messageActionGiftCode">messageActionGiftCode</a>.<code>slug</code> should be used to generate a <ahref="/api/links#premium-giftcode-links">giftcode link</a>, that the user can use to redeem the subscription, or re-gift it to someone else. </p>
<p>If <code>winners_are_visible</code> flag is set while starting a giveaway, giveaway winners are public and will be listed in a <ahref="/constructor/messageMediaGiveawayResults">messageMediaGiveawayResults</a> message that will be automatically sent to the channel once the giveaway ends. </p>
<p>Any user can invoke <ahref="/method/payments.checkGiftCode">payments.checkGiftCode</a> with the link's slug to obtain info about the giveaway, such as the channel that gifted the subscription (<code>from_id</code>), and the user that originally received the gift (<code>to_id</code>).<br>
This can also be useful to channel administrators to precisely determine the winners of a giveaway, for example if the giveaway also included some extra gifts apart from Premium subscriptions (<em>like Teslas</em>): the winners can simply send their link as undisputable proof that they won the giveaway, because the user that received the gift can be viewed in the <code>to_id</code> field returned by Telegram when invoking <ahref="/method/payments.checkGiftCode">payments.checkGiftCode</a> on the slug.<br>
Another way for admins to check who received the gifts is to simply use <ahref="/method/premium.getBoostsList">premium.getBoostsList</a> while the boosts received by the gifts are still active. </p>
<p>To claim the <ahref="/api/premium">Telegram Premium</a> subscription, simply invoke <ahref="/method/payments.applyGiftCode">payments.applyGiftCode</a>, passing the link's <code>slug</code>.</p></div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
