Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
Toggle table of contents sidebar

# Poll

class telegram.Poll(id, question, options, total_voter_count, is_closed, is_anonymous, type, allows_multiple_answers, correct_option_id=None, explanation=None, explanation_entities=None, open_period=None, close_date=None, *, api_kwargs=None)

  Bases: `telegram.TelegramObject`

  This object contains information about a poll.

  Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their `id` is equal.

  Examples

  Poll Bot

  Parameters:

    - id (`str`) – Unique poll identifier.

    - question (`str`) – Poll question, `1`- `300` characters.

    - options (Sequence[`PollOption`]) –

      List of poll options.

      Changed in version 20.0: Accepts any `collections.abc.Sequence` as input instead of just a list. The input is converted to a tuple.

    - is_closed (`bool`) – `True`, if the poll is closed.

    - is_anonymous (`bool`) – `True`, if the poll is anonymous.

    - type (`str`) – Poll type, currently can be `REGULAR` or `QUIZ`.

    - allows_multiple_answers (`bool`) – `True`, if the poll allows multiple answers.

    - correct_option_id (`int`, optional) – A zero based identifier of the correct answer option. Available only for closed polls in the quiz mode, which were sent (not forwarded), by the bot or to a private chat with the bot.

    - explanation (`str`, optional) – Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-`200` characters.

    - explanation_entities (Sequence[`telegram.MessageEntity`], optional) –

      Special entities like usernames, URLs, bot commands, etc. that appear in the `explanation`. This list is empty if the message does not contain explanation entities.

      Changed in version 20.0:

      - This attribute is now always a (possibly empty) list and never `None`.

      - Accepts any `collections.abc.Sequence` as input instead of just a list. The input is converted to a tuple.

    - open_period (`int`, optional) – Amount of time in seconds the poll will be active after creation.

    - close_date (`datetime.datetime`, optional) –

      Point in time (Unix timestamp) when the poll will be automatically closed. Converted to `datetime.datetime`.

      Changed in version 20.3: The default timezone of the bot is used for localization, which is UTC unless `telegram.ext.Defaults.tzinfo` is used.

  id

    Unique poll identifier.

    Type:

      `str`

  question

    Poll question, `1`- `300` characters.

    Type:

      `str`

  options

    List of poll options.

    Changed in version 20.0: This attribute is now an immutable tuple.

    Type:

      Tuple[`PollOption`]

  total_voter_count

    Total number of users that voted in the poll.

    Type:

      `int`

  is_closed

    `True`, if the poll is closed.

    Type:

      `bool`

  is_anonymous

    `True`, if the poll is anonymous.

    Type:

      `bool`

  type

    Poll type, currently can be `REGULAR` or `QUIZ`.

    Type:

      `str`

  allows_multiple_answers

    `True`, if the poll allows multiple answers.

    Type:

      `bool`

  correct_option_id

    Optional. A zero based identifier of the correct answer option. Available only for closed polls in the quiz mode, which were sent (not forwarded), by the bot or to a private chat with the bot.

    Type:

      `int`

  explanation

    Optional. Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-`200` characters.

    Type:

      `str`

  explanation_entities

    Special entities like usernames, URLs, bot commands, etc. that appear in the `explanation`. This list is empty if the message does not contain explanation entities.

    Changed in version 20.0: This attribute is now an immutable tuple.

    Changed in version 20.0: This attribute is now always a (possibly empty) list and never `None`.

    Type:

      Tuple[`telegram.MessageEntity`]

  open_period

    Optional. Amount of time in seconds the poll will be active after creation.

    Type:

      `int`

  close_date

    Optional. Point in time when the poll will be automatically closed.

    Changed in version 20.3: The default timezone of the bot is used for localization, which is UTC unless `telegram.ext.Defaults.tzinfo` is used.

    Type:

      `datetime.datetime`

  Available In

  - `telegram.ExternalReplyInfo.poll`

  - `telegram.Message.poll`

  - `telegram.Update.poll`

  Returned In

  `telegram.Bot.stop_poll()`

  MAX_EXPLANATION_LENGTH = 200

    `telegram.constants.PollLimit.MAX_EXPLANATION_LENGTH`

    New in version 20.0.

  MAX_EXPLANATION_LINE_FEEDS = 2

    `telegram.constants.PollLimit.MAX_EXPLANATION_LINE_FEEDS`

    New in version 20.0.

  MAX_OPEN_PERIOD = 600

    `telegram.constants.PollLimit.MAX_OPEN_PERIOD`

    New in version 20.0.

  MAX_OPTION_LENGTH = 100

    `telegram.constants.PollLimit.MAX_OPTION_LENGTH`

    New in version 20.0.

  MAX_OPTION_NUMBER = 10

    `telegram.constants.PollLimit.MAX_OPTION_NUMBER`

    New in version 20.0.

  MAX_QUESTION_LENGTH = 300

    `telegram.constants.PollLimit.MAX_QUESTION_LENGTH`

    New in version 20.0.

  MIN_OPEN_PERIOD = 5

    `telegram.constants.PollLimit.MIN_OPEN_PERIOD`

    New in version 20.0.

  MIN_OPTION_LENGTH = 1

    `telegram.constants.PollLimit.MIN_OPTION_LENGTH`

    New in version 20.0.

  MIN_OPTION_NUMBER = 2

    `telegram.constants.PollLimit.MIN_OPTION_NUMBER`

    New in version 20.0.

  MIN_QUESTION_LENGTH = 1

    `telegram.constants.PollLimit.MIN_QUESTION_LENGTH`

    New in version 20.0.

  QUIZ = 'quiz'

    `telegram.constants.PollType.QUIZ`

  REGULAR = 'regular'

    `telegram.constants.PollType.REGULAR`

  classmethod de_json(data, bot)

    See `telegram.TelegramObject.de_json()`.

  parse_explanation_entities(types=None)

    Returns a `dict` that maps `telegram.MessageEntity` to `str`. It contains entities from this polls explanation 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 `explanation_entities` attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. See `parse_explanation_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`]

  parse_explanation_entity(entity)

    Returns the text from a given `telegram.MessageEntity`.

    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 `Message.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 this message.

    Returns:

      The text of the given entity.

    Return type:

      `str`

    Raises:

      RuntimeError – If the poll has no explanation.