Documentation

Referral Links · Overview

Track where your traders actually come from.

A referral link is a deep-linked bot URL that encodes a campaign, channel, or partner. When a trader taps it, Trading Layer records first-touch attribution and keeps it attached to every downstream webhook — so your analytics know exactly which source drove every signal execution.

01

Why it exists

What is a referral link?

You run a bot. Traders arrive from many places — YouTube reviews, your Telegram channel, affiliate posts, paid ads. A referral link is the shared vocabulary between those sources and Trading Layer's dashboard. One link per source, attached to every trader that opens the bot through it.

One link per source.

Create a link in the dashboard, share its URL, and every trader who taps it is credited to that source on first touch.

Works with a plain Telegram URL.

No tracking pixels, no JS. Just the Telegram deep-link with a ref_XXX token in the start parameter.

Routes through your webhooks.

Every trader and signal event carries referralLinkId so your downstream systems can partition on source.

02

What's inside

Anatomy of a referral link.

Each link is a small record on the tenant. These fields are set once on the dashboard when you create the link; everything else — attribution, UTM passthrough, event tagging — flows from them.

Internal name
A human-readable label only you see — e.g. 'Q2 YouTube mid-roll'. Never sent to users.
Start payload
The ref_XXX token embedded in the Telegram start parameter. Generated by Trading Layer when the link is created — tenants don't pick it and can't edit it. It uniquely identifies the link at attribution time. See Deep-link format for the exact format.
Destination
Where the link points: straight to your Telegram bot, or a landing page that hands off to the bot. Set on the dashboard.
UTM parameters
Optional utm_source, utm_medium, utm_campaign, utm_term, and utm_content. If you chose a landing-page destination, we append these to the base URL.
Partner code
An optional identifier for the partner / affiliate that owns the link. Useful for reporting by source but has no effect on bot routing.
Status
Either 'active' or archived. Archived links stop accepting new attributions; existing attributions are preserved.
03

First touch wins

Attribution model.

Attribution is set the first time a trader opens the bot with a matching start payload, and it stays with that trader forever. Later /start links don't overwrite it.

RegEx

The attribution matcher

pattern · /regex/
/^ref_[A-Za-z0-9]{20}(?:_cid[A-Za-z0-9_-]+)?/

The bot only accepts referral payloads that start with our fixed ref_ token. The first 24 characters identify the referral link. If the payload continues with _cid, everything after that marker is stored as Click ID. See Deep-link format for the full rules, examples, and pitfalls.

  1. 01

    Trader taps the deep link

    Telegram opens the bot with the start payload intact, for example ref_03f1500eece04bf9ab5a_cidJOPAPETUHA.

  2. 02

    The bot parses the fixed prefix

    The first 24 characters are looked up in active referral links. If _cid is present, the suffix after it is stored as Click ID.

  3. 03

    Attribution is pinned first-touch

    If the same trader later opens the bot with a different referral link, the attribution row isn't changed. The latest raw payload and latest Click ID are still saved on trader metadata.

  4. 04

    All later events carry the link id

    Every trader-scoped webhook can send the attributed referralLinkId, raw start payload, Click ID, and referral UTM fields when those params are configured.

04

Where attribution shows up

Referrals in webhooks.

Most trader and signal events can be filtered by referral link on an individual endpoint. When filtered, only deliveries whose attributed link matches your filter are sent.

  • trader.started Carries referralLinkId and referralAttributed from the very first contact.
  • trader.onboarded Preserves the original attribution as the trader completes onboarding.
  • trader.mt5_connected Same attribution as when the trader first started.
  • signal.action.executed Attribution is sticky per trader, so signal actions route to the source too.

For the complete event list, see the Webhooks · Event types reference. Events marked referral-filterable pick up attribution automatically.

data
{
  "traderId": "1c027951-63bf-4df0-bcfd-4e47377914b6",
  "telegramId": 1880622198,
  "referralLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "referralAttributed": true,
  "rawStartPayload": "ref_03f1500eece04bf9ab5a_cidJOPAPETUHA",
  "clickId": "JOPAPETUHA"
}

The first 24 characters of rawStartPayload are the token we generated (ref_03f1500eece04bf9ab5a). If the next characters are _cid, the remaining suffix is parsed and stored as Click ID.

05

Housekeeping

Lifecycle and status.

Links have a simple two-state lifecycle. Archived links preserve history but stop accepting new attributions.

Active

Default state. Appears in the dashboard dropdowns, can be shared publicly, and accepts new attributions.

Archived

Hidden from picker UIs and ignored by attribution parsing. Existing trader attributions remain intact — your historical reporting is unaffected.