Telegram Deep Links and Start Parameters
· 4 min read · 18+ readers

Deep links are URLs that open a specific place in Telegram: a chat, a 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
| Purpose | Link |
|---|---|
| Open a public user, bot, channel or group | https://t.me/username |
| Open a bot with a payload | https://t.me/botname?start=PAYLOAD |
| Add a bot to a group | https://t.me/botname?startgroup=PAYLOAD |
| Add a bot to a channel as admin | https://t.me/botname?startchannel plus an admin parameter |
| Open a Mini App with a payload | https://t.me/botname/appname?startapp=PAYLOAD |
| Open a specific message in a public channel | https://t.me/channelname/123 |
| Join a private chat | https://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 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.
One-time links for linking accounts
To connect a website account to a Telegram user:
- Your site creates a random token and stores it with the website user.
- It shows
https://t.me/botname?start=link_<token>. - The user taps it and presses Start.
- 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 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.
Mini App links
?startapp=payload passes a value to the 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.
Invite links
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.
Keep a link register
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

Mini App Menu Button, Direct Links and the startapp Parameter
Launch a Telegram Mini App from the menu button, inline buttons, direct t.me links and attachment menu, and pass data with startapp. Includes link formats.

Link in Bio Tools for Telegram Creators
What a link in bio page is, what to put on it, how to choose between tools, track clicks and keep your Telegram link front and centre.

Telegram Bot Commands, Menus and Onboarding Flows
Design a bot that new fans can use in seconds: start message, command list, inline buttons, menus, language, error handling and a human fallback.

Add a Bot as Channel Admin and Post to Your Channel
Give a bot posting rights in a Telegram channel, find the chat id, send posts with sendMessage, schedule them from code and fix common permission errors.

Get a Username for Your Telegram Channel or Group
How to make a channel or group public with a t.me username: steps, naming rules, what changes, changing it later and what to do if the name is taken.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Bot Privacy Mode and Group Admin Rights Explained
- BotFather Commands: What Each One Does
- Common Telegram Bot Errors and How to Fix Them
- Connect a Bot to Your Telegram Business Account (Chatbot Mode)
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial