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