TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Mini App Menu Button, Direct Links and the startapp Parameter

· 4 min read · 18+ readers

Mini App Menu Button, Direct Links and the startapp Parameter: TSocial guide cover card

A Mini App icon (grid) Mini App can start in several ways, and each one tells your app slightly different things. Knowing the options lets you open the app on exactly the right screen from a channel megaphone icon channel post, a bio link or a chat. This guide describes the launch methods and how to pass data with the startapp parameter. Confirm details in the official Mini Apps documentation, since options are added over time.

Launch methods

1. The menu button

The button beside the message box in a chat with your bot icon bot. Set it in BotFather with /setmenubutton, or from code with setChatMenuButton:

{ "menu_button": { "type": "web_app", "text": "Open", "web_app": { "url": "https://app.example.com/" } } }

Pass chat_id to set it for one user, or leave it out for the default. Apps opened this way get the user data in initData, and they can send data back to the bot only through certain features.

2. Inline keyboard button

A button under a message, with web_app:

{ "inline_keyboard": [[ { "text": "Open", "web_app": { "url": "https://app.example.com/page" } } ]] }

Different URLs can open different pages.

3. Reply keyboard button

A keyboard button with web_app sends data from the app back to the bot using Telegram.WebApp.sendData, and then the app closes. This suits simple forms.

4. Direct link to a named Mini App

After creating an app with /newapp, the link icon link is:

https://t.me/<bot_username>/<app_short_name>

You can share it anywhere: in a channel, a bio or a website. Telegram shows a preview with the app's title and photo.

5. Main Mini App link

If you configure a Main Mini App for the bot in BotFather, a link such as https://t.me/<bot_username>?startapp opens it, and the profile of the bot shows an Open button. The documentation describes a mode query parameter, such as compact, for how it opens. Check the current values before you rely on them.

6. Other places

Inline mode results, the attachment menu and links within other apps can launch Mini Apps too. These need extra setup. See the documentation.

Mock BotFather chat showing the /setmenubutton steps: choose bot, send URL, send button label
Setting the menu button with /setmenubutton. Generic illustration, not a real chat or user data.

The startapp parameter

Add ?startapp=VALUE to a direct link:

https://t.me/yourbot/shop?startapp=product_42

Inside the app, read it from:

const param = Telegram.WebApp.initDataUnsafe.start_param;   // "product_42"

The same value is also in the signed initData string as start_param, so your server can read it after validation. See validating initData.

Rules for the value:

  • Up to 64 characters.
  • Only letters, digits, underscore and hyphen are allowed. Encode anything else, for example with base64url.
  • It is visible to the user, so never put secrets in it.
  • Treat it as untrusted input: validate and look it up in your database. Do not assume it is yours.

Example scheme: post_123, ref_abc, topic_growth. Then route inside your app:

const p = Telegram.WebApp.initDataUnsafe.start_param ?? "";
if (p.startsWith("post_")) openPost(p.slice(5));
else if (p.startsWith("ref_")) saveReferral(p.slice(4));
NeedUse
An always visible entry in the bot chatMenu button
A link to share on a website or channelDirect link
Open a specific screenstartapp
Send one form result to the botReply keyboard web_app
Return to the chat after finishingtg.close()

Fullscreen and other options

Telegram has added options such as fullscreen mode and bottom bar controls in newer versions. Check Telegram.WebApp.version and isVersionAtLeast before you call new methods, and give older apps a graceful fallback.

Tracking sources

Because startapp can carry a tag, you can measure where visitors came from: src_ig, src_tiktok, src_email. Save the tag when the user first opens the app, and count it in your analytics. See deep links and start parameters.

Troubleshooting

  • Parameter missing: you opened the app through a path that does not pass it, such as the menu icon (three lines) menu button. Use the direct link.
  • Characters rejected: encode the value to the allowed set.
  • Link opens the bot chat, not the app: the app short name is wrong or the app was deleted.

Quick checklist

  • Menu button set in BotFather or with setChatMenuButton.
  • A direct link created with /newapp for sharing.
  • startapp values use only allowed characters and stay under 64 characters.
  • The app reads start_param and routes safely.
  • Server side checks read start_param from validated initData.
  • Source tags are saved on first open.
  • Links are tested from a channel, a bio and a chat.
  • Fallbacks exist for older Telegram versions.

Document your routes

Keep a list of the startapp values your app understands and what each opens. When marketing wants a new link, they can pick from the list, and developers do not need to guess what old links mean.

Frequently asked questions

Can the parameter change after launch?

No. It is fixed for that launch. Reopen with a new link to change it.

Is the parameter secure?

No. Anyone can edit a link. Validate on your server.

How do I open a link from a website?

Use the direct link. It opens Telegram if installed, or the web version.

Do I need both a menu button and a direct link?

Many bots use both: the menu button for convenience and direct links for sharing.

Related guides

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Mini App Menu Button, Direct Links and the startapp Parameter | TSocial