Telegram Gifts

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.

Sending gifts

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.

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 gift
• gift_id: Identifier of the gift, from starGift.id
• message: 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.
  Note that this flag can only be set if starGift.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.

Collectible gifts

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#dfda0499 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 = 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;

---functions---

payments.getStarGiftUpgradePreview#9c9abcb1 gift_id:long = payments.StarGiftUpgradePreview;
payments.upgradeStarGift#cf4f0781 flags:# keep_original_details:flags.0?true msg_id:int = Updates;

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 traits, 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.

To obtain a preview of the possible attributes 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 gift
• keep_original_details: Set this flag to keep the original gift text, sender and receiver in the upgraded gift

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, simply invoke payments.upgradeStarGift with the same flags instead of using the payments.getPaymentForm payment flow.

Upgrading a gift will emit a messageActionStarGiftUnique

Transferring gifts

---functions---

payments.transferStarGift#333fb526 msg_id:int to_id:InputUser = Updates;