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, allows_revoting=None, members_only=None, correct_option_ids=None, description=None, description_entities=None, country_codes=None, media=None, explanation_media=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.

    - members_only (`bool`) –

      `True`, if voting is limited to users who have been members of the chat where the poll was originally sent for more than `24` hours.

      Added in version 22.8.

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

      Deprecated since version 22.8: Use `correct_option_ids` instead.

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

    - explanation_media (`telegram.PollMedia`, optional) –

      Media added to the quiz explanation.

      Added in version 22.8.

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

    - allows_revoting (`bool`, optional) –

      `True`, if the poll allows to change the chosenanswer options.

      Added in version 22.8.

    - correct_option_ids (Sequence[`int`], optional) –

      Array of 0-based identifiers of the correct answer options. Available only for polls in quiz mode which are closed or were sent (not forwarded) by the bot or to the private chat with the bot.

      Added in version 22.8.

    - country_codes (Sequence[`str`], optional) –

      A list of two-letter `ISO 3166-1 alpha-2` country codes indicating the countries from which users can vote in the poll. The country code `"FT"` is used for users with anonymous numbers. If omitted, then users from any country can participate in the poll.

      Added in version 22.8.

    - description (`str`, optional) –

      Description of the poll; for polls inside the `Message` object only.

      Added in version 22.8.

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

      Special entities like usernames, URLs, bot commands, etc. that appear in the description

      Added in version 22.8.

    - media (`telegram.PollMedia`, optional) –

      Media added to the poll description; for polls inside the `Message` object only.

      Added in version 22.8.

  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`

  members_only

    `True`, if voting is limited to users who have been members of the chat where the poll was originally sent for more than `24` hours.

    Added in version 22.8.

    Type:

      `bool`

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

  explanation_media

    Optional. Media added to the quiz explanation.

    Added in version 22.8.

    Type:

      `telegram.PollMedia`

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

  allows_revoting

    `True`, if the poll allows to change the chosenanswer options

    Added in version 22.8.

    Type:

      `bool`

  correct_option_ids

    Array of 0-based identifiers of the correct answer options. Available only for polls in quiz mode which are closed or were sent (not forwarded) by the bot or to the private chat with the bot.

    Added in version 22.8.

    Type:

      tuple[`int`]

  country_codes

    Optional. A list of two-letter `ISO 3166-1 alpha-2` country codes indicating the countries from which users can vote in the poll. The country code `"FT"` is used for users with anonymous numbers. If omitted, then users from any country can participate in the poll.

    Added in version 22.8.

    Type:

      tuple[`str`]

  description

    Optional. Description of the poll; for polls inside the Message object only

    Added in version 22.8.

    Type:

      `str`

  description_entities

    Special entities like usernames, URLs, bot commands, etc. that appear in the description

    Added in version 22.8.

    Type:

      tuple[`telegram.MessageEntity`]

  media

    Optional. Media added to the poll description; for polls inside the Message object only.

    Added in version 22.8.

    Type:

      `telegram.PollMedia`

  MAX_DESCRIPTION_CHARACTERS = 1024

    `telegram.constants.PollLimit.MAX_DESCRIPTION_CHARACTERS`

    Added in version 22.8.

  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 = 2628000

    `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_MEMBERSHIP_HOURS = 24

    `telegram.constants.PollLimit.MIN_MEMBERSHIP_HOURS`

    Added in version 22.8.

  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 = 1

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

  property correct_option_id

    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.

    Deprecated since version 22.8: Use `correct_option_ids` instead.

  classmethod de_json(data, bot=None)

    See `telegram.TelegramObject.de_json()`.

  parse_description_entities(types=None)

    Returns a `dict` that maps `telegram.MessageEntity` to `str`. It contains entities from this polls description 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 22.8.

    Note

    This method should always be used instead of the `description_entities` attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. See `parse_description_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 description.

  parse_description_entity(entity)

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

    Added in version 22.8.

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

    Returns:

      The text of the given entity.

    Return type:

      `str`

    Raises:

      RuntimeError – If the poll has no description.

  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`