Affiliate Tracking & Deep Linking: Start Parameters, Attribution Metrics & Referral Funnel Architecture

Crucial Technical Constraint: The 64-Byte Payload Limit

Telegram's MTProto specification enforces a strict limit: the string following ?start= cannot exceed 64 bytes and must only contain alphanumeric characters, underscores (_), and hyphens (-). Never attempt to pass raw JSON strings directly in the URL! Instead, encode your payload into compact URL-safe Base64 (e.g. b64encode(f"{uid}_{campaign}")) or store a 16-character random UUID token in Redis that maps to your internal tracking session.

import base64
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def handle_start_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user = update.effective_user
    user_id = user.id

    # Check if a deep link start parameter was supplied
    if context.args and len(context.args) > 0:
        raw_payload = context.args[0]
        try:
            # Example payload format: "ref_alex99_promo2026"
            parts = raw_payload.split("_")
            if len(parts) >= 2 and parts[0] == "ref":
                partner_tag = parts[1]
                campaign_id = parts[2] if len(parts) > 2 else "direct"

                # Record attribution in database (idempotent, first-touch)
                await bind_user_attribution(
                    new_user_id=user_id,
                    partner_id=partner_tag,
                    campaign_tag=campaign_id
                )
                print(f"[ATTRIBUTION] User {user_id} bound to Partner {partner_tag} (Campaign: {campaign_id})")
        except Exception as e:
            print(f"[WARN] Failed to parse start payload: {e}")

    welcome_text = (
        f"👋 Welcome {user.first_name}!

"
        f"You have been granted access to our institutional crypto signals ecosystem.
"
        f"Use /subscribe to view membership tiers or /help for guidance."
    )
    await update.message.reply_text(welcome_text, parse_mode="HTML")

Frequently Asked Technical Questions (FAQ)