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.

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 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#9bb3ef44 flags:# name_hidden:flags.0?true saved:flags.2?true converted:flags.3?true gift:StarGift message:flags.1?TextWithEntities convert_stars:long = MessageAction;

payments.userStarGifts#6b65b517 flags:# count:int gifts:Vector<UserStarGift> next_offset:flags.0?string users:Vector<User> = payments.UserStarGifts;

---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;

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:

• user_id: Identifier of the user that will receive the gift
• gift_id: Identifier of the gift, from starGift.id
• message: Optional message, attached with the gift
• 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 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, or convert it 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).

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.