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

---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: 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)

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).
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.