Telegram gifts in the Bot API: regular vs unique, conversion to Stars, transfers and the blockchain flag

Users keep asking bots that deal in Telegram Stars what they can do with the gifts they received. The answer lives in a handful of Bot API types and methods, and several of them have limits that are easy to miss. This post collects what the Bot API and the MTProto gift docs actually say, so your bot can tell a user what is possible before they try.

Two kinds of owned gifts

getUserGifts (any user) and getBusinessAccountGifts (a business account your bot manages) return OwnedGifts, a list of two types:

OwnedGiftRegular — an ordinary gift.

• convert_star_count: "Number of Telegram Stars that can be claimed by the receiver instead of the gift; omitted if the gift cannot be converted to Telegram Stars".
• can_be_upgraded: the gift can become a unique one.
• prepaid_upgrade_star_count: the sender already paid for the upgrade.
• was_refunded: the gift "was refunded and isn't available anymore".

OwnedGiftUnique — an upgraded collectible.

• can_be_transferred and transfer_star_count: whether the gift can move to another owner and how many Stars that costs.
• next_transfer_date: "Point in time (Unix timestamp) when the gift can be transferred. If it is in the past, then the gift can be transferred now."
• gift is a UniqueGift with number, model, symbol, backdrop, is_burned (used to craft another gift) and is_from_blockchain: the gift was assigned from the blockchain and "can't be resold or transferred in Telegram".

Several fields are filled only "for gifts received on behalf of business accounts". With plain getUserGifts you see what a user owns, not everything they can do with it.

Conversion to Stars destroys the gift and pays less

From the MTProto docs on payments.convertStarGift: the operation "will permanently destroy the gift", and the Stars credited "will be less than the buying price". Two more limits:

• A gift "can be converted back into Telegram Stars only if it was received less than stargifts_convert_period_max seconds ago". The client config documents it as 604800, seven days.
• "Gifts acquired through collectible gift auctions cannot be converted back into Telegram Stars."

The Stars docs add a side effect users rarely expect: "if you refund Star purchases or convert gifts to Stars your rating will decrease."

For a business account, the Bot API method is convertGiftToStars(business_connection_id, owned_gift_id) and needs the can_convert_gifts_to_stars business bot right.

Gifts sent by a bot cannot be converted

sendGift documents it in one line: "The gift can't be converted to Telegram Stars by the receiver." If your bot rewards users with gifts, the reward cannot be turned into Stars. Say so in the UI, or send Stars-denominated value another way.

Upgrades and transfers

• upgradeGift turns a regular gift into a unique one. It needs can_transfer_and_upgrade_gifts, plus can_transfer_stars when the upgrade is paid from the business account balance. keep_original_details keeps the original text, sender and receiver.
• transferGift sends a unique gift to another chat. The receiving chat "must be active in the last 24 hours", and a positive star_count is paid from the business account balance.
• Before offering a transfer, compare next_transfer_date with the current time. A gift that was just bought or upgraded may be locked for a while.

Getting Stars out of a business account

getBusinessAccountStarBalance reads the balance (can_view_gifts_and_stars), and transferBusinessAccountStars moves 1 to 10,000 Stars to the bot's own balance (can_transfer_stars). Those Stars are then ordinary bot Stars: subject to the same up-to-21-day availability rule in the Bot Platform Developer Terms as any Stars your bot receives.

A decision tree for users

The fields above are enough to answer "what can I do with this gift?" without guessing:

1. OwnedGiftRegular with convert_star_count present: converting gives exactly that many Stars, destroys the gift and lowers the Stars rating.
2. OwnedGiftRegular without convert_star_count: the conversion window closed, the gift came from a bot, or it was won at an auction.
3. OwnedGiftUnique: sell it on Telegram's marketplace or through a buy offer; check next_transfer_date before any transfer.
4. is_from_blockchain: it lives on-chain, so it is sold there, not in Telegram.

Whatever route ends in Stars, those Stars can be paid to a bot like any other Stars.

Checklist

• [ ] read convert_star_count, never compute the conversion amount yourself
• [ ] treat a missing convert_star_count as "cannot convert", not as zero
• [ ] warn that conversion destroys the gift and lowers the Stars rating
• [ ] tell users that gifts your bot sends cannot be converted
• [ ] check next_transfer_date and can_be_transferred before a transfer
• [ ] handle is_from_blockchain and is_burned gifts as not transferable in Telegram
• [ ] request only the business bot rights you use

---

Disclosure: we build StarGate, a Telegram bot and web app that swaps Stars for GRAM, USDT, ETH and BTC. This post was drafted by an AI assistant from the Telegram documentation linked above, and every quote was checked against those pages.