Telegram Deep Link Attribution, Explained

How Telegram start payloads actually work

A Telegram deep link is a normal URL: t.me/yourbot?start=PAYLOAD, or the native form tg://resolve?domain=yourbot&start=PAYLOAD. Once a /start is actually sent, your bot receives a message whose text is /start PAYLOAD. That message is the entire attribution event. There is no referrer header, no cookie, no landing page script, no click ID appended by the platform. Whatever you did not encode into the payload is gone the moment the user leaves the browser for the Telegram app.

Two constraints shape everything else. First, the payload is capped at 64 characters and accepts only A-Z, a-z, 0-9, underscore and hyphen — so a UTM query string cannot be stuffed into it. Second, the payload only reaches the bot if a /start is sent: a cold user taps the Start button and you get it, while a returning user who opens the chat from their list and types “hi” arrives with nothing attached. Design your reporting around starts, not opens. The mechanics of the URL itself, including the startgroup variant used to add a bot to a group, are covered in the Telegram deep link glossary entry.

Naming conventions that survive a year of campaigns

Payload codes are written once and read forever, usually by someone who was not in the room when they were minted. Fix a slot order and never deviate from it — for example channel_creative_geo_period, producing ig_reel_hookb_br_2603. Positional slots stay readable to a human at a glance and parseable by a script without a lookup table.

• Lowercase only. Codes get retyped from screenshots and lowercased by tools. Normalise on the way in.
• One separator. Pick underscore or hyphen and forbid the other, so ig-reel_br cannot coexist with ig_reel_br.
• Unambiguous dates. Use yymm, never 0304 — a European and an American read that differently.
• Budget for growth. Aim for 24 to 32 characters even though 64 are allowed, so a variant suffix can be appended later.
• Never recycle a code. An old creative can resurface in a repost years later, and a reused code silently credits the wrong campaign.

Mapping payloads to campaigns, sources and tags

A payload does two jobs, and it helps to separate them: it selects what the subscriber sees, and it records where the subscriber came from. In mySkua the incoming payload is resolved against your campaign codes first. On a match, that campaign delivers its own promo code, its message in the subscriber's language, its media and its inline URL buttons. On no match, the payload is still kept as a source and turned into a tag, and the subscriber gets the standard welcome flow.

That distinction makes payloads useful beyond a dashboard number, because sources and tags are also targeting criteria: drips and broadcasts can be aimed at a language, a source, a tag or a category. A code like tg_partnerx_pt_2604 is both an attribution record and an audience — that cohort can get a different day-three message than your Instagram traffic, with no separate list to maintain.

One link per creative, channel and geo

Granularity is decided when you mint the link and can never be recovered afterwards. If every Instagram placement shares instagram, no later analysis will tell you which reel did the work. The counterweight is that thousands of near-identical codes are their own kind of unreadable. The practical rule: mint a separate link for any dimension you would actually move budget over. If you would never pause a creative independently, it does not need its own code. If you buy geo by geo, geo belongs in the payload.

A second axis comes for free. When a bot asks subscribers to pick a category — Sport or Casino, say — that choice is recorded independently of the link they arrived through, so crossing source against category tells you which channels bring which intent without multiplying your link count.

Handling unknown or malformed payloads

Deep links live in hostile places. Bio-link tools rewrite URLs and sometimes strip the query string. Screenshots get retyped with a missing underscore. A partner appends their own suffix to a code you gave them. Plan for it:

• Never discard an unrecognised payload. Store the raw string as a source even when it matches no campaign — it is a lead you can still attribute later.
• Normalise before matching: trim, lowercase, and drop characters outside the allowed set rather than rejecting the whole start.
• Always deliver a message. Someone arriving on a broken or expired code must still get the default welcome; a silent bot looks dead.
• Separate the window from the tagging. If a campaign has closed, record the source but fall back to your standard offer instead of honouring a retired promotion.
• Review the unmatched list weekly. Every entry is either a typo to fix at the source or a campaign somebody forgot to create.

Joining bot data with your ad platform reporting

Ad platform reporting ends at the click on your t.me link; bot reporting begins at the /start. Nothing crosses that boundary automatically, so the payload has to be your join key: use the same code in the ad name that you use in the payload. A join on that string then puts spend, impressions and clicks beside subscribers and activations.

Expect the two sides never to match. Clicks always exceed starts: the app switch fails, the user reads the bot profile without tapping Start, or the click was accidental. Watch the click-to-start ratio per link instead — a stable ratio that suddenly halves usually means a broken link or a creative the bot profile does not confirm, not a tracking bug. On the bot side you export subscriber growth, campaign activations and delivery stats; Telegram bot analytics covers the cohort and retention views that make those numbers comparable week to week.

Attribution windows and one-time activation rules

Deep links get forwarded. Without rules, one enthusiastic subscriber sharing a code in a group chat can inflate a campaign until it looks like your best performer. Three mechanisms keep the numbers honest:

• One-time activation per subscriber. A campaign counts once per person however many times they open the link, so re-taps do not compound.
• New users only. For acquisition tests, restrict a campaign so existing subscribers who tap the link are not counted as new conversions.
• An active window. A hard start and end date means a creative resurfacing after the flight cannot credit a closed campaign — it falls through to your default flow.

Decide explicitly whether a report is first touch or last touch. The source recorded at the first /start is sticky and answers “where did this subscriber come from”. Campaign activations are event level and answer “which offers did they engage with”. Summing the two into one conversion column is where double counting starts. Payout models built on partner links — the pattern in affiliate marketing with a Telegram bot — should state which of the two they pay on, in writing, before the first link is issued.

Debugging links that report the wrong source

When a link credits the wrong campaign or nothing at all, work down this list in order:

• Read the raw start message. Most “attribution bugs” are a payload that never arrived, not a payload mapped wrongly.
• Test cold, not warm. If you have already started the bot you are not reproducing a new subscriber — use a second account, or delete the chat first.
• Check the username. t.me/brand and t.me/brand_bot are different destinations, and only one is your bot.
• Check case and separators against your convention — IG_Reel and ig_reel are different strings before normalisation.
• Check the campaign gates: does the code exist, is it inside its active window, and is new-users-only excluding your test account?
• Check the hop. Shorteners and link-in-bio tools are the most common place a query string is dropped. Open the final URL and confirm ?start= survived.
• Check for a stale copy. A pinned post or a partner's cached creative can keep sending a retired code for months.

Where to start

If you run one link today, split it three ways this week — by channel, by creative and by geo — and write the naming scheme somewhere your team can read it. Attribution on Telegram is not a tool you buy; it is a convention you enforce every time a link is created. The platform only has to keep every payload, match what it recognises, and store the rest as a source you can query later.

mySkua is in a private, invite-only beta. If you run Telegram funnels across several bots and want to work this way, join the waitlist to request access — we onboard new teams in small batches and are happy to look at your link scheme when we do.