CINXE.COM

<!DOCTYPE html> <html class=""> <head> <meta charset="utf-8"> <title>Custom emojis</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta property="description" content="Telegram allows including animated and static custom emojis inside of messages."> <meta property="og:title" content="Custom emojis"> <meta property="og:image" content=""> <meta property="og:description" content="Telegram allows including animated and static custom emojis inside of messages."> <link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4"> <link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png"> <link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" /> <link href="/css/bootstrap.min.css?3" rel="stylesheet"> <link href="/css/telegram.css?241" rel="stylesheet" media="screen"> <style> </style> </head> <body class="preload"> <div class="dev_page_wrap"> <div class="dev_page_head navbar navbar-static-top navbar-tg"> <div class="navbar-inner"> <div class="container clearfix"> <ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul> <ul class="nav navbar-nav"> <li><a href="//telegram.org/">Home</a></li> <li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li> <li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li> <li class="active"><a href="/api">API</a></li> <li class=""><a href="/mtproto">Protocol</a></li> <li class=""><a href="/schema">Schema</a></li> </ul> </div> </div> </div> <div class="container clearfix"> <div class="dev_page"> <div id="dev_page_content_wrap" class=" "> <div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/custom-emoji" >Custom emojis</a></li></ul></div> <h1 id="dev_page_title">Custom emojis</h1> <div id="dev_page_content"> <p>Telegram allows including animated and static custom emojis inside of messages.</p> <h3><a class="anchor" href="#custom-emoji-entities" id="custom-emoji-entities" name="custom-emoji-entities"><i class="anchor-icon"></i></a>Custom emoji entities</h3> <pre><code><a href='/constructor/messageEntityCustomEmoji'>messageEntityCustomEmoji</a>#c8cf05f8 offset:<a href='/type/int'>int</a> length:<a href='/type/int'>int</a> document_id:<a href='/type/long'>long</a> = <a href='/type/MessageEntity'>MessageEntity</a>; <a href='/constructor/document'>document</a>#8fd4c4d8 flags:<a href='/type/%23'>#</a> id:<a href='/type/long'>long</a> access_hash:<a href='/type/long'>long</a> file_reference:<a href='/type/bytes'>bytes</a> date:<a href='/type/int'>int</a> mime_type:<a href='/type/string'>string</a> size:<a href='/type/long'>long</a> thumbs:flags.0?<a href='/type/Vector%20t'>Vector</a><<a href='/type/PhotoSize'>PhotoSize</a>> video_thumbs:flags.1?<a href='/type/Vector%20t'>Vector</a><<a href='/type/VideoSize'>VideoSize</a>> dc_id:<a href='/type/int'>int</a> attributes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/DocumentAttribute'>DocumentAttribute</a>> = <a href='/type/Document'>Document</a>; <a href='/constructor/documentAttributeCustomEmoji'>documentAttributeCustomEmoji</a>#fd149899 flags:<a href='/type/%23'>#</a> free:flags.0?<a href='/constructor/true'>true</a> text_color:flags.1?<a href='/constructor/true'>true</a> alt:<a href='/type/string'>string</a> stickerset:<a href='/type/InputStickerSet'>InputStickerSet</a> = <a href='/type/DocumentAttribute'>DocumentAttribute</a>; ---functions--- <a href='/method/messages.getCustomEmojiDocuments'>messages.getCustomEmojiDocuments</a>#d9ab0f54 document_id:<a href='/type/Vector%20t'>Vector</a><<a href='/type/long'>long</a>> = <a href='/type/Vector%20t'>Vector</a><<a href='/type/Document'>Document</a>>;</code></pre> <p>Custom emojis are a special kind of <a href="/api/entities">entity聽禄</a>, containing just a <code>document_id</code>, which can be passed to <a href="/method/messages.getCustomEmojiDocuments">messages.getCustomEmojiDocuments</a> to fetch the <a href="/api/stickers">static, animated or video sticker emoji</a> that should be displayed to the user as described in the <a href="/api/stickers">stickers documentation</a>. </p> <p>Custom emoji documents will contain <a href="/constructor/documentAttributeCustomEmoji">documentAttributeCustomEmoji</a> attribute instead of a <a href="/constructor/documentAttributeSticker">documentAttributeSticker</a>, containing information on the associated emoji (<code>alt</code>), whether the emoji can be used by non-premium users (<code>free</code>) and the associated <code>stickerset</code>.<br> If the <a href="/constructor/documentAttributeCustomEmoji">documentAttributeCustomEmoji</a>.<code>text_color</code> flag is set, the color of this TGS custom emoji should be changed to the text color when used in messages, the accent color if used as emoji status, white on chat photos, or another appropriate color based on context.</p> <p>Note that when sending messages with attached custom emojis, the <a href="/constructor/messageEntityCustomEmoji">messageEntityCustomEmoji</a> <a href="/api/entities">entity聽禄</a> must wrap exactly one regular emoji (the one contained in <a href="/constructor/documentAttributeCustomEmoji">documentAttributeCustomEmoji</a>.<code>alt</code>) in the related text, otherwise the server will ignore it. </p> <p>Like stickers, custom emojis are organized in <a href="/api/stickers#stickersets">stickersets</a>: see the <a href="/api/stickers">stickers documentation聽禄</a> for more info on how to work with them.</p> <p>To send a message with one or more custom emojis, create and attach <a href="/constructor/messageEntityCustomEmoji">messageEntityCustomEmoji</a> <a href="/api/entities">entities聽禄</a> to a message.<br> Note that you can attach a maximum of <code>message_animated_emoji_max</code> custom emojis, as specified by the <a href="/api/config#message-animated-emoji-max">appConfig field聽禄</a>. </p> <h3><a class="anchor" href="#emoji-categories" id="emoji-categories" name="emoji-categories"><i class="anchor-icon"></i></a>Emoji categories</h3> <p>The custom emoji selection UI should offer a list of categories to quickly filter results by a (list of) emojis, or by some other criteria, see <a href="/api/emoji-categories">here聽禄</a> for more info. </p> <h3><a class="anchor" href="#emoji-keywords" id="emoji-keywords" name="emoji-keywords"><i class="anchor-icon"></i></a>Emoji keywords</h3> <pre><code><a href='/constructor/emojiKeyword'>emojiKeyword</a>#d5b3b9f9 keyword:<a href='/type/string'>string</a> emoticons:<a href='/type/Vector%20t'>Vector</a><<a href='/type/string'>string</a>> = <a href='/type/EmojiKeyword'>EmojiKeyword</a>; <a href='/constructor/emojiKeywordDeleted'>emojiKeywordDeleted</a>#236df622 keyword:<a href='/type/string'>string</a> emoticons:<a href='/type/Vector%20t'>Vector</a><<a href='/type/string'>string</a>> = <a href='/type/EmojiKeyword'>EmojiKeyword</a>; <a href='/constructor/emojiKeywordsDifference'>emojiKeywordsDifference</a>#5cc761bd lang_code:<a href='/type/string'>string</a> from_version:<a href='/type/int'>int</a> version:<a href='/type/int'>int</a> keywords:<a href='/type/Vector%20t'>Vector</a><<a href='/type/EmojiKeyword'>EmojiKeyword</a>> = <a href='/type/EmojiKeywordsDifference'>EmojiKeywordsDifference</a>; <a href='/constructor/emojiLanguage'>emojiLanguage</a>#b3fb5361 lang_code:<a href='/type/string'>string</a> = <a href='/type/EmojiLanguage'>EmojiLanguage</a>; <a href='/constructor/emojiURL'>emojiURL</a>#a575739d url:<a href='/type/string'>string</a> = <a href='/type/EmojiURL'>EmojiURL</a>; ---functions--- <a href='/method/messages.getEmojiKeywords'>messages.getEmojiKeywords</a>#35a0e062 lang_code:<a href='/type/string'>string</a> = <a href='/type/EmojiKeywordsDifference'>EmojiKeywordsDifference</a>; <a href='/method/messages.getEmojiKeywordsDifference'>messages.getEmojiKeywordsDifference</a>#1508b6af lang_code:<a href='/type/string'>string</a> from_version:<a href='/type/int'>int</a> = <a href='/type/EmojiKeywordsDifference'>EmojiKeywordsDifference</a>; <a href='/method/messages.getEmojiKeywordsLanguages'>messages.getEmojiKeywordsLanguages</a>#4e9963b2 lang_codes:<a href='/type/Vector%20t'>Vector</a><<a href='/type/string'>string</a>> = <a href='/type/Vector%20t'>Vector</a><<a href='/type/EmojiLanguage'>EmojiLanguage</a>>; <a href='/method/messages.getEmojiURL'>messages.getEmojiURL</a>#d5b10c26 lang_code:<a href='/type/string'>string</a> = <a href='/type/EmojiURL'>EmojiURL</a>;</code></pre> <p>First of all, invoke <a href="/method/messages.getEmojiKeywordsLanguages">messages.getEmojiKeywordsLanguages</a> to obtain a list of languages that must be used when fetching emoji keyword lists: usually the method will return the passed language codes (if localized) + <code>en</code> + some language codes for similar languages (if applicable).<br> Then, invoke <a href="/method/messages.getEmojiKeywords">messages.getEmojiKeywords</a> for all the returned language codes to fetch localized lists of keywords, associated to UTF-8 emojis. </p> <p>Use the returned keywords to allow users to search both emojis and custom emojis by keyword, by displaying both the UTF-8 emojis associated to the keyword and the custom emojis associated to those UTF-8 emojis. </p> <p>Invoke <a href="/method/messages.getEmojiKeywordsDifference">messages.getEmojiKeywordsDifference</a> regularly to fetch updates to locally stored keyword lists for all languages. </p> <p><a href="/method/messages.getEmojiURL">messages.getEmojiURL</a> may be used to fetch an HTTP URL which can be used to automatically log in into translation platform and suggest new emoji keywords: the URL will be valid for 30 seconds after generation. </p> <p>Additionally, custom emojis and non-mask stickers may also have a set of <em>custom</em> keywords, returned in the <a href="/api/stickers#stickersets">custom emoji stickerset information</a>: </p> <pre><code><a href='/constructor/stickerKeyword'>stickerKeyword</a>#fcfeb29c document_id:<a href='/type/long'>long</a> keyword:<a href='/type/Vector%20t'>Vector</a><<a href='/type/string'>string</a>> = <a href='/type/StickerKeyword'>StickerKeyword</a>; <a href='/constructor/messages.stickerSet'>messages.stickerSet</a>#6e153f16 set:<a href='/type/StickerSet'>StickerSet</a> packs:<a href='/type/Vector%20t'>Vector</a><<a href='/type/StickerPack'>StickerPack</a>> keywords:<a href='/type/Vector%20t'>Vector</a><<a href='/type/StickerKeyword'>StickerKeyword</a>> documents:<a href='/type/Vector%20t'>Vector</a><<a href='/type/Document'>Document</a>> = <a href='/type/messages.StickerSet'>messages.StickerSet</a>; <a href='/constructor/stickerSetFullCovered'>stickerSetFullCovered</a>#40d13c0e set:<a href='/type/StickerSet'>StickerSet</a> packs:<a href='/type/Vector%20t'>Vector</a><<a href='/type/StickerPack'>StickerPack</a>> keywords:<a href='/type/Vector%20t'>Vector</a><<a href='/type/StickerKeyword'>StickerKeyword</a>> documents:<a href='/type/Vector%20t'>Vector</a><<a href='/type/Document'>Document</a>> = <a href='/type/StickerSetCovered'>StickerSetCovered</a>;</code></pre></div> </div> </div> </div> <div class="footer_wrap"> <div class="footer_columns_wrap footer_desktop"> <div class="footer_column footer_column_telegram"> <h5>Telegram</h5> <div class="footer_telegram_description"></div> Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed. </div> <div class="footer_column"> <h5><a href="//telegram.org/faq">About</a></h5> <ul> <li><a href="//telegram.org/faq">FAQ</a></li> <li><a href="//telegram.org/privacy">Privacy</a></li> <li><a href="//telegram.org/press">Press</a></li> </ul> </div> <div class="footer_column"> <h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5> <ul> <li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li> <li><a href="//telegram.org/android">Android</a></li> <li><a href="//telegram.org/dl/web">Mobile Web</a></li> </ul> </div> <div class="footer_column"> <h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5> <ul> <li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li> <li><a href="//macos.telegram.org/">macOS</a></li> <li><a href="//telegram.org/dl/web">Web-browser</a></li> </ul> </div> <div class="footer_column footer_column_platform"> <h5><a href="/">Platform</a></h5> <ul> <li><a href="/api">API</a></li> <li><a href="//translations.telegram.org/">Translations</a></li> <li><a href="//instantview.telegram.org/">Instant View</a></li> </ul> </div> </div> <div class="footer_columns_wrap footer_mobile"> <div class="footer_column"> <h5><a href="//telegram.org/faq">About</a></h5> </div> <div class="footer_column"> <h5><a href="//telegram.org/blog">Blog</a></h5> </div> <div class="footer_column"> <h5><a href="//telegram.org/apps">Apps</a></h5> </div> <div class="footer_column"> <h5><a href="/">Platform</a></h5> </div> <div class="footer_column"> <h5><a href="//telegram.org/press">Press</a></h5> </div> </div> </div> </div> <script src="/js/main.js?47"></script> <script src="/js/jquery.min.js?1"></script> <script src="/js/bootstrap.min.js?1"></script> <script>window.initDevPageNav&&initDevPageNav(); backToTopInit("Go up"); removePreloadInit(); </script> </body> </html>