赠品和礼品

拥有任何权限的Telegram频道和超级群组管理员可以发起赠送活动，随机向其关注者分发Telegram Premium订阅和其他礼物，以换取推广。

赠品和礼品码

只有当giveaway_gifts_purchase_available配置值设置为 true 时，才能启用此功能。

请注意，下面描述的流程也可以用于向多个朋友赠送高级订阅，这与旧的赠送流程不同，旧的赠送流程只允许赠送一个订阅，并且有一些额外的限制，而此流程中没有这些限制。

请注意，高级多礼品链接会跳转到使用下面描述的新礼品流程的页面。

模式：

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#fb790393 flags:# users:Vector<InputUser> boost_peer:flags.0?InputPeer currency:string amount:long message:flags.1?TextWithEntities = 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#aa073beb 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:flags.4?int stars:flags.5?long until_date:int = MessageMedia;messageActionGiveawayLaunch#a80f51e4 flags:# stars:flags.0?long = MessageAction; messageActionGiveawayResults#87e2f155 flags:# stars:flags.0?true winners_count:int unclaimed_count:int = MessageAction;messageActionGiftCode#56d03994 flags:# via_giveaway:flags.0?true unclaimed:flags.5?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 message:flags.4?TextWithEntities = 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#e175e66f flags:# winner:flags.0?true refunded:flags.1?true start_date:int gift_code_slug:flags.3?string stars_prize:flags.4?long finish_date:int winners_count:int activated_count:flags.2?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;---functions---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;

首先，调用payments.getPremiumGiftCodeOptions获取premiumGiftCodeOption构造函数的列表，其中包含管理员可以选择的赠品选项列表，指示将在赠品中赠送的Telegram Premiumamount订阅的数量和持续时间，以及它们在指定位置的价格currency（请参阅构造函数页面 »以了解有关这些字段的更多信息）。

管理员选择特定礼品码选项后，调用payments.getPaymentForm，传入一个inputInvoicePremiumGiftCode参数，其中包含所选的premiumGiftCodeOption选项option以及purpose以下任一内容：

• 使用`inputStorePaymentPremiumGiveaway`创建一个赠送活动，Telegram 会随机选择option.users指定频道/超级群组的订阅者参与（如果设置了 `inputStorePaymentPremiumGiveaway` 字段purpose.boost_peer，则仅限活动创建日期之后的新订阅者）。用户必须加入的其他频道/超级群组也可以在 `inputStorePaymentPremiumGiveaway` 中指定。可以通过传递一个最多包含 `giveaway_countries_max`个国家/地区的白名单来限制参与赠送活动的用户范围，白名单中国家/地区代码以两位字母的 ISO 3166-1 alpha-2 国家/地区代码的形式指定。赠送活动的结束日期必须在 `inputStorePaymentPremiumGiveaway` 中指定，且必须在 `inputStorePaymentPremiumGiveaway` 中指定，并且结束日期必须在 `inputStorePaymentPremiumGiveaway` 中指定，且结束日期必须在 `inputStorePaymentPremiumGiveaway` 中指定（最多为 `giveaway_period_max`秒）。届时，Telegram 将根据上述条件随机选择订阅者，并通过 `messageActionGiftCode`构造函数向他们发送 Telegram Premium 礼品码，客户端应使用此构造函数生成礼品码链接。指定的频道/超级群组将从每位获奖者处获得giveaway_boosts_per_premium推广，这些推广在赠送订阅的有效期内不能重新分配给其他频道/超级群组。purpose.only_new_subscribers
  additional_peers
  countries_iso2
  until_dateoption.users
  boost_peer
• 或者使用`inputStorePaymentPremiumGiftCode`，仅将Telegram Premium订阅赠送给指定频道/超级群组中的特定订阅者（purpose.users最多`giveaway_add_peers_max`purpose.boost_peer个用户） ，每个用户将获得`giveaway_boosts_per_premium` 个推广名额，这些名额在赠送订阅的有效期内不能重新分配给其他频道/超级群组。用户也可以通过不设置 ` giveaway_add_peers_max` 字段
  ，直接将此方法赠送给联系人：在这种情况下，将Telegram Premium订阅赠送给其他用户将为我们创建`boosts_per_sent_gift`个推广名额，并为接收用户创建一个推广名额。boost_peer

然后，按照付款文档中描述的发票付款流程进行操作 »。

还有更多替代支付方式可供选择：

• Premium Bot 流程，通过联系premium_bot_username，并按照赠品的内联键盘支付流程进行操作（带有价格的最终键盘将包含带有发票深度链接的按钮 »，应该使用这些按钮进行支付）。
• 通过Fragment付款，也允许进行更大额的购买。
• 基于payments.assignAppStoreTransaction/payments.assignPlayMarketTransaction的应用商店订阅流程，目前不适用于第三方应用。

然后：

• 如果付款是通过payments.getPaymentForm或payments.assignAppStoreTransaction/payments.assignPlayMarketTransaction付款流程进行的，则赠送活动将在付款完成后立即启动。

• 否则，如果使用了高级机器人或片段流程，则在完成赠品付款后，调用premium.getBoostsStatus，并将peer我们在支付赠品费用时选择的频道/超级组的 ID 传递给它，以获取premium.boostsStatus中的prepaidGiveaway构造函数，其中包含有关预付费赠品的信息。prepaid_giveaways

  要实际启动 Fragment 和 bot 流程的赠品活动，请调用payments.launchPrepaidGiveaway，并将prepaidGiveaway传递给，id将giveaway_id频道/超级组的 ID 传递给peer，并将赠品设置purpose（如上所述填充）传递给 。

最后：

• 如果付款成功，并且我们使用inputStorePaymentPremiumGiveaway发起抽奖活动：将向频道/超级组发送messageActionGiveawayLaunch服务消息和包含messageMediaGiveaway的媒体消息。

  活动结束后，系统会向频道/超级群组发送一条消息“messageActionGiveawayResults”，获奖者将自动收到来自 Telegram 服务用户的“messageActionGiftCode”slug服务消息，其中包含可用于生成礼品码链接以兑换高级订阅的密钥。
  消息“messageActionGiftCode”via_giveaway标志将被设置。

• 如果付款成功，并且我们只是向特定用户赠送一些订阅：`inputStorePaymentPremiumGiftCode`，则指定的用户将自动收到来自 Telegram 服务用户的`messageActionGiftCode`slug服务消息，其中包含可用于生成礼品码链接以兑换高级订阅的密钥。`messageActionGiftCode`标志
  不会被设置。via_giveaway

  请注意，如果付款是代表用户进行的（即boost_peer未设置），则收到礼物的用户将收到来自赠送用户的messageService ，其中包含一个messageActionGiftPremium构造函数，其中包含有关赠送的 Telegram Premium 订阅的价格和有效期的更多信息。
  客户端应显示此消息，并附上来自inputStickerSetPremiumGifts 贴纸集的贴纸：这里有一个示例。

messageActionGiftCode应该用于生成礼品码链接，用户可以使用该链接兑换订阅，或将其转赠给其他人。slug

如果在开始抽奖活动时设置了标志，则抽奖活动的获奖者将公开，并在抽奖活动结束后自动发送到频道/超级群组的messageMediaGiveawayResultswinners_are_visible消息中列出。

任何用户都可以使用链接的别名调用`payments.checkGiftCode`from_id来获取赠品的相关信息，例如赠送订阅的频道/超级群组（ ）以及最初收到礼物的用户（to_id）。
这对于频道/超级群组管理员来说也很有用，可以帮助他们精确确定赠品的获奖者。例如，如果赠品除了高级订阅之外还包含其他礼物（例如特斯拉汽车）：获奖者只需发送他们的链接即可作为无可争议的获奖证明，因为在调用`payments.checkGiftCode`并传入别名to_id后，Telegram 返回的字段中会显示收到礼物的用户。管理员还可以使用另一种方法来查看谁收到了礼物，那就是在礼物获得的推广仍然有效时 ，直接使用`premium.getBoostsList` 。

要领取Telegram Premium订阅，只需调用payments.applyGiftCode，并传递链接的slug.

明星赠品

starsGiveawayOption#94ce852a flags:# extended:flags.0?true default:flags.1?true stars:long yearly_boosts:int store_product:flags.2?string currency:string amount:long winners:Vector<StarsGiveawayWinnersOption> = StarsGiveawayOption;starsGiveawayWinnersOption#54236209 flags:# default:flags.0?true users:int per_user_stars:long = StarsGiveawayWinnersOption;inputInvoiceStars#65f00ce3 purpose:InputStorePaymentPurpose = InputInvoice;inputStorePaymentStarsGiveaway#751f08fa flags:# only_new_subscribers:flags.0?true winners_are_visible:flags.3?true stars:long 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 users:int = InputStorePaymentPurpose;---functions---payments.getStarsGiveawayOptions#bd1efd3e = Vector<StarsGiveawayOption>;payments.getPaymentForm#37148dbb flags:# invoice:InputInvoice theme_params:flags.0?DataJSON = payments.PaymentForm;

星形奖品赠送活动与普通赠送活动类似，唯一的区别在于，赠送活动不会赠送礼物或Telegram Premium 会员资格，而是会自动向获奖者分发Telegram 星星。

首先，调用payments.getStarsGiveawayOptions获取starsGiveawayOption构造函数列表，其中包含管理员可以选择的赠品选项列表，指示赠品活动的获奖者人数、赠品活动中将赠送的Telegram Starsamount数量以及它们在指定货币中的价格（有关这些字段和所有剩余字段的更多信息，currency请参阅构造函数页面 » ）。

管理员选定具体的赠送选项后，调用payments.getPaymentForm，并传入一个包含inputStorePaymentStarsGiveaway构造函数的inputInvoiceStars对象，其中：

• ，以及从选定的starsGiveawayOptionstars和一些额外的选项中指定，如构造函数页面 »中所述。currencyamount
• 可以在以下位置指定用户必须加入才能参与抽奖活动的其他频道/超级群组additional_peers。
• 可以通过传递一个明确的白名单来限制可以参与抽奖的用户集合，该白名单最多包含giveaway_countries_max个国家/地区，这些国家/地区以两位字母 ISO 3166-1 alpha-2 国家/地区代码的形式指定countries_iso2。
• 必须在 `giveaway_period_max` 中指定抽奖活动的结束日期until_date，且该日期最多只能是之后的`giveaway_period_max`秒；届时，Telegram 将users根据上述条件随机选择订阅者，并通过`messageActionPrizeStars`per_user_stars构造函数向他们发送Telegram Stars。此外，如果抽奖活动结束时频道中的成员数量少于中奖者数量，则还可以发出带有`--returns` 标志的`messageActionPrizeStars` 消息，将剩余的 Stars 退还给抽奖活动的创建者。
  unclaimed
• 指定的频道/超级组合boost_peer将获得starsGiveawayOption 的yearly_boosts推广，为期一年。

然后，按照付款文档中描述的发票付款流程进行操作 »。

还有更多替代支付方式可供选择：

• Premium Bot 流程，通过联系premium_bot_username，并按照内联键盘支付流程进行星级赠品支付（带有价格的最终键盘将包含带有发票深度链接的按钮 »，应使用这些按钮进行支付）。
• 基于payments.assignAppStoreTransaction/payments.assignPlayMarketTransaction的应用商店订阅流程，目前不适用于第三方应用。

然后：

• 如果付款是通过payments.getPaymentForm或payments.assignAppStoreTransaction/payments.assignPlayMarketTransaction付款流程进行的，则赠送活动将在付款完成后立即启动。

• 否则，如果使用了高级机器人流程，在完成赠品支付后，调用`premium.getBoostsStatus`，peer并将支付赠品时选择的频道/超级群组的 ID 传递给它，以获取`premium.boostsStatus`中的`prepaidStarsGiveaway`构造函数，其中包含有关预付费星星赠品的信息。要实际启动机器人流程的赠品活动，请调用`payments.launchPrepaidGiveaway`，并将`prepaidStarsGiveaway`传递给它，频道/超级群组的 ID 传递给它，赠品设置（在上方创建的`inputStorePaymentStarsGiveaway`中填充）传递给它。prepaid_giveaways
  idgiveaway_idpeerpurpose