Telegram Bot Deep Links: Handle start Parameters and Account Linking
A Telegram bot deep link passes a parameter through a private-chat /start command. It does not, by itself, prove that a website account and a Telegram user belong to the same person. Use the parameter to look up a server-side onboarding request, wait for the bot update, and require explicit confirmation before committing a sensitive account link. Opening the URL is not completion.
Key takeaways
- Telegram permits up to 64 characters in the startup parameter: letters, digits, underscores, and hyphens.
startis the private-chat entry point;startgrouphas a different group-addition flow.- A campaign code can be public. An account-linking token should be unpredictable, short-lived, and single-use.
- Bot onboarding and authorization of an existing Telegram messaging account are separate integrations.
What a Telegram start link actually sends
Telegram’s bot features documentation describes deep linking, including connecting a Telegram user to an account on another platform. The syntax is https://t.me/<bot_username>?start=<parameter>. These angle-bracket values describe URL syntax, not a working bot or a production token.
The client deep-link specification describes a Start button that invokes the bot startup action with the parameter. Design your UI around the resulting command, not a browser click or an assumed automatic message. The bot receives command text such as /start airplane, using Telegram’s own example parameter.
The parameter allows A-Z, a-z, 0-9, _, and -, up to 64 characters. Telegram recommends base64url for encoding binary or other content. Encoding is not encryption and does not establish trust. Do not put a password, bot token, API hash, email address, or reusable login credential in the URL.
For a group-addition journey, Telegram documents startgroup separately. Do not accept a group command as proof of a private account-linking flow.
Separate routing from identity
| Purpose | Recommended parameter | What receiving it establishes |
|---|---|---|
| Open a help topic | Public allowlisted topic code | The user requested that topic |
| Record a campaign entry | Public campaign code | An attributed entry, not verified identity |
| Link an authenticated website account | Opaque, single-use server-side reference | A pending association that still needs confirmation |
A user can type command text or share a URL. Therefore, a payload containing a customer number is not proof that its sender owns that customer record. Even an unpredictable token can be forwarded or exposed; randomness alone does not prove the intended pair of accounts.
If the credential boundary is unclear, first read Telegram API ID and API hash vs bot token. A startup parameter is application input, not any of those credentials.
Recommended account-linking workflow
The following is an application design recommendation, not a Telegram-provided token service or a new UnifyPort endpoint.
- Begin inside an authenticated website session. Show which account will be linked and require a deliberate action. Protect the website action with your normal session and request-forgery controls.
- Create a pending request on the server. Generate a cryptographically random URL-safe token. Store its hash, the intended website account, intended bot, purpose, expiry, and pending status. These are suggested local records, not Telegram API fields. Choose expiry according to your risk policy; Telegram’s parameter format does not set your application’s token lifetime.
- Receive and validate the actual update. Authenticate your ingress, accept only the intended bot’s private-chat message, parse an exact
/startcommand, and validate parameter length and alphabet. Use the incoming sender identity rather than an ID supplied in the parameter. Telegram’s Bot API reference defines theUpdateandMessageobjects. - Claim without silently granting access. Atomically associate the pending request with the observed Telegram user. Reject an expired request or an attempt by a different user after it has been claimed. Do not reveal website account details to an unconfirmed Telegram sender.
- Confirm the pair in the originating website session. Display the proposed Telegram identity and ask the signed-in account owner to approve it. A mismatched identity should cancel the request, not overwrite an existing link. For sensitive workflows, add an appropriate confirmation in Telegram as well.
- Commit once and retain a minimal audit record. Make final consumption and association atomic. Duplicate delivery or a second Start press must not create another link, move a link, or repeat a benefit. Provide a separate authenticated unlink action.
Keep raw tokens out of analytics, logs, screenshots, and support tickets. Rate-limit invalid attempts. If confirmation never arrives, expire the pending request without granting access.
Diagnose the missing boundary
| Observation | Check next |
|---|---|
| Link opens, no command arrives | Correct bot username, Start interaction, and bot update intake |
Plain /start arrives | Offer normal onboarding; do not infer an account from missing input |
| Parameter is invalid or expired | Ask the user to create a new request from the signed-in website |
| Same update arrives again | Reuse the stored processing outcome, without repeating the association |
| Different Telegram user presents a claimed token | Reject and offer a fresh flow; never transfer the link automatically |
| Bot command arrives, website still says pending | Inspect application claim and confirmation state, not just transport |
For transport selection, use the separate Bot API webhook vs unified inbound webhook comparison. Choosing polling or a webhook does not solve identity confirmation.
Where UnifyPort fits—and where it does not
This onboarding flow belongs to an official Telegram bot. UnifyPort’s Telegram authorization reference instead documents code, QR, and session-import flows for connecting an existing account through an unofficial interface. A bot startup parameter does not authorize that account or replace its approval step.
If your actual task is routing messages from an existing messaging account, use that authorization reference and the documented message.received event. Do not assume a bot deep link will arrive in the connected ordinary account’s inbox. Keep identity linking in your application even when downstream support also spans WhatsApp, LINE, or Zalo.
FAQ
Does opening the link complete account linking?
No. Wait for the bot command and your own confirmation transaction. A link click alone proves neither message receipt nor account ownership.
Can I put a customer ID in the start parameter?
It can serve as non-sensitive routing input, but never as authorization. Use a random server-side reference and explicit confirmation for account linking.
Does base64url protect a secret?
No. It is an encoding. Keep sensitive data on the server and treat the linking URL as sensitive until its token is consumed or expires.
Is this the same as Telegram user-account login?
No. Starting a bot interaction does not create an authorized user-account session. Choose the integration by the identity your application needs.
Next step and sources
Start with Telegram’s deep-link specification, then test missing parameters, forwarded links, expiry, duplicate updates, conflicting identities, and cancellation. These are proposed acceptance tests, not reported test results.
Official references checked on 2026-11-10:
Turn messaging integration into a stable product pipeline.
Start by sending through one API, then bring every inbound message back into your business system with standard events.