rustigram_types/gifts.rs
1use serde::{Deserialize, Serialize};
2
3use crate::chat::Chat;
4use crate::sticker::Sticker;
5
6// ─── Regular gift ─────────────────────────────────────────────────────────────
7
8/// Background of a regular gift.
9#[derive(Debug, Clone, Serialize, Deserialize)]
10pub struct GiftBackground {
11 /// Center color of the background in RGB format.
12 pub center_color: u32,
13 /// Edge color of the background in RGB format.
14 pub edge_color: u32,
15 /// Text color of the background in RGB format.
16 pub text_color: u32,
17}
18
19/// A Telegram gift that can be sent to users.
20///
21/// Retrieve available gifts with [`getAvailableGifts`](https://core.telegram.org/bots/api#getavailablegifts).
22#[derive(Debug, Clone, Serialize, Deserialize)]
23pub struct Gift {
24 /// Unique gift identifier.
25 pub id: String,
26 /// The sticker that represents this gift.
27 pub sticker: Sticker,
28 /// Number of Telegram Stars that must be paid to send this gift.
29 pub star_count: u32,
30 /// Number of Telegram Stars required to upgrade this gift to a unique gift.
31 #[serde(skip_serializing_if = "Option::is_none")]
32 pub upgrade_star_count: Option<u32>,
33 /// `true` if the gift can only be purchased by Telegram Premium subscribers.
34 #[serde(skip_serializing_if = "Option::is_none")]
35 pub is_premium: Option<bool>,
36 /// `true` if the gift can be used to customize a user's appearance after upgrading.
37 #[serde(skip_serializing_if = "Option::is_none")]
38 pub has_colors: Option<bool>,
39 /// Total number of gifts of this type that can be sent; absent if unlimited.
40 #[serde(skip_serializing_if = "Option::is_none")]
41 pub total_count: Option<u32>,
42 /// Number of remaining gifts of this type available to all users.
43 #[serde(skip_serializing_if = "Option::is_none")]
44 pub remaining_count: Option<u32>,
45 /// Total number of gifts of this type the bot can send; for limited gifts only.
46 #[serde(skip_serializing_if = "Option::is_none")]
47 pub personal_total_count: Option<u32>,
48 /// Number of remaining gifts of this type the bot can send; for limited gifts only.
49 #[serde(skip_serializing_if = "Option::is_none")]
50 pub personal_remaining_count: Option<u32>,
51 /// Background of the gift.
52 #[serde(skip_serializing_if = "Option::is_none")]
53 pub background: Option<GiftBackground>,
54 /// Total number of unique gift variants obtainable by upgrading this gift.
55 #[serde(skip_serializing_if = "Option::is_none")]
56 pub unique_gift_variant_count: Option<u32>,
57 /// Information about the chat that published the gift.
58 #[serde(skip_serializing_if = "Option::is_none")]
59 pub publisher_chat: Option<Chat>,
60}
61
62/// Collection of available gifts returned by `getAvailableGifts`.
63#[derive(Debug, Clone, Serialize, Deserialize)]
64pub struct Gifts {
65 /// The list of available gifts.
66 pub gifts: Vec<Gift>,
67}
68
69// ─── Unique gift ──────────────────────────────────────────────────────────────
70
71/// Model of a unique gift.
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct UniqueGiftModel {
74 /// Name of the model.
75 pub name: String,
76 /// The sticker that represents this model.
77 pub sticker: Sticker,
78 /// Number of unique gifts receiving this model per 1000 upgrades. Always `0` for crafted gifts.
79 pub rarity_per_mille: u32,
80 /// Rarity tier for crafted models: `"uncommon"`, `"rare"`, `"epic"`, or `"legendary"`.
81 #[serde(skip_serializing_if = "Option::is_none")]
82 pub rarity: Option<String>,
83}
84
85/// Symbol shown on the pattern of a unique gift.
86#[derive(Debug, Clone, Serialize, Deserialize)]
87pub struct UniqueGiftSymbol {
88 /// Name of the symbol.
89 pub name: String,
90 /// The sticker that represents this symbol.
91 pub sticker: Sticker,
92 /// Number of unique gifts receiving this symbol per 1000 upgrades.
93 pub rarity_per_mille: u32,
94}
95
96/// Colors of the backdrop of a unique gift.
97#[derive(Debug, Clone, Serialize, Deserialize)]
98pub struct UniqueGiftBackdropColors {
99 /// Center color of the backdrop in RGB format.
100 pub center_color: u32,
101 /// Edge color of the backdrop in RGB format.
102 pub edge_color: u32,
103 /// Color applied to the symbol in RGB format.
104 pub symbol_color: u32,
105 /// Text color of the backdrop in RGB format.
106 pub text_color: u32,
107}
108
109/// Backdrop of a unique gift.
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct UniqueGiftBackdrop {
112 /// Name of the backdrop.
113 pub name: String,
114 /// Colors of the backdrop.
115 pub colors: UniqueGiftBackdropColors,
116 /// Number of unique gifts receiving this backdrop per 1000 upgrades.
117 pub rarity_per_mille: u32,
118}
119
120/// Color scheme for a user's name, replies, and link previews based on a unique gift.
121#[derive(Debug, Clone, Serialize, Deserialize)]
122pub struct UniqueGiftColors {
123 /// Custom emoji identifier of the gift's model.
124 pub model_custom_emoji_id: String,
125 /// Custom emoji identifier of the gift's symbol.
126 pub symbol_custom_emoji_id: String,
127 /// Main color in light themes in RGB format.
128 pub light_theme_main_color: u32,
129 /// Up to 3 additional colors in light themes in RGB format.
130 pub light_theme_other_colors: Vec<u32>,
131 /// Main color in dark themes in RGB format.
132 pub dark_theme_main_color: u32,
133 /// Up to 3 additional colors in dark themes in RGB format.
134 pub dark_theme_other_colors: Vec<u32>,
135}
136
137/// A unique gift upgraded from a regular gift.
138#[derive(Debug, Clone, Serialize, Deserialize)]
139pub struct UniqueGift {
140 /// Identifier of the regular gift from which this was upgraded.
141 pub gift_id: String,
142 /// Human-readable name of the original regular gift.
143 pub base_name: String,
144 /// Unique name usable in `https://t.me/nft/...` links and story areas.
145 pub name: String,
146 /// Unique number among gifts upgraded from the same regular gift.
147 pub number: u32,
148 /// Model of the gift.
149 pub model: UniqueGiftModel,
150 /// Symbol of the gift.
151 pub symbol: UniqueGiftSymbol,
152 /// Backdrop of the gift.
153 pub backdrop: UniqueGiftBackdrop,
154 /// `true` if the original regular gift was exclusively purchaseable by Premium subscribers.
155 #[serde(skip_serializing_if = "Option::is_none")]
156 pub is_premium: Option<bool>,
157 /// `true` if the gift was used to craft another gift and is no longer available.
158 #[serde(skip_serializing_if = "Option::is_none")]
159 pub is_burned: Option<bool>,
160 /// `true` if the gift is from the TON blockchain and cannot be resold or transferred.
161 #[serde(skip_serializing_if = "Option::is_none")]
162 pub is_from_blockchain: Option<bool>,
163 /// Color scheme for the owner's chat name, replies, and link previews.
164 #[serde(skip_serializing_if = "Option::is_none")]
165 pub colors: Option<UniqueGiftColors>,
166 /// Information about the chat that published the gift.
167 #[serde(skip_serializing_if = "Option::is_none")]
168 pub publisher_chat: Option<Chat>,
169}
170
171// ─── Service messages ─────────────────────────────────────────────────────────
172
173/// Service message: a regular gift was sent or received.
174///
175/// Sealed but without [`Default`]: the required `gift` field is a [`Gift`],
176/// which has no meaningful default and would drag one through `Sticker` and the
177/// whole gift model hierarchy. Same reasoning as
178/// [`ExternalReplyInfo`](crate::message::ExternalReplyInfo) — this type is only
179/// received, never constructed.
180#[derive(Debug, Clone, Serialize, Deserialize)]
181#[non_exhaustive]
182pub struct GiftInfo {
183 /// Information about the gift.
184 pub gift: Gift,
185 /// Identifier of the received gift for the bot; present only if the gift
186 /// can be upgraded or converted to Telegram Stars.
187 #[serde(skip_serializing_if = "Option::is_none")]
188 pub owned_gift_id: Option<String>,
189 /// Number of Telegram Stars the gift can be converted to by the receiver.
190 #[serde(skip_serializing_if = "Option::is_none")]
191 pub convert_star_count: Option<i64>,
192 /// Number of Telegram Stars prepaid by the sender for a later upgrade.
193 #[serde(skip_serializing_if = "Option::is_none")]
194 pub prepaid_upgrade_star_count: Option<i64>,
195 /// `true` if the gift upgrade is sent as a separate service message.
196 #[serde(skip_serializing_if = "Option::is_none")]
197 pub is_upgrade_separate: Option<bool>,
198 /// `true` if the gift can be upgraded to a unique gift.
199 #[serde(skip_serializing_if = "Option::is_none")]
200 pub can_be_upgraded: Option<bool>,
201 /// Text message accompanying the gift.
202 #[serde(skip_serializing_if = "Option::is_none")]
203 pub text: Option<String>,
204 /// Special entities appearing in the accompanying text.
205 #[serde(skip_serializing_if = "Option::is_none")]
206 pub entities: Option<Vec<crate::message::MessageEntity>>,
207 /// `true` if the sender and gift text are visible only to the receiver.
208 #[serde(skip_serializing_if = "Option::is_none")]
209 pub is_private: Option<bool>,
210 /// Unique number of the upgraded gift among gifts upgraded from the same one.
211 #[serde(skip_serializing_if = "Option::is_none")]
212 pub unique_gift_number: Option<i64>,
213}
214
215/// Service message: a unique gift was sent or received.
216///
217/// Sealed without [`Default`] for the same reason as [`GiftInfo`].
218#[derive(Debug, Clone, Serialize, Deserialize)]
219#[non_exhaustive]
220pub struct UniqueGiftInfo {
221 /// Information about the gift.
222 pub gift: UniqueGift,
223 /// Origin of the gift.
224 ///
225 /// One of `"upgrade"`, `"transfer"`, or `"resale"`.
226 pub origin: String,
227 /// Currency of the last resale, if the gift was bought from another user.
228 #[serde(skip_serializing_if = "Option::is_none")]
229 pub last_resale_currency: Option<String>,
230 /// Amount paid at the last resale, in the smallest unit of the currency.
231 #[serde(skip_serializing_if = "Option::is_none")]
232 pub last_resale_amount: Option<i64>,
233 /// Identifier of the received gift for the bot.
234 #[serde(skip_serializing_if = "Option::is_none")]
235 pub owned_gift_id: Option<String>,
236 /// Number of Telegram Stars that must be paid to transfer the gift.
237 #[serde(skip_serializing_if = "Option::is_none")]
238 pub transfer_star_count: Option<i64>,
239 /// Point in time when the gift can be transferred, as a Unix timestamp.
240 #[serde(skip_serializing_if = "Option::is_none")]
241 pub next_transfer_date: Option<i64>,
242}