GiftApi
This file is generated from spec/openapi.json (Bot API 10.3) by tools/generate.php.
Do not edit it by hand - run composer spec:build instead.
Gifts and Telegram Premium subscriptions a bot can send, upgrade, transfer, or convert back to Stars.
Mixed into Telegram through Methods. Every method is named exactly as the Bot API names it, takes exactly the fields the Bot API documents (use named arguments for the optional ones), and resolves with the hydrated result.
Tags
Table of Contents
Methods
- convertGiftToStars() : PromiseInterface<string|int, bool>
- Converts a given regular gift to Telegram Stars. Requires the can_convert_gifts_to_stars business bot right. Returns True on success.
- getAvailableGifts() : PromiseInterface<string|int, Gifts>
- Returns the list of gifts that can be sent by the bot to users and channel chats. Requires no parameters. Returns a Gifts object.
- getBusinessAccountGifts() : PromiseInterface<string|int, OwnedGifts>
- Returns the gifts received and owned by a managed business account. Requires the can_view_gifts_and_stars business bot right. Returns OwnedGifts on success.
- getChatGifts() : PromiseInterface<string|int, OwnedGifts>
- Returns the gifts owned by a chat. Returns OwnedGifts on success.
- getUserGifts() : PromiseInterface<string|int, OwnedGifts>
- Returns the gifts owned and hosted by a user. Returns OwnedGifts on success.
- giftPremiumSubscription() : PromiseInterface<string|int, bool>
- Gifts a Telegram Premium subscription to the given user. Returns True on success.
- sendGift() : PromiseInterface<string|int, bool>
- 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.
- setBusinessAccountGiftSettings() : PromiseInterface<string|int, bool>
- Changes the privacy settings pertaining to incoming gifts in a managed business account.
- transferGift() : PromiseInterface<string|int, bool>
- Transfers an owned unique gift to another user. Requires the can_transfer_and_upgrade_gifts business bot right. Requires can_transfer_stars business bot right if the transfer is paid.
- upgradeGift() : PromiseInterface<string|int, bool>
- Upgrades a given regular gift to a unique gift. Requires the can_transfer_and_upgrade_gifts business bot right. Additionally requires the can_transfer_stars business bot right if the upgrade is paid. Returns True on success.
Methods
convertGiftToStars()
Converts a given regular gift to Telegram Stars. Requires the can_convert_gifts_to_stars business bot right. Returns True on success.
public
convertGiftToStars(string $business_connection_id, string $owned_gift_id) : PromiseInterface<string|int, bool>
Parameters
- $business_connection_id : string
-
Unique identifier of the business connection
- $owned_gift_id : string
-
Unique identifier of the regular gift that should be converted to Telegram Stars
Tags
Return values
PromiseInterface<string|int, bool>getAvailableGifts()
Returns the list of gifts that can be sent by the bot to users and channel chats. Requires no parameters. Returns a Gifts object.
public
getAvailableGifts() : PromiseInterface<string|int, Gifts>
Tags
Return values
PromiseInterface<string|int, Gifts>getBusinessAccountGifts()
Returns the gifts received and owned by a managed business account. Requires the can_view_gifts_and_stars business bot right. Returns OwnedGifts on success.
public
getBusinessAccountGifts(string $business_connection_id[, bool|null $exclude_unsaved = null ][, bool|null $exclude_saved = null ][, bool|null $exclude_unlimited = null ][, bool|null $exclude_limited_upgradable = null ][, bool|null $exclude_limited_non_upgradable = null ][, bool|null $exclude_unique = null ][, bool|null $exclude_from_blockchain = null ][, bool|null $sort_by_price = null ][, string|null $offset = null ][, int|null $limit = null ]) : PromiseInterface<string|int, OwnedGifts>
Parameters
- $business_connection_id : string
-
Unique identifier of the business connection
- $exclude_unsaved : bool|null = null
-
Optional. Pass True to exclude gifts that aren't saved to the account's profile page
- $exclude_saved : bool|null = null
-
Optional. Pass True to exclude gifts that are saved to the account's profile page
- $exclude_unlimited : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased an unlimited number of times
- $exclude_limited_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can be upgraded to unique
- $exclude_limited_non_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can't be upgraded to unique
- $exclude_unique : bool|null = null
-
Optional. Pass True to exclude unique gifts
- $exclude_from_blockchain : bool|null = null
-
Optional. Pass True to exclude gifts that were assigned from the TON blockchain and can't be resold or transferred in Telegram
- $sort_by_price : bool|null = null
-
Optional. Pass True to sort results by gift price instead of send date. Sorting is applied before pagination.
- $offset : string|null = null
-
Optional. Offset of the first entry to return as received from the previous request; use empty string to get the first chunk of results
- $limit : int|null = null
-
Optional. The maximum number of gifts to be returned; 1-100. Defaults to 100.
Tags
Return values
PromiseInterface<string|int, OwnedGifts>getChatGifts()
Returns the gifts owned by a chat. Returns OwnedGifts on success.
public
getChatGifts(int|string $chat_id[, bool|null $exclude_unsaved = null ][, bool|null $exclude_saved = null ][, bool|null $exclude_unlimited = null ][, bool|null $exclude_limited_upgradable = null ][, bool|null $exclude_limited_non_upgradable = null ][, bool|null $exclude_from_blockchain = null ][, bool|null $exclude_unique = null ][, bool|null $sort_by_price = null ][, string|null $offset = null ][, int|null $limit = null ]) : PromiseInterface<string|int, OwnedGifts>
Parameters
- $chat_id : int|string
-
Unique identifier for the target chat or username of the target channel in the format @username
- $exclude_unsaved : bool|null = null
-
Optional. Pass True to exclude gifts that aren't saved to the chat's profile page. Always True, unless the bot has the can_post_messages administrator right in the channel.
- $exclude_saved : bool|null = null
-
Optional. Pass True to exclude gifts that are saved to the chat's profile page. Always False, unless the bot has the can_post_messages administrator right in the channel.
- $exclude_unlimited : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased an unlimited number of times
- $exclude_limited_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can be upgraded to unique
- $exclude_limited_non_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can't be upgraded to unique
- $exclude_from_blockchain : bool|null = null
-
Optional. Pass True to exclude gifts that were assigned from the TON blockchain and can't be resold or transferred in Telegram
- $exclude_unique : bool|null = null
-
Optional. Pass True to exclude unique gifts
- $sort_by_price : bool|null = null
-
Optional. Pass True to sort results by gift price instead of send date. Sorting is applied before pagination.
- $offset : string|null = null
-
Optional. Offset of the first entry to return as received from the previous request; use an empty string to get the first chunk of results
- $limit : int|null = null
-
Optional. The maximum number of gifts to be returned; 1-100. Defaults to 100.
Tags
Return values
PromiseInterface<string|int, OwnedGifts>getUserGifts()
Returns the gifts owned and hosted by a user. Returns OwnedGifts on success.
public
getUserGifts(int $user_id[, bool|null $exclude_unlimited = null ][, bool|null $exclude_limited_upgradable = null ][, bool|null $exclude_limited_non_upgradable = null ][, bool|null $exclude_from_blockchain = null ][, bool|null $exclude_unique = null ][, bool|null $sort_by_price = null ][, string|null $offset = null ][, int|null $limit = null ]) : PromiseInterface<string|int, OwnedGifts>
Parameters
- $user_id : int
-
Unique identifier of the user
- $exclude_unlimited : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased an unlimited number of times
- $exclude_limited_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can be upgraded to unique
- $exclude_limited_non_upgradable : bool|null = null
-
Optional. Pass True to exclude gifts that can be purchased a limited number of times and can't be upgraded to unique
- $exclude_from_blockchain : bool|null = null
-
Optional. Pass True to exclude gifts that were assigned from the TON blockchain and can't be resold or transferred in Telegram
- $exclude_unique : bool|null = null
-
Optional. Pass True to exclude unique gifts
- $sort_by_price : bool|null = null
-
Optional. Pass True to sort results by gift price instead of send date. Sorting is applied before pagination.
- $offset : string|null = null
-
Optional. Offset of the first entry to return as received from the previous request; use an empty string to get the first chunk of results
- $limit : int|null = null
-
Optional. The maximum number of gifts to be returned; 1-100. Defaults to 100.
Tags
Return values
PromiseInterface<string|int, OwnedGifts>giftPremiumSubscription()
Gifts a Telegram Premium subscription to the given user. Returns True on success.
public
giftPremiumSubscription(int $user_id, int $month_count, int $star_count[, string|null $text = null ][, string|null $text_parse_mode = null ][, array<int, MessageEntity|array<string|int, mixed>>|null $text_entities = null ]) : PromiseInterface<string|int, bool>
Parameters
- $user_id : int
-
Unique identifier of the target user who will receive a Telegram Premium subscription
- $month_count : int
-
Number of months the Telegram Premium subscription will be active for the user; must be one of 3, 6, or 12
- $star_count : int
-
Number of Telegram Stars to pay for the Telegram Premium subscription; must be 1000 for 3 months, 1500 for 6 months, and 2500 for 12 months
- $text : string|null = null
-
Optional. Text that will be shown along with the service message about the subscription; 0-128 characters
- $text_parse_mode : string|null = null
-
Optional. Mode for parsing entities in the text. See formatting options for more details. Entities other than "bold", "italic", "underline", "strikethrough", "spoiler", "custom_emoji", and "date_time" are ignored.
- $text_entities : array<int, MessageEntity|array<string|int, mixed>>|null = null
-
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", "custom_emoji", and "date_time" are ignored.
Tags
Return values
PromiseInterface<string|int, bool>sendGift()
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.
public
sendGift(string $gift_id[, int|null $user_id = null ][, int|string|null $chat_id = null ][, bool|null $pay_for_upgrade = null ][, string|null $text = null ][, string|null $text_parse_mode = null ][, array<int, MessageEntity|array<string|int, mixed>>|null $text_entities = null ]) : PromiseInterface<string|int, bool>
Parameters
- $gift_id : string
-
Identifier of the gift; limited gifts can't be sent to channel chats
- $user_id : int|null = null
-
Optional. Required if chat_id is not specified. Unique identifier of the target user who will receive the gift.
- $chat_id : int|string|null = null
-
Optional. Required if user_id is not specified. Unique identifier for the chat or username of the channel (in the format @username) that will receive the gift.
- $pay_for_upgrade : bool|null = null
-
Optional. Pass True to pay for the gift upgrade from the bot's balance, thereby making the upgrade free for the receiver
- $text : string|null = null
-
Optional. Text that will be shown along with the gift; 0-128 characters
- $text_parse_mode : string|null = null
-
Optional. Mode for parsing entities in the text. See formatting options for more details. Entities other than "bold", "italic", "underline", "strikethrough", "spoiler", "custom_emoji", and "date_time" are ignored.
- $text_entities : array<int, MessageEntity|array<string|int, mixed>>|null = null
-
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", "custom_emoji", and "date_time" are ignored.
Tags
Return values
PromiseInterface<string|int, bool>setBusinessAccountGiftSettings()
Changes the privacy settings pertaining to incoming gifts in a managed business account.
public
setBusinessAccountGiftSettings(string $business_connection_id, bool $show_gift_button, AcceptedGiftTypes|array<string|int, mixed> $accepted_gift_types) : PromiseInterface<string|int, bool>
Requires the can_change_gift_settings business bot right. Returns True on success.
Parameters
- $business_connection_id : string
-
Unique identifier of the business connection
- $show_gift_button : bool
-
Pass True if a button for sending a gift to the user or by the business account must always be shown in the input field
- $accepted_gift_types : AcceptedGiftTypes|array<string|int, mixed>
-
Types of gifts accepted by the business account
Tags
Return values
PromiseInterface<string|int, bool>transferGift()
Transfers an owned unique gift to another user. Requires the can_transfer_and_upgrade_gifts business bot right. Requires can_transfer_stars business bot right if the transfer is paid.
public
transferGift(string $business_connection_id, string $owned_gift_id, int $new_owner_chat_id[, int|null $star_count = null ]) : PromiseInterface<string|int, bool>
Returns True on success.
Parameters
- $business_connection_id : string
-
Unique identifier of the business connection
- $owned_gift_id : string
-
Unique identifier of the regular gift that should be transferred
- $new_owner_chat_id : int
-
Unique identifier of the chat which will own the gift. The chat must be active in the last 24 hours.
- $star_count : int|null = null
-
Optional. The amount of Telegram Stars that will be paid for the transfer from the business account balance. If positive, then the can_transfer_stars business bot right is required.
Tags
Return values
PromiseInterface<string|int, bool>upgradeGift()
Upgrades a given regular gift to a unique gift. Requires the can_transfer_and_upgrade_gifts business bot right. Additionally requires the can_transfer_stars business bot right if the upgrade is paid. Returns True on success.
public
upgradeGift(string $business_connection_id, string $owned_gift_id[, bool|null $keep_original_details = null ][, int|null $star_count = null ]) : PromiseInterface<string|int, bool>
Parameters
- $business_connection_id : string
-
Unique identifier of the business connection
- $owned_gift_id : string
-
Unique identifier of the regular gift that should be upgraded to a unique one
- $keep_original_details : bool|null = null
-
Optional. Pass True to keep the original gift text, sender and receiver in the upgraded gift
- $star_count : int|null = null
-
Optional. The amount of Telegram Stars that will be paid for the upgrade from the business account balance. If gift.prepaid_upgrade_star_count > 0, then pass 0, otherwise, the can_transfer_stars business bot right is required and gift.upgrade_star_count must be passed.