tgbot/types/definitions/
gift.rs

1use serde::{Deserialize, Serialize};
2
3use crate::{
4    api::{Method, Payload},
5    types::{Chat, ChatId, Integer, ParseMode, Sticker, TextEntities, TextEntity, User},
6};
7
8/// Describes the types of gifts that can be gifted to a user or a chat.
9#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, PartialOrd, Serialize)]
10pub struct AcceptedGiftTypes {
11    /// Whether limited regular gifts are accepted.
12    pub limited_gifts: bool,
13    /// Whether a Telegram Premium subscription is accepted.
14    pub premium_subscription: bool,
15    /// Whether unique gifts or gifts that can be upgraded to unique for free are accepted.
16    pub unique_gifts: bool,
17    /// Whether unlimited regular gifts are accepted.
18    pub unlimited_gifts: bool,
19}
20
21impl AcceptedGiftTypes {
22    /// Sets a new value for the `limited_gifts` flag.
23    ///
24    /// # Arguments
25    ///
26    /// * `value` - Whether limited regular gifts are accepted.
27    pub fn with_limited_gifts(mut self, value: bool) -> Self {
28        self.limited_gifts = value;
29        self
30    }
31
32    /// Sets a new value for the `premium_subscription` flag.
33    ///
34    /// # Arguments
35    ///
36    /// * `value` - Whether a Telegram Premium subscription is accepted.
37    pub fn with_premium_subscription(mut self, value: bool) -> Self {
38        self.premium_subscription = value;
39        self
40    }
41
42    /// Sets a new value for the `unique_gifts` flag.
43    ///
44    /// # Arguments
45    ///
46    /// * `value` - Whether unique gifts or gifts that can be upgraded to unique for free are accepted.
47    pub fn with_unique_gifts(mut self, value: bool) -> Self {
48        self.unique_gifts = value;
49        self
50    }
51
52    /// Sets a new value for the `unlimited_gifts` flag.
53    ///
54    /// # Arguments
55    ///
56    /// * `value` - Whether unlimited regular gifts are accepted.
57    pub fn with_unlimited_gifts(mut self, value: bool) -> Self {
58        self.unlimited_gifts = value;
59        self
60    }
61}
62
63/// Represents a gift that can be sent by the bot.
64#[serde_with::skip_serializing_none]
65#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
66pub struct Gift {
67    /// Unique identifier of the gift.
68    pub id: String,
69    /// The number of Telegram Stars that must be paid to send the sticker.
70    pub star_count: Integer,
71    /// The sticker that represents the gift.
72    pub sticker: Sticker,
73    /// Information about the chat that published the gift.
74    pub publisher_chat: Option<Chat>,
75    /// The number of remaining gifts of this type that can be sent;
76    /// for limited gifts only.
77    pub remaining_count: Option<Integer>,
78    /// The total number of the gifts of this type that can be sent;
79    /// for limited gifts only.
80    pub total_count: Option<Integer>,
81    /// The number of Telegram Stars that must be paid to upgrade the gift to a unique one.
82    pub upgrade_star_count: Option<Integer>,
83}
84
85impl Gift {
86    /// Creates a new `Gift`.
87    ///
88    /// # Arguments
89    ///
90    /// * `id` - Unique identifier of the gift.
91    /// * `sticker` - The sticker that represents the gift.
92    /// * `star_count` - The number of Telegram Stars that must be paid to send the sticker.
93    pub fn new<T>(id: T, sticker: Sticker, star_count: Integer) -> Self
94    where
95        T: Into<String>,
96    {
97        Self {
98            id: id.into(),
99            star_count,
100            sticker,
101            publisher_chat: None,
102            remaining_count: None,
103            total_count: None,
104            upgrade_star_count: None,
105        }
106    }
107
108    /// Sets a new publisher chat.
109    ///
110    /// # Arguments
111    ///
112    /// * `value` - Information about the chat that published the gift.
113    pub fn with_publisher_chat<T>(mut self, value: T) -> Self
114    where
115        T: Into<Chat>,
116    {
117        self.publisher_chat = Some(value.into());
118        self
119    }
120
121    /// Sets a new remaining count.
122    ///
123    /// # Arguments
124    ///
125    /// * `value` - The number of remaining gifts of this type that can be sent.
126    pub fn with_remaining_count(mut self, value: Integer) -> Self {
127        self.remaining_count = Some(value);
128        self
129    }
130
131    /// Sets a new total count.
132    ///
133    /// # Arguments
134    ///
135    /// * `value` - The total number of the gifts of this type that can be sent.
136    pub fn with_total_count(mut self, value: Integer) -> Self {
137        self.total_count = Some(value);
138        self
139    }
140
141    /// Sets a new upgrade star count.
142    ///
143    /// # Arguments
144    ///
145    /// * `value` - The number of Telegram Stars that must be paid to upgrade the gift to a unique one.
146    pub fn with_upgrade_star_count(mut self, value: Integer) -> Self {
147        self.upgrade_star_count = Some(value);
148        self
149    }
150}
151
152/// Describes a service message about a regular gift that was sent or received.
153#[serde_with::skip_serializing_none]
154#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
155pub struct GiftInfo {
156    /// Information about the gift.
157    pub gift: Gift,
158    /// Whether the gift can be upgraded to a unique gift.
159    pub can_be_upgraded: Option<bool>,
160    /// Number of Telegram Stars that can be claimed by the receiver by converting the gift;
161    /// omitted if conversion to Telegram Stars is impossible.
162    pub convert_star_count: Option<Integer>,
163    /// Special entities that appear in the text.
164    pub entities: Option<TextEntities>,
165    /// Whether the sender and gift text are shown only to the gift receiver;
166    /// otherwise, everyone will be able to see them.
167    pub is_private: Option<bool>,
168    /// Unique identifier of the received gift for the bot;
169    /// only present for gifts received on behalf of business accounts.
170    pub owned_gift_id: Option<String>,
171    /// Number of Telegram Stars that were prepaid by the sender for the ability to upgrade the gift.
172    pub prepaid_upgrade_star_count: Option<Integer>,
173    /// Text of the message that was added to the gift.
174    pub text: Option<String>,
175}
176
177impl GiftInfo {
178    /// Creates a new `GiftInfo`.
179    ///
180    /// # Arguments
181    ///
182    /// * `gift` - Information about the gift.
183    pub fn new(gift: Gift) -> Self {
184        Self {
185            gift,
186            can_be_upgraded: None,
187            convert_star_count: None,
188            entities: None,
189            is_private: None,
190            owned_gift_id: None,
191            prepaid_upgrade_star_count: None,
192            text: None,
193        }
194    }
195
196    /// Sets a new value for the `can_be_upgraded` flag.
197    ///
198    /// # Arguments
199    ///
200    /// * `value` - Whether the gift can be upgraded to a unique gift.
201    pub fn with_can_be_upgraded(mut self, value: bool) -> Self {
202        self.can_be_upgraded = Some(value);
203        self
204    }
205
206    /// Sets a new convert star count.
207    ///
208    /// # Arguments
209    ///
210    /// * `value` - Number of Telegram Stars that can be claimed by the receiver by converting the gift;
211    ///   omitted if conversion to Telegram Stars is impossible.
212    pub fn with_convert_star_count(mut self, value: Integer) -> Self {
213        self.convert_star_count = Some(value);
214        self
215    }
216
217    /// Sets a new list of entities.
218    ///
219    /// # Arguments
220    ///
221    /// * `value` - Special entities that appear in the text.
222    pub fn with_entities<T>(mut self, value: T) -> Self
223    where
224        T: IntoIterator<Item = TextEntity>,
225    {
226        self.entities = Some(TextEntities::from_iter(value));
227        self
228    }
229
230    /// Sets a new value for the `is_private` flag.
231    ///
232    /// # Arguments
233    ///
234    /// * `value` - Whether the sender and gift text are shown only to the gift receiver;
235    ///   otherwise, everyone will be able to see them.
236    pub fn with_is_private(mut self, value: bool) -> Self {
237        self.is_private = Some(value);
238        self
239    }
240
241    /// Sets a new owned gift ID.
242    ///
243    /// # Arguments
244    ///
245    /// * `value` - Unique identifier of the received gift for the bot;
246    ///   only present for gifts received on behalf of business accounts.
247    pub fn with_owned_gift_id<T>(mut self, value: T) -> Self
248    where
249        T: Into<String>,
250    {
251        self.owned_gift_id = Some(value.into());
252        self
253    }
254
255    /// Sets a new prepaid upgrade star count.
256    ///
257    /// # Arguments
258    ///
259    /// * `value` - Number of Telegram Stars that were prepaid by the sender for the ability to upgrade the gift.
260    pub fn with_prepaid_upgrade_star_count(mut self, value: Integer) -> Self {
261        self.prepaid_upgrade_star_count = Some(value);
262        self
263    }
264
265    /// Sets a new text.
266    ///
267    /// # Arguments
268    ///
269    /// * `value` - Text of the message that was added to the gift.
270    pub fn with_text<T>(mut self, value: T) -> Self
271    where
272        T: Into<String>,
273    {
274        self.text = Some(value.into());
275        self
276    }
277}
278
279/// Represent a list of gifts.
280#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
281pub struct Gifts {
282    gifts: Vec<Gift>,
283}
284
285impl<T> From<T> for Gifts
286where
287    T: IntoIterator<Item = Gift>,
288{
289    fn from(value: T) -> Self {
290        Self {
291            gifts: value.into_iter().collect(),
292        }
293    }
294}
295
296/// Returns the list of gifts that can be sent by the bot to users.
297#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
298pub struct GetAvailableGifts;
299
300impl Method for GetAvailableGifts {
301    type Response = Gifts;
302
303    fn into_payload(self) -> Payload {
304        Payload::empty("getAvailableGifts")
305    }
306}
307
308/// Describes a gift received and owned by a user or a chat.
309#[derive(Clone, Debug, derive_more::From, Deserialize, PartialEq, Serialize)]
310#[serde(tag = "type", rename_all = "snake_case")]
311#[allow(clippy::large_enum_variant)]
312pub enum OwnedGift {
313    /// A regular gift owned by a user or a chat.
314    Regular(OwnedGiftRegular),
315    /// A unique gift received and owned by a user or a chat.
316    Unique(OwnedGiftUnique),
317}
318
319/// Describes a regular gift owned by a user or a chat.
320#[serde_with::skip_serializing_none]
321#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
322pub struct OwnedGiftRegular {
323    /// Information about the regular gift.
324    pub gift: Gift,
325    /// Date the gift was sent in Unix time.
326    pub send_date: Integer,
327    /// Whether the gift can be upgraded to a unique gift;
328    /// for gifts received on behalf of business accounts only.
329    pub can_be_upgraded: Option<bool>,
330    /// Number of Telegram Stars that can be claimed by the receiver instead of the gift;
331    /// omitted if the gift cannot be converted to Telegram Stars.
332    pub convert_star_count: Option<Integer>,
333    /// Special entities that appear in the text.
334    pub entities: Option<TextEntities>,
335    /// Whether the sender and gift text are shown only to the gift receiver;
336    /// otherwise, everyone will be able to see them.
337    pub is_private: Option<bool>,
338    /// Whether the gift is displayed on the account's profile page;
339    /// for gifts received on behalf of business accounts only.
340    pub is_saved: Option<bool>,
341    /// Unique identifier of the gift for the bot; for gifts received on behalf of business accounts only.
342    pub owned_gift_id: Option<String>,
343    /// Number of Telegram Stars that were paid by the sender for the ability to upgrade the gift.
344    pub prepaid_upgrade_star_count: Option<Integer>,
345    /// Sender of the gift if it is a known user.
346    pub sender_user: Option<User>,
347    /// Text of the message that was added to the gift.
348    pub text: Option<String>,
349    /// Whether the gift was refunded and isn't available anymore.
350    pub was_refunded: Option<bool>,
351}
352
353impl OwnedGiftRegular {
354    /// Creates a new `OwnedGiftRegular`.
355    ///
356    /// # Arguments
357    ///
358    /// * `gift` - Information about the regular gift.
359    /// * `send_date` - Date the gift was sent in Unix time.
360    pub fn new(gift: Gift, send_date: Integer) -> Self {
361        Self {
362            gift,
363            send_date,
364            can_be_upgraded: None,
365            convert_star_count: None,
366            entities: None,
367            is_private: None,
368            is_saved: None,
369            owned_gift_id: None,
370            prepaid_upgrade_star_count: None,
371            sender_user: None,
372            text: None,
373            was_refunded: None,
374        }
375    }
376
377    /// Sets a new value for the `can_be_upgraded` flag.
378    ///
379    /// # Arguments
380    ///
381    /// * `value` - Whether the gift can be upgraded to a unique gift;
382    ///   for gifts received on behalf of business accounts only.
383    pub fn with_can_be_upgraded(mut self, value: bool) -> Self {
384        self.can_be_upgraded = Some(value);
385        self
386    }
387
388    /// Sets a new convert star count.
389    ///
390    /// # Arguments
391    ///
392    /// * `value` - Number of Telegram Stars that can be claimed by the receiver instead of the gift;
393    ///   omitted if the gift cannot be converted to Telegram Stars.
394    pub fn with_convert_star_count(mut self, value: Integer) -> Self {
395        self.convert_star_count = Some(value);
396        self
397    }
398
399    /// Sets a new list of text entities.
400    ///
401    /// # Arguments
402    ///
403    /// * `value` - Special entities that appear in the text.
404    pub fn with_entities<T>(mut self, value: T) -> Self
405    where
406        T: IntoIterator<Item = TextEntity>,
407    {
408        self.entities = Some(value.into_iter().collect());
409        self
410    }
411
412    /// Sets a new value for the `is_private` flag.
413    ///
414    /// # Arguments
415    ///
416    /// * `value` - Whether the sender and gift text are shown only to the gift receiver;
417    ///   otherwise, everyone will be able to see them.
418    pub fn with_is_private(mut self, value: bool) -> Self {
419        self.is_private = Some(value);
420        self
421    }
422
423    /// Sets a new value for the `is_saved` flag.
424    ///
425    /// # Arguments
426    ///
427    /// * `value` - Whether the gift is displayed on the account's profile page;
428    ///   for gifts received on behalf of business accounts only.
429    pub fn with_is_saved(mut self, value: bool) -> Self {
430        self.is_saved = Some(value);
431        self
432    }
433
434    /// Sets a new owned gift ID.
435    ///
436    /// # Arguments
437    ///
438    /// * `value` - Unique identifier of the gift for the bot;
439    ///   for gifts received on behalf of business accounts only.
440    pub fn with_owned_gift_id<T>(mut self, value: T) -> Self
441    where
442        T: Into<String>,
443    {
444        self.owned_gift_id = Some(value.into());
445        self
446    }
447
448    /// Sets a new prepaid upgrade star count.
449    ///
450    /// # Arguments
451    ///
452    /// * `value` - Number of Telegram Stars that were paid by the sender for the ability to upgrade the gift.
453    pub fn with_prepaid_upgrade_star_count(mut self, value: Integer) -> Self {
454        self.prepaid_upgrade_star_count = Some(value);
455        self
456    }
457
458    /// Sets a new sender user.
459    ///
460    /// # Arguments
461    ///
462    /// * `value` - Sender of the gift if it is a known user.
463    pub fn with_sender_user(mut self, value: User) -> Self {
464        self.sender_user = Some(value);
465        self
466    }
467
468    /// Sets a new text.
469    ///
470    /// # Arguments
471    ///
472    /// * `value` - Text of the message that was added to the gift.
473    pub fn with_text<T>(mut self, value: T) -> Self
474    where
475        T: Into<String>,
476    {
477        self.text = Some(value.into());
478        self
479    }
480
481    /// Sets a new value for the `was_refunded` flag.
482    ///
483    /// # Arguments
484    ///
485    /// * `value` - Whether the gift was refunded and isn't available anymore.
486    pub fn with_was_refunded(mut self, value: bool) -> Self {
487        self.was_refunded = Some(value);
488        self
489    }
490}
491
492/// Describes a unique gift received and owned by a user or a chat.
493#[serde_with::skip_serializing_none]
494#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
495pub struct OwnedGiftUnique {
496    /// Information about the unique gift.
497    pub gift: UniqueGift,
498    /// Date the gift was sent in Unix time.
499    pub send_date: Integer,
500    /// Number of Telegram Stars that must be paid to transfer the gift;
501    /// omitted if the bot cannot transfer the gift.
502    pub transfer_star_count: Option<Integer>,
503    /// Whether the gift can be transferred to another owner;
504    /// for gifts received on behalf of business accounts only.
505    pub can_be_transferred: Option<bool>,
506    /// Whether the gift is displayed on the account's profile page;
507    /// for gifts received on behalf of business accounts only.
508    pub is_saved: Option<bool>,
509    /// Point in time (Unix timestamp) when the gift can be transferred.
510    ///
511    /// If it is in the past, then the gift can be transferred now.
512    pub next_transfer_date: Option<Integer>,
513    /// Unique identifier of the received gift for the bot;
514    /// for gifts received on behalf of business accounts only.
515    pub owned_gift_id: Option<String>,
516    /// Sender of the gift if it is a known user.
517    pub sender_user: Option<User>,
518}
519
520impl OwnedGiftUnique {
521    /// Creates a new `OwnedGiftUnique`.
522    ///
523    /// # Arguments
524    ///
525    /// * `gift` - Information about the unique gift.
526    /// * `send_date` - Date the gift was sent in Unix time.
527    pub fn new(gift: UniqueGift, send_date: Integer) -> Self {
528        Self {
529            gift,
530            send_date,
531            transfer_star_count: None,
532            can_be_transferred: None,
533            is_saved: None,
534            next_transfer_date: None,
535            owned_gift_id: None,
536            sender_user: None,
537        }
538    }
539
540    /// Sets a new transfer star count.
541    ///
542    /// # Arguments
543    ///
544    /// * `value` Number of Telegram Stars that must be paid to transfer the gift;
545    ///   omitted if the bot cannot transfer the gift.
546    pub fn with_transfer_star_count(mut self, value: Integer) -> Self {
547        self.transfer_star_count = Some(value);
548        self
549    }
550
551    /// Sets a new value for the `can_be_transferred` flag.
552    ///
553    /// # Arguments
554    ///
555    /// * `value` - Whether the gift can be transferred to another owner;
556    ///   for gifts received on behalf of business accounts only.
557    pub fn with_can_be_transferred(mut self, value: bool) -> Self {
558        self.can_be_transferred = Some(value);
559        self
560    }
561
562    /// Sets a new value for the `is_saved` flag.
563    ///
564    /// # Arguments
565    ///
566    /// * `value` - Whether the gift is displayed on the account's profile page;
567    ///   for gifts received on behalf of business accounts only.
568    pub fn with_is_saved(mut self, value: bool) -> Self {
569        self.is_saved = Some(value);
570        self
571    }
572
573    /// Sets a new next transfer date.
574    ///
575    /// # Arguments
576    ///
577    /// * `value` - Point in time (Unix timestamp) when the gift can be transferred.
578    pub fn with_next_transfer_date(mut self, value: Integer) -> Self {
579        self.next_transfer_date = Some(value);
580        self
581    }
582
583    /// Sets a new owned gift ID.
584    ///
585    /// # Arguments
586    ///
587    /// * `value` - Unique identifier of the received gift for the bot;
588    ///   for gifts received on behalf of business accounts only.
589    pub fn with_owned_gift_id<T>(mut self, value: T) -> Self
590    where
591        T: Into<String>,
592    {
593        self.owned_gift_id = Some(value.into());
594        self
595    }
596
597    /// Sets a new sender user.
598    ///
599    /// # Arguments
600    ///
601    /// * `value` - Sender of the gift if it is a known user.
602    pub fn with_sender_user(mut self, value: User) -> Self {
603        self.sender_user = Some(value);
604        self
605    }
606}
607
608/// Contains the list of gifts received and owned by a user or a chat.
609#[serde_with::skip_serializing_none]
610#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
611pub struct OwnedGifts {
612    /// The list of gifts.
613    pub gifts: Vec<OwnedGift>,
614    /// The total number of gifts owned by the user or the chat.
615    pub total_count: Integer,
616    /// Offset for the next request.
617    ///
618    /// If empty, then there are no more results.
619    pub next_offset: Option<String>,
620}
621
622impl OwnedGifts {
623    /// Creates a new `OwnedGifts`.
624    ///
625    /// # Arguments
626    ///
627    /// * `gifts` - The list of gifts.
628    /// * `total_count` - The total number of gifts owned by the user or the chat.
629    pub fn new<T>(gifts: T, total_count: Integer) -> Self
630    where
631        T: IntoIterator<Item = OwnedGift>,
632    {
633        Self {
634            gifts: gifts.into_iter().collect(),
635            total_count,
636            next_offset: None,
637        }
638    }
639
640    /// Sets a new next offset.
641    ///
642    /// # Arguments
643    ///
644    /// * `value` - Offset for the next request.
645    pub fn with_next_offset<T>(mut self, value: T) -> Self
646    where
647        T: Into<String>,
648    {
649        self.next_offset = Some(value.into());
650        self
651    }
652}
653
654/// Describes a unique gift that was upgraded from a regular gift.
655#[serde_with::skip_serializing_none]
656#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
657pub struct UniqueGift {
658    /// Backdrop of the gift.
659    pub backdrop: UniqueGiftBackdrop,
660    /// Human-readable name of the regular gift from which this unique gift was upgraded.
661    pub base_name: String,
662    /// Model of the gift.
663    pub model: UniqueGiftModel,
664    /// Unique name of the gift. This name can be used in https://t.me/nft/... links and story areas.
665    pub name: String,
666    /// Unique number of the upgraded gift among gifts upgraded from the same regular gift.
667    pub number: Integer,
668    /// Symbol of the gift.
669    pub symbol: UniqueGiftSymbol,
670    /// Information about the chat that published the gift.
671    pub publisher_chat: Option<Chat>,
672}
673
674impl UniqueGift {
675    /// Creates a new `UniqueGift`.
676    ///
677    /// # Arguments
678    ///
679    /// * `backdrop` - Backdrop of the gift.
680    /// * `base_name` - Human-readable name of the regular gift from which this unique gift was upgraded.
681    /// * `model` - Model of the gift.
682    /// * `name` - Unique name of the gift. This name can be used in https://t.me/nft/... links and story areas.
683    /// * `number` - Unique number of the upgraded gift among gifts upgraded from the same regular gift.
684    /// * `symbol` - Symbol of the gift.
685    pub fn new<A, B>(
686        backdrop: UniqueGiftBackdrop,
687        base_name: A,
688        model: UniqueGiftModel,
689        name: B,
690        number: Integer,
691        symbol: UniqueGiftSymbol,
692    ) -> Self
693    where
694        A: Into<String>,
695        B: Into<String>,
696    {
697        Self {
698            backdrop,
699            base_name: base_name.into(),
700            model,
701            name: name.into(),
702            number,
703            symbol,
704            publisher_chat: None,
705        }
706    }
707
708    /// Sets a new publisher chat.
709    ///
710    /// # Arguments
711    ///
712    /// * `value` - Information about the chat that published the gift.
713    pub fn with_publisher_chat<T>(mut self, value: T) -> Self
714    where
715        T: Into<Chat>,
716    {
717        self.publisher_chat = Some(value.into());
718        self
719    }
720}
721
722/// Describes the backdrop of a unique gift.
723#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
724pub struct UniqueGiftBackdrop {
725    /// Colors of the backdrop.
726    pub colors: UniqueGiftBackdropColors,
727    /// Name of the backdrop.
728    pub name: String,
729    /// The number of unique gifts that receive this backdrop for every 1000 gifts upgraded.
730    pub rarity_per_mille: Integer,
731}
732
733/// Describes the colors of the backdrop of a unique gift.
734#[derive(Clone, Copy, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
735pub struct UniqueGiftBackdropColors {
736    /// The color in the center of the backdrop in RGB format
737    pub center_color: Integer,
738    /// The color on the edges of the backdrop in RGB format
739    pub edge_color: Integer,
740    /// The color to be applied to the symbol in RGB format
741    pub symbol_color: Integer,
742    /// The color for the text on the backdrop in RGB format
743    pub text_color: Integer,
744}
745
746/// Describes the model of a unique gift.
747#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
748pub struct UniqueGiftModel {
749    /// Name of the model.
750    pub name: String,
751    /// The number of unique gifts that receive this model for every 1000 gifts upgraded.
752    pub rarity_per_mille: Integer,
753    /// The sticker that represents the unique gift
754    pub sticker: Sticker,
755}
756
757/// Describes the symbol shown on the pattern of a unique gift.
758#[derive(Clone, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
759pub struct UniqueGiftSymbol {
760    /// Name of the symbol.
761    pub name: String,
762    /// The number of unique gifts that receive this model for every 1000 gifts upgraded.
763    pub rarity_per_mille: Integer,
764    /// The sticker that represents the unique gift.
765    pub sticker: Sticker,
766}
767
768/// Origin of the unique gift.
769#[derive(Clone, Copy, Debug, Deserialize, PartialEq, PartialOrd, Serialize)]
770#[serde(rename_all = "snake_case")]
771pub enum UniqueGiftOrigin {
772    /// Resale for gifts bought from other users.
773    Resale,
774    /// Transfer for gifts transferred from other users or channels.
775    Transfer,
776    /// Upgrade for gifts upgraded from regular gifts.
777    Upgrade,
778}
779
780/// Describes a service message about a unique gift that was sent or received.
781#[serde_with::skip_serializing_none]
782#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
783pub struct UniqueGiftInfo {
784    /// Information about the gift.
785    pub gift: UniqueGift,
786    /// Origin of the gift.
787    pub origin: UniqueGiftOrigin,
788    /// For gifts bought from other users, the price paid for the gift.
789    pub last_resale_star_count: Option<Integer>,
790    /// Point in time (Unix timestamp) when the gift can be transferred.
791    ///
792    /// If it is in the past, then the gift can be transferred now.
793    pub next_transfer_date: Option<Integer>,
794    /// Unique identifier of the received gift for the bot;
795    /// only present for gifts received on behalf of business accounts.
796    pub owned_gift_id: Option<String>,
797    /// Number of Telegram Stars that must be paid to transfer the gift;
798    /// omitted if the bot cannot transfer the gift.
799    pub transfer_star_count: Option<Integer>,
800}
801
802impl UniqueGiftInfo {
803    /// Creates a new `UniqueGiftInfo`.
804    ///
805    /// # Arguments
806    ///
807    /// * `gift` - Information about the gift.
808    /// * `origin` - Origin of the gift.
809    pub fn new(gift: UniqueGift, origin: UniqueGiftOrigin) -> Self {
810        Self {
811            gift,
812            origin,
813            last_resale_star_count: None,
814            next_transfer_date: None,
815            owned_gift_id: None,
816            transfer_star_count: None,
817        }
818    }
819
820    /// Sets a new last resale star count.
821    ///
822    /// # Arguments
823    ///
824    /// * `value` - The price paid for the gift.
825    pub fn with_last_resale_star_count(mut self, value: Integer) -> Self {
826        self.last_resale_star_count = Some(value);
827        self
828    }
829
830    /// Sets a new next transfer date.
831    ///
832    /// # Arguments
833    ///
834    /// * `value` - Point in time (Unix timestamp) when the gift can be transferred.
835    pub fn with_next_transfer_date(mut self, value: Integer) -> Self {
836        self.next_transfer_date = Some(value);
837        self
838    }
839
840    /// Sets a new owned gift ID.
841    ///
842    /// # Arguments
843    ///
844    /// * `value` - Unique identifier of the received gift for the bot;
845    ///   only present for gifts received on behalf of business accounts.
846    pub fn with_owned_gift_id<T>(mut self, value: T) -> Self
847    where
848        T: Into<String>,
849    {
850        self.owned_gift_id = Some(value.into());
851        self
852    }
853
854    /// Sets a new transfer star count.
855    ///
856    /// # Arguments
857    ///
858    /// * `value` - Number of Telegram Stars that must be paid to transfer the gift;
859    ///   omitted if the bot cannot transfer the gift.
860    pub fn with_transfer_star_count(mut self, value: Integer) -> Self {
861        self.transfer_star_count = Some(value);
862        self
863    }
864}
865
866/// Gifts a Telegram Premium subscription to the given user.
867#[serde_with::skip_serializing_none]
868#[derive(Clone, Debug, Serialize)]
869pub struct GiftPremiumSubscription {
870    month_count: Integer,
871    star_count: Integer,
872    user_id: Integer,
873    text: Option<String>,
874    text_entities: Option<TextEntities>,
875    text_parse_mode: Option<ParseMode>,
876}
877
878impl GiftPremiumSubscription {
879    /// Creates a new `GiftPremiumSubscription`.
880    ///
881    /// # Arguments
882    ///
883    /// * `month_count` - Number of months the Telegram Premium subscription will be active for the user;
884    ///   must be one of 3, 6, or 12.
885    /// * `star_count` - Number of Telegram Stars to pay for the Telegram Premium subscription;
886    ///   must be 1000 for 3 months, 1500 for 6 months, and 2500 for 12 months.
887    /// * `user_id` - Unique identifier of the target user who will receive a Telegram Premium subscription.
888    pub fn new(month_count: Integer, star_count: Integer, user_id: Integer) -> Self {
889        Self {
890            month_count,
891            star_count,
892            user_id,
893            text: None,
894            text_entities: None,
895            text_parse_mode: None,
896        }
897    }
898
899    /// Sets a new text.
900    ///
901    /// # Arguments
902    ///
903    /// * `value` - Text that will be shown along with the service message about the subscription; 0-128 characters
904    pub fn with_text<T>(mut self, value: T) -> Self
905    where
906        T: Into<String>,
907    {
908        self.text = Some(value.into());
909        self
910    }
911
912    /// Sets a new list of text entities.
913    ///
914    /// # Arguments
915    ///
916    /// * `value` - A list of special entities that appear in the gift text.
917    ///   Entities other than “bold”, “italic”, “underline”,
918    ///   “strikethrough”, “spoiler”, and “custom_emoji” are ignored.
919    pub fn with_text_entities<T>(mut self, value: T) -> Self
920    where
921        T: IntoIterator<Item = TextEntity>,
922    {
923        self.text_parse_mode = None;
924        self.text_entities = Some(TextEntities::from_iter(value));
925        self
926    }
927
928    /// Sets a new text parse mode.
929    ///
930    /// # Arguments
931    ///
932    /// * `value` - Mode for parsing entities in the text.
933    ///   Entities other than “bold”, “italic”, “underline”,
934    ///   “strikethrough”, “spoiler”, and “custom_emoji” are ignored.
935    pub fn with_text_parse_mode(mut self, value: ParseMode) -> Self {
936        self.text_entities = None;
937        self.text_parse_mode = Some(value);
938        self
939    }
940}
941
942impl Method for GiftPremiumSubscription {
943    type Response = bool;
944
945    fn into_payload(self) -> Payload {
946        Payload::json("giftPremiumSubscription", self)
947    }
948}
949
950/// Sends a gift to the given user.
951///
952/// The gift can't be converted to Telegram Stars by the user.
953#[serde_with::skip_serializing_none]
954#[derive(Clone, Debug, Serialize)]
955pub struct SendGift {
956    gift_id: String,
957    chat_id: Option<ChatId>,
958    pay_for_upgrade: Option<bool>,
959    text: Option<String>,
960    text_parse_mode: Option<ParseMode>,
961    text_entities: Option<TextEntities>,
962    user_id: Option<Integer>,
963}
964
965impl SendGift {
966    /// Creates a new `SendGift` with a `user_id`.
967    ///
968    /// # Arguments
969    ///
970    /// * `chat_id` - Unique identifier of the target chat that will receive the gift.
971    /// * `gift_id` - Identifier of the gift
972    pub fn for_chat_id<A, B>(chat_id: A, gift_id: B) -> Self
973    where
974        A: Into<ChatId>,
975        B: Into<String>,
976    {
977        Self {
978            gift_id: gift_id.into(),
979            chat_id: Some(chat_id.into()),
980            pay_for_upgrade: None,
981            text: None,
982            text_parse_mode: None,
983            text_entities: None,
984            user_id: None,
985        }
986    }
987
988    /// Creates a new `SendGift` with a `user_id`.
989    ///
990    /// # Arguments
991    ///
992    /// * `user_id` - Unique identifier of the target user that will receive the gift.
993    /// * `gift_id` - Identifier of the gift
994    pub fn for_user_id<T>(user_id: Integer, gift_id: T) -> Self
995    where
996        T: Into<String>,
997    {
998        Self {
999            gift_id: gift_id.into(),
1000            chat_id: None,
1001            pay_for_upgrade: None,
1002            text: None,
1003            text_parse_mode: None,
1004            text_entities: None,
1005            user_id: Some(user_id),
1006        }
1007    }
1008
1009    /// Sets a new value for the `pay_for_upgrade` flag.
1010    ///
1011    /// # Arguments
1012    ///
1013    /// * `value` - Whether to pay for the gift upgrade from the bot's balance,
1014    ///   thereby making the upgrade free for the receiver.
1015    pub fn with_pay_for_upgrade(mut self, value: bool) -> Self {
1016        self.pay_for_upgrade = Some(value);
1017        self
1018    }
1019
1020    /// Sets a new text.
1021    ///
1022    /// # Arguments
1023    ///
1024    /// * `value` - Text that will be shown along with the gift; 0-255 characters.
1025    pub fn with_text<T>(mut self, value: T) -> Self
1026    where
1027        T: Into<String>,
1028    {
1029        self.text = Some(value.into());
1030        self
1031    }
1032
1033    /// Sets a new text parse mode.
1034    ///
1035    /// # Arguments
1036    ///
1037    /// * `value` - Mode for parsing entities in the text.
1038    ///
1039    /// Entities other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”, and “custom_emoji” are ignored.
1040    /// Text entities will be set to [`None`] when this method is called.
1041    pub fn with_text_parse_mode(mut self, value: ParseMode) -> Self {
1042        self.text_parse_mode = Some(value);
1043        self.text_entities = None;
1044        self
1045    }
1046
1047    /// Sets a new text entities.
1048    ///
1049    /// # Arguments
1050    ///
1051    /// * `value` - A list of special entities that appear in the gift text.
1052    ///
1053    /// Entities other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”, and “custom_emoji” are ignored.
1054    /// Text parse mode will be set to [`None`] when this method is called.
1055    pub fn with_text_entities<T>(mut self, value: T) -> Self
1056    where
1057        T: IntoIterator<Item = TextEntity>,
1058    {
1059        self.text_entities = Some(value.into_iter().collect());
1060        self.text_parse_mode = None;
1061        self
1062    }
1063}
1064
1065impl Method for SendGift {
1066    type Response = bool;
1067
1068    fn into_payload(self) -> Payload {
1069        Payload::json("sendGift", self)
1070    }
1071}
tgbot/types/definitions/gift.rs

tgbot/types/definitions/
gift.rs
