How to Share Mini App Content to Telegram Stories: Custom Story Canvases, Deep Link Attribution & Viral Loops
Supercharge your mini app's organic acquisition. Discover how the Telegram Web Apps API enables games and tools to generate bespoke visual media and post it directly to user stories—attaching deep-linked referral buttons that convert viewers into active players with a single tap.
How WebApp.shareToStory Operates
A technical breakdown of the Telegram Web Apps JS SDK method that coordinates story canvas generation.
// Triggering story share from inside a WebApp / Mini App
Telegram.WebApp.shareToStory(
"https://cdn.yourapp.com/stories/user_achievement_9281.jpg",
{
text: "I just reached Level 50 in Cyber Quest! Can you beat my score?",
widget_link: {
url: "https://t.me/CyberQuestBot?startapp=ref_user9281",
name: "Play Cyber Quest"
}
}
);
// Under the hood: Client native bridge event
window.TelegramWebviewProxy.postEvent("web_app_share_to_story", JSON.stringify({
media_url: "https://cdn.yourapp.com/stories/user_achievement_9281.jpg",
text: "I just reached Level 50...",
widget_link: { ... }
}));
When invoking Telegram.WebApp.shareToStory, the mini app supplies a media asset URL (JPEG/PNG or MP4 video) alongside caption copy and a widget_link descriptor. The Telegram client pre-downloads the media into its native story editor, positions the custom link widget, and opens the preview dialog. The user retains complete creative control to add stickers or text before finalizing the broadcast.
Simulate generating a story achievement card inside a game and previewing how friends interact with the viral deep link.
How to Share Mini App Achievements to Stories
A simple user journey for sharing game moments with your friends.
Mini App Story Sharing FAQ
Answers regarding developer asset constraints, video support, and user security.
startapp=ref123), the bot can credit referral bonuses, Telegram Stars, or in-game gold directly to the inviter's account upon sign-up.
