DEV Community: Vibe Seeker

One Inline Button for Everyone: Parameters, Authentication, and Callbacks in a Telegram Mini App

Vibe Seeker — Fri, 14 Aug 2026 14:02:36 +0000

The code examples in this series are written in C#/.NET 10 (since that's what our production uses), but this article is about Telegram mechanics, not the language. The exact same architecture can be built on Node.js, Python, or Go without changes. That easily transferable mechanic is exactly why this article was written.

What is this article about? This is the second part of a series on how we vibe-coded GoosleeBot — a bridge from Telegram to Google Meet, Zoom, and other video conferencing services. This part covers the least-documented area of Telegram development: the session mechanism that ties together a chat, a mini app, and an external browser into a single application. Here's what's inside:

how to pass parameters from an inline bot into a mini app when the chat button is shared among all participants;
how to authenticate a mini app user in a single request — with a ready-made skeleton for initData validation;
how to preserve state where Telegram variables don't work at all — in an external browser;
how to push changes from the chat into the mini app instantly (spoiler: WebSocket in telegram-webview works fine);
how to edit chat messages with an async queue without getting banned by the Bot API;
and more.

The Full Series Outline:

Part 1 — the product story and an honest verdict on Telegram as a platform: agent memory rules, the "where am I?" function, tunnels.
Part 2 (you are here) — the session mechanism: parameters, authentication, callbacks, editing without getting banned.
Part 3 — UX hacks: a bot that "rings" like a real phone, building an onboarding funnel in a single JSON file, and why you must pre-calculate URLs before the user clicks.

The Problem: Shared Button, Dumb Link, and Half the Flow Is Outside Telegram Entirely

Our main scenario looks innocent enough: a chat has a bot message with a "Join the call" button. But that button has three unpleasant properties that no tutorial mentions:

First: one button for everyone. The chat message is shared — all participants see it. Anyone can tap it, and for each person the mini app must open with their own context: who you are, which call you're in, what you're allowed to do. And the button can do exactly one thing — open a URL. The same URL for everyone.

Second: authentication and callbacks are required. Opening a page isn't enough — you need to know who opened it (without taking their word for it), and then deliver the results of their actions back: into the chat message, to other participants, into their mini app.

Third, and most insidious: part of the flow leaves for an external browser. OAuth authorization with Google or Zoom, by the providers' own rules, happens in the system browser — and the moment the user goes there, all mini app variables cease to exist. No Telegram.WebApp, no initData, nothing. Of all the Telegram context, the only thing that survives is exactly what you put into the URL yourself.

Three problems — one solution: server-side sessions. And an important framing note right away: this isn't a trick for passing parameters. It's a full-fledged equivalent of a classic web session — a server-side object with a lifetime and a typed value store, on which all server logic rests. If your product has even one scenario of "leave the mini app and come back" — the session mechanism is mandatory, no exceptions.

The Session as a Server-Side Object

The skeleton is dead simple (reminder: this is C#, but it's just a dictionary with a TTL — available in any language):

public sealed class Session
{
    public string Key { get; init; }          // Guid without dashes — goes into the URL
    public SessionType SessionType { get; set; }  // RequestCall | MiniAppRoute | AccessToken | ...
    public TimeSpan SessionLifeTime { get; set; }
    public bool IsExpired => UtcNow - CreatedDate > SessionLifeTime;

    public T? GetData<T>() where T : class { ... }   // typed scenario data
    public void SetData<T>(T? value) where T : class { ... }
}

The store is a plain ConcurrentDictionary<string, Session> in process memory; a background worker sweeps out expired entries. The key is a random Guid: it's unpredictable, so it acts as a secret on its own.

The key thing here is GetData<T>(). Each session type has its own data class, and that data isn't "for passing around" — it's the working state that server logic depends on. For example, an inline-call session holds: who created the call, the list of users who pressed buttons, the chosen provider, the call status, the inline message ID in the chat, and the last rendered text of that message. The server reads and mutates this state at every step of the scenario — exactly like a classic web session; the only difference is that the key arrives not in a cookie (remember the rule from Part 1: cookies in the webview are unreliable) but in the URL and tokens.

The Chain: From a Chat Button to a Personal Page

Now the actual solution — a chain of three sessions. It sounds heavyweight; in practice it's three dictionary entries and two redirects:

[chat]     RequestCall session ─── shared, one per call
               │  key goes into the button: t.me/MyBot/app?startapp={key}
               ▼
[mini app] router page: collects Telegram.WebApp.initData → POST /init
               │  server validates the signature, finds the RequestCall by key
               ▼
[server]   AccessToken session ── personal, one per user,
               │                 holds a reference to the shared OriginalSession
               ▼
[page]     redirect to the target page with the personal token in the URL

Step by step:

1. Creation. When a user invokes the bot in a chat, the server creates a RequestCall session — shared for that call. The key goes into the buttons. For callback buttons we encode it directly in the payload ({key}@@@{command}); for the mini app button — in the startapp parameter of the deep link. This is the only channel: Telegram won't let a button pass anything other than that string.

2. The router. The button doesn't open the target page — it opens a lightweight router page. Its JS collects initData and sends it to the server:

const tg = window.Telegram.WebApp;
const resp = await fetch('/miniapp/init', {
  method: 'POST',
  body: JSON.stringify({
    initData: tg.initData,               // signed string — for verification
    startParam: tg.initDataUnsafe.start_param,  // RequestCall session key
    platform: tg.platform,               // remember "where am I?" from Part 1
  }),
});
const { redirectUrl } = await resp.json();
location.replace(redirectUrl);

3. Validation and exchange. The server validates the initData signature (next section), finds the shared session by the key from start_param, and issues a personal AccessToken session: "user X in the context of call Y." Inside it — a reference to the shared one:

var accessSession = SessionService.Create(SessionType.AccessToken, lifeTime);
accessSession.SetData(new AccessTokenSessionData {
    UserId = user.Id,
    OriginalSession = requestCallSession,  // shared call context — one for all
});
return RedirectUrlFor(page, accessSession.Key);  // token goes into the target page URL

One shared call session — many personal tokens layered on top of it. Any request from the target page carries a personal token, and the server knows both "who" and "in which call" in a single lookup. The "one button for everyone" problem is solved.

4. External browser. And now the whole point of all this. When a user returns from OAuth with Google and lands on our callback URL — they arrive in a regular browser, without a single Telegram variable. But the token was placed in the URL in advance. The server retrieves the AccessToken session from it → then the OriginalSession from that → and continues the scenario as if nobody went anywhere. The state survived the transition chat → mini app → external browser → back, because it never left the server.

Authentication: Don't Trust `initDataUnsafe` at Face Value

Telegram puts user data into the mini app two ways: initDataUnsafe (a convenient parsed object) and initData (a raw string with a cryptographic signature). The word "Unsafe" in the name isn't coy: anyone can fabricate that data by sending you any user_id they like. Using it for UI — fine. For server-side decisions — only after verifying the signature of the raw string.

The validation algorithm is described in the Telegram docs; here's its complete skeleton — one static method:

public static bool Validate(string initData, string botToken)
{
    var parsed = ParseQuery(initData);           // initData is a query string
    var receivedHash = parsed["hash"];

    var dataCheckString = string.Join('\n',      // all fields except hash,
        parsed.Where(kv => kv.Key != "hash")    // sorted by key
              .OrderBy(kv => kv.Key, StringComparer.Ordinal)
              .Select(kv => $"{kv.Key}={kv.Value}"));

    var secretKey = HMACSHA256(key: "WebAppData", message: botToken);
    var expected  = HMACSHA256(key: secretKey,   message: dataCheckString);

    if (!FixedTimeEquals(expected, receivedHash)) return false;  // constant time!
    return UtcNow - FromUnix(parsed["auth_date"]) < MaxAge;      // and freshness: we use 1 hour
}

Three details that an agent in vibe-coding mode consistently misses — check these by hand:

Field sorting is ordinal, not culture-dependent — otherwise the signature "sometimes doesn't match."
Hash comparison in constant time (FixedTimeEquals), not == — protection against timing attacks on signature brute-forcing.
Checking auth_date. A signature without an expiry is a permanent pass: a once-intercepted initData string would work for years.

After validation, the user_id from initData can be treated as proven — Telegram has signed it. Notice what this gives you: registration, login, and password recovery in your application don't exist as tasks. This is one of the main reasons to build business applications on Telegram at all.

Honesty Box: All of This Lives in Process Memory

Yes, our sessions are in-memory, ConcurrentDictionary, no Redis. This is a deliberate tradeoff, and here are its boundaries:

When this is fine: a single application instance; sessions are short-lived (minutes to hours) and inherently recoverable — in the worst case the user just taps the button again; business-critical state (calls, users, settings) lives in PostgreSQL anyway, the session only orchestrates the scenario.
When it breaks: a restart or deployment wipes live scenarios (for us that means "the button stopped responding, please invoke the menu again"); a second instance behind a load balancer won't see another instance's sessions — hello sticky sessions or an external store.

The takeaway for vibe-coders: start with an in-memory dictionary — zero infrastructure and all the mechanics in this article work as-is. But define a session store interface from day one, so that Redis, when you need it, is a one-class swap, not a rewrite.

Callbacks: Signal via WebSocket, Data via Request

One last arrow remains: changes need to flow back. A participant chose a provider in their mini app — your page needs to update the status; someone joined the meeting — the chat message should reflect that.

I already spoiled this in Part 1: SignalR (WebSocket) inside telegram-webview works natively on all platforms. The scheme:

When the page opens, the client joins a group keyed by the shared call session: all participants in the same call are in the same room.
When server state changes, the server sends the group a bare StateChanged event — with no data.
The client, upon receiving the signal, fetches the current state itself via a regular HTTP request with its personal token.

// server: state changed → poke the group (with debounce, see below)
await hub.Clients.Group(callSessionKey).SendAsync("StateChanged");

// client: the signal is not data — it's an invitation to ask
connection.on('StateChanged', () => refreshState());  // GET with own token

Why is the signal empty? Three reasons: no need to think about permissions in the push channel (each client fetches state with its own token — the server decides what it can see); a lost signal breaks nothing (the next refreshState will catch up); and events can be debounced — during a burst of changes, the group gets one nudge every N milliseconds instead of a queue of stale snapshots. Plus a cheap safety net: an infrequent background poll in case the WebSocket has actually died.

Bonus Tip: Edit Messages Through a Queue — Otherwise You Get Banned

Callbacks reach not only mini apps but also that very inline message in the chat: "Done. Connected: Anna, Dmitry." And here vibe-coders hit a widespread pitfall: naive code calls editMessageText on every state change. Two participants press buttons simultaneously — two edits; a burst of events — a burst of edits. Bot API has two reactions to this: error 400: message is not modified (text matches what's already there) and flood limits up to temporary bot blocking — for a product living in other people's chats, that's death.

The solution: don't edit the message from business logic at all. Instead:

logic:   "session X state changed" → mark X in queue (deduplication by key)
worker:  takes key → builds text and keyboard FROM CURRENT session state
         → compares with the last sent text (stored in the session!)
         → match: silently skip  |  changed: editMessageText, remember the text

Three properties this achieves: deduplication — ten changes per second produce one edit, because marks collapse by session key and the text is built from the final state; idempotency — comparing against LastInlineMessageText from the session guarantees we never send Telegram what it already has (note: this is yet another job for server-side session state); async — business logic doesn't wait on the Telegram API and doesn't crash from its errors.

Agent memory rule: the chat message is a projection of session state, updated by a background worker. Business logic never touches messages.

Summary

The mechanics in this article are a reusable skeleton for any business mini app with a "shared button" and an "exit to the outside": a server-side session with typed state; personal tokens layered over a shared context; the initData signature as a replacement for an entire login system; empty WebSocket signals instead of data in push; and a projection queue for chat messages. Not a single one of these elements is tied to C# — this is a protocol for working with the platform.

Part 3 will be about tricks: how a bot "calls" a user so that the phone behaves like an actual incoming call (spoiler: we delete and resend the message — and why that works). Why the familiar web pattern "click → server generates link → redirect" is impossible in Telegram and how to live with the fact that the final URL must be in the button before the click. And the script-chat: an onboarding funnel entirely in a single JSON file — with a typing effect, slides, and per-step analytics.

Try the bridge yourself: @GoosleeBot · gooslibot.com

Nuances of Developing a Business App on Telegram Mini Apps: What I Learned About the Platform

Vibe Seeker — Tue, 11 Aug 2026 16:26:55 +0000

The code examples in this series are written in C#/.NET 10 (since that's what our production uses), but this article is about Telegram mechanics, not the language. The exact same architecture can be built on Node.js, Python, or Go without changes. That easily transferable mechanic is exactly why this article was written.

What is this article about? We used "vibe-coding" to build a bridge from Telegram to Google Meet, Zoom, and other video conferencing services. Along the way, we stepped on every possible rake you can hit when developing a business application as a Telegram Mini App. This article contains four practical hacks that you will absolutely need when writing any business app on this platform. Here are some of them:

a ready-to-use block of rules for your agent's memory — Telegram web engine constraints plus catalog requirements (copy as is into CLAUDE.md);
a "where am I?" function — platform and mode detection, without which every page turns into a guessing game;
a tunnel from day one — a trick that turns deploy-for-every-tiny-change into lightning-fast iterations;
how to manage state between bot calls, miniapp, and an external browser;
a bot that "rings" like a phone;
and more;

The Full Series Outline:

Part 1 (You are here) — The product's story and an honest verdict on Telegram as a platform for business apps: what's cheap, what's painful, and what you must tell your AI agent before writing the first line of code.
Part 2 — The session mechanism: how to pass parameters from an inline bot to a Mini App and read them in an external browser; authentication, feedback loops, and how to avoid bans when editing messages.
Part 3 — UX hacks: a bot that "rings" like a real phone, building an onboarding funnel in a single JSON file, and why you must pre-calculate URLs before the user clicks.

How It All Started

Calls in Telegram work great — but strictly as calls: voice, video, hang up. Meetings are a completely different genre, and it's practically non-existent in Telegram. Meanwhile, ecosystems have grown around Google Meet and Zoom: AI summaries, transcriptions, recordings, calendar integrations, and CRM syncs. When a conversation turns to business, you usually want a proper meeting with all these tools.

But the text conversation itself lives in Telegram: that's where your team group is, or the client who finds it "more convenient." Every time a chat matures to a "let's jump on a call" stage, a ritual begins: open Google Meet or Zoom, create a meeting, copy the link, return to the chat, paste it, and explain where to click.

Our idea was brazenly simple: let the bot create the link. Right in the chat, with a single button, using the service available to both me and my counterpart. That's how GoosleeBot was born — a bridge from Telegram to the world of video meetings: Google Meet, Zoom, Microsoft Teams, Jitsi, FaceTime, and others.

What followed was pure vibe-coding: AI agents, prompts, and iterations. The numbers speak for themselves: the first MVP (Google Meet, Zoom, and Jitsi) was ready in two days and proved the idea worked. Then came four weeks of polishing. Here is the crucial part: the main time sink wasn't writing code — AI writes code fast. The time was eaten up by the sheer volume of scenarios we had to cover and manually test: two participants vs. a group, the first call vs. the hundredth, whether the creator has a specific provider connected, iOS vs. Desktop, a private chat vs. an external group. Every combination had to be clicked through in the real Telegram app.

That's why this article isn't a "look how great we are" showcase. It's a list of things I would hardcode into my AI agent's memory before writing the first line of code. Because the main lesson is this: Telegram is an excellent platform for productivity apps, but its web engine is not a standard browser, and the Bot API is not a standard REST backend. If your agent doesn't know this, it will confidently generate beautiful code that simply won't work.

How It Looks to the User

Scenario: in any chat, you trigger the bot and press a button — the bot creates a room with an available provider and places a "Join" button in the chat. If the other person doesn't respond, the bot can "call" them: sending repeated call messages, mimicking a real incoming call (how this is implemented is covered in part three of the series — it's a simple, clever trick).

Neither participant installs anything new. That's the whole premise: distribution through chat is a Telegram feature that no "traditional" platform offers.

Rules to Put in Your Agent's Memory Before Starting

This is the core section of the article. If you vibe-code for Telegram, copy this section directly into your agent's CLAUDE.md or system prompt as is. Every single rule was paid for with hours of debugging "why does this behave differently on iPhone."

Block A. Telegram's Web Engine Is Not a Browser

Never use 100vh. Use only viewportStableHeight / the CSS variable var(--tg-viewport-height) and subscribe to the viewportChanged event. What breaks: on iOS, the bottom of the page slides under the bottom panel; on Android, the keyboard compresses the viewport and breaks the layout.
No window.open or target="\_blank". Use Telegram.WebApp.openLink() for external links and openTelegramLink() for internal ones. What breaks: on some clients, clicking simply does nothing without any error.
No alert, confirm, or prompt. Use only showAlert, showConfirm, or showPopup. What breaks: the same silent failure instead of a modal dialog, happening unpredictably for certain users, which is even harder to debug.
Don't rely on cookies for authentication in miniapps. The Webview loses them unpredictably. Authenticate using an explicitly passed token (in headers or query parameters). What breaks: the user gets logged out between sessions, leaving you searching for a non-existent server bug for a week.
localStorage is a cache, not a database. Store everything important on the server (or in CloudStorage). What breaks: user state suddenly disappears, and you won't even realize it happened.
"Back" navigation must go through Telegram's BackButton, not the browser history. What breaks: the system back button on Android closes the entire miniapp instead of going back one step.
The first thing on every page — figure out where you are: platform and mode (miniapp or standard browser). CSS and logic branch from here. Function provided below.
Everything the user can click must be ready before the click. The standard web flow "click → server processes → builds URL → redirect" doesn't work in Telegram: there are no redirects. The target URL must already be inside the button when it renders — so all redirect logic must be pre-calculated (detailed breakdown in Part 3).
Test on at least three platforms: iOS, Android, Desktop. These are three distinct webviews with different rendering and behavior. "It works on my desktop" counts as zero out of three.

Block B. Catalog Requirements — From Day One, Not "We'll Polish Later"

App catalogs (both Telegram's official directory and third-party miniapp showcases) have strict requirements. Adapting a finished app for them later is the most expensive work in a project. So configure your agent's memory strictly from the start:

Multi-language support from the very first screen. Not a single hardcoded string in the markup — route everything through locale files. The user's language code comes automatically via initDataUnsafe.user.language\_code. Adding a second language to a codebase with hardcoded UI text means rewriting the application.
Theming only via themeParams. All colors must come from --tg-theme-\* CSS variables. Dark and light themes are mandatory, along with subscribing to themeChanged. Never hardcode colors. What breaks: white text on a white background for half your users — and rejection from catalogs.
Catalogs test languages, both themes, and all platforms. These are mandatory release requirements, not optional polish. The agent must consider them part of the Definition of Done for every page.

The "Where Am I?" Function — An Essential First Building Block

In our app, the exact same page opens on iOS, Android, desktop — and sometimes in a regular browser when a user copies a link. CSS and behavior differ in all four cases, so this helper was the very first piece of code we wrote:

function whereAmI() {
  const tg = window.Telegram?.WebApp;
  const inMiniApp = !!tg \&\& tg.initData !== '';   // empty initData = regular browser
  const platform = tg?.platform ?? 'browser';     // ios | android | tdesktop | macos | weba | ...
  const isMobile = platform === 'ios' || platform === 'android';
  return { inMiniApp, platform, isMobile };
}

// then — add class to body and branch behavior
document.body.classList.add(`plt-${platform}`, inMiniApp ? 'in-tg' : 'in-browser');

Where this matters in practice:

CSS. Header/footer spacing, iOS safe areas, keyboard behavior on Android — everything attaches to plt-\* CSS classes.
Redirects. After Google OAuth authentication, a mobile user should return to Telegram via a tg:// deep link, while a desktop user receives a standard https redirect. Get this wrong, and you end up with either a frozen browser or a user kicked out of the miniapp.
Fallback for non-Telegram environments. If initData is empty, it's not a miniapp — so instead of the app, we show an "open via bot" landing page.

A small detail? Sure. But without it, every page turns into a guessing game.

Practical Tip: A Tunnel From Day One

Telegram doesn't work with "localhost": both the bot's webhook and the miniapp URL must be public HTTPS endpoints. That's why your first tool on a project — before the database, before CI — should be a tunneling service: ngrok, cloudflared, Visual Studio dev tunnels, or anything that exposes your local machine to a persistent public URL.

This creates a smooth dev workflow: the bot and miniapp point to the tunnel URL, you edit code locally with hot reload, and test changes immediately in real Telegram on a physical phone. Without a tunnel, every iteration requires a full deployment; with a tunnel, it takes seconds. Remember the endless scenarios that took four weeks? Without a tunnel, that would have taken months.

Verdict: Telegram as a Platform for Productivity Apps

What is cheap — absurdly cheap:

Distribution. The product spreads simply by sharing a button in a chat. Zero installations, zero landing pages to launch: the other person sees the button — and instantly becomes a user.
Out-of-the-box authentication. Telegram cryptographically signs user data and hands it to the miniapp. No sign-ups, no passwords, no "Log in with Google" needed — you only need to verify the signature correctly (which is covered in detail in Part 2).
Inline mechanics. The bot works in any chat, even where it isn't added as a member. That's the essence of the "bridge": the product lives directly inside existing conversations instead of waiting for users to visit a separate app.
Real-time features work — and you should use them. We were skeptical whether SignalR (WebSockets) would run smoothly inside Telegram's webview. It did: a full real-time hub with groups runs reliably in production across all platforms. Call status updates land in the miniapp instantly without page reloads. We keep polling fallback as insurance, not as the primary channel. If your agent suggests "let's just poll every second," don't fall for it — WebSocket connections work fine.

What is painful:

Client fragmentation. iOS, Android, Desktop, web — four separate Telegram implementations with different webviews. Hence Rule #9 and the "where am I?" function.
A web engine with quirks. Everything in Block A above paints its full picture.
Catalog guidelines. Multi-language support and themes aren't optional. Anyone who discovers this at the end of development ends up rewriting their UI layout.
On a minor note: receiving updates from Telegram toggles with a flag between webhook and polling in our code — super handy for debugging, and that's pretty much all you need to know about that.

Bottom line: if your product is about communication, coordination, or "getting things done without leaving the chat," Telegram gives you a massive head start over traditional platforms. The cost is webview discipline. And that discipline can easily be delegated: just hand your agent the rules from this article.

What's Next in the Series

Part 2 — the subtle mechanics. An inline chat button is shared by all participants and simply opens a URL. How do you pass specific call parameters into the miniapp? How do you verify who clicked it without getting spoofed? How do you send responses back from the miniapp into the chat? Plus a sneaky trap: part of the workflow inevitably leads to an external browser (e.g. Google OAuth) — where miniapp variables don't exist at all, leaving only what you explicitly passed in the URL. I'll share our session mechanism that solves all of this at once — it's not just a parameter-passing hack, but a true server-side session abstraction: a typed key-value store powering the entire call logic. Bonus: how to edit chat messages via an async queue without getting rate-limited by the Bot API.

Part 3 — the tricks. How to make a bot "call" — complete with repeated ring notifications like a real incoming call (spoiler: we delete and re-send the message). Why links must be prepared ahead of time — and this isn't just about pre-generating URLs: in standard web, you click, the server processes the request, generates a link, and redirects — in Telegram, this flow physically doesn't work since there are no redirects, so all redirect workload must be pre-calculated before the click. How to onboard users using a simple JSON file instead of a complex onboarding library: a scripted chat that types, shows slides, and sends funnel metrics to analytics.

---

Try the bridge yourself: @GoosleeBot · gooslibot.com