Telegram bot deep links: start parameters, group installation, and attribution

The same Telegram bot may be reached from a product page, campaign, partner link, or group invitation. If every entry point opens a generic home screen, users must explain their intent again and the operator cannot reliably tell which link led to an actual start or installation.

A Telegram bot deep link carries a small start parameter into the first interaction. It can select an onboarding path, identify a campaign, or initialize a bot after it is added to a group. It should not act as a login credential, permanent permission, or unforgeable proof of an order.

Private chats and groups use different entry points

A common private-chat link is:

https://t.me/your_bot?start=campaign_oct

After the user presses Start, the bot receives a /start message with the parameter. Group installation uses startgroup:

https://t.me/your_bot?startgroup=community_a

Telegram first asks the user to select a group where the bot may be added, then passes the parameter to the bot. A group or channel link may also request a set of administrator permissions. The user and Telegram still determine the effective permissions, so the bot must inspect what it actually received at runtime.

For websites, QR codes, and forwarded content, prefer https://t.me/.... Telegram also defines tg:// URIs, but HTTPS links are easier to share across browsers and external applications.

Keep the parameter short, nonsensitive, and revocable

Telegram documents a maximum of 64 base64url characters for a bot start parameter. The common character set is uppercase and lowercase letters, digits, underscores, and hyphens.

Do not put an email address, phone number, access token, full order identifier, or user permission directly in the URL. Links can appear in browser history, analytics logs, screenshots, and forwarded messages. A safer pattern passes a short opaque identifier:

https://t.me/your_bot?start=src_7K2pQ

The bot resolves that identifier against its own business records. If it represents a one-time account link, store an expiration, allowed-use count, and intended user and enforce them on the server. A parameter that merely looks random is not authorization.

Attribute a start, not just a click

Opening the link does not mean that the user pressed Start, registered, installed the bot, or completed a purchase. Separate the funnel:

1. someone visits the webpage or QR code;
2. the user presses Start in Telegram;
3. the bot recognizes the parameter and shows the intended welcome path;
4. the user completes the goal, such as registering or adding the bot to a group.

Only receipt of the parameterized start message confirms the second step. For a group, also record the group identifier, installing user, effective bot permissions, and initialization result instead of relying only on the startgroup value.

A link may be opened repeatedly or forwarded. Attribution can count each valid start, but side effects such as coupons, referral rewards, and account linking need a separate idempotency rule.

A deep-link requirement you can adapt

Add private-chat and group deep links. Accept start for private chats and startgroup for group installation. Accept only 1–64 letters, digits, underscores, or hyphens. Unknown, expired, or malformed values must show the generic welcome flow without exposing internal data. A parameter selects a source and flow; it never grants permission directly. Record the source, user, time, and result for each valid start. Reusing a one-time identifier must not issue a benefit twice. After group installation, inspect the bot's effective permissions and list any missing requirement instead of claiming success. Preserve the default flow for /start without a parameter.

This specification does not require an arbitrary external API. A first version can keep source mappings in the bot's existing business data and add a website or analytics integration only after its need and runtime support are confirmed.

Test the boundaries

• Plain /start still opens the default welcome flow.
• A known parameter shows the matching content and records one valid start.
• Unknown, oversized, spaced, or specially punctuated values trigger no sensitive action.
• A one-time identifier cannot issue a coupon, link an account, or create a record twice.
• If user B opens a link intended for user A, the bot rejects it or requires the agreed confirmation.
• A member who cannot add bots to a group does not produce a successful-install record.
• When the bot lacks an effective permission, it identifies that permission and supports retry after an administrator fixes it.
• A forwarded or expired campaign link produces a clear expiration message.

BotFatherV2 relevance and limits

With BotFatherV2, the source rules, welcome copy, stored records, and failure paths above can be described through an AI conversation and checked with fictional parameters.

BotFatherV2 is independent and is not affiliated with Telegram's official BotFather. AI-assisted creation does not automatically add website analytics, third-party login, or payment capabilities. External services require separate checks for runtime support, credential handling, cost, and privacy. The current fixed SDK also excludes arbitrary npm packages and Node/Bun APIs.

Sources and verification date

• Telegram, Deep links, official English technical documentation; no publication date displayed. Checked October 12, 2026.
• BitBear Studio, BotFatherV2, Build with AI, English product documentation; no publication date displayed. Checked October 12, 2026.