• API
• Telegram Gifts

Users can sendGifts to their friends. The recipients of gifts can display them on their profile pages or turn them intoTelegram 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#901689ea hash:int gifts:Vector<StarGift> =payments.StarGifts;starGift#49c577cd flags:# limited:flags.0?true sold_out:flags.1?true birthday:flags.2?true id:long sticker:Document stars:long availability_remains:flags.0?int availability_total:flags.0?int convert_stars:long first_sale_date:flags.1?int last_sale_date:flags.1?int =StarGift;inputInvoiceStarGift#25d8c1d8 flags:# hide_name:flags.0?true user_id:InputUser gift_id:long message:flags.1?TextWithEntities =InputInvoice;messageActionStarGift#8557637 flags:# name_hidden:flags.0?true saved:flags.2?true converted:flags.3?true gift:StarGift message:flags.1?TextWithEntities convert_stars:flags.4?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#87acf08e flags:# unsave:flags.0?true user_id:InputUser msg_id:int =Bool;payments.convertStarGift#0421e027 user_id:InputUser msg_id:int =Bool;payments.getUserStarGifts#5e72c7e1 user_id:InputUser offset:string limit:int =payments.UserStarGifts;

Usepayments.getStarGifts to obtain the full list of of availablestarGifts.

Once the user chooses a (non-sold_out) gift, they may buy it spendingstarGift.starsTelegram Stars from our balance by invokingpayments.getPaymentForm, passing aninputInvoiceStarGift, passing the following parameters:

• user_id: Identifier of the user that will receive the gift
• gift_id: Identifier of the gift, fromstarGift.id
• message: Optional message, attached with the gift: the maximum length for this field is specified in thestargifts_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)

Then, follow theusual payment flow ».

Once the payment is completed, the user passed touser_id will receive amessageService with amessageActionStarGift from us, containing info about the received gift.

The user may then choose to display the received gift on their profile usingpayments.saveStarGift.
Received gifts may also be automatically displayed on the profile, depending on the destination user'sprivacy settings (inputPrivacyKeyStarGiftsAutoSave key).

Alternatively, the gift may be converted intoTelegram Stars usingpayments.convertStarGift; the latter operation will permanently destroy the gift, converting it intostarGift.convert_stars Telegram Stars, added to the user's balance (note thatstarGift.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 intoTelegram Stars only if it was received less thanstargifts_convert_period_max seconds ago, as specified by the client configuration ».

Both methods take auser_id and amsg_id, the first should contain the identifier of the user that sent us the gift, and the second should contain the ID of themessageService with themessageActionStarGift.

If the user decides to display the received gift on their profile, it will be fetchable by all users usingpayments.getUserStarGifts.
The same method may also be used to fetch all gifts received by the current user from any user, by passinginputUserSelf touser_id.

Note that gift support must disabled if thestargifts_blocked client configuration flag » is set to true.