Skip to content
Back to top
View this page

# 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, question_entities=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

  Available In

  - `telegram.ExternalReplyInfo.poll`

  - `telegram.Message.effective_attachment`

  - `telegram.Message.poll`

  - `telegram.Update.poll`

  Returned In

  `telegram.Bot.stop_poll()`

  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` | `datetime.timedelta`, optional) –

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

      Changed in version v22.2: `datetime.timedelta` objects are accepted in addition to plain `int` values.

    - 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.

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

      Special entities that appear in the `question`. Currently, only custom emoji entities are allowed in poll questions.

      Added in version 21.2.

  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.

    Deprecated since version v22.2: In a future major version this attribute will be of type `datetime.timedelta`. You can opt-in early by setting PTB_TIMEDELTA=true or `PTB_TIMEDELTA=1` as an environment variable.

    Type:

      `int` | `datetime.timedelta`

  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`

  question_entities

    Special entities that appear in the `question`. Currently, only custom emoji entities are allowed in poll questions. This list is empty if the question does not contain entities.

    Added in version 21.2.

    Type:

      tuple[`telegram.MessageEntity`]

  MAX_EXPLANATION_LENGTH = 200

    `telegram.constants.PollLimit.MAX_EXPLANATION_LENGTH`

    Added in version 20.0.

  MAX_EXPLANATION_LINE_FEEDS = 2

    `telegram.constants.PollLimit.MAX_EXPLANATION_LINE_FEEDS`

    Added in version 20.0.

  MAX_OPEN_PERIOD = 600

    `telegram.constants.PollLimit.MAX_OPEN_PERIOD`

    Added in version 20.0.

  MAX_OPTION_LENGTH = 100

    `telegram.constants.PollLimit.MAX_OPTION_LENGTH`

    Added in version 20.0.

  MAX_OPTION_NUMBER = 12

    `telegram.constants.PollLimit.MAX_OPTION_NUMBER`

    Added in version 20.0.

  MAX_QUESTION_LENGTH = 300

    `telegram.constants.PollLimit.MAX_QUESTION_LENGTH`

    Added in version 20.0.

  MIN_OPEN_PERIOD = 5

    `telegram.constants.PollLimit.MIN_OPEN_PERIOD`

    Added in version 20.0.

  MIN_OPTION_LENGTH = 1

    `telegram.constants.PollLimit.MIN_OPTION_LENGTH`

    Added in version 20.0.

  MIN_OPTION_NUMBER = 2

    `telegram.constants.PollLimit.MIN_OPTION_NUMBER`

    Added in version 20.0.

  MIN_QUESTION_LENGTH = 1

    `telegram.constants.PollLimit.MIN_QUESTION_LENGTH`

    Added in version 20.0.

  QUIZ = 'quiz'

    `telegram.constants.PollType.QUIZ`

  REGULAR = 'regular'

    `telegram.constants.PollType.REGULAR`

  classmethod de_json(data, bot=None)

    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`]

    Raises:

      RuntimeError – If the poll has no explanation.

  parse_explanation_entity(entity)

    Returns the text in `explanation` from a given `telegram.MessageEntity` of `explanation_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 `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 `explanation_entities`.

    Returns:

      The text of the given entity.

    Return type:

      `str`

    Raises:

      RuntimeError – If the poll has no explanation.

  parse_question_entities(types=None)

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

    Added in version 21.2.

    Note

    This method should always be used instead of the `question_entities` attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. See `parse_question_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_question_entity(entity)

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

    Added in version 21.2.

    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 `question_entities`.

    Returns:

      The text of the given entity.

    Return type:

      `str`