telegram.helpers Module¶

This module contains convenience helper functions.

Changed in version 20.0: Previously, the contents of this module were available through the (no longer existing) module telegram.utils.helpers.

telegram.helpers.create_deep_linked_url(bot_username, payload=None, group=False)[source]¶

Creates a deep-linked URL for this bot_username with the specified payload. See https://core.telegram.org/bots/features#deep-linking to learn more.

The payload may consist of the following characters: A-Z, a-z, 0-9, _, -

Note

Works well in conjunction with CommandHandler("start", callback, filters=filters.Regex('payload'))

Examples

create_deep_linked_url(bot.get_me().username, "some-params")
Deep Linking

Parameters:

bot_username (str) – The username to link to.
payload (str, optional) – Parameters to encode in the created URL.
group (bool, optional) – If True the user is prompted to select a group to add the bot to. If False, opens a one-on-one conversation with the bot. Defaults to False.

Returns:

An URL to start the bot with specific parameters.

Return type:

str

Raises:

ValueError – If the length of the payload exceeds 64 characters, contains invalid characters, or if the bot_username is less than 4 characters.

telegram.helpers.effective_message_type(entity)[source]¶

Extracts the type of message as a string identifier from a telegram.Message or a telegram.Update.

Parameters:: entity (telegram.Update | telegram.Message) – The update or message to extract from.
Returns:: One of telegram.constants.MessageType if the entity contains a message that matches one of those types. None otherwise.
Return type:: str | None

telegram.helpers.escape_markdown(text, version=1, entity_type=None)[source]¶

Helper function to escape telegram markup symbols.

Changed in version 20.3: Custom emoji entity escaping is now supported.

Parameters:

text (str) – The text.
version (int | str) – Use to specify the version of telegrams Markdown. Either 1 or 2. Defaults to 1.
entity_type (str, optional) – For the entity types 'pre', 'code' and the link part of 'text_link' and 'custom_emoji', only certain characters need to be escaped in 'MarkdownV2'. See the official API documentation for details. Only valid in combination with version=2, will be ignored else.

telegram.helpers.mention_html(user_id, name)[source]¶

Helper function to create a user mention as HTML tag.

Parameters:

user_id (int) – The user’s id which you want to mention.
name (str) – The name the mention is showing.

Returns:

The inline mention for the user as HTML.

Return type:

str

telegram.helpers.mention_markdown(user_id, name, version=1)[source]¶

Helper function to create a user mention in Markdown syntax.

Parameters:

user_id (int) – The user’s id which you want to mention.
name (str) – The name the mention is showing.
version (int | str) – Use to specify the version of Telegram’s Markdown. Either 1 or 2. Defaults to 1.

Returns:

The inline mention for the user as Markdown.

Return type:

str