Users can send Gifts to their friends. The recipients of gifts can display them on their profile pages or turn them into Telegram Stars ». Telegram Stars can be used for many things, including supporting creators and buying services in mini apps.
payments.starGiftsNotModified#a388a368 = payments.StarGifts;
payments.starGifts#2ed82995 hash:int gifts:Vector<StarGift> chats:Vector<Chat> users:Vector<User> = payments.StarGifts;
starGift#bcff5b flags:# limited:flags.0?true sold_out:flags.1?true birthday:flags.2?true require_premium:flags.7?true limited_per_user:flags.8?true id:long sticker:Document stars:long availability_remains:flags.0?int availability_total:flags.0?int availability_resale:flags.4?long convert_stars:long first_sale_date:flags.1?int last_sale_date:flags.1?int upgrade_stars:flags.3?long resell_min_stars:flags.4?long title:flags.5?string released_by:flags.6?Peer per_user_total:flags.8?int per_user_remains:flags.8?int = StarGift;
inputInvoiceStarGift#e8625e92 flags:# hide_name:flags.0?true include_upgrade:flags.2?true peer:InputPeer gift_id:long message:flags.1?TextWithEntities = InputInvoice;
messageActionStarGift#4717e8a4 flags:# name_hidden:flags.0?true saved:flags.2?true converted:flags.3?true upgraded:flags.5?true refunded:flags.9?true can_upgrade:flags.10?true gift:StarGift message:flags.1?TextWithEntities convert_stars:flags.4?long upgrade_msg_id:flags.5?int upgrade_stars:flags.8?long from_id:flags.11?Peer peer:flags.12?Peer saved_id:flags.12?long = MessageAction;
payments.userStarGifts#6b65b517 flags:# count:int gifts:Vector<UserStarGift> next_offset:flags.0?string users:Vector<User> = payments.UserStarGifts;
inputPrivacyKeyStarGiftsAutoSave#e1732341 = InputPrivacyKey;
privacyKeyStarGiftsAutoSave#2ca4fdf8 = PrivacyKey;
---functions---
payments.getStarGifts#c4563590 hash:int = payments.StarGifts;
payments.saveStarGift#2a2a697c flags:# unsave:flags.0?true stargift:InputSavedStarGift = Bool;
payments.convertStarGift#74bf076b stargift:InputSavedStarGift = Bool;
payments.getUserStarGifts#5e72c7e1 user_id:InputUser offset:string limit:int = payments.UserStarGifts;Use payments.getStarGifts to obtain the full list of of available starGifts; to obtain gifts currently on resale », use payments.getResaleStarGifts.
Once the user chooses a (non-sold_out) gift, they may buy it spending starGift.stars Telegram Stars from our balance by invoking payments.getPaymentForm, passing an inputInvoiceStarGift, passing the following parameters:
peer: Identifier of the user or channel that will receive the giftgift_id: Identifier of the gift, from starGift.idmessage: Optional message, attached with the gift: the maximum length for this field is specified in the stargifts_message_length_max client configuration value ».hide_name: If set, your name will be hidden if the destination user decides to display the gift on their profile (they will still see that you sent the gift)include_upgrade: Set this flag to additionally prepay starGift.upgrade_stars Telegram Stars, allowing the receiver to convert the gift to a collectible gift » without paying anything.upgrade_stars is set. Then, follow the usual payment flow ».
Once the payment is completed, the user passed to user_id will receive a messageService with a messageActionStarGift from us, containing info about the received gift.
The user may then choose to display the received gift on their profile using payments.saveStarGift.
Received gifts may also be automatically displayed on the profile, depending on the destination user's privacy settings (inputPrivacyKeyStarGiftsAutoSave key).
Alternatively, the gift may be converted into Telegram Stars using payments.convertStarGift; the latter operation will permanently destroy the gift, converting it into starGift.convert_stars Telegram Stars, added to the user's balance (note that starGift.convert_stars will be less than the buying price (starGift.stars) of the gift if it was originally bought using Telegram Stars bought a long time ago).
A gift can be converted back into Telegram Stars only if it was received less than stargifts_convert_period_max seconds ago, as specified by the client configuration ».
Both methods take a user_id and a msg_id, the first should contain the identifier of the user that sent us the gift, and the second should contain the ID of the messageService with the messageActionStarGift.
If the user decides to display the received gift on their profile, it will be fetchable by all users using payments.getUserStarGifts.
The same method may also be used to fetch all gifts received by the current user from any user, by passing inputUserSelf to user_id.
Note that gift support must disabled if the stargifts_blocked client configuration flag » is set to true.
A received gift may be upgraded to a collectible gift.
Collectible gifts have special attributes and can be transferred to other users or auctioned on NFT marketplaces.
When you upgrade a gift it unlocks a new appearance from dozens of custom variations made by Telegram artists. Collectibles also receive a random set of secondary attributes, including a background color, icon and number. This means every collectible gift is a unique work of art — and that some will be more rare than others.
messageActionStarGift#4717e8a4 flags:# name_hidden:flags.0?true saved:flags.2?true converted:flags.3?true upgraded:flags.5?true refunded:flags.9?true can_upgrade:flags.10?true gift:StarGift message:flags.1?TextWithEntities convert_stars:flags.4?long upgrade_msg_id:flags.5?int upgrade_stars:flags.8?long from_id:flags.11?Peer peer:flags.12?Peer saved_id:flags.12?long = MessageAction;
savedStarGift#1ea646df flags:# name_hidden:flags.0?true unsaved:flags.5?true refunded:flags.9?true can_upgrade:flags.10?true pinned_to_top:flags.12?true from_id:flags.1?Peer date:int gift:StarGift message:flags.2?TextWithEntities msg_id:flags.3?int saved_id:flags.11?long convert_stars:flags.4?long upgrade_stars:flags.6?long can_export_at:flags.7?int transfer_stars:flags.8?long can_transfer_at:flags.13?int can_resell_at:flags.14?int collection_id:flags.15?Vector<int> = SavedStarGift;
starGift#bcff5b flags:# limited:flags.0?true sold_out:flags.1?true birthday:flags.2?true require_premium:flags.7?true limited_per_user:flags.8?true id:long sticker:Document stars:long availability_remains:flags.0?int availability_total:flags.0?int availability_resale:flags.4?long convert_stars:long first_sale_date:flags.1?int last_sale_date:flags.1?int upgrade_stars:flags.3?long resell_min_stars:flags.4?long title:flags.5?string released_by:flags.6?Peer per_user_total:flags.8?int per_user_remains:flags.8?int = StarGift;
starGiftAttributeModel#39d99013 name:string document:Document rarity_permille:int = StarGiftAttribute;
starGiftAttributePattern#13acff19 name:string document:Document rarity_permille:int = StarGiftAttribute;
starGiftAttributeBackdrop#d93d859c name:string backdrop_id:int center_color:int edge_color:int pattern_color:int text_color:int rarity_permille:int = StarGiftAttribute;
starGiftAttributeOriginalDetails#e0bff26c flags:# sender_id:flags.0?Peer recipient_id:Peer date:int message:flags.1?TextWithEntities = StarGiftAttribute;
payments.starGiftUpgradePreview#167bd90b sample_attributes:Vector<StarGiftAttribute> = payments.StarGiftUpgradePreview;
inputSavedStarGiftUser#69279795 msg_id:int = InputSavedStarGift;
inputSavedStarGiftChat#f101aa7f peer:InputPeer saved_id:long = InputSavedStarGift;
inputSavedStarGiftSlug#2085c238 slug:string = InputSavedStarGift;
---functions---
payments.getStarGiftUpgradePreview#9c9abcb1 gift_id:long = payments.StarGiftUpgradePreview;
payments.upgradeStarGift#aed6e4f5 flags:# keep_original_details:flags.0?true stargift:InputSavedStarGift = Updates;A received gift can be upgraded to a collectible gift if the messageActionStarGift.can_upgrade flag is set.
To obtain a preview of the possible attributes (chosen randomly) the gift can receive after the upgrade, invoke payments.getStarGiftUpgradePreview.
To upgrade a received gift, pay starGift.upgrade_stars Telegram Stars from our balance by invoking payments.getPaymentForm, passing an inputInvoiceStarGiftUpgrade with the following parameters:
stargift: The identifier of the received giftkeep_original_details: Set this flag to keep the original gift text, sender and receiver in the upgraded gift as a starGiftAttributeOriginalDetails attribute.Then, follow the usual payment flow ».
If the original sender of the gift has already paid for the upgrade by setting inputInvoiceStarGift.include_upgrade when buying the gift (this will be signaled by the messageActionStarGift.upgrade_stars flag), simply invoke payments.upgradeStarGift with the same flags instead of using the payments.getPaymentForm payment flow.
Upgrading a gift will emit a messageActionStarGiftUnique, containing info about the newly upgraded gift and some extra information.
messageActionStarGiftUnique#2e3ae60e flags:# upgrade:flags.0?true transferred:flags.1?true saved:flags.2?true refunded:flags.5?true gift:StarGift can_export_at:flags.3?int transfer_stars:flags.4?long from_id:flags.6?Peer peer:flags.7?Peer saved_id:flags.7?long resale_stars:flags.8?long can_transfer_at:flags.9?int can_resell_at:flags.10?int = MessageAction;
inputSavedStarGiftUser#69279795 msg_id:int = InputSavedStarGift;
inputSavedStarGiftChat#f101aa7f peer:InputPeer saved_id:long = InputSavedStarGift;
inputSavedStarGiftSlug#2085c238 slug:string = InputSavedStarGift;
payments.resaleStarGifts#947a12df flags:# count:int gifts:Vector<StarGift> next_offset:flags.0?string attributes:flags.1?Vector<StarGiftAttribute> attributes_hash:flags.1?long chats:Vector<Chat> counters:flags.2?Vector<StarGiftAttributeCounter> users:Vector<User> = payments.ResaleStarGifts;
---functions---
payments.updateStarGiftPrice#3baea4e1 stargift:InputSavedStarGift resell_stars:long = Updates;
payments.getResaleStarGifts#7a5fa236 flags:# sort_by_price:flags.1?true sort_by_num:flags.2?true attributes_hash:flags.0?long gift_id:long attributes:flags.3?Vector<StarGiftAttributeId> offset:string limit:int = payments.ResaleStarGifts;A collectible gift we own » can be put up for sale on the gift marketplace » by using payments.updateStarGiftPrice, specifying the price in resell_stars; if someone buys the gift, you will get resell_stars*stars_stargift_resale_commission_permille » /1000 stars.
The minimum and maximum resale prices are specified in the stars_stargift_resale_amount_min »/stars_stargift_resale_amount_max » client configuration parameters; passing 0 will unlist the gift from the marketplace.
To obtain gifts currently on resale, use payments.getResaleStarGifts.
messageActionStarGiftUnique#2e3ae60e flags:# upgrade:flags.0?true transferred:flags.1?true saved:flags.2?true refunded:flags.5?true gift:StarGift can_export_at:flags.3?int transfer_stars:flags.4?long from_id:flags.6?Peer peer:flags.7?Peer saved_id:flags.7?long resale_stars:flags.8?long can_transfer_at:flags.9?int can_resell_at:flags.10?int = MessageAction;
inputSavedStarGiftUser#69279795 msg_id:int = InputSavedStarGift;
inputSavedStarGiftChat#f101aa7f peer:InputPeer saved_id:long = InputSavedStarGift;
inputSavedStarGiftSlug#2085c238 slug:string = InputSavedStarGift;
inputInvoiceStarGiftTransfer#4a5f5bd9 stargift:InputSavedStarGift to_id:InputPeer = InputInvoice;
---functions---
payments.transferStarGift#7f18176a stargift:InputSavedStarGift to_id:InputPeer = Updates;A collectible gift may be transferred to another user.
To transfer a collectible gift, pay starGift.upgrade_stars Telegram Stars from our balance by invoking payments.getPaymentForm, passing an inputInvoiceStarGiftTransfer with the following parameters:
stargift: The identifier of the received giftto_id: The destination peerThen, follow the usual payment flow ».
If the original sender of the gift has already paid for the upgrade by setting inputInvoiceStarGift.include_upgrade when buying the gift (this will be signaled by the messageActionStarGift.upgrade_stars flag), simply invoke payments.upgradeStarGift with the same flags instead of using the payments.getPaymentForm payment flow.