MessageEntity¶
- class telegram.MessageEntity(type, offset, length, url=None, user=None, language=None, custom_emoji_id=None, *, api_kwargs=None)[source]¶
Bases:
telegram.TelegramObject
This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their
type
,offset
andlength
are equal.- Parameters:
type (
str
) –Type of the entity. Can be
MENTION
(@username),HASHTAG
(#hashtag),CASHTAG
($USD),BOT_COMMAND
(/start@jobs_bot),URL
(https://telegram.org),EMAIL
(do-not-reply@telegram.org),PHONE_NUMBER
(+1-212-555-0123),BOLD
(bold text),ITALIC
(italic text),UNDERLINE
(underlined text),STRIKETHROUGH
,SPOILER
(spoiler message),BLOCKQUOTE
(block quotation),CODE
(monowidth string),PRE
(monowidth block),TEXT_LINK
(for clickable text URLs),TEXT_MENTION
(for users without usernames),CUSTOM_EMOJI
(for inline custom emoji stickers).Added in version 20.0: Added inline custom emoji
Added in version 20.8: Added block quotation
offset (
int
) – Offset in UTF-16 code units to the start of the entity.length (
int
) – Length of the entity in UTF-16 code units.url (
str
, optional) – ForTEXT_LINK
only, url that will be opened after user taps on the text.user (
telegram.User
, optional) – ForTEXT_MENTION
only, the mentioned user.language (
str
, optional) – ForPRE
only, the programming language of the entity text.custom_emoji_id (
str
, optional) –For
CUSTOM_EMOJI
only, unique identifier of the custom emoji. Usetelegram.Bot.get_custom_emoji_stickers()
to get full information about the sticker.Added in version 20.0.
- type[source]¶
Type of the entity. Can be
MENTION
(@username),HASHTAG
(#hashtag),CASHTAG
($USD),BOT_COMMAND
(/start@jobs_bot),URL
(https://telegram.org),EMAIL
(do-not-reply@telegram.org),PHONE_NUMBER
(+1-212-555-0123),BOLD
(bold text),ITALIC
(italic text),UNDERLINE
(underlined text),STRIKETHROUGH
,SPOILER
(spoiler message),BLOCKQUOTE
(block quotation),CODE
(monowidth string),PRE
(monowidth block),TEXT_LINK
(for clickable text URLs),TEXT_MENTION
(for users without usernames),CUSTOM_EMOJI
(for inline custom emoji stickers).Added in version 20.0: Added inline custom emoji
Added in version 20.8: Added block quotation
- Type:
str
- url[source]¶
Optional. For
TEXT_LINK
only, url that will be opened after user taps on the text.- Type:
str
- user[source]¶
Optional. For
TEXT_MENTION
only, the mentioned user.- Type:
- custom_emoji_id[source]¶
Optional. For
CUSTOM_EMOJI
only, unique identifier of the custom emoji. Usetelegram.Bot.get_custom_emoji_stickers()
to get full information about the sticker.Added in version 20.0.
- Type:
str
Use In
Available In
- ALL_TYPES = [<MessageEntityType.BLOCKQUOTE>, <MessageEntityType.BOLD>, <MessageEntityType.BOT_COMMAND>, <MessageEntityType.CASHTAG>, <MessageEntityType.CODE>, <MessageEntityType.CUSTOM_EMOJI>, <MessageEntityType.EMAIL>, <MessageEntityType.EXPANDABLE_BLOCKQUOTE>, <MessageEntityType.HASHTAG>, <MessageEntityType.ITALIC>, <MessageEntityType.MENTION>, <MessageEntityType.PHONE_NUMBER>, <MessageEntityType.PRE>, <MessageEntityType.SPOILER>, <MessageEntityType.STRIKETHROUGH>, <MessageEntityType.TEXT_LINK>, <MessageEntityType.TEXT_MENTION>, <MessageEntityType.UNDERLINE>, <MessageEntityType.URL>][source]¶
A list of all available message entity types.
- Type:
List[
str
]
- BLOCKQUOTE = 'blockquote'[source]¶
telegram.constants.MessageEntityType.BLOCKQUOTE
Added in version 20.8.
- CUSTOM_EMOJI = 'custom_emoji'[source]¶
telegram.constants.MessageEntityType.CUSTOM_EMOJI
Added in version 20.0.
- EXPANDABLE_BLOCKQUOTE = 'expandable_blockquote'[source]¶
telegram.constants.MessageEntityType.EXPANDABLE_BLOCKQUOTE
Added in version 21.3.
- SPOILER = 'spoiler'[source]¶
telegram.constants.MessageEntityType.SPOILER
Added in version 13.10.
- static adjust_message_entities_to_utf_16(text, entities)[source]¶
Utility functionality for converting the offset and length of entities from Unicode (
str
) to UTF-16 (utf-16-le
encodedbytes
).Tip
Only the offsets and lengths calulated in UTF-16 is acceptable by the Telegram Bot API. If they are calculated using the Unicode string (
str
object), errors may occur when the text contains characters that are not in the Basic Multilingual Plane (BMP). For more information, see Unicode and Plane (Unicode).Added in version 21.4.
Examples
Below is a snippet of code that demonstrates how to use this function to convert entities from Unicode to UTF-16 space. The
unicode_entities
are calculated in Unicode and the utf_16_entities are calculated in UTF-16.text = "𠌕 bold 𝄢 italic underlined: 𝛙𝌢𑁍" unicode_entities = [ MessageEntity(offset=2, length=4, type=MessageEntity.BOLD), MessageEntity(offset=9, length=6, type=MessageEntity.ITALIC), MessageEntity(offset=28, length=3, type=MessageEntity.UNDERLINE), ] utf_16_entities = MessageEntity.adjust_message_entities_to_utf_16( text, unicode_entities ) await bot.send_message( chat_id=123, text=text, entities=utf_16_entities, ) # utf_16_entities[0]: offset=3, length=4 # utf_16_entities[1]: offset=11, length=6 # utf_16_entities[2]: offset=30, length=6
- Parameters:
text (
str
) – The text that the entities belong toentities (Sequence[
telegram.MessageEntity
]) – Sequence of entities with offset and length calculated in Unicode
- Returns:
Sequence of entities with offset and length calculated in UTF-16 encoding
- Return type:
Sequence[
telegram.MessageEntity
]