Skip to content
Back to top
View this page

# OwnedGiftRegular

class telegram.OwnedGiftRegular(gift, send_date, owned_gift_id=None, sender_user=None, text=None, entities=None, is_private=None, is_saved=None, can_be_upgraded=None, was_refunded=None, convert_star_count=None, prepaid_upgrade_star_count=None, *, api_kwargs=None)

  Bases: `telegram.OwnedGift`

  Describes a regular gift owned by a user or a chat.

  Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their `gift` and `send_date` are equal.

  Available In

  `telegram.OwnedGifts.gifts`

  Added in version 22.1.

  Parameters:

    - gift (`telegram.Gift`) – Information about the regular gift.

    - owned_gift_id (`str`, optional) – Unique identifier of the gift for the bot; for gifts received on behalf of business accounts only.

    - sender_user (`telegram.User`, optional) – Sender of the gift if it is a known user.

    - send_date (`datetime.datetime`) – Date the gift was sent as `datetime.datetime`. The default timezone of the bot is used for localization, which is UTC unless `telegram.ext.Defaults.tzinfo` is used..

    - text (`str`, optional) – Text of the message that was added to the gift.

    - entities (Sequence[`telegram.MessageEntity`], optional) – Special entities that appear in the text.

    - is_private (`bool`, optional) – `True`, if the sender and gift text are shown only to the gift receiver; otherwise, everyone will be able to see them.

    - is_saved (`bool`, optional) – `True`, if the gift is displayed on the account’s profile page; for gifts received on behalf of business accounts only.

    - can_be_upgraded (`bool`, optional) – `True`, if the gift can be upgraded to a unique gift; for gifts received on behalf of business accounts only.

    - was_refunded (`bool`, optional) – `True`, if the gift was refunded and isn’t available anymore.

    - convert_star_count (`int`, optional) – Number of Telegram Stars that can be claimed by the receiver instead of the gift; omitted if the gift cannot be converted to Telegram Stars.

    - prepaid_upgrade_star_count (`int`, optional) – Number of Telegram Stars that were paid by the sender for the ability to upgrade the gift.

  type

    Type of the gift, always `REGULAR`.

    Type:

      `str`

  gift

    Information about the regular gift.

    Type:

      `telegram.Gift`

  owned_gift_id

    Optional. Unique identifier of the gift for the bot; for gifts received on behalf of business accounts only.

    Type:

      `str`

  sender_user

    Optional. Sender of the gift if it is a known user.

    Type:

      `telegram.User`

  send_date

    Date the gift was sent as `datetime.datetime`. The default timezone of the bot is used for localization, which is UTC unless `telegram.ext.Defaults.tzinfo` is used..

    Type:

      `datetime.datetime`

  text

    Optional. Text of the message that was added to the gift.

    Type:

      `str`

  entities

    Optional. Special entities that appear in the text.

    Type:

      Sequence[`telegram.MessageEntity`]

  is_private

    Optional. `True`, if the sender and gift text are shown only to the gift receiver; otherwise, everyone will be able to see them.

    Type:

      `bool`

  is_saved

    Optional. `True`, if the gift is displayed on the account’s profile page; for gifts received on behalf of business accounts only.

    Type:

      `bool`

  can_be_upgraded

    Optional. `True`, if the gift can be upgraded to a unique gift; for gifts received on behalf of business accounts only.

    Type:

      `bool`

  was_refunded

    Optional. `True`, if the gift was refunded and isn’t available anymore.

    Type:

      `bool`

  convert_star_count

    Optional. Number of Telegram Stars that can be claimed by the receiver instead of the gift; omitted if the gift cannot be converted to Telegram Stars.

    Type:

      `int`

  prepaid_upgrade_star_count

    Optional. Number of Telegram Stars that were paid by the sender for the ability to upgrade the gift.

    Type:

      `int`

  classmethod de_json(data, bot=None)

    See `telegram.OwnedGift.de_json()`.

  parse_entities(types=None)

    Returns a `dict` that maps `telegram.MessageEntity` to `str`. It contains entities from this owned gift’s text filtered by their `type` attribute as the key, and the text that each entity belongs to as the value of the `dict`.

    Note

    This method should always be used instead of the `entities` attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. See `parse_entity` for more info.

    Parameters:

      types (list[`str`], optional) – List of `MessageEntity` types as strings. If the `type` attribute of an entity is contained in this list, it will be returned. Defaults to `telegram.MessageEntity.ALL_TYPES`.

    Returns:

      A dictionary of entities mapped to the text that belongs to them, calculated based on UTF-16 codepoints.

    Return type:

      dict[`telegram.MessageEntity`, `str`]

    Raises:

      RuntimeError – If the owned gift has no text.

  parse_entity(entity)

    Returns the text in `text` from a given `telegram.MessageEntity` of `entities`.

    Note

    This method is present because Telegram calculates the offset and length in UTF-16 codepoint pairs, which some versions of Python don’t handle automatically. (That is, you can’t just slice `OwnedGiftRegular.text` with the offset and length.)

    Parameters:

      entity (`telegram.MessageEntity`) – The entity to extract the text from. It must be an entity that belongs to `entities`.

    Returns:

      The text of the given entity.

    Return type:

      `str`

    Raises:

      RuntimeError – If the owned gift has no text.