<p>Stickers can be contained in <ahref="/constructor/document">document</a> constructors attached to <ahref="/constructor/message">messages</a>, and always have an attribute of type <ahref="/constructor/documentAttributeSticker">documentAttributeSticker</a>. </p>
<p>The <ahref="/constructor/documentAttributeSticker">documentAttributeSticker</a> attribute contains information about the associated <ahref="#stickersets">stickerset</a>, the emoji that represents the sticker, and more. </p>
<p>There are multiple available sticker types:</p>
<p>Static stickers are <ahref="https://en.wikipedia.org/wiki/WebP">WebP</a> images with the following specs:</p>
<ul>
<li>For stickers, either the width or height must be equal to 512 pixels.</li>
<li>For <ahref="/api/custom-emoji">custom emojis</a>, the resolution must be equal to 100x100 pixels.</li>
<li>Transparency is supported.</li>
</ul>
<p>They're identified by <code>mime_type</code> field of the associated <ahref="/constructor/document">document</a>, always equal to <code>image/webp</code>.</p>
<p>See <ahref="/stickers#static-stickers-and-emoji">here »</a> for tips on how to create the perfect static sticker, and <ahref="#creating-stickersets">here »</a> for info on how to upload it using the API.</p>
<p>Animated stickers are <ahref="https://en.wikipedia.org/wiki/Lottie_(file_format)">Lottie vector animations »</a>. </p>
<p>Telegram uses a special <code>.tgs</code> file format for lottie animations, which consists in a gzipped bodymovin JSON file, playable using the <ahref="https://github.com/Samsung/rlottie">rlottie</a> library. </p>
<p>Lottie animation specs:</p>
<ul>
<li>The canvas size must be 512х512 pixels.</li>
<li>Objects must not leave the canvas.</li>
<li>Animation length must not exceed 3 seconds.</li>
<li>All animations must be looped.</li>
<li>All animations must run at 60 Frames Per Second.</li>
</ul>
<p>They're identified by <code>mime_type</code> field of the associated <ahref="/constructor/document">document</a>, always equal to <code>application/x-tgsticker</code>.</p>
<p>See <ahref="/stickers#creating-animations">here »</a> for tips on how to create the perfect animated sticker, and <ahref="#creating-stickersets">here »</a> for info on how to upload it using the API.</p>
<p>Video stickers are <ahref="https://en.wikipedia.org/wiki/VP9">VP9</a> videos with the following specs:</p>
<ul>
<li>The video must be encoded using <ahref="https://en.wikipedia.org/wiki/VP9">VP9</a>, in a <ahref="https://en.wikipedia.org/wiki/WebM">WebM</a> container.</li>
<li>The <ahref="https://en.wikipedia.org/wiki/WebM">WebM</a> container must have <strong>no audio stream</strong>.</li>
<li>For stickers, either the width or height must be equal to 512 pixels.</li>
<li>For <ahref="/api/custom-emoji">custom emojis</a>, the resolution must be equal to 100x100 pixels.</li>
<li>Maximum duration: 3 seconds.</li>
<li>Frame rate: up to 30 FPS.</li>
<li>Transparency is supported.</li>
<li>The video should be looped for optimal user experience.</li>
</ul>
<p>They're identified by <code>mime_type</code> field of the associated <ahref="/constructor/document">document</a>, always equal to <code>video/webm</code>.</p>
<p>See <ahref="/stickers#video-stickers-and-emoji">here »</a> for tips on how to create the perfect video sticker, and <ahref="#creating-stickersets">here »</a> for info on how to upload it using the API.</p>
<p>Stickers are grouped together in so-called sticker packs: however, in the API they're referred to as "sticker sets", and the name "sticker pack" is reserved for something else, read on for more info. </p>
<p>Use <ahref="/method/messages.getStickerSet">messages.getStickerSet</a> to fetch information about the stickerset, providing the following parameters:</p>
<ul>
<li><code>stickerset</code> - One of the following constructors:<ul>
<li><ahref="/constructor/inputStickerSetID">inputStickerSetID</a> - For stickersets contained in received messages</li>
<li><ahref="/constructor/inputStickerSetShortName">inputStickerSetShortName</a> - For stickersets contained in <ahref="/api/links#stickerset-links">sticker deep links »</a></li>
<li><ahref="/constructor/inputStickerSetAnimatedEmoji">inputStickerSetAnimatedEmoji</a> - For <ahref="/api/animated-emojis">animated emoji »</a> stickers.</li>
<li><ahref="/constructor/inputStickerSetAnimatedEmojiAnimations">inputStickerSetAnimatedEmojiAnimations</a> - For <ahref="/api/animated-emojis#emoji-reactions">animated emoji reaction »</a> stickers.</li>
<li><ahref="/constructor/inputStickerSetDice">inputStickerSetDice</a> - For <ahref="/api/dice">dice »</a> stickersets.</li>
<li><ahref="/constructor/inputStickerSetPremiumGifts">inputStickerSetPremiumGifts</a> - For <ahref="/api/premium">premium gift animation »</a> stickers.</li>
<li><ahref="/constructor/inputStickerSetEmojiGenericAnimations">inputStickerSetEmojiGenericAnimations</a> - For <ahref="/api/reactions#animated-normal-emojis">generic emoji reaction animations</a>.</li>
<li><ahref="/constructor/inputStickerSetEmojiDefaultStatuses">inputStickerSetEmojiDefaultStatuses</a> - Standard <ahref="/api/emoji-status">emoji status</a> stickerset.</li>
</ul>
</li>
<li><code>hash</code> - Initially 0, afterwards should contain the <code>hash</code> field from the returned <ahref="/constructor/stickerSet">stickerSet</a>.</li>
</ul>
<p>The method will return a <ahref="/constructor/messages.stickerSetNotModified">messages.stickerSetNotModified</a> if a non-zero <code>hash</code> is provided and the stickerset wasn't modified since the last time we fetched it.<br>
Otherwise, a <ahref="/constructor/messages.stickerSet">messages.stickerSet</a> will be returned, containing:</p>
<ul>
<li>A <ahref="/constructor/stickerSet">stickerSet</a> constructor with info about the stickerset</li>
<li>A vector of <ahref="/constructor/document">document</a> constructors, containing all the stickers.<br>
Note that even if we provided an old <code>hash</code> and just a few stickers were modified/reordered, all stickers will be returned anyway. </li>
<li>A vector of <ahref="/constructor/stickerPack">stickerPack</a> constructors, containing all the stickers IDs in the stickerpack, grouped by emoji.<br>
The main emoji to use when previewing stickers in the chat list is present in the <code>alt</code> field of the <ahref="/constructor/document">document</a>.<br>
This field is actually used to allow associating more than one emoji to a sticker: this means that the same document ID may be present in multiple <ahref="/constructor/stickerPack">stickerPacks</a>.</li>
<p>Certain parts of the API may return partial <ahref="/type/StickerSetCovered">StickerSetCovered</a> constructors instead of full <ahref="/constructor/document">document</a> constructors for every sticker in the set:</p>
<ul>
<li><ahref="/constructor/stickerSetCovered">stickerSetCovered</a> - Contains generic info about a stickerset and one preview sticker: use <ahref="/method/messages.getStickerSet">messages.getStickerSet</a> to fetch all the stickers in the stickerset.</li>
<li><ahref="/constructor/stickerSetMultiCovered">stickerSetMultiCovered</a> - Contains generic info about a stickerset and multiple preview stickers: use <ahref="/method/messages.getStickerSet">messages.getStickerSet</a> to fetch all the stickers in the stickerset.</li>
<li><ahref="/constructor/stickerSetFullCovered">stickerSetFullCovered</a> - Contains generic info about a stickerset and all stickers in the set (not just a preview): currently only used for <ahref="/api/custom-emoji">custom emoji stickersets</a>, to avoid a further call to <ahref="/method/messages.getStickerSet">messages.getStickerSet</a>.</li>
</ul>
<p>Also, like all files, sticker <ahref="/constructor/document">documents</a> have a set of previews that should be handled as described <ahref="/api/files#image-thumbnail-types">here »</a>.</p>
<p>A <ahref="#stickersets">stickerset</a> can be installed using <ahref="/method/messages.installStickerSet">messages.installStickerSet</a>, <code>archived=false</code>, with possible return values: </p>
<ul>
<li><ahref="/constructor/messages.stickerSetInstallResultSuccess">messages.stickerSetInstallResultSuccess</a> - The stickerset was successfully installed</li>
<li><ahref="/constructor/messages.stickerSetInstallResultArchive">messages.stickerSetInstallResultArchive</a> - The stickerset was successfully installed, displacing some older unused stickersets specified in the <code>sets</code> field by <ahref="#archived-stickersets">archiving them</a>. </li>
</ul>
<p>Use <ahref="/method/messages.uninstallStickerSet">messages.uninstallStickerSet</a> or <ahref="/method/messages.toggleStickerSets">messages.toggleStickerSets</a> with the <code>uninstall</code> flag to uninstall one or more stickersets. </p>
<p>An <ahref="/constructor/updateNewStickerSet">updateNewStickerSet</a> update will be emitted to the other logged-in sessions when installing stickersets. </p>
<p>An <ahref="/constructor/updateStickerSets">updateStickerSets</a> update will be emitted to the other logged-in sessions when uninstalling or archiving stickersets.<br>
This update should trigger a call to the following methods: </p>
<ul>
<li>If <code>masks</code> is set, call <ahref="/method/messages.getMaskStickers">messages.getMaskStickers</a>. </li>
<li>If <code>emoji</code> is set, call <ahref="/method/messages.getEmojiStickers">messages.getEmojiStickers</a>. </li>
<li>Otherwise, call <ahref="/method/messages.getAllStickers">messages.getAllStickers</a> and <ahref="/method/messages.getArchivedStickers">messages.getArchivedStickers</a>.</li>
</ul>
<p>Use <ahref="/method/messages.reorderStickerSets">messages.reorderStickerSets</a> to reorder installed stickersets by the <ahref="/constructor/stickerSet">stickerSet</a> ID: notice that normal, <ahref="#mask-stickers">mask</a> and <ahref="/api/custom-emoji">custom emoji</a> stickersets are ordered independently, use the appropriate flags to sort the correct type of stickerset.</p>
<p>An <ahref="/constructor/updateStickerSetsOrder">updateStickerSetsOrder</a> update will be emitted to the other logged-in sessions when reordering stickersets.<br>
This update should trigger a call to <ahref="/method/messages.getAllStickers">messages.getAllStickers</a>, <ahref="/method/messages.getArchivedStickers">messages.getArchivedStickers</a>, <ahref="/method/messages.getEmojiStickers">messages.getEmojiStickers</a>. </p>
<p>Use <ahref="/method/messages.getAllStickers">messages.getAllStickers</a> to fetch all installed and non-archived stickersets.<br>
Use <ahref="/method/messages.getEmojiStickers">messages.getEmojiStickers</a> to fetch all installed and non-archived <ahref="/api/custom-emoji">custom emoji</a> stickersets. </p>
<p>Bots and users can create stickersets by using the following methods.<br>
Users can also create stickersets by interacting with the official <ahref="https://t.me/stickers">@stickers</a> bot. </p>
<p>Note that unofficial bots <strong>must</strong> append a <code>"_by_<bot_username>"</code> prefix to the stickerset short name when creating stickersets.
Also note that users can't directly modify stickersets created using <ahref="/method/stickers.createStickerSet">stickers.createStickerSet</a>, and must use the <ahref="https://t.me/stickers">@stickers</a> bot, instead: only the sticker creation+shortname methods are available directly to users to allow <ahref="/import-stickers">importing stickers using the stickers SDK</a>. </p>
<p>Use <ahref="/method/messages.uploadMedia">messages.uploadMedia</a> to upload stickers and thumbnails, if you don't already have access to a previously uploaded <ahref="/constructor/document">document</a>. </p>
<p>Use <ahref="/method/stickers.checkShortName">stickers.checkShortName</a> to check if a given short name is available, and <ahref="/method/stickers.suggestShortName">stickers.suggestShortName</a> to let the server suggest a short name, given the stickerset title.</p>
<p>Use <ahref="/method/stickers.createStickerSet">stickers.createStickerSet</a> to create normal, <ahref="#animated-stickers">animated</a>, <ahref="#video-stickers">video</a> or <ahref="#mask-stickers">mask</a> stickersets.<br>
<ahref="/api/custom-emoji">Custom emoji</a> stickersets can only be created using the <ahref="https://t.me/stickers">@stickers</a> bot for now. </p>
<p>Use <ahref="/method/stickers.addStickerToSet">stickers.addStickerToSet</a> to add stickers to the stickerset.<br>
Use <ahref="/method/stickers.addStickerToSet">stickers.setStickerSetThumb</a> to edit the stickerset thumbnail after creation.<br>
Use <ahref="/method/stickers.removeStickerFromSet">stickers.removeStickerFromSet</a> to remove stickers from a stickerset, and <ahref="/method/stickers.changeStickerPosition">stickers.changeStickerPosition</a> to move stickers in a stickerset (simply providing the sticker document is enough). </p>
<p>You can use <ahref="/method/messages.searchStickerSets">messages.searchStickerSets</a> to search globally available stickersets by name: note that this method returns a set of <ahref="#stickerset-previews">stickerset previews »</a>.</p>
<p>Telegram showcases a set of featured stickersets: they can be fetched using <ahref="/method/messages.getFeaturedStickers">messages.getFeaturedStickers</a> or <ahref="/method/messages.getFeaturedEmojiStickers">messages.getFeaturedEmojiStickers</a>, for <ahref="/api/custom-emoji">custom emojis</a>. </p>
<p>Clients should preload featured stickers on startup according to the value of the <code>preload_featured_stickers</code><ahref="/constructor/config">configuration parameter</a>. </p>
<p>The method also returns a set of unread <ahref="/constructor/stickerSet">stickerSet</a> IDs in the <code>unread</code> field: use <ahref="/method/messages.readFeaturedStickers">messages.readFeaturedStickers</a> to mark them as read: note that this will only affect the <code>unread</code> field, all stickersets will still be returned, unless you also <ahref="/api/offsets#hash-generation">generate a <code>hash</code></a>.<br>
This method will also emit an <ahref="/constructor/updateReadFeaturedStickers">updateReadFeaturedStickers</a> or <ahref="/constructor/updateReadFeaturedEmojiStickers">updateReadFeaturedEmojiStickers</a> update on all other logged-in sessions. </p>
<p><ahref="/method/messages.getOldFeaturedStickers">messages.getOldFeaturedStickers</a> can be used to fetch an extended list with even more featured stickersets, that were previously featured in the short list returned by <ahref="/method/messages.getFeaturedStickers">messages.getFeaturedStickers</a>. </p>
<p>A stickerset can be faved or unfaved using <ahref="/method/messages.faveSticker">messages.faveSticker</a>.</p>
<p>Favorited stickers can be fetched using <ahref="/method/messages.getFavedStickers">messages.getFavedStickers</a>: note that this method returns a set of <ahref="#stickerset-previews">stickerset previews »</a>.</p>
<p>Users can fave only a certain number of stickersets, as specified by the following <ahref="/api/config#client-configuration">configuration</a> parameters:</p>
<ul>
<li>Premium users can fave a total of <ahref="/api/config#stickers-faved-limit-premium"><code>stickers_faved_limit_premium</code> stickersets</a>. </li>
<li>Non-Premium users can fave a total of <ahref="/api/config#stickers-faved-limit-default"><code>stickers_faved_limit_default</code> stickersets</a>. </li>
</ul>
<p>An <ahref="/constructor/updateFavedStickers">updateFavedStickers</a> update will be emitted to the other logged-in sessions when faving or unfaving stickersets.<br>
This update should trigger a call to <ahref="/method/messages.getFavedStickers">messages.getFavedStickers</a>. </p>
<p>One or more stickersets can be archived (or unarchived) using <ahref="/method/messages.installStickerSet">messages.installStickerSet</a> with <code>archived=true|false</code>, or <ahref="/method/messages.toggleStickerSets">messages.toggleStickerSets</a> with either the <code>archive</code> or <code>unarchive</code> flag. </p>
<p>An unused stickerset may also be automatically archived when <ahref="#installing-stickersets">installing new stickersets</a>.</p>
<p>Archived stickers are not returned by <ahref="/method/messages.getAllStickers">messages.getAllStickers</a> and can only be fetched using <ahref="/method/messages.getArchivedStickers">messages.getArchivedStickers</a>: note that this method returns a set of <ahref="#stickerset-previews">stickerset previews »</a>.</p>
<p>An <ahref="/constructor/updateStickerSets">updateStickerSets</a> update will be emitted to the other logged-in sessions when archiving or unarchiving stickersets.<br>
This update should trigger a call to <ahref="/method/messages.getArchivedStickers">messages.getArchivedStickers</a>. </p>
<p>After using a sticker in a message, clients should invoke <ahref="/method/messages.saveRecentSticker">messages.saveRecentSticker</a> (normal and <ahref="#mask-stickers">mask</a> stickers only, mask stickers should set the <code>attached</code> flag). </p>
<p>A sticker can be then removed from the recent stickers list using <ahref="/method/messages.saveRecentSticker">messages.saveRecentSticker</a> with <code>unsave=true</code>; the entire list can be cleared using <ahref="/method/messages.clearRecentStickers">messages.clearRecentStickers</a>. </p>
<p>Use <ahref="/method/messages.getRecentStickers">messages.getRecentStickers</a> to fetch the recent stickers list.</p>
<p>Users can add only a certain number of recent stickers, according to the value of the <code>stickers_recent_limit</code><ahref="/constructor/config">configuration parameter</a>. </p>
<p>An <ahref="/constructor/updateRecentStickers">updateRecentStickers</a> update will be emitted to the other logged-in sessions when modifying the recent stickerset list.<br>
This update should trigger a call to <ahref="/method/messages.getRecentStickers">messages.getRecentStickers</a>. </p>
<p>The <code>update_stickersets_order</code> flag should be set when manually choosing and using stickers, <ahref="#mask-stickers">masks</a> and <ahref="/api/custom-emoji">custom emojis</a> from a specific stickerset in the stickerset selection bar (not through suggested or recent stickersets UI views).<br>
Note that for <ahref="/api/custom-emoji">custom emojis</a>, the flag should only be set when manually choosing custom emojis from a single custom emoji stickerset (not multiple custom emoji stickersets). </p>
<p>Setting this flag will trigger an <ahref="/constructor/updateMoveStickerSetToTop">updateMoveStickerSetToTop</a> update (instead of the usual <ahref="/constructor/updateStickerSetsOrder">updateStickerSetsOrder</a>/<ahref="/constructor/updateStickerSetsOrder">updateStickerSets</a> updates), indicating that the installed stickerset list was reordered and the specified stickerset was moved to the top.</p>
<p>Note that the API also offers a separate list of recent <em>stickers</em> (not stickersets), see <ahref="#recent-stickers">here »</a> for more info. </p>
<p>Clients should show a popup with a list of suggested stickers and <ahref="/api/custom-emoji">custom emojis</a> when the user enters an emoji in the text bar. </p>
<p><strong>If</strong> the <ahref="/api/config#stickers-emoji-suggest-only-api"><code>stickers_emoji_suggest_only_api</code> app configuration parameter</a> is set to true, clients must invoke <ahref="/method/messages.getStickers">messages.getStickers</a>/<ahref="/method/messages.searchCustomEmoji">messages.searchCustomEmoji</a> to fetch a list of suggested stickers/<ahref="/api/custom-emoji">custom emojis</a> for the emoji.<br>
The <ahref="/api/config#stickers-emoji-cache-time">stickers_emoji_cache_time appConfig parameter</a> specifies the validity period of the local cache of <ahref="/method/messages.getStickers">messages.getStickers</a>/<ahref="/method/messages.searchCustomEmoji">messages.searchCustomEmoji</a>, also relevant when generating the pagination hash when invoking the method. </p>
<p><strong>Otherwise</strong>, the following local logic should be used. </p>
<li>Construct two lists of recently used stickers, matching the emoji:<ul>
<li>List <strong>a</strong>) Contains all non-Premium stickers.</li>
<li>List <strong>b</strong>) Contains all Premium stickers. </li>
</ul>
</li>
<li>The final suggested sticker list <strong>c</strong> is composed as follows:<ul>
<li>If the user doesn't have a <ahref="/api/premium">Premium subscription</a>: all stickers from <strong>a</strong>, followed by <code>stickers_premium_by_emoji_num</code> stickers from <strong>b</strong>.</li>
<li>If the user has a <ahref="/api/premium">Premium subscription</a>: <code>stickers_normal_by_emoji_per_premium_num</code> stickers from <strong>a</strong>, followed by 1 sticker from <strong>b</strong>, and so on until both lists are empty.</li>
<p>Stickers of all kinds can be attached to photos and videos.<br>
First, overlay the sticker on top of the media file locally (properly handling eventual default <ahref="#mask-stickers">mask coordinates</a>), and <ahref="/api/files">upload</a> the modified media file.<br>
Then, when sending the media file using <ahref="/method/messages.sendMedia">messages.sendMedia</a>, indicate the stickers that were overlaid in the <code>stickers</code> field of <ahref="/constructor/inputMediaUploadedPhoto">inputMediaUploadedPhoto</a> or <ahref="/constructor/inputMediaUploadedPhoto">inputMediaUploadedDocument</a>. </p>
<p>Sent stickered <ahref="/constructor/photo">photos</a> will have the <code>has_stickers</code> flag set.<br>
Sent stickered <ahref="/constructor/document">video documents</a> will have a <ahref="/constructor/documentAttributeHasStickers">documentAttributeHasStickers</a> attribute. </p>
<p>When receiving such a media file, clients should call <ahref="/method/messages.getAttachedStickers">messages.getAttachedStickers</a>, passing the media: the method will return a set of <ahref="#stickerset-previews">stickerset previews »</a>, with info about the stickersets (not stickers) used in the media.</p>
<p>Mask stickers are a special kind of <ahref="#static-stickers">static</a> stickers that are meant to be overlaid on top of photos and attached to media, as specified <ahref="#attached-stickers">here »</a>.</p>
<p>Mask stickers can optionally have associated coordinates, contained in the <ahref="/constructor/maskCoords">maskCoords</a> constructor. </p>
<p>The <code>n</code> position indicates where the mask should be placed:</p>
<ul>
<li>0 => Relative to the forehead</li>
<li>1 => Relative to the eyes</li>
<li>2 => Relative to the mouth</li>
<li>3 => Relative to the chin</li>
</ul>
<p>The <code>x</code>, <code>y</code> and <code>zoom</code> parameters further refine the position relative to the chosen facial feature. </p>
<p>Note that these coordinates are only used to provide a default position when <ahref="#attached-stickers">attaching stickers to media</a>, by locally running facial recognition software and placing the mask sticker at the appropriate coordinates relative to the chosen facial feature.<br>
The final sticker position can be modified by the user before generating a new photo/video with the sticker baked-in.<br>
The final coordinates will not be sent along with the attached media, as they are only used as a suggested default position when placing the sticker. </p>
