Telegram Mini App मैस्कॉट: लोडिंग स्क्रीन, थीम और हैप्टिक्स

Charmotion टीम द्वारा · अपडेट: 25 अक्टूबर 2026

गाइड का कवर इलस्ट्रेशन: Telegram Mini App मैस्कॉट: लोडिंग स्क्रीन, थीम और Haptics, Charmotion के डेमो कैरेक्टर के साथ

Telegram की अपनी Mini App लोडिंग स्क्रीन में एक placeholder SVG आइकन और light व dark बैकग्राउंड तथा header colors होते हैं, जो @BotFather में सेट किए जाते हैं। Telegram किसी एनिमेटेड विकल्प का ज़िक्र नहीं करता। एनिमेटेड मैस्कॉट दिखाने के लिए SVG को कैरेक्टर के resting pose के रूप में बनाएँ, Rive फ़ाइल लोड होने पर Telegram.WebApp.ready() कॉल करें, और web app के अंदर मिलते-जुलते रंगों में intro चलाएँ।

मुख्य बातें

लोडिंग स्क्रीन की सेटिंग्स @BotFather में Bot Settings, Configure Mini App के अंदर होती हैं। API एक SVG placeholder और चार रंग सेव करता है।
ready() Telegram का placeholder छिपा देता है। अगर आप इसे कभी कॉल नहीं करते, तो placeholder तब तक दिखता रहता है जब तक पेज पूरी तरह लोड न हो जाए।
BotFather के बैकग्राउंड रंगों को अपने ऐप के बैकग्राउंड जैसा ही रखें, ताकि placeholder से intro पर जाते समय कोई flash न हो।
Telegram की theme से मेल खाने के लिए themeParams, --tg-theme-* CSS variables और themeChanged event का इस्तेमाल करें।
रिएक्शन के साथ HapticFeedback (Bot API 6.1+) जोड़ें: success और error के लिए notificationOccurred, और टैप के लिए हल्का impactOccurred।

पहले से कोई कैरेक्टर या लोगो है? अपने कैरेक्टर को असली ऐप स्क्रीन में देखें: स्प्लैश, ऑनबोर्डिंग, लोडिंग और एम्प्टी स्टेट स्क्रीन। यह फ़्री है, आपके ब्राउज़र में चलता है और कुछ भी अपलोड नहीं होता।

क्या मैं Telegram Mini App की लोडिंग स्क्रीन कस्टमाइज़ कर सकता हूँ?

कुछ हद तक। Telegram के Mini Apps पेज के अनुसार ऐप्स "अपनी लोडिंग स्क्रीन कस्टमाइज़ कर सकते हैं, अपना आइकन और light व dark themes के लिए खास रंग जोड़कर"। इसे @BotFather में /mybots, आपका bot, Bot Settings, Configure Mini App, Enable Mini App के ज़रिए कॉन्फ़िगर किया जाता है। Telegram API documentation बताता है कि botAppSettings object में क्या सेव होता है:

फ़ील्ड	यह क्या है
`placeholder_path`	SVG placeholder लोगो
`background_color`, `background_dark_color`	लोडिंग स्क्रीन बैकग्राउंड, light और dark
`header_color`, `header_dark_color`	Header रंग, light और dark

दोनों में से कोई भी पेज placeholder के एनिमेशन का ज़िक्र नहीं करता, इसलिए इसे स्थिर इमेज ही मानें। लोडिंग स्क्रीन तब खत्म होती है जब आपका कोड ऐसा कहे। Telegram ready() को वह method बताता है जो "Telegram ऐप को सूचित करता है कि Mini App दिखाए जाने के लिए तैयार है", और आगे कहता है: "यह method कॉल होते ही loading placeholder छिप जाता है और Mini App दिखने लगता है। अगर method कॉल नहीं किया गया, तो placeholder तभी छिपेगा जब पेज पूरी तरह लोड हो जाएगा।"

स्थिर placeholder से एनिमेटेड intro पर कैसे जाएँ?

दोनों स्क्रीन को एक जैसा दिखाएँ। जब तक आपका पेज और Rive फ़ाइल लोड होते हैं, placeholder दिखता है। फ़ाइल तैयार होने पर ready() कॉल करें और उसी बैकग्राउंड पर, उसी pose से intro शुरू करें।

लॉन्च का क्रम: OS की स्टैटिक लॉन्च स्क्रीन, फिर ऐप के अंदर launch एनिमेशन, फिर idle — OS एक स्टैटिक लॉन्च स्क्रीन दिखाता है; पहला view स्क्रीन पर आते ही आपका एनिमेशन चलता है।

SVG को resting pose के रूप में बनाएँ (या उसका एक सरल silhouette), बीच में रखें, ताकि intro का पहला फ़्रेम वहीं से शुरू हो जहाँ placeholder खत्म हुआ था।
बिल्कुल एक जैसे रंग इस्तेमाल करें। BotFather के light और dark बैकग्राउंड को उन्हीं रंगों पर सेट करें जो आपका पेज हर theme में अपने बैकग्राउंड के लिए इस्तेमाल करता है।
Rive onLoad में ready() कॉल करें, फिर intro चलाएँ, और फिर interactive कैरेक्टर पर स्विच करें।
Placeholder को स्क्रीन पर बहुत देर तक न रखें। Telegram ready() को "जितनी जल्दी हो सके" कॉल करने की सलाह देता है, इसलिए अपनी पसंद का एक छोटा timeout सेट करें और फ़ाइल धीमी हो तो intro छोड़ दें।

<head>
  <script src="https://telegram.org/js/telegram-web-app.js?64"></script>
  <style>
    body { margin: 0; background: var(--tg-theme-bg-color, #ffffff); }
    #mascot { width: 220px; height: 220px; display: block; margin: 48px auto 0; }
  </style>
</head>
<body>
  <canvas id="mascot" role="img" aria-label="Mascot"></canvas>
  <script src="/vendor/rive-canvas-2.47.1.js"></script>
  <script src="/app.js"></script>
</body>

const tg = window.Telegram.WebApp;
const canvas = document.getElementById("mascot");
const INTRO_MS = 2600;              // the launch intro fires no end event
let shown = false;

function show() {                    // hide Telegram's placeholder exactly once
  if (shown) return;
  shown = true;
  tg.ready();
}

const intro = new rive.Rive({
  src: "/mascot.riv",
  canvas,
  stateMachine: "LaunchStateMachine",
  autoplay: false,                   // start only when the app is visible
  onLoad: () => {
    intro.resizeDrawingSurfaceToCanvas();
    show();
    intro.play();
    setTimeout(startCharacter, INTRO_MS);
  },
});

// Don't hold Telegram's placeholder if the file is slow: skip the intro.
setTimeout(() => { if (!shown) { show(); startCharacter(); } }, 1500);

let mascot;
function startCharacter() {
  if (mascot) return;
  intro.cleanup();
  mascot = new rive.Rive({
    src: "/mascot.riv",
    canvas,
    stateMachine: "CharacterViewModelMachine",
    autoplay: true,
    autoBind: true,
    onLoad: () => mascot.resizeDrawingSurfaceToCanvas(),
  });
}

यहाँ intro LaunchStateMachine चलाता है, जो एक बार चलता है और जिसका कोई end event नहीं है, इसलिए intro की लंबाई जितना एक timer चलाकर कैरेक्टर पर आगे बढ़ें। रनटाइम और उसके WASM को खुद host करने से (RuntimeLoader.setWasmUrl() के साथ) पहला load CDN के बजाय आपके अपने domain से होता है।

मैस्कॉट को Telegram की light और dark themes से कैसे मैच करें?

Mini App को यूज़र की मौजूदा theme Telegram.WebApp.themeParams से मिलती है: bg_color, secondary_bg_color, text_color, hint_color, link_color, button_color और भी बहुत कुछ, सब #RRGGBB में। यही वैल्यू var(--tg-theme-bg-color) जैसे CSS variables के रूप में भी उपलब्ध हैं, और colorScheme की वैल्यू "light" या "dark" होती है।

बैकग्राउंड: पेज पर var(--tg-theme-bg-color) इस्तेमाल करें। Rive canvas ट्रांसपेरेंट होता है, इसलिए कैरेक्टर जो भी theme हो उस पर सीधे दिखता है, उसके चारों ओर कोई box नहीं होता।
Live बदलाव: themeChanged event "तब होता है जब भी यूज़र के Telegram ऐप में theme settings बदली जाती हैं (night mode पर स्विच करना भी शामिल है)।"
Header और बैकग्राउंड: setHeaderColor() और setBackgroundColor(), #RRGGBB या keywords bg_color और secondary_bg_color स्वीकार करते हैं।

वीडियो फ़ॉलबैक थोड़े मुश्किल होते हैं। GIF या MP4 का बैकग्राउंड ठोस होता है जो हर थीम से मेल नहीं खाएगा, और ट्रांसपेरेंट WebM के साथ Apple के WebKit के लिए HEVC alpha .mov विकल्प भी चाहिए; ट्रांसपेरेंट वीडियो गाइड इस जोड़ी को समझाती है। यही एक कारण है कि Telegram के अंदर Rive canvas ज़्यादा आसान विकल्प है।

मैस्कॉट के रिएक्शन में haptic feedback कैसे जोड़ें?

Telegram.WebApp.HapticFeedback Bot API 6.1 में तीन methods के साथ आया:

impactOccurred(style), जिसमें light, medium, heavy, rigid या soft दिया जाता है।
notificationOccurred(type), जिसमें error, success या warning दिया जाता है।
selectionChanged(), जिसे Telegram के अनुसार सिर्फ़ तब इस्तेमाल करें जब selection बदले, उसके confirm होने पर नहीं।

haptic को उसी call में फ़ायर करें जिसमें एनिमेशन ट्रिगर होता है, ताकि दोनों एक साथ चलें:

const haptics = tg.isVersionAtLeast("6.1") ? tg.HapticFeedback : null;

function react(kind) {               // kind: "success" | "error" | "yes" | "no"
  mascot.viewModelInstance.trigger(kind).trigger();
  if (!haptics) return;
  if (kind === "success" || kind === "error") haptics.notificationOccurred(kind);
  else haptics.impactOccurred("light");
}

tg.onEvent("themeChanged", () => {
  document.body.style.background = tg.themeParams.bg_color || "";
});
tg.onEvent("deactivated", () => mascot && mascot.pause());   // minimized
tg.onEvent("activated", () => mascot && mascot.play());

Telegram के शब्दों में ऐप "उचित haptics चला सकता है", इसलिए इन्हें एकमात्र feedback न मानकर एक अतिरिक्त सुविधा मानें। यह sample deactivated पर कैरेक्टर को रोक भी देता है (minimize किए गए Mini App के लिए Bot API 8.0 के events) और activated पर फिर से चालू करता है।

क्या Telegram के अंदर Rive मैस्कॉट स्मूद चलेगा?

Mini App, Telegram के अंदर दिखने वाला एक वेब पेज है, इसलिए वेब के सामान्य नियम ही लागू होते हैं।

डाउनलोड साइज़: version 2.47.1 में canvas रनटाइम compression से पहले लगभग 628 KB JavaScript और लगभग 2.2 MB WASM है। इन्हें लंबे cache lifetime के साथ serve करें ताकि दोबारा खोलने पर ये तुरंत लोड हों।
एक कैरेक्टर: मूड वाला एक canvas कई अलग एनिमेशन से हल्का होता है।
Viewport में बदलाव: Mini App को खींचकर लंबा या छोटा किया जा सकता है। Telegram का viewportChanged event isStateStable भेजता है; drawing surface को तभी resize करें जब यह true हो, drag के हर फ़्रेम पर नहीं।
मोशन कम करें: prefers-reduced-motion चेक करें और अगर यह सेट है तो एक स्थिर पोज़ दिखाएँ।

क्या उसी कैरेक्टर से Telegram स्टिकर बन सकते हैं?

हाँ, video stickers के रूप में। Telegram के video stickers VP9 से encode की गई WEBM फ़ाइलें होते हैं, जिनकी एक साइड ठीक 512 px होती है, अधिकतम 3 सेकंड, 30 fps तक और 256 KB तक, बिना audio के। कैरेक्टर का ट्रांसपेरेंट WebM एक ffmpeg command से convert हो जाता है, जिसकी जानकारी कैरेक्टर एनिमेशन से Telegram video stickers में है।

Animated .TGS स्टिकर एक अलग फ़ॉर्मेट है: Lottie का एक हिस्सा, जो After Effects के vector shapes से बनता है। Rive फ़ाइल या render किया गया वीडियो सीधे .TGS नहीं बन सकता।

Mini App के लिए Charmotion क्या देता है?

एक कैरेक्टर या लोगो इमेज से, Charmotion एक .riv बनाता है जिसमें वे दोनों हिस्से हैं जो यह पेज इस्तेमाल करता है: LaunchStateMachine, लगभग 2.6 सेकंड का एक लॉन्च इंट्रो जो रुके हुए पोज़ पर खत्म होता है और खत्म होने पर कोई इवेंट नहीं भेजता, और CharacterViewModelMachine, जिसमें 0 से 9 तक एक mood नंबर और success, error, yes, no, enter और exit ट्रिगर हैं। सेट में ट्रांसपेरेंट WebM और HEVC MOV (वीडियो स्टिकर के लिए अच्छे सोर्स), MP4, 9:16 वीडियो और एक GIF भी हैं, साथ में वेब कोड। यह .TGS एक्सपोर्ट नहीं करता। पूरा सेट, .riv और ट्रांसपेरेंट वीडियो समेत, हर पेड प्लान पर है ($20/माह से)।

Telegram Mini App के लॉन्च में एनिमेटेड मैस्कॉट कैसे जोड़ें

Placeholder बनाएँ. कैरेक्टर के आराम वाले पोज़ को एक सरल, बीच में रखे SVG के रूप में एक्सपोर्ट करें।
BotFather कॉन्फ़िगर करें. Bot Settings, Configure Mini App खोलें, SVG अपलोड करें और अपने पेज से मेल खाते light और dark बैकग्राउंड और header रंग सेट करें।
Telegram का script लोड करें. telegram-web-app.js को head में बाकी scripts से पहले जोड़ें।
Rive फ़ाइल लोड करें. autoplay बंद रखकर intro instance बनाएँ, onLoad में Telegram.WebApp.ready() call करें, फिर play करें।
handoff करें. intro की अवधि पूरी होने के बाद इंटरैक्टिव कैरेक्टर शुरू करें, और अगर loading में बहुत समय लगे तो intro छोड़ दें।
थीम और haptics जोड़ें. --tg-theme-bg-color इस्तेमाल करें, themeChanged को सुनें और रिएक्शन के साथ HapticFeedback जोड़ें।

अक्सर पूछे जाने वाले सवाल

क्या Telegram Mini App का placeholder एनिमेटेड SVG हो सकता है?

Telegram placeholder को SVG लोगो के रूप में document करता है और एनिमेशन के बारे में कुछ नहीं कहता, इसलिए स्थिर इमेज मानकर चलें। मोशन को अपने web app में रखें: Rive फ़ाइल लोड होने पर ready() call करें और intro को उसी पोज़ और बैकग्राउंड रंग से शुरू करें।

अगर Mini App कभी Telegram.WebApp.ready() call न करे तो क्या होता है?

Telegram अपना loading placeholder तब तक दिखाता है जब तक पेज पूरी तरह लोड न हो जाए, फिर उसे हटा देता है। अगर आपका पेज बड़ी इमेज या scripts लोड करता है तो इसमें ज़रूरत से ज़्यादा देर लग सकती है। जैसे ही ज़रूरी interface, मैस्कॉट के पहले फ़्रेम समेत, दिखाया जा सके, ready() call करें।

क्या Telegram haptics हर जगह काम करते हैं?

इसकी गारंटी नहीं है। HapticFeedback के लिए Bot API 6.1 या उसके बाद का version चाहिए, इसलिए isVersionAtLeast("6.1") चेक करें, और Telegram के docs कहते हैं कि ऐप haptics चला सकता है। जिन devices में vibration motor नहीं है उनमें कुछ नहीं होगा, इसलिए विज़ुअल रिएक्शन को ही मुख्य feedback रखें।

इस गाइड से झटपट जवाब

क्या मैं Telegram Mini App की लोडिंग स्क्रीन कस्टमाइज़ कर सकता हूँ?

स्रोत

Telegram Mini Apps, Telegram
Mini Apps on the Telegram API (botAppSettings), Telegram
Stickers: requirements for static, animated and video stickers, Telegram
Web (JS) runtime, Rive
Rive parameters (web runtime), Rive
Preloading WASM, Rive