tgbot/types/gift/
mod.rs

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

tgbot/types/gift/
mod.rs
