<p>Before posting a story, clients should invoke <ahref="/method/stories.canSendStory">stories.canSendStory</a>, to make sure they can send stories to the specified <code>peer</code> (which can be <ahref="/constructor/inputPeerSelf">inputPeerSelf</a> to send the story as a normal user and <ahref="/constructor/inputPeerChannel">inputPeerChannel</a> to send a story as a channel or supergroup). </p>
<p>Use <ahref="/method/stories.getChatsToSend">stories.getChatsToSend</a> to obtain a list of channels/supergroups where the user can post stories; <ahref="/method/stories.canSendStory">stories.canSendStory</a> must still be used before uploading a story to make sure no other limit was reached, as described in the <ahref="/api/stories#posting-stories">main documentation»</a>.
Note that in order to obtain permission to post stories as a channel/supergroup, it must be boosted, first, see <ahref="/api/boost">here»</a> for more info. </p>
<li>If we're trying to send a story as a channel/supergroup:<ul>
<li>The current user is an administrator of the channel/supergroup and has <ahref="/constructor/chatAdminRights"><code>post_stories</code> admin rights</a>; otherwise, a <code>CHAT_ADMIN_REQUIRED</code> error is returned.</li>
<li>AND the channel/supergroup has <ahref="/api/boost">received enough boosts to post the story»</a>; otherwise, a <code>BOOSTS_REQUIRED</code> error is returned.</li>
<li>If we're trying to send a story as the current user:<ul>
<li>The user can post stories according to the <ahref="/api/config#stories-posting"><code>stories_posting</code> client configuration parameter</a>; otherwise, a <code>PREMIUM_ACCOUNT_REQUIRED</code> error is returned.</li>
<li>AND The user hasn't hit the maximum active stories limit specified by the <ahref="/api/config#story-expiring-limit-default"><code>story_expiring_limit_*</code> client configuration parameters</a>; otherwise a <code>STORIES_TOO_MUCH</code> error is returned, indicating that the user should buy a <ahref="/api/premium">Premium</a> subscription, delete an active story, or wait for the oldest story to expire.</li>
<li>AND The user hasn't hit the weekly story limit specified by the <ahref="/api/config#stories-sent-weekly-limit-default"><code>stories_sent_weekly_limit_*</code> client configuration parameters</a>; otherwise, a <code>STORY_SEND_FLOOD_WEEKLY_%d</code> error is returned, indicating the number of seconds to wait before posting a new story.</li>
<li>AND The user hasn't hit the monthly story limit specified by the <ahref="/api/config#stories-sent-monthly-limit-default"><code>stories_sent_monthly_limit_*</code> client configuration parameters</a>; otherwise, a <code>STORY_SEND_FLOOD_MONTHLY_%d</code> error is returned, indicating the number of seconds to wait before posting a new story.</li>
</ul>
</li>
</ul>
<p>After checking if a story can be posted, the client may invoke <ahref="/method/stories.sendStory">stories.sendStory</a> to upload the story.<br>
Note that if any of the conditions changes in the period between the call to <ahref="/method/stories.canSendStory">stories.canSendStory</a> and <ahref="/method/stories.sendStory">stories.sendStory</a> (for example, the user uploads a story from another client, reaching the weekly limit), the same errors listed above for <ahref="/method/stories.canSendStory">stories.canSendStory</a> will be emitted by <ahref="/method/stories.sendStory">stories.sendStory</a>. </p>
<p>The parameters of <ahref="/method/stories.sendStory">stories.sendStory</a> are fully described on the <ahref="/method/stories.sendStory">method page»</a>, here are some of the most important ones:</p>
<li><code>media</code>: The story media (a vertical photo or a vertical video, max 30 MB).</li>
<li><code>media_areas</code>: <ahref="/api/stories#media-areas">Media areas</a> associated to the story, see <ahref="/api/stories#media-areas">here»</a> for more info.</li>
<li><code>privacy_rules</code>: A set of <ahref="/api/privacy#privacy-rules">privacy rules»</a> for the story as an array of <ahref="/type/InputPrivacyRule">InputPrivacyRule</a> constructors, indicating who can or can't view the story.</li>
<li><code>expire</code>: Period after which the story is moved to <ahref="#pinned-or-archived-stories">archive</a> (and <ahref="#pinned-or-archived-stories">to the profile</a> if <code>pinned</code> is set), in seconds; must be one of <code>6 * 3600</code>, <code>12 * 3600</code>, <code>86400</code>, or <code>2 * 86400</code> for Telegram Premium users, and <code>86400</code> otherwise.</li>
<li><code>pinned</code>: Whether to also <ahref="#pinned-or-archived-stories">add the story to the profile</a> automatically upon expiration. If not set, the story will only be added to the <ahref="#pinned-or-archived-stories">archive</a>. </li>
<li><code>caption</code> and <code>entities</code>: The story caption, and related <ahref="/api/entities">styled text entities</a>; note that the story caption length is limited by the <ahref="/api/config#story-caption-length-limit-default"><code>story_caption_length_limit_*</code> »</a> config keys, and story entities should only be sent and displayed according to the value of the <ahref="/api/config#stories-entities">stories_entities»</a> config key.</li>
<p>Once a story is successfully uploaded, an <ahref="/constructor/updateStoryID">updateStoryID</a> will be returned, indicating the story ID (<code>id</code>) that was attributed to the story (like for messages, <code>random_id</code> indicates the <code>random_id</code> that was passed to <ahref="/method/stories.sendStory">stories.sendStory</a>: this way, you can tell which story was assigned a specific <code>id</code> by checking which <ahref="/method/stories.sendStory">stories.sendStory</a> call has the returned <code>random_id</code>). </p>
<p>Also, posting a story will emit an <ahref="/constructor/updateStory">updateStory</a> both for us, and for our subscribers/contacts (even if they have <ahref="#hiding-stories-of-other-users">hidden</a> our stories). </p>
<p>Additionally, a message containing a <ahref="/constructor/messageMediaStory">messageMediaStory</a> with the <code>via_mention</code> flag coming from the story poster will also be generated automatically if the poster mentions us in the story's caption. </p>
<p><strong>Note</strong>: <ahref="/api/files#editing-uploaded-files">usually</a>, when editing just the <ahref="/type/DocumentAttribute">DocumentAttribute</a>s of files (like the file name through <ahref="/constructor/documentAttributeFilename">documentAttributeFilename</a>, the timestamp of a video thumbnail through <ahref="/constructor/documentAttributeVideo">documentAttributeVideo</a>.<code>preload_prefix_size</code>, etc) without editing the media itself, a full download+reupload of the underlying media is required, as the attributes are baked into the media and cannot be modified through <ahref="/constructor/inputMediaDocument">inputMediaDocument</a> (unlike some other attributes like <code>spoiler</code>, which may be edited without a reupload, simply by passing the old media in <ahref="/constructor/inputMediaDocument">inputMediaDocument</a>.<code>id</code> and tweaking the appropriate flags of <ahref="/constructor/inputMediaDocument">inputMediaDocument</a>). </p>
<p>However, a full download+reupload can be avoided <strong>just for video stories</strong>, when editing only the <ahref="/constructor/documentAttributeVideo">documentAttributeVideo</a>.<code>video_start_ts</code> attribute: in this case, <ahref="/constructor/inputMediaUploadedDocument">inputMediaUploadedDocument</a> should be used, passing to <code>file</code> an <ahref="/constructor/inputFileStoryDocument">inputFileStoryDocument</a> with the old story media instead of the re-uploaded <ahref="/constructor/inputFile">inputFile</a>, and populating the remaining fields and attributes with exactly the same values used previously, except for the <ahref="/constructor/documentAttributeVideo">documentAttributeVideo</a>.<code>video_start_ts</code> attribute, which should contain the new value. </p>
<h4><aclass="anchor"href="#pinned-or-archived-stories"id="pinned-or-archived-stories"name="pinned-or-archived-stories"><iclass="anchor-icon"></i></a>Pinned or archived stories</h4>
<p>After an active story expires, it is automatically added to the story archive: stories in the story archive are only visible to the poster, or to channel/supergroup admins with <ahref="/constructor/chatAdminRights"><code>edit_stories</code> admin rights</a> rights. </p>
<p>Use <ahref="/method/stories.getStoriesArchive">stories.getStoriesArchive</a> to fetch stories in the story archive. </p>
<p>Archived stories may then be pinned on the profile, where they may be fetched using <ahref="/method/stories.getPinnedStories">stories.getPinnedStories</a> by users who explicitly open your profile: use <ahref="/method/stories.togglePinned">stories.togglePinned</a> to pin or unpin one or more stories to your profile. </p>
<p>Stories may also be autopinned upon expiration if the <code>pinned</code> flag is set <ahref="#posting-stories">when posting them</a>. </p>
<p>Additionally, stories pinned to a profile may <strong>also</strong> be pinned <strong>to the top of the profile</strong> using <ahref="/method/stories.togglePinnedToTop">stories.togglePinnedToTop</a>; stories that are pinned to the top of the profile (max <ahref="/api/config#stories-pinned-to-top-count-max">stories_pinned_to_top_count_max</a>) should be displayed first when opening the profile.<br>
Stories pinned to the top of the profile will be returned first when invoking <ahref="/method/stories.getPinnedStories">stories.getPinnedStories</a> with <code>offset_id=0</code>, and their IDs will also be contained in <ahref="/constructor/stories.stories">stories.stories</a>.<code>pinned_to_top</code>. </p>
<p>Use the <ahref="/method/stories.deleteStories">stories.deleteStories</a> method to delete one or more active, pinned or archived stories by their IDs, passed in <code>id</code>. </p>
<h4><aclass="anchor"href="#preventing-users-from-seeing-your-stories"id="preventing-users-from-seeing-your-stories"name="preventing-users-from-seeing-your-stories"><iclass="anchor-icon"></i></a>Preventing users from seeing your stories</h4>
<p>Active stories of contacts, subscribed channels/supergroups and the <ahref="/api/config#stories-changelog-user-id">changelog user</a> should be shown in the action bar of the homescreen.<br>
Use <ahref="/method/stories.getAllStories">stories.getAllStories</a> to fetch the full list of active stories. </p>
<p>Optionally, the <code>hidden</code> flag can be set to fetch the <ahref="#hiding-stories-of-other-users">hidden stories to be shown in the archived tab</a>, instead of the main story list. </p>
<p>Pagination using this method is a bit different from usual: a <code>state</code> string is used to maintain the pagination state. </p>
<ul>
<li>Initially, neither the <code>next</code> or <code>state</code> flags should be set: upon completion of the RPC call, a new <code>state</code> string is returned and should be stored locally, associated either to the main or hidden story list (depending on the value of <code>hidden</code> we passed); pass the locally stored <code>state</code> to all future calls of the method. </li>
<li>If more stories are available, the returned <ahref="/constructor/stories.allStories">stories.allStories</a>.<code>has_more</code> flag will be set: in this case, the client should re-call the method with the newly returned <code>state</code><strong>and</strong> the <code>next</code> flag set to fetch a new <code>state</code> and the remaining stories from the chosen story list; the process should be repeated until no more stories are available (<code>has_more</code> will <strong>not</strong> be set). </li>
</ul>
<p>Once the full story list is fetched, <ahref="/constructor/stories.allStories">stories.allStories</a> can be called with the stored <code>state</code><strong>without</strong> setting the <code>next</code> flag to check for updates in an active story list: if no changes have occurred since our last call, <ahref="/constructor/stories.allStoriesNotModified">stories.allStoriesNotModified</a> is returned, otherwise <ahref="/constructor/stories.allStories">stories.allStories</a> is returned (possibly requiring further pagination as described above).<br>
Note that a change is currently only defined as an addition or removal (i.e. by moving it to the hidden list or vice versa) of a peer to/from a story list, not as a new story being posted; those changes are received as simple <ahref="/constructor/updateStory">updateStory</a> updates. </p>
<p>Changes to the active stories list are contained in the <ahref="/constructor/stories.allStories">stories.allStories</a>.<code>peer_stories</code> field: this field contains a vector of <ahref="/constructor/peerStories">peerStories</a> constructors, one for each peer, containing the peer ID, the ID of the maximum read story (if any), and a list of <ahref="/type/StoryItem">StoryItem</a> constructors of type:</p>
<ul>
<li><ahref="/constructor/storyItem">storyItem</a> - Represents an active story</li>
<li><ahref="/constructor/storyItemSkipped">storyItemSkipped</a> - Represents an active story, whose full information was omitted for space and performance reasons; use <ahref="/method/stories.getStoriesByID">stories.getStoriesByID</a> to fetch full info about the skipped story/stories when and if needed.</li>
<li><ahref="/constructor/storyItemDeleted">storyItemDeleted</a> - Represents a previously active story, that was now deleted</li>
</ul>
<p>Use <ahref="/method/stories.getPeerStories">stories.getPeerStories</a> may also be used to fetch the full active story list of a specific peer. </p>
<p>Use <ahref="/method/stories.readStories">stories.readStories</a> to mark all stories up to a certain ID as read, for a given peer: using this method will emit an <ahref="/constructor/updateReadStories">updateReadStories</a> update to all logged-in sessions if a newer ID is marked as read.<br>
Use <ahref="/method/stories.getAllReadPeerStories">stories.getAllReadPeerStories</a> to obtain the latest read story ID for all peers when first logging in, returned as a list of <ahref="/constructor/updateReadStories">updateReadStories</a> updates: further calls to this method are not needed after login, as updates to the latest read story ID will be sent using <ahref="/constructor/updateReadStories">updateReadStories</a> updates, with the usual <ahref="/api/updates">update delivering methods</a>. </p>
<p>Use <ahref="/method/stories.incrementStoryViews">stories.incrementStoryViews</a> to actually increment the view counter of stories the user has seen (pass max 200 story IDs at a time). </p>
<h4><aclass="anchor"href="#hiding-stories-of-other-users"id="hiding-stories-of-other-users"name="hiding-stories-of-other-users"><iclass="anchor-icon"></i></a>Hiding stories of other users</h4>
<p>Use <ahref="/method/stories.toggleAllStoriesHidden">stories.togglePeerStoriesHidden</a> to hide the active stories of a specific peer, preventing them from being displayed on the action bar on the homescreen.<br>
When the stories of a user are marked as hidden, the <code>stories_hidden</code> flag is set on the related <ahref="/constructor/user">user</a> constructor, and they should only be visible on the action bar when opening the <ahref="/api/folders#peer-folders">archive folder</a>, by setting the <code>hidden</code> flag when calling <ahref="/method/stories.getAllStories">stories.getAllStories</a>, see <ahref="#watching-stories">here</a> for more info. </p>
<p>Note that the <ahref="/api/folders#peer-folders">archive folder is the peer folder used for archived chats</a>: hidden stories are displayed there purely due to a UI implementation detail, not because they're actually added to the <ahref="/api/folders#peer-folders">archive peer folder»</a> or the <ahref="#pinned-or-archived-stories">story archive»</a>, which are different things. </p>
<p>Stories can be shared as messages to any chat by simply using <ahref="/method/messages.sendMedia">messages.sendMedia</a>, passing an <ahref="/constructor/inputMediaStory">inputMediaStory</a> referencing the shared story. </p>
<p>The story will be shared as a <ahref="/constructor/messageMediaStory">messageMediaStory</a>, and should be displayed as a message forwarded from the poster of the story (even though <ahref="/method/messages.forwardMessages">messages.forwardMessages</a> was not used an the <code>fwd_from</code> field of the <ahref="/constructor/message">message</a><strong>won't</strong> be set). </p>
<p>A message containing a <ahref="/constructor/messageMediaStory">messageMediaStory</a> with the <code>via_mention</code> flag coming from the story poster will also be generated automatically if the poster mentions us in the story's caption. </p>
<h3><aclass="anchor"href="#fetching-the-interaction-list"id="fetching-the-interaction-list"name="fetching-the-interaction-list"><iclass="anchor-icon"></i></a>Fetching the interaction list</h3>
<p>Use <ahref="/method/stories.getStoryViewsList">stories.getStoryViewsList</a> to obtain the full list of users that have interacted with a specific story we posted as a user, returned as a list of <ahref="/type/StoryView">StoryView</a> constructors; pass the returned <code>next_offset</code> (if present) to <code>offset</code> to paginate through the results; the full list is available at all times only to <ahref="/api/premium">Premium</a> users, and will be deleted on stories posted by non-<ahref="/api/premium">Premium</a> users <ahref="/api/config#story-viewers-expire-period">story_viewers_expire_period»</a> seconds after the story expires; if it's still viewable, the <code>has_viewers</code> flag will be set. </p>
<p>The above method can only be used for stories posted by users, to fetch almost the exact same information for stories posted by channels/supergroups, use <ahref="/method/stories.getStoryReactionsList">stories.getStoryReactionsList</a>: the data returned by both methods is actually almost exactly the same, the only difference is that:</p>
<li><ahref="/method/stories.getStoryViewsList">stories.getStoryViewsList</a> can only be used for stories posted by the current user and also contains view and <ahref="/api/block">blocklist</a> information. </li>
<li><ahref="/method/stories.getStoryReactionsList">stories.getStoryReactionsList</a> can only be used for stories posted by channels/supergroups we're an admin of and does not contain view information</li>
<li>Story forwards as a message to a public chat/channel: <ahref="/constructor/storyViewPublicForward">storyViewPublicForward</a>/<ahref="/constructor/storyReactionPublicForward">storyReactionPublicForward</a></li>
<li>Story reposts (as a story to a public channel/supergroup/user): <ahref="/constructor/storyViewPublicRepost">storyViewPublicRepost</a>/<ahref="/constructor/storyReactionPublicRepost">storyReactionPublicRepost</a></li>
<p>Additionally, <ahref="/method/stories.getStoriesViews">stories.getStoriesViews</a> can be used to obtain info about the view count, forward count, reactions and recent viewers list of one or more stories, using a single, unpaginated method call, obviously potentially returning less info than <ahref="/method/stories.getStoryViewsList">stories.getStoryViewsList</a>. </p>
<h3><aclass="anchor"href="#replying-to-stories"id="replying-to-stories"name="replying-to-stories"><iclass="anchor-icon"></i></a>Replying to stories</h3>
<p>You may reply to stories posted by users and supergroups by using <ahref="/method/messages.sendMessage">messages.sendMessage</a>, <ahref="/method/messages.sendMedia">messages.sendMedia</a> or any other method used to send messages, passing an <ahref="/constructor/inputReplyToStory">inputReplyToStory</a> to <code>reply_to</code>, with the ID of the user that posted the story (which must also be the destination <code>peer</code> of the message) and the story ID. </p>
<p>Stories may be reposted by using <ahref="/method/stories.sendStory">stories.sendStory</a>, populating the <code>fwd_from_story</code> field with the original story ID and the <code>fwd_from_id</code> with the peer that posted the original story. </p>
<p>The user may modify the story (for example by overlaying a round video reaction on top of the media); either way, the modified or the original media must be passed to the <code>media</code> field as usual, and the <code>fwd_modified</code> flag must be set if the media was modified. </p>
<p>Reposted stories will have the <ahref="/constructor/storyItem">storyItem</a> set and populated with a <ahref="/constructor/storyFwdHeader">storyFwdHeader</a> constructor, containing info about the original story.</p>
<p><ahref="/method/stories.searchPosts">stories.searchPosts</a> may be used to globally search for stories from all users (even non-contacts and other peers we've never seen before) using either a hashtag passed to <code>hashtag</code> (without the <code>#</code>) or a <ahref="#location-tags">location tag</a> passed to <code>area</code>. </p>
<p>Global search should be automatically triggered when clicking on a hashtag in the description of a story, or when clicking on a <ahref="#location-tags">location tag</a> (results displayed under the map). </p>
<p>Note <ahref="/constructor/mediaAreaGeoPoint">mediaAreaGeoPoint</a> areas may be searched only if they have an associated <code>address</code>. </p>
<p>Either <code>hashtag</code> or <code>area</code> must always be set when invoking the method, <code>offset</code> must initially be an empty string.<br>
Paginate the results by re-calling the method, passing to <code>offset</code> the <ahref="/constructor/stories.foundStories">stories.foundStories</a>.<code>next_offset</code> field returned by the previous call. </p>
<p>Use <ahref="/method/stories.exportStoryLink">stories.exportStoryLink</a> to generate a <ahref="/api/links#story-links">story deep link</a> for a specific story. </p>
<p>Stories can have so-called "media areas": clickable rectangular areas with animated overlays on top of the story offering functionality like location tags or reactions. </p>
<p>The coordinates and size of each media area is specified in a <ahref="/constructor/mediaAreaCoordinates">mediaAreaCoordinates</a> constructor attached to each <ahref="/type/MediaArea">MediaArea</a>, see <ahref="/constructor/mediaAreaCoordinates">the constructor page»</a> for more info. </p>
<p>After construction, the vector of <ahref="/type/MediaArea">MediaArea</a> constructors can be passed to <ahref="/method/stories.sendStory">stories.sendStory</a> or <ahref="/method/stories.editStory">stories.editStory</a>.</p>
<p>Messages from channels can be reposted to stories using <ahref="/constructor/inputMediaAreaChannelPost">inputMediaAreaChannelPost</a>/<ahref="/constructor/mediaAreaChannelPost">mediaAreaChannelPost</a>.</p>
<p>Clients should fetch and display a copy of the channel post on top of the story according to the <ahref="#media-areas">media area</a><code>coordinates</code>: clicking on the media area should open the linked post.</p>
<p>Location tags are represented by a <ahref="/constructor/mediaAreaVenue">mediaAreaVenue</a> or <ahref="/constructor/mediaAreaGeoPoint">mediaAreaGeoPoint</a>, associated to a location sticker on top of the story media with an associated <ahref="#media-areas">clickable media area</a>. </p>
<p>Both constructors have an associated geolocation represented as a <ahref="/constructor/geoPoint">geoPoint</a>, and information about the clickable media area on top of the story media as a <ahref="/constructor/mediaAreaCoordinates">mediaAreaCoordinates</a> constructor. </p>
<p><ahref="/constructor/mediaAreaGeoPoint">mediaAreaGeoPoint</a> is used to represent a simple geolocation with an <em>optional</em> textual address.<br>
<ahref="/constructor/mediaAreaVenue">mediaAreaVenue</a> is used to represent the location of a specific venue (i.e. a mall, a shop, a dance school et cetera), and apart from the venue's coordinates, it also contains a textual representation of the address, the venue name (<code>title</code>) and a venue type/ID (<code>venue_id</code>/<code>venue_type</code>) in a format supported by the venue provider specified in <code>provider</code>. </p>
<p>Currently, the only provider that needs to be supported is <code>foursquare</code>. </p>
<p>To send a <ahref="/constructor/mediaAreaVenue">mediaAreaVenue</a>, clients should use <ahref="/constructor/inputMediaAreaVenue">inputMediaAreaVenue</a>, constructed as follows:</p>
<li>If the user gives permission to share their location with the location provider, query the inline bot specified in the <ahref="/api/config#stories-venue-search-username"><code>stories_venue_search_username</code> client configuration parameter»</a>, as described as the <ahref="/api/bots/inline">inline queries documentation»</a>, populating the <code>geo_point</code>.<br>
Note that this should be done transparently in a map UI, not in the usual inline query UI in the chat text bar. </li>
<li>The results returned by the bot, containing a list of venues close to the specified <code>geo_point</code>, should be listed in the lower section of the map UI: upon selection, construct the <ahref="/constructor/inputMediaAreaVenue">inputMediaAreaVenue</a> with:<ul>
<li><code>query_id</code>: the <code>query_id</code> from <ahref="/constructor/messages.botResults">messages.botResults</a>.</li>
<li><code>result_id</code>: the <code>id</code> of the chosen result.</li>
</ul>
</li>
</ul>
<p>Clients may only re-use existing <ahref="/constructor/mediaAreaVenue">mediaAreaVenue</a>s when repositioning a pre-existing location tag when editing a story; use <ahref="/constructor/inputMediaAreaVenue">inputMediaAreaVenue</a> when posting a new story or adding a new location tag to an existing story.</p>
<p><ahref="#searching-stories">Global story search»</a> should be automatically triggered when clicking on a location, passing the <ahref="/constructor/mediaAreaGeoPoint">mediaAreaGeoPoint</a>/<ahref="/constructor/mediaAreaVenue">mediaAreaVenue</a> to <ahref="/method/stories.searchPosts">stories.searchPosts</a>, with results displayed under the map. </p>
<p>Note <ahref="/constructor/mediaAreaGeoPoint">mediaAreaGeoPoint</a> areas may be searched only if they have an associated <code>address</code>. </p>
<p>Story <ahref="/api/reactions">reactions</a> are implemented using a simple in-UI button that allows the user to send any reaction using <ahref="/method/stories.sendReaction">stories.sendReaction</a>. </p>
<p>Sending this method will return an <ahref="/constructor/updateSentStoryReaction">updateSentStoryReaction</a> update to all logged-in sessions.<br>
The story poster will also receive an <ahref="/constructor/updateNewStoryReaction">updateNewStoryReaction</a> update when a user reacts to their story, if enabled as specified <ahref="/api/reactions#notifications-about-reactions">here»</a>. </p>
<p>However, the poster of a story may also use <ahref="/constructor/mediaAreaSuggestedReaction">mediaAreaSuggestedReaction</a><ahref="#media-areas">media areas»</a> to suggest some specific reactions as simple clickable buttons: they're rendered as a round comic-style thought bubble with its "tail" on the right, white background and the <ahref="/api/reactions">reaction»</a> from the <code>reaction</code> field located in its center.<br>
The maximum number of story reaction media areas that can be added to a story is specified by the <ahref="/api/config#stories-suggested-reactions-limit-default"><code>stories_suggested_reactions_limit_*</code> »</a> config keys.<br>
<p>URL media areas offer stickers that when clicked, should offer the user a prompt (implemented as a tooltip on the sticker) to open the specified <code>url</code>. </p>
<p>The maximum number of URL media areas that can be added to a story is specified by the <ahref="/api/config#stories-area-url-max"><code>stories_area_url_max</code> »</a> config key. </p>
<p>Users can now share the weather in their stories by adding one weather media area represented by <ahref="/constructor/mediaAreaWeather">mediaAreaWeather</a> to their stories. </p>
<p>The weather media area should be rendered using the background ARGB color specified in <code>color</code>, and should contain the emoji specified in <code>emoji</code> (rendered as an <ahref="/api/animated-emojis">animated emoji</a>), followed by the temperature specified in <code>temperature_c</code> (Celsius, which should be converted by the client to Fahrenheit if required by the device's settings), followed by <code>°C</code> or <code>°F</code> depending on the unit used. </p>
<p>To fetch the current temperature and emoji to use when <em>creating</em> a weather media area when posting a story, clients should internally make an <ahref="/api/bots/inline">inline query</a> with <ahref="/method/messages.getInlineBotResults">messages.getInlineBotResults</a> to the <code>bot</code> specified in the <ahref="/api/config#weather-search-username">weather_search_username</a> client configuration parameter, passing the user's current location in <code>geo_point</code> and <ahref="/constructor/inputPeerEmpty">inputPeerEmpty</a> in <code>peer</code>.<br>
This query will return a single <ahref="/constructor/botInlineResult">botInlineResult</a>: the <code>emoji</code> to use will be contained in the <ahref="/constructor/botInlineResult">botInlineResult</a>.<code>title</code> and the temperature (always in Celsius) will be contained in <ahref="/constructor/botInlineResult">botInlineResult</a>.<code>description</code> (it will contain just the value without the unit, so it can be easily casted to a double). </p>
<p>The inline query should be made internally by the client when the user creates a new weather media area, not by showing the usual inline query UI, but by treating the inline query as an API call to fetch the weather for the current user's location. </p>
<p>If the <ahref="/api/config#story-weather-preload">story_weather_preload</a> client configuration parameter is equal to true, clients should preload the weather using the flow specified above on startup (as opposed to only doing it when creating a weather media area). </p>
<p><ahref="/api/premium">Premium users</a> may enable <ahref="https://telegram.org/tour/stories#stealth-mode">stealth mode</a>, erasing their views from any stories they opened in the past <ahref="/api/config#stories-stealth-past-period"><code>stories_stealth_past_period</code> seconds»</a>, and hiding their views on stories for the next <ahref="/api/config#stories-stealth-future-period"><code>stories_stealth_future_period</code> seconds»</a>, as specified by the <ahref="/api/config#client-configuration">client configuration»</a>.</p>
<p>Invoke <ahref="/method/stories.activateStealthMode">stories.activateStealthMode</a> to activate stealth mode, passing the <code>past</code> flag to erase views from any stories opened in the past <ahref="/api/config#stories-stealth-past-period"><code>stories_stealth_past_period</code> seconds»</a> and/or the <code>future</code> flag to hide future story views for the next <ahref="/api/config#stories-stealth-future-period"><code>stories_stealth_future_period</code> seconds»</a>. </p>
<p>Clients can only invoke this method every <ahref="/api/config#stories-stealth-cooldown-period"><code>stories_stealth_cooldown_period</code> seconds</a> as specified by the <ahref="/api/config#client-configuration">client configuration</a>: invoking the method before the cooldown period has expired will trigger a <code>FLOOD_WAIT_X</code> error, with <code>X</code> being the number of seconds left before the cooldown period expires. </p>
<p>An <ahref="/constructor/updateStoriesStealthMode">updateStoriesStealthMode</a> constructor will be returned, containing the following fields:</p>
<ul>
<li><code>active_until_date</code> - the date up to which stealth mode will be active</li>
<li><code>cooldown_until_date</code> - the date starting from which the user will be allowed to call <ahref="/method/stories.activateStealthMode">stories.activateStealthMode</a> again; calling the method earlier will return a <code>FLOOD_WAIT_X</code> error as specified above.</li>
<p>Use <ahref="/method/stats.getStoryStats">stats.getStoryStats</a> to obtain statistics about a story; the returned <ahref="/type/StatsGraph">StatsGraph</a> graphs can be rendered <ahref="/api/stats#graph-visualization">as described here»</a>. </p>
<p>Use <ahref="/method/stats.getStoryPublicForwards">stats.getStoryPublicForwards</a> to obtain forwards of a story as a message to public chats and reposts by public channels.</p></div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
