Skip to main content

Tutorial: Referral System

Build a referral system that rewards users for inviting friends.

What We're Building​

A system where:

  1. Users get a unique invite link
  2. New users join through the link
  3. Both referrer and referee get rewards
  4. Users can track their referral count

When someone clicks t.me/YourBot?start=12345:

  • Telegram opens your bot
  • Sends /start 12345 command
  • The 12345 is available as {{ctx.Match}}

We'll use this to track who invited whom!

  1. Add a Command Trigger for /invite
  2. Add a Send Message:
🎁 Invite friends and earn rewards!

Your personal invite link:
https://t.me/{{bot.username}}?start={{user.id}}

Share this link and get:
• 10 points per friend who joins
• Bonus rewards at milestones!

Your referrals so far: {{var.referral_count ?? 0}}

Step 2: Handle New Users with Referral​

Modify your /start handler:

Check for Referral Code​

  1. Add a Condition: ctx.Match != "" && ctx.Match != user.id

This checks:

  • There's a referral code
  • User isn't trying to refer themselves

Step 3: Process the Referral​

When a valid referral is detected:

  1. Save the referrer:

    • Set var.referred_by = {{ctx.Match}}

  2. Reward the new user:

    • Set var.balance = 10 (or add to existing)

  3. Notify and reward the referrer:

    • This requires sending a message to another user (see below)

Step 4: Reward the Referrer​

To message the referrer, you need to:

  1. Add a Send Message node
  2. Connect a Chat ID from the referral code

Message to referrer:

🎉 Great news!

Someone joined using your invite link!
+10 points added to your balance.

Your new balance: {{var.balance}}
Your total referrals: {{var.referral_count}}

Step 5: Track Referral Count​

For the referrer:

  1. Add a Counter node in increment mode
  2. Or use expression: var.referral_count + 1

Complete Referral Flow​

Enhancements​

Milestone Bonuses​

Reward users at referral milestones:

ReferralsBonus
550 points
10100 points
25500 points
50VIP status

Leaderboard​

Track top referrers:

🏆 Top Referrers This Month:

1. @alice - 47 referrals
2. @bob - 38 referrals
3. @charlie - 29 referrals

You: #12 with 8 referrals

Anti-Fraud​

Prevent abuse:

  1. Limit reward: Only reward once per referrer
  2. Require action: Referee must complete registration
  3. Rate limit: Max referrals per day
https://t.me/YourBot?start={{user.id}}
PartMeaning
t.me/YourBotYour bot's username
?start=Telegram's deep link parameter
{{user.id}}The referrer's user ID

Tips​

Make Sharing Easy

The invite link should be easy to copy and share. Consider adding share buttons!

Track Performance

Log referral data to see which users are your best advocates.

Reward Both Sides

Double-sided rewards (for both referrer and referee) increase participation.

Next Steps​