Gifts

Clients can browse, send, sell, and transfer Telegram Star gifts.

Getting Available Gifts

getGifts lists the gifts available for purchase.

const gifts = await client.getGifts();

for (const gift of gifts) {
  console.log(gift.id, gift.price);
}

id is the identifier used when sending a gift.

Getting a GiftUSER-ONLY

getGift with a gift slug lets you fetch its details.

const gift = await client.getGift("delicious-bento");

Getting Claimed Gifts

getClaimedGifts lists gifts claimed by a user or channel.

const claimed = await client.getClaimedGifts(chatId);

for (const gift of claimed.gifts) {
  console.log(gift);
}

You can filter the results and use the returned offset to fetch the next page.

const claimed = await client.getClaimedGifts(chatId, {
  isUniqueExcluded: true,
  limit: 50,
  offset,
});

Sending a Gift

To purchase and send a gift, call sendGift with the recipient and the gift identifier.

await client.sendGift(userId, giftId);

Optionally, pass a message to attach text to the gift.

await client.sendGift(userId, giftId, {
  message: "Enjoy!",
});

Selling a Gift

With sellGift, you can convert a gift to Telegram Stars. Reference the gift by its chat and identifier.

await client.sellGift({ type: "chat", chatId, id });

For a gift in a private chat, use type: "user" with the messageId.

await client.sellGift({ type: "user", messageId });

Transferring a Gift

transferGift gives a saved gift to another user.

await client.transferGift(userId, { type: "chat", chatId, id });

Bot clients must pass the business connection identifier:

await client.transferGift(userId, { type: "chat", chatId, id }, {
  businessConnectionId,
});

Crafting Gifts

Combine eligible gifts with craftGifts. Pass each gift as a reference by its slug, chat and identifier, or private-chat message identifier.

await client.craftGifts([
  { type: "chat", chatId, id: firstGiftId },
  { type: "chat", chatId, id: secondGiftId },
]);

Bot clients must pass the business connection identifier:

await client.craftGifts([
  { type: "chat", chatId, id: firstGiftId },
  { type: "chat", chatId, id: secondGiftId },
], {
  businessConnectionId,
});