TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Telegram Deep Links and Start Parameters

· 4 min read · 18+ readers

Telegram Deep Links and Start Parameters: TSocial guide cover card

Deep links are URLs that open a specific place in Telegram: a chat, a bot icon bot with a payload, a Mini App screen, an invite. They are the glue of every Telegram funnel. This guide lists the main formats, explains how to use payloads for tracking and notes the limits. Confirm the current syntax at core.telegram.org/api/links.

Basic formats

PurposeLink
Open a public user, bot, channel or grouphttps://t.me/username
Open a bot with a payloadhttps://t.me/botname?start=PAYLOAD
Add a bot to a grouphttps://t.me/botname?startgroup=PAYLOAD
Add a bot to a channel as adminhttps://t.me/botname?startchannel plus an admin parameter
Open a Mini App with a payloadhttps://t.me/botname/appname?startapp=PAYLOAD
Open a specific message in a public channelhttps://t.me/channelname/123
Join a private chathttps://t.me/+INVITEHASH

There is also a tg:// scheme such as tg://resolve?domain=username, which opens the app directly. Web pages usually use the t.me form because it works on every device and falls back to a landing page.

The start parameter

When someone opens https://t.me/botname?start=ig_may, Telegram shows the bot chat and a Start button. After pressing Start, the bot receives a message with the text /start ig_may. Your handler reads the part after the command:

const text = update.message.text;            // "/start ig_may"
const payload = text.split(" ")[1] ?? "";    // "ig_may"

Rules:

  • The payload is limited to 64 characters.
  • Allowed characters are letters, digits, underscore and hyphen. Encode other data with base64url if you must.
  • It is visible to users and can be edited, so never trust it blindly.
  • It arrives only when the user presses Start for the first time or opens the link icon link again. In an existing chat, a link with a new payload still sends /start payload.

Using payloads for tracking

Create one link per source:

  • ?start=src_instagram
  • ?start=src_tiktok
  • ?start=src_email_nov

In your database store source when you first see a user, and never overwrite it. After a few weeks you can count users per source and see which ones buy. See link in bio tools and the traffic guides, for example Instagram to Telegram.

To connect a website account to a Telegram user:

  1. Your site creates a random token and stores it with the website user.
  2. It shows https://t.me/botname?start=link_<token>.
  3. The user taps it and presses Start.
  4. Your bot receives /start link_<token>, looks up the token, binds the Telegram id and deletes the token.

Make tokens random, single use and short lived.

startgroup and startchannel

?startgroup=payload lets a user pick a group to add the bot to. After adding, the bot receives /start payload in the group. ?startchannel works similarly for adding to a channel megaphone icon channel as an administrator, with rights listed in an admin parameter. Use them in onboarding for moderation or posting bots. See adding a bot as channel admin.

?startapp=payload passes a value to the Mini App icon (grid) Mini App. See menu button, direct link and startapp.

Public usernames

A link like https://t.me/yourchannel only works if the channel is public with a username. See getting a username.

Private groups and channels use invite links created by admins. They can be single use, limited by count or time, or require join approval. Create a separate link for each source to measure joins.

QR codes and sharing

Any of these links can be put into a QR code. Use a short link and test it on iOS and Android. Add a plain text version near the code.

Common mistakes

  • Using characters outside the allowed set in a payload.
  • Putting secrets in links.
  • Changing a bot username and breaking old links.
  • Forgetting that the payload arrives only with /start.

Quick checklist

  • Payloads use only letters, digits, underscore and hyphen.
  • Payloads stay under 64 characters.
  • One link per traffic source.
  • The source is saved once, on first contact.
  • Link account tokens are random, single use and short lived.
  • Links are tested on iOS, Android and desktop.
  • No secrets appear in any link.
  • Old links are kept working when names change.

Maintain a simple sheet of every deep link you publish, with the payload, the place it is used and the date. When you review results you will know exactly which link brought which users, and when you change a bot or app name you will know which links need updating.

Frequently asked questions

Can I pass more than 64 characters?

Not in the payload. Store the data on your server and send a short key.

Does the payload work if the user already started the bot?

Yes. Telegram sends /start payload when they open the link.

Do links work on desktop?

Yes. They open the desktop app or Telegram Web.

Are payloads private?

No. Treat them as public.

Related guides

More in Build on Telegram

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

Telegram Deep Links and Start Parameters | TSocial