Referral Program: Rewards for Invites with Abuse Protection

The referral program rewards members who bring new members to your server: when someone reaches a certain number of real invites, Kage automatically grants a role or XP. The count comes from invite tracking, which subtracts anything fake or left.

This program is about invites on your server. It has nothing to do with the platform's Kage Points system. For a short walkthrough, see the guide Setting up the referral system.

Requirements

• Invite tracking: It runs automatically, but needs Kage's Manage Server permission (see Invite tracking).
• For role rewards: Kage needs Manage Roles, and its role must be above the reward role in the role list.
• For XP rewards: The level system should be on (see Levels and XP), so that the XP have an effect.
• Access: In the dashboard you need Manage Server. The /referral slash commands can likewise only be used with this permission.

How the program works

1. A member joins through an invite. Tracking attributes the join to the inviter and classifies it as real or fake.
2. Only if the join is not fake, Kage checks the inviter's rewards.
3. Kage calculates their net invites (real and still on the server).
4. For every reward whose threshold is reached and which the person has not yet received, Kage grants the reward:

- Role: Kage grants the role if the person does not yet hold it.
- XP: Kage credits the XP as event XP. They are not multiplied.

1. Each threshold applies once per person. After that it is noted as granted.
2. The reward appears in the module's Logs tab ("Referral reward(s) for …").

Important:

• The check runs when a further member joins. So a reward appears with the join that reaches the threshold, not retroactively at a later time.
• If someone leaves the server later, Kage does not take back a reward that was already granted.
• If the inviter is not on the server at the moment of the check, Kage grants no role but still notes the threshold as reached. The role is then lost for good. XP, by contrast, are credited.

Abuse protection

A join does not count as real if the invited Discord account is younger than the minimum account age (default 7 days, adjustable from 0 to 365) or if the person has already been on the server. Fake joins trigger no rewards and do not count toward net invites. They feed into the "Fake" figure of invite tracking.

With the value 0, every account counts as old enough. The minimum account age also affects tracking itself.

Commands

The /referral group can only be used with Manage Server. Only you see all replies.

The commands add-role and add-xp also turn the module on. If a reward already exists for a threshold, the new one replaces it. At most 25 rewards are possible.

Settings at a glance

Only one reward per threshold is possible, and every reward needs a role or an XP amount, otherwise the dashboard refuses to save.

Checking the result

1. Create a reward: /referral add-role with threshold 1 and a test role.
2. Test join: Join with an account older than the minimum account age through an invite from a test account.
3. Result: The inviting account gets the role, and the Logs tab names the reward.
4. Check: /referral list shows the thresholds, /invites the numbers.

Troubleshooting

The reward does not arrive

Check that the program is active and the reward is saved. Check whether the join counted as real (account old enough, not already on the server) and whether the net number reaches the threshold. If the person has already received the reward once, they do not get it again.

The role is not assigned

Kage's role is below the reward role, or Kage lacks Manage Roles. The threshold still counts as reached afterwards. In that case, grant the role by hand.

The count is wrong

Invite tracking only attributes joins through readable invites, and fake or left joins do not count. Check the numbers with /invites.

Further reading

Basis of the count: Invite tracking. XP and ranks: Levels and XP and Ranks, levels and rewards.