Crate telegram_webapp_sdk

Expand description

§Telegram WebApp SDK

telegram-webapp-sdk provides a type-safe and ergonomic wrapper around the Telegram Web Apps JavaScript API.

§Features

Comprehensive coverage of Telegram Web App JavaScript APIs.
Framework integrations for Yew and Leptos.
Optional macros for automatic initialization and routing.

§Macros

The macros are available with the macros feature. Enable it in your Cargo.toml:

telegram-webapp-sdk = { version = "0.2", features = ["macros"] }

Reduce boilerplate in Telegram Mini Apps using the provided macros:

telegram_page!("/", fn index() {
    // render page
});

telegram_app!(fn main() -> Result<(), wasm_bindgen::JsValue> {
    telegram_router!();
    Ok(())
});

When running outside Telegram in debug builds, telegram_app! loads mock settings from telegram-webapp.toml.

Configurable mock Telegram.WebApp for local development and testing.
API helpers for user interactions, storage, device sensors and more.

§Installation

Add the crate to your Cargo.toml:

[dependencies]
telegram-webapp-sdk = "0.2"

Enable optional features as needed:

telegram-webapp-sdk = { version = "0.2", features = ["macros", "yew", "mock"] }

macros — enables telegram_app!, telegram_page!, and telegram_router!.
yew — exposes a use_telegram_context hook.
leptos — integrates the context into the Leptos reactive system.
mock — installs a configurable mock Telegram.WebApp for local development.

§Quick start

§Yew

use telegram_webapp_sdk::yew::use_telegram_context;
use yew::prelude::*;

#[function_component(App)]
fn app() -> Html {
    let ctx = use_telegram_context().expect("context");
    html! { <span>{ ctx.init_data.auth_date }</span> }
}

§Leptos

use leptos::prelude::*;
use telegram_webapp_sdk::leptos::provide_telegram_context;

#[component]
fn App() -> impl IntoView {
    provide_telegram_context().expect("context");
    let ctx = use_context::<telegram_webapp_sdk::core::context::TelegramContext>()
        .expect("context");
    view! { <span>{ ctx.init_data.auth_date }</span> }
}

§Mock environment

The mock feature simulates a Telegram.WebApp instance, enabling local development without Telegram:

let config = telegram_webapp_sdk::mock::MockConfig::default();
let ctx = telegram_webapp_sdk::mock::install(config)?;

§User interactions

Request access to sensitive user data or open the contact interface:

use telegram_webapp_sdk::api::user::{request_contact, request_phone_number, open_contact};
use telegram_webapp_sdk::webapp::TelegramWebApp;

request_contact()?;
request_phone_number()?;
open_contact()?;

let app = TelegramWebApp::try_instance()?;
app.request_write_access(|granted| {
    let _ = granted;
})?;

These calls require the user’s explicit permission before any information is shared.

§Keyboard control

Hide the native keyboard when it’s no longer required:

use telegram_webapp_sdk::webapp::TelegramWebApp;
let app = TelegramWebApp::try_instance()?;
app.hide_keyboard()?;

§Closing confirmation

Prompt users before the Mini App closes:

use telegram_webapp_sdk::webapp::TelegramWebApp;
let app = TelegramWebApp::try_instance()?;
app.enable_closing_confirmation()?;
assert!(app.is_closing_confirmation_enabled());
// later
app.disable_closing_confirmation()?;

§Invoice payments

Open invoices and react to the final payment status:

use telegram_webapp_sdk::webapp::TelegramWebApp;

let app = TelegramWebApp::try_instance()?;
let handle = app.on_invoice_closed(|status| {
    let _ = status;
})?;
app.open_invoice("https://invoice", |_status| {})?;
app.off_event(handle)?;

Share links, prepared messages, or stories and join voice chats:

use js_sys::Object;
use telegram_webapp_sdk::webapp::TelegramWebApp;

let app = TelegramWebApp::try_instance()?;
app.share_url("https://example.com", Some("Check this out"))?;
app.join_voice_chat("chat", None)?;
app.share_message("msg-id", |sent| {
    let _ = sent;
})?;
let params = Object::new();
app.share_to_story("https://example.com/image.png", Some(&params.into()))?;

§Settings button

Control the Telegram client’s settings button and handle user clicks:

use telegram_webapp_sdk::api::settings_button::{show, hide, on_click, off_click};
use wasm_bindgen::prelude::Closure;

let cb = Closure::wrap(Box::new(|| {}) as Box<dyn Fn()>);
on_click(&cb)?;
show()?;
hide()?;
off_click(&cb)?;

§Cloud storage

Persist small key-value pairs in Telegram’s cloud using CloudStorage:

use js_sys::Reflect;
use telegram_webapp_sdk::api::cloud_storage::{get_items, set_items};
use wasm_bindgen_futures::JsFuture;

JsFuture::from(set_items(&[("counter", "1")])?).await?;
let obj = JsFuture::from(get_items(&["counter"])?).await?;
let value = Reflect::get(&obj, &"counter".into())?.as_string();
assert_eq!(value, Some("1".into()));

All functions return a Promise and require the Web App to run inside Telegram.

§Home screen

Prompt users to add the app to their home screen and check the current status:

use telegram_webapp_sdk::webapp::TelegramWebApp;
let app = TelegramWebApp::try_instance()?;
let _shown = app.add_to_home_screen()?;
app.check_home_screen_status(|status| {
    let _ = status;
})?;

§Event callbacks

Callback registration methods return an EventHandle for later deregistration.

use telegram_webapp_sdk::webapp::TelegramWebApp;
let app = TelegramWebApp::try_instance()?;
let handle = app.on_event("my_event", |value| {
    let _ = value;
})?;
app.off_event(handle)?;

§Background events

Some Telegram events may fire while the Mini App is in the background. Register callbacks for these with on_background_event:

use telegram_webapp_sdk::webapp::{BackgroundEvent, TelegramWebApp};

let app = TelegramWebApp::try_instance()?;
let handle = app.on_background_event(BackgroundEvent::MainButtonClicked, |_| {})?;
app.off_event(handle)?;

Supported background events:

Event	Payload
`mainButtonClicked`	none
`backButtonClicked`	none
`settingsButtonClicked`	none
`writeAccessRequested`	`bool` granted flag
`contactRequested`	`bool` shared flag
`phoneRequested`	`bool` shared flag
`invoiceClosed`	status `String`
`popupClosed`	object `{ button_id: Option<String> }`
`qrTextReceived`	scanned text `String`
`clipboardTextReceived`	clipboard text `String`

§Appearance

Customize colors and react to theme or safe area updates:

§Fullscreen and orientation

Control the Mini App display and screen orientation:

use telegram_webapp_sdk::webapp::TelegramWebApp;
let app = TelegramWebApp::try_instance()?;
app.set_header_color("#000000")?;
app.set_background_color("#ffffff")?;
app.set_bottom_bar_color("#cccccc")?;
let theme_handle = app.on_theme_changed(|| {})?;
let safe_handle = app.on_safe_area_changed(|| {})?;
let content_handle = app.on_content_safe_area_changed(|| {})?;
// later: app.off_event(theme_handle)?; etc.

app.request_fullscreen()?;
app.lock_orientation("portrait")?;
// later...
app.unlock_orientation()?;
app.exit_fullscreen()?;

§Haptic feedback

Trigger device vibrations through Telegram’s HapticFeedback API:

use telegram_webapp_sdk::api::haptic::{
    impact_occurred, notification_occurred, selection_changed,
    HapticImpactStyle, HapticNotificationType,
};

impact_occurred(HapticImpactStyle::Light)?;
notification_occurred(HapticNotificationType::Success)?;
selection_changed()?;

§Device storage

Persist lightweight data on the user’s device:

use telegram_webapp_sdk::api::device_storage::{set, get};

set("theme", "dark").await?;
let value = get("theme").await?;

§Secure storage

Store sensitive data encrypted and restorable:

use telegram_webapp_sdk::api::secure_storage::{set, restore};

set("token", "secret").await?;
let _ = restore("token").await?;

§Location manager

Retrieve user location and react to related events via Telegram’s location manager:

use telegram_webapp_sdk::api::location_manager::{
    init, get_location, open_settings, on_location_requested,
};
use wasm_bindgen::closure::Closure;

init()?;
let _ = get_location();
open_settings()?;

let cb = Closure::wrap(Box::new(|| {}) as Box<dyn Fn()>);
on_location_requested(&cb)?;
cb.forget();

§Device sensors

Access motion sensors if the user’s device exposes them.

use telegram_webapp_sdk::api::accelerometer::{start, get_acceleration, stop};

start()?;
let reading = get_acceleration();
stop()?;

Callbacks for sensor lifecycle events are available through on_started, on_changed, on_stopped, and on_failed functions for accelerometer, gyroscope, and device orientation sensors.

§Init data validation

Validate the integrity of the Telegram.WebApp.initData payload on the server. The validate_init_data module is re-exported at the crate root and can be used directly or through the TelegramWebApp::validate_init_data helper:

use telegram_webapp_sdk::{
    validate_init_data::ValidationKey,
    TelegramWebApp
};

let bot_token = "123456:ABC";
let query = "user=alice&auth_date=1&hash=48f4c0e9d3dd46a5734bf2c5d4df9f4ec52a3cd612f6482a7d2c68e84e702ee2";
TelegramWebApp::validate_init_data(query, ValidationKey::BotToken(bot_token))?;

// For Ed25519-signed data
TelegramWebApp::validate_init_data(
    &init_data,
    ValidationKey::Ed25519PublicKey(pk.as_bytes())
)?;

§API coverage

See WEBAPP_API.md for a checklist of supported Telegram WebApp JavaScript API methods and features.

§Changelog

See CHANGELOG.md for release notes.

§License

telegram-webapp-sdk is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Re-exports§

pub use utils::validate_init_data;
pub use webapp::TelegramWebApp;

Modules§

api
core
logger
utils
webapp