sendGift

Returns: True✏️ Formattable textOfficial docs ↗

Sends a gift to the given user or channel chat. The gift can't be converted to Telegram Stars by the receiver. Returns True on success.

Parameters

user_idIntegerOptional

Required if chat\_id is not specified. Unique identifier of the target user who will receive the gift.

chat_idIntegerStringOptional

Required if user\_id is not specified. Unique identifier for the chat or username of the channel (in the format @channelusername) that will receive the gift.

gift_idStringRequired

Identifier of the gift; limited gifts can't be sent to channel chats

pay_for_upgradeBooleanOptional

Pass True to pay for the gift upgrade from the bot's balance, thereby making the upgrade free for the receiver

textStringOptional✏️ FormattableminLen 0maxLen 128

Text that will be shown along with the gift; 0-128 characters

text_parse_modeStringOptional

Mode for parsing entities in the text. See formatting options for more details. Entities other than "bold", "italic", "underline", "strikethrough", "spoiler", and "custom\_emoji" are ignored.

text_entitiesMessageEntity[]Optional

A JSON-serialized list of special entities that appear in the gift text. It can be specified instead of text\parse\mode. Entities other than "bold", "italic", "underline", "strikethrough", "spoiler", and "custom\_emoji" are ignored.

Returns

On success, True is returned.

GramIO Usage

// Send a gift to a user by user_id
// First fetch available gifts via getAvailableGifts to get a valid gift_id
await bot.api.sendGift({
    user_id: 123456789,
    gift_id: "gift_abc123",
    text: "Happy birthday! 🎉",
});

// Send a gift to a channel
await bot.api.sendGift({
    chat_id: "@mychannel",
    gift_id: "gift_abc123",
    text: "Thanks for following!",
});

// Send a gift with formatted text using text_entities
// Only bold, italic, underline, strikethrough, spoiler, custom_emoji are supported
await bot.api.sendGift({
    user_id: 123456789,
    gift_id: "gift_abc123",
    text: format`${bold("Congratulations!")} You earned this gift ${italic("for your contribution")}`,
});

// Pay for the gift upgrade from the bot's Star balance
await bot.api.sendGift({
    user_id: 123456789,
    gift_id: "gift_premium_xyz",
    pay_for_upgrade: true,
    text: "Enjoy the premium upgrade — on us!",
});

// Retrieve available gifts first, then send the cheapest one
const gifts = await bot.api.getAvailableGifts();
const gift = gifts.gifts[0];

if (gift) {
    await bot.api.sendGift({
        user_id: 123456789,
        gift_id: gift.id,
    });
}

Errors

Code	Error	Cause
400	Bad Request: user not found	user_id is invalid or the user has never started your bot
400	Bad Request: chat not found	chat_id is invalid or the bot is not a member
400	Bad Request: GIFT_INVALID	gift_id does not exist or has sold out — use getAvailableGifts to fetch current valid IDs
400	Bad Request: limited gifts can't be sent to channel chats	The gift_id is a limited-edition gift; these can only go to users, not channels
400	Bad Request: not enough stars	Bot doesn't have sufficient Telegram Stars balance to send this gift
403	Forbidden: bot was blocked by the user	User blocked the bot — catch and skip
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Always fetch fresh gift_id values via getAvailableGifts. Gift IDs are not static — limited gifts can sell out. Hardcoding an ID that has expired will cause GIFT_INVALID.
• Either user_id or chat_id is required, not both. Providing neither (or both) will result in a 400 error. user_id targets individual users; chat_id targets channels.
• Limited gifts cannot be sent to channels. Only regular (non-limited) gifts are allowed for chat_id targets.
• text supports only a subset of formatting entities. Even with format helper or text_parse_mode, only bold, italic, underline, strikethrough, spoiler, and custom_emoji are rendered. All others are silently stripped.
• pay_for_upgrade deducts Stars from the bot's balance. This makes the upgrade free for the receiver. Ensure the bot has enough Stars before setting this to true.
• Receivers cannot convert these gifts to Stars. Unlike user-sent gifts, gifts from bots cannot be converted by the recipient.

See Also

• getAvailableGifts — list all sendable gift IDs with star costs
• Gift — the Gift type object
• Gifts — the Gifts collection type
• Formatting — how to use format for text_entities
• auto-retry plugin — automatic 429 handling