Telegram channel administrators may launch giveaways to randomly distribute Telegram Premium subscriptions and other gifts among their followers, in exchange for boosts.

This functionality should only be enabled if the giveaway_gifts_purchase_available config value is set to true.

Note that the flow described below can also be used to gift a Premium subscriptions to multiple friends, and is different from the old gift flow, which allowed gifting only one subscription with some extra limitations, not present in this flow.

Note that premium multigift links lead to a page that uses the new gift flow described below.


premiumGiftCodeOption#257e962b flags:# users:int months:int store_product:flags.0?string store_quantity:flags.1?int currency:string amount:long = PremiumGiftCodeOption;

inputStorePaymentPremiumGiveaway#160544ca flags:# only_new_subscribers:flags.0?true winners_are_visible:flags.3?true boost_peer:InputPeer additional_peers:flags.1?Vector<InputPeer> countries_iso2:flags.2?Vector<string> prize_description:flags.4?string random_id:long until_date:int currency:string amount:long = InputStorePaymentPurpose;
inputStorePaymentPremiumGiftCode#a3805f3f flags:# users:Vector<InputUser> boost_peer:flags.0?InputPeer currency:string amount:long = InputStorePaymentPurpose;

inputInvoicePremiumGiftCode#98986c0d purpose:InputStorePaymentPurpose option:PremiumGiftCodeOption = InputInvoice;

prepaidGiveaway#b2539d54 id:long months:int quantity:int date:int = PrepaidGiveaway;

premium.boostsStatus#4959427a flags:# my_boost:flags.2?true level:int current_level_boosts:int boosts:int gift_boosts:flags.4?int next_level_boosts:flags.0?int premium_audience:flags.1?StatsPercentValue boost_url:string prepaid_giveaways:flags.3?Vector<PrepaidGiveaway> my_boost_slots:flags.2?Vector<int> = premium.BoostsStatus;

messageMediaGiveaway#daad85b0 flags:# only_new_subscribers:flags.0?true winners_are_visible:flags.2?true channels:Vector<long> countries_iso2:flags.1?Vector<string> prize_description:flags.3?string quantity:int months:int until_date:int = MessageMedia;

messageActionGiveawayLaunch#332ba9ed = MessageAction;
messageActionGiveawayResults#2a9fadc5 winners_count:int unclaimed_count:int = MessageAction;

messageActionGiftCode#678c2e09 flags:# via_giveaway:flags.0?true unclaimed:flags.2?true boost_peer:flags.1?Peer months:int slug:string currency:flags.2?string amount:flags.2?long crypto_currency:flags.3?string crypto_amount:flags.3?long = MessageAction;

payments.giveawayInfo#4367daa0 flags:# participating:flags.0?true preparing_results:flags.3?true start_date:int joined_too_early_date:flags.1?int admin_disallowed_chat_id:flags.2?long disallowed_country:flags.4?string = payments.GiveawayInfo;
payments.giveawayInfoResults#00cd5570 flags:# winner:flags.0?true refunded:flags.1?true start_date:int gift_code_slug:flags.0?string finish_date:int winners_count:int activated_count:int = payments.GiveawayInfo;

payments.checkedGiftCode#284a1096 flags:# via_giveaway:flags.2?true from_id:flags.4?Peer giveaway_msg_id:flags.3?int to_id:flags.0?long date:int months:int used_date:flags.1?int chats:Vector<Chat> users:Vector<User> = payments.CheckedGiftCode;


payments.getPremiumGiftCodeOptions#2757ba54 flags:# boost_peer:flags.0?InputPeer = Vector<PremiumGiftCodeOption>;

payments.getPaymentForm#37148dbb flags:# invoice:InputInvoice theme_params:flags.0?DataJSON = payments.PaymentForm;

premium.getBoostsStatus#042f1f61 peer:InputPeer = premium.BoostsStatus;

payments.launchPrepaidGiveaway#5ff58f20 peer:InputPeer giveaway_id:long purpose:InputStorePaymentPurpose = Updates;

payments.getGiveawayInfo#f4239425 peer:InputPeer msg_id:int = payments.GiveawayInfo;

payments.checkGiftCode#8e51b4c1 slug:string = payments.CheckedGiftCode;
payments.applyGiftCode#f6e26854 slug:string = Updates;

First of all, invoke payments.getPremiumGiftCodeOptions to obtain a list of premiumGiftCodeOption constructors, containing a list of giveaway options that may be chosen by the admin, indicating the number and duration of the of Telegram Premium subscriptions that will be gifted in the giveaway, along with their price (amount) in the specified currency (see the constructor page » for more info on these fields).

Once the admin has chosen a specific gift code option, invoke payments.getPaymentForm, passing an inputInvoicePremiumGiftCode, with the chosen premiumGiftCodeOption in option and a purpose containing either:

  • inputStorePaymentPremiumGiveaway to create a giveaway, where Telegram will randomly select option.users subscribers to the channel specified in purpose.boost_peer (only new subscribers starting from the giveaway creation date if the purpose.only_new_subscribers field is set).
    Additional channels that the user must join to participate to the giveaway can be specified in additional_peers.
    The set of users that can participate to the giveaway can be restricted by passing an explicit whitelist of up to giveaway_countries_max countries, specified as two-letter ISO 3166-1 alpha-2 country codes in countries_iso2.
    The end date of the giveaway must be specified in until_date, and it must be at most giveaway_period_max seconds in the future; at that date, Telegram will randomly choose option.users subscribers according to the conditions specified above, and send them a Telegram Premium giftcode as a messageActionGiftCode constructor, that should be used client-side to generate a giftcode link.
    The channel specified in boost_peer will receive giveaway_boosts_per_premium boosts from each user, that cannot be reassigned to another channel for the duration of the gifted subscription.
  • or inputStorePaymentPremiumGiftCode, to gift Telegram Premium subscriptions only to some specific subscribers (purpose.users, max giveaway_add_peers_max users) of the channel specified in purpose.boost_peer, which will receive giveaway_boosts_per_premium boosts from each user, that cannot be reassigned to another channel for the duration of the gifted subscription.
    Users may also use this method to simply gift subscriptions to contacts by not setting the boost_peer field: in this case, 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.

Then, follow the invoice payment flow as described in the payments documentation ».

More alternative payment flows are also available:



The messageActionGiftCode.slug should be used to generate a giftcode link, that the user can use to redeem the subscription, or re-gift it to someone else.

If winners_are_visible flag is set while starting a giveaway, giveaway winners are public and will be listed in a messageMediaGiveawayResults message that will be automatically sent to the channel once the giveaway ends.

Any user can invoke payments.checkGiftCode with the link's slug to obtain info about the giveaway, such as the channel that gifted the subscription (from_id), and the user that originally received the gift (to_id).
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 (like Teslas): 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 to_id field returned by Telegram when invoking payments.checkGiftCode on the slug.
Another way for admins to check who received the gifts is to simply use premium.getBoostsList while the boosts received by the gifts are still active.

To claim the Telegram Premium subscription, simply invoke payments.applyGiftCode, passing the link's slug.