Skip to content
Back to top
View this page

# 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)

  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)

  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)

  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)

  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)

  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`