Telegram Bot Deep Link Tutorial: Pass Parameters to Your Bot

A Telegram bot deep link is a t.me URL that opens a bot and passes a parameter to your /start handler. Use it for referral codes, campaign tracking, user IDs from your website, anything you need to associate with the new chat. Here’s the format and the bot-side code.

The deep link format

https://t.me/yourbot?start=YOUR_PARAMETER

When the user taps “Start” in the bot, Telegram sends your backend a /start YOUR_PARAMETER message. Your bot can read the parameter and react accordingly.

Constraints on the parameter

  • Maximum 64 characters.
  • Allowed characters: A-Z, a-z, 0-9, underscore, hyphen.
  • Case-sensitive.
  • No spaces, no slashes, no special characters.

If you need to pass complex data (a JSON blob, a long URL), encode it base64 first.

Bot-side: read the parameter (Python example)

from telegram.ext import Application, CommandHandler
async def start(update, context):
    args = context.args
    if args:
        parameter = args[0]
        await update.message.reply_text(f"You came from: {parameter}")
    else:
        await update.message.reply_text("Welcome! No referral code.")
app = Application.builder().token("BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

The context.args array contains everything after /start. args[0] is your parameter.

Bot-side: Node.js example (Telegraf)

const { Telegraf } = require('telegraf');
const bot = new Telegraf('BOT_TOKEN');
bot.start((ctx) => {
  const param = ctx.startPayload;
  if (param) {
    ctx.reply(`You came from: ${param}`);
  } else {
    ctx.reply('Welcome! No referral code.');
  }
});
bot.launch();

Common use cases

Referral tracking

https://t.me/yourbot?start=ref_user_123

Read the ref_user_123, look up user 123 in your DB, credit them with the referral.

Campaign attribution

https://t.me/yourbot?start=campaign_summer2026

Track which marketing channel drove each new user.

Pre-onboarding flow

https://t.me/yourbot?start=onboarding_paid_user

Skip generic onboarding for users coming from a paid signup flow.

Linking website accounts to Telegram

  1. User clicks “Connect Telegram” on your site.
  2. You generate a token tied to their account.
  3. Redirect them to t.me/yourbot?start=token_xyz.
  4. Bot receives /start token_xyz, looks up the token, links the Telegram chat to the website account.

Adding to a group instead of starting a chat

https://t.me/yourbot?startgroup=true

Triggers Telegram’s “Add to Group” flow. The bot is added with admin permissions you specified during BotFather setup.

You can pass a parameter too: ?startgroup=group_param_value (sends to the bot when added).

Channel attach (for bots that post to channels)

https://t.me/yourbot?startchannel=true

How to share the link

  • Email signatures.
  • Website “Connect with us on Telegram” buttons.
  • QR codes for offline campaigns.
  • Inside other Telegram messages — when shared in a chat, the link previews with the bot’s name and description.

Encoding longer payloads

If you need more than 64 chars or special characters, base64 encode:

// Original payload: {"user":"123","ref":"abc"}
// Base64: eyJ1c2VyIjoiMTIzIiwicmVmIjoiYWJjIn0=
// Strip padding (Telegram doesn't like =): eyJ1c2VyIjoiMTIzIiwicmVmIjoiYWJjIn0
// Link: https://t.me/yourbot?start=eyJ1c2VyIjoiMTIzIiwicmVmIjoiYWJjIn0

Bot side: pad back to base64 length, decode, parse JSON.

Checking the link is recognized

Test: open the link in a browser → should open Telegram with the bot’s profile and a Start button. Tap Start. Bot should receive the parameter. If it doesn’t:

  • Bot username typo (must match exactly, case-insensitive).
  • Bot is private and blocked.
  • Parameter contains illegal characters.
  • Parameter exceeds 64 characters.

Common mistakes

  • Going over 64 characters. Bot silently ignores oversized parameters. Base64-encode larger payloads, then truncate or split.
  • Using illegal characters (spaces, slashes, plus signs). Parameter is rejected.
  • Mixing up start and startgroup. Different parameters, different flows.
  • Storing the parameter in cleartext. If it’s a token, treat it like a password — short-lived, single-use.
  • Forgetting to handle the “no parameter” case. Users find your bot by direct search too. Don’t crash on missing args.

FAQ

Can I pass multiple parameters?

Officially no — only one start parameter. Workaround: use a separator like _ and split server-side: ?start=ref_123_camp_summer.

How do I track conversions from a deep link?

Log every parameter received in your bot DB with a timestamp and the resulting user ID. Match against your campaign source.

Will the parameter persist if the user doesn’t tap Start immediately?

Yes — Telegram remembers the parameter until they tap Start. Even hours later.

Can I use deep links in inline mode?

Yes — inline keyboards can include URL buttons that point to t.me deep links, opening other bots or chats.

Are deep links secure for OAuth-style flows?

The parameter travels in cleartext through Telegram’s servers. Treat it like a one-time token, not a permanent secret. Validate server-side.

Generate the link in seconds

Use the Telegram link generator for the t.me deep link. Pair with the QR code generator for print campaigns.