Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
Toggle table of contents sidebar

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